Repository navigation
[FEATURE] add server instructions - #136
Conversation
97e56a8 to
bd25185
Compare
There was a problem hiding this comment.
🟡 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
bd25185 to
ea486c4
Compare
ea486c4 to
1a09b6e
Compare
Nexucis
left a comment
There was a problem hiding this comment.
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 tidyandgo test -race ./...are all green.- An exhaustive check over every
resourcessubset ×read_only(131,072 configs) finds no instructions mentioning an unregistered tool. The longest output is 985 chars. - Moving the selection and registration into
Newkeeps the same tools, middleware and log messages/fields, andtotalstill matches. The selection is logged inExecute, afterrunner.Start()sets up logrus, so-log.level/-log.formatstill apply as described. - go-sdk v1.8.0 returns
ServerOptions.Instructionsin theInitializeResult.
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>
97caff4 to
5e27cfc
Compare
Nexucis
left a comment
There was a problem hiding this comment.
Thanks @ibakshay, LGTM! All the points of my previous review are addressed. I checked 5e27cfc (97caff4 before the rebase):
buildInstructionsnow uses the exported tool-name constants ofdashboard,datasourceandglobaldatasource, the same ones the tools use as theirmcp.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_rangehint names only the three list tools. At runtime,perses_get_prometheus_metric_metadatastill rejectstime_range, while the list tools andperses_query_prometheusaccept it. TestNewmoved toserver_test.go, with a checked assertion andt.Context(). It now compares with a literal tool list and theread-only-dashboard-prometheus.mdgolden 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
maindidn't change the code:git range-diffshows 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) andgo test -race ./...are all green. The exhaustive check over everyresourcessubset ×read_onlystill 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.
TestNewreadstestdata/instructions/read-only-dashboard-prometheus.mdwith the case name and config copied fromTestBuildInstructions, which is the only test that updates it. If the case is renamed,TestNewkeeps reading the old file. A shared constant would avoid that.

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:datasourcefor discovery and queries (the datasource list tools give the other datasources);perses_get_prometheus_metric_metadata;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 sametime_rangeto the metric name, label name and label value tools (perses_get_prometheus_metric_metadatahas notime_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_onlyandresources: a step or a tool name only appears when the tool is registered, e.g. withresources: dashboardonly the first sentence remains. To build them before the server is created, the tools are now selected and registered inNewinstead ofExecute(buildTools+selectTools, same filtering as before). The selection is still logged inExecute, once the application has configured the logs, so-log.level/-log.formatkeep applying to these messages. The now unusedpersesClientfield 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:
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.