Skip to content

[FEATURE] add server instructions - #136

Merged
Nexucis merged 2 commits into
mainfrom
ibakshay-server-instructions
Nov 17, 2026
Merged

Nexucis merged 2 commits into
mainfrom
ibakshay-server-instructions

Conversation

@ibakshay

@ibakshay ibakshay commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #135 (Prometheus tools): review only the last commit. The base will move to main once #135 is merged.

What

The MCP server now sends instructions to every client on initialize. They say what Perses is and how to combine the Prometheus tools of #135 to answer questions about monitored systems:

  1. use the same datasource for discovery and queries (the datasource list tools give the other datasources);
  2. before writing PromQL, check the metric and label names with the discovery tools, and the metric types with perses_get_prometheus_metric_metadata;
  3. query with perses_query_prometheus, not with the raw datasource proxy tools (perses_query_global_datasource, perses_query_project_datasource); for a past time range, pass the same time_range to the metric name, label name and label value tools (perses_get_prometheus_metric_metadata has no time_range).

A last sentence says that the panels of the existing dashboards show which metrics and queries matter for a system. With all the tools, the instructions are about 1000 characters.

The instructions only describe the order and the choice of the tools. What a tool does and its parameters stay in its description, and are not repeated: hosts may not use the instructions, while they always send the tool descriptions.

They are built from the registered tools, so they follow read_only and resources: a step or a tool name only appears when the tool is registered, e.g. with resources: dashboard only the first sentence remains. To build them before the server is created, the tools are now selected and registered in New instead of Execute (buildTools + selectTools, same filtering as before). The selection is still logged in Execute, once the application has configured the logs, so -log.level/-log.format keep applying to these messages. The now unused persesClient field of the server is removed.

Docs: docs/overview.md#server-instructions.

Why

With about 70 tools, models often skip discovery and guess metric names, or fetch large raw results through the proxy tools. Hosts add server instructions to the context once per session, which is the place for this cross-tool workflow; the tool descriptions only describe each tool.

The instructions follow the guidance of the MCP blog post Server Instructions: Giving LLMs a user manual for your server:

  • describe the relationships between the tools and the workflows, which the tool descriptions cannot convey;
  • do not repeat the tool descriptions;
  • keep them short, and only for the enabled tools, like the toolset instructions of the GitHub MCP server;
  • no general behavioral instructions or marketing.

The post also notes that hosts use the instructions differently (e.g. Claude Code and VS Code add them to the context) and that they cannot guarantee a behavior: the important rules, like checking metric names before writing PromQL, also stay in the tool descriptions.

@ibakshay
ibakshay added this pull request to stack #137 November 13, 2026 04:53
@ibakshay
ibakshay force-pushed the ibakshay-server-instructions branch from 97e56a8 to bd25185 Compare November 13, 2026 04:56
@ibakshay
ibakshay requested a balanced review from Copilot November 13, 2026 21:44

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The generated workflow omits explicit requirements to reuse the same datasource and historical time range across discovery and queries, risking queries against a different datasource or missed series from older incidents.

1 open issue
What changed in this PR

Adds initialization instructions to help MCP clients use Perses and the Prometheus tools introduced in #135. The instructions are generated from the enabled toolset.

Changes:

  • Builds and registers tools during server construction, while keeping selection logging at startup.
  • Generates tool-aware guidance for metric discovery, querying, and dashboard tools.
  • Adds filtering and initialization tests and documents server instructions.
File Description
internal/​permcp/​server.go Separates tool selection from logging and attaches initialization instructions.
internal/​permcp/​instructions.go Builds guidance using registered tool names.
internal/​permcp/​instructions_test.go Tests filtering, instruction content, and delivery during initialization.
docs/​overview.md Explains server instructions and enabled-tool filtering.

Review effort: Balanced

Comment thread internal/permcp/instructions.go Resolved
@ibakshay
ibakshay force-pushed the ibakshay-server-instructions branch from bd25185 to ea486c4 Compare November 13, 2026 23:17
@ibakshay
ibakshay requested a balanced review from Copilot November 13, 2026 23:34

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the configuration-aware MCP initialization guidance.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@ibakshay
ibakshay force-pushed the ibakshay-server-instructions branch from ea486c4 to 1a09b6e Compare November 15, 2026 10:55
@ibakshay ibakshay changed the title feat: add server instructions [FEATURE] add server instructions Nov 15, 2026

@Nexucis Nexucis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @ibakshay! Building the instructions from the registered tools is a clean way to keep them consistent with read_only/resources. Overall LGTM; I left a few minor points and nits inline. Every suggestion block compiles, passes lint and passes the tests once the golden files are regenerated with -update.

What I checked on 1a09b6e:

  • go build, go vet, gofmt, golangci-lint (0 issues), go mod tidy and go test -race ./... are all green.
  • An exhaustive check over every resources subset × read_only (131,072 configs) finds no instructions mentioning an unregistered tool. The longest output is 985 chars.
  • Moving the selection and registration into New keeps the same tools, middleware and log messages/fields, and total still matches. The selection is logged in Execute, after runner.Start() sets up logrus, so -log.level/-log.format still apply as described.
  • go-sdk v1.8.0 returns ServerOptions.Instructions in the InitializeResult.

Comment thread internal/permcp/instructions.go Resolved
Comment thread internal/permcp/instructions.go Resolved
Comment thread internal/permcp/instructions.go Resolved
Comment thread internal/permcp/instructions.go Resolved
Comment thread internal/permcp/instructions_test.go Resolved
Comment thread internal/permcp/instructions_test.go Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified in the initialization guidance and tool-registration changes.

No open issues 🎉

Review effort: Balanced

Base automatically changed from ibakshay-prometheus-tools to main November 17, 2026 12:55
Send instructions to every MCP client on initialize: what Perses is and
how to combine the Prometheus tools to answer questions about monitored
systems: use the same datasource for discovery and queries, check the
metric and label names and the metric types before writing PromQL, query
with perses_query_prometheus rather than the raw datasource proxy tools,
and pass the same time_range to the discovery tools for a past range.
The instructions only give the order and the choice of the tools; what
each tool does stays in its description.

The instructions are built from the registered tools, so they follow
read_only and resources and never mention a missing tool. To build them,
the tools are now selected and registered when the server is created
instead of in Execute.

Signed-off-by: Akshay Iyyadurai Balasundaram <akshay.iyyadurai.balasundaram@sap.com>
- Export the tool names of the dashboard, datasource and globaldatasource
  packages and use them in the instructions, so the compiler catches a
  rename; drop TestInstructionToolNamesExist.
- Drop the fixed list of resources from the first sentence: it does not
  depend on the registered tools.
- Reword the datasource and query steps so they read correctly with one
  or two tools, and name the Prometheus tools that accept time_range
  instead of "the discovery tools" (metric metadata rejects it).
- Move the New test to server_test.go as TestNew: checked type
  assertion, t.Context(), a literal list of registered tools and the new
  read-only-dashboard-prometheus golden file.
- Add the prometheus-datasource and read-only-dashboard-prometheus
  golden files.

Signed-off-by: Akshay Iyyadurai Balasundaram <akshay.iyyadurai.balasundaram@sap.com>
@Nexucis
Nexucis force-pushed the ibakshay-server-instructions branch from 97caff4 to 5e27cfc Compare November 17, 2026 12:56

@Nexucis Nexucis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @ibakshay, LGTM! All the points of my previous review are addressed. I checked 5e27cfc (97caff4 before the rebase):

  • buildInstructions now uses the exported tool-name constants of dashboard, datasource and globaldatasource, the same ones the tools use as their mcp.Tool.Name. So the names in the text always match the registered tools.
  • The first sentence no longer depends on the config, and the wording is grammatical in every golden file, including the cases with a single datasource tool.
  • The time_range hint names only the three list tools. At runtime, perses_get_prometheus_metric_metadata still rejects time_range, while the list tools and perses_query_prometheus accept it.
  • TestNew moved to server_test.go, with a checked assertion and t.Context(). It now compares with a literal tool list and the read-only-dashboard-prometheus.md golden file. It fails when the instructions are empty, when the read-only filter is dropped, and when the text changes without updating the golden file.
  • The rebase onto main didn't change the code: git range-diff shows both commits unchanged, and the tree is identical to 97caff4 merged with the final #135.
  • go build, go vet, gofmt, go mod tidy, golangci-lint (0 issues) and go test -race ./... are all green. The exhaustive check over every resources subset × read_only still finds no mention of an unregistered tool, and the longest output is 1038 chars.

Two optional nits, not blocking:

  • The description still starts with "Stacked on #135 (Prometheus tools): review only the last commit…", but #135 is merged now.
  • TestNew reads testdata/instructions/read-only-dashboard-prometheus.md with the case name and config copied from TestBuildInstructions, which is the only test that updates it. If the case is renamed, TestNew keeps reading the old file. A shared constant would avoid that.

@Nexucis
Nexucis added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit e16a85b Nov 17, 2026
7 checks passed
@Nexucis
Nexucis deleted the ibakshay-server-instructions branch November 17, 2026 13:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants