Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,16 @@ On top of that, you can restrict the tools exposed to the LLM:
> Give the identity of the MCP server the smallest set of permissions it needs, and enable the read-only mode unless you
> want the LLM to modify your resources.

### Server instructions

When an LLM host connects, the MCP server sends it [instructions](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle#initialization)
that most hosts add to the context of the LLM: what Perses is, and how to answer questions about the monitored
systems with the [Prometheus tools](./tools.md#prometheus) (use the same datasource for all the calls, check the
metric and label names before writing PromQL, query with `perses_query_prometheus` rather than the raw datasource
proxy tools). The instructions only give the order and the choice of the tools; the tool descriptions document each
tool. They are built from the registered tools: with `read_only` or `resources`, they never mention a tool that is not
available.

## Features

### Manage the Perses resources
Expand Down
87 changes: 87 additions & 0 deletions internal/permcp/instructions.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
// Copyright The Perses Authors
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package permcp

import (
"fmt"
"strings"

"github.com/perses/common/set"

"github.com/perses/mcp-server/pkg/tools"
"github.com/perses/mcp-server/pkg/tools/dashboard"
"github.com/perses/mcp-server/pkg/tools/datasource"
"github.com/perses/mcp-server/pkg/tools/globaldatasource"
"github.com/perses/mcp-server/pkg/tools/prometheus"
)

// buildInstructions returns the server instructions sent to every client on initialize: what Perses is and how to
// answer questions about monitored systems. They only mention the registered tools. They describe the order and the
// choice of the tools: what a tool does and its parameters are in its description.
func buildInstructions(registered []*tools.Tool) string {
names := set.New[string]()
for _, tool := range registered {
names.Add(tool.MCPTool.Name)
}
// code returns the registered tools among toolNames, formatted as code.
code := func(toolNames ...string) []string {
var available []string
for _, name := range toolNames {
if names.Contains(name) {
available = append(available, "`"+name+"`")
}
}
return available
}

var b strings.Builder
b.WriteString("Perses is an open-source observability dashboard tool. " +
"This server gives access to Perses resources.\n")

// The Prometheus tools are all read-only tools of the same resource: they are all registered or none is.
if !names.Contains(prometheus.QueryToolName) {
return b.String()
}

datasourceStep := "Datasource: use the same `datasource` for discovery and queries"
if listTools := code(globaldatasource.ListToolName, datasource.ListToolName); len(listTools) > 0 {
datasourceStep += "; find the other datasources with " + strings.Join(listTools, " and ")
}
datasourceStep += "."

queryStep := fmt.Sprintf("Query with `%s`", prometheus.QueryToolName)
if proxyTools := code(globaldatasource.QueryToolName, datasource.QueryToolName); len(proxyTools) > 0 {
queryStep += ", not the raw datasource proxy " + strings.Join(proxyTools, " or ")
}
queryStep += fmt.Sprintf(". For a past time range, pass the same `time_range` to `%s`, `%s` and `%s`.",
prometheus.ListMetricNamesToolName, prometheus.ListLabelNamesToolName, prometheus.ListLabelValuesToolName)

steps := []string{
datasourceStep,
fmt.Sprintf("Before writing PromQL, check the metric and label names with `%s`, `%s` and `%s`, and the metric "+
"types with `%s`.", prometheus.ListMetricNamesToolName, prometheus.ListLabelNamesToolName,
prometheus.ListLabelValuesToolName, prometheus.GetMetricMetadataToolName),
queryStep,
}
b.WriteString("\nTo answer questions about monitored systems (metrics):\n")
for i, step := range steps {
fmt.Fprintf(&b, "%d. %s\n", i+1, step)
}

if dashboards := code(dashboard.ListToolName, dashboard.GetToolName); len(dashboards) > 0 {
fmt.Fprintf(&b, "\nThe panels of existing dashboards (%s) show which metrics and queries matter for a system.\n",
strings.Join(dashboards, ", "))
}
return b.String()
}
101 changes: 101 additions & 0 deletions internal/permcp/instructions_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
// Copyright The Perses Authors
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package permcp

import (
"flag"
"os"
"path/filepath"
"regexp"
"slices"
"testing"

apiclient "github.com/perses/perses/pkg/client/api"
"github.com/perses/perses/pkg/client/perseshttp"
"github.com/perses/spec/go/common"

"github.com/perses/mcp-server/pkg/tools"
)

var updateGolden = flag.Bool("update", false, "update the golden files of the instructions")

// toolNameRegexp matches the tool names of the instructions: buildInstructions always formats them as code.
var toolNameRegexp = regexp.MustCompile("`(perses_[a-z_]+)`")

func allTestTools(t *testing.T) []*tools.Tool {
t.Helper()
client := apiclient.NewWithClient(&perseshttp.RESTClient{BaseURL: common.MustParseURL("http://127.0.0.1:1")})
return buildTools(client)
}

func toolNames(selected []*tools.Tool) []string {
var result []string
for _, tool := range selected {
result = append(result, tool.MCPTool.Name)
}
return result
}

// checkMentionedTools fails when the instructions mention a tool which is not registered.
func checkMentionedTools(t *testing.T, instructions string, registered []string) {
t.Helper()
for _, match := range toolNameRegexp.FindAllStringSubmatch(instructions, -1) {
if !slices.Contains(registered, match[1]) {
t.Errorf("instructions mention the unregistered tool %s", match[1])
}
}
}

// TestBuildInstructions compares the instructions with the golden files of testdata/instructions.
// Run `go test ./internal/permcp -run TestBuildInstructions -update` to update them.
func TestBuildInstructions(t *testing.T) {
all := allTestTools(t)
tests := []struct {
name string
cfg Config
}{
{name: "all", cfg: Config{}},
{name: "read-only", cfg: Config{ReadOnly: true}},
{name: "prometheus", cfg: Config{AllowedResources: []string{"prometheus"}}},
{name: "prometheus-globaldatasource", cfg: Config{AllowedResources: []string{"prometheus", "globaldatasource"}}},
{name: "dashboard", cfg: Config{AllowedResources: []string{"dashboard"}}},
{name: "prometheus-datasource", cfg: Config{AllowedResources: []string{"prometheus", "datasource"}}},
{name: "read-only-dashboard-prometheus", cfg: Config{ReadOnly: true, AllowedResources: []string{"dashboard", "prometheus"}}},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
selected := selectTools(all, tt.cfg).selected
instructions := buildInstructions(selected)

golden := filepath.Clean(filepath.Join("testdata", "instructions", tt.name+".md"))
if *updateGolden {
if err := os.WriteFile(golden, []byte(instructions), 0o600); err != nil {
t.Fatal(err)
}
}
want, err := os.ReadFile(golden)
if err != nil {
t.Fatalf("reading the golden file (run with -update to create it): %v", err)
}
if instructions != string(want) {
t.Errorf("instructions differ from %s (run with -update to update it):\n%s", golden, instructions)
}

checkMentionedTools(t, instructions, toolNames(selected))
if len(instructions) > 2000 {
t.Errorf("instructions are %d chars long", len(instructions))
}
})
}
}
96 changes: 59 additions & 37 deletions internal/permcp/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -54,20 +54,28 @@ func New(cfg Config) (async.SimpleTask, error) {

logrus.WithField("url", cfg.PersesServer.URL).Info("Perses client initialized")

// The tools are selected first: the instructions are built from them, so that they never mention a missing tool.
selection := selectTools(buildTools(persesClient), cfg)

mcpServer := mcp.NewServer(&mcp.Implementation{
Name: "perses-mcp-server",
Title: "Perses MCP Server"},
&mcp.ServerOptions{
Instructions: buildInstructions(selection.selected),
Capabilities: &mcp.ServerCapabilities{
Tools: &mcp.ToolCapabilities{ListChanged: false},
},
})
mcpServer.AddReceivingMiddleware(recoverPanics)

for _, tool := range selection.selected {
tool.RegisterWith(mcpServer)
}

return &server{
cfg: cfg,
persesClient: persesClient,
mcpServer: mcpServer,
cfg: cfg,
mcpServer: mcpServer,
tools: selection,
}, nil
}

Expand All @@ -84,10 +92,10 @@ type server struct {
async.SimpleTask
// cfg contains the server configuration settings
cfg Config
// persesClient is the client interface for interacting with the Perses API
persesClient apiclient.ClientInterface
// mcpServer is the Model Context Protocol server instance
mcpServer *mcp.Server
// tools are the registered and the skipped tools, logged when the server starts
tools toolSelection
}

func (s *server) Execute(ctx context.Context, cancelFunc context.CancelFunc) error {
Expand All @@ -96,7 +104,8 @@ func (s *server) Execute(ctx context.Context, cancelFunc context.CancelFunc) err
"transport": s.cfg.Transport,
}).Info("Starting Perses MCP Server")

s.registerTools()
// The tools are registered by New, before the application configures the logs: they are logged here.
s.tools.log()
// start server
// The channel is buffered, so the go routine is not blocked when the transport stops after the end of this method.
transportErr := make(chan error, 1)
Expand Down Expand Up @@ -130,11 +139,12 @@ func (s *server) Execute(ctx context.Context, cancelFunc context.CancelFunc) err
return nil
}

func (s *server) registerTools() {
v1Client := s.persesClient.V1()
// buildTools returns the tools of all the resources.
func buildTools(persesClient apiclient.ClientInterface) []*tools.Tool {
v1Client := persesClient.V1()
resources := []resource.Resource{
project.New(v1Client),
dashboard.New(s.persesClient),
dashboard.New(persesClient),
ephemeraldashboard.New(v1Client),
datasource.New(v1Client),
globaldatasource.New(v1Client),
Expand All @@ -146,51 +156,63 @@ func (s *server) registerTools() {
globalvariable.New(v1Client),
plugin.New(v1Client),
schema.New(v1Client),
validate.New(s.persesClient),
migrate.New(s.persesClient),
validate.New(persesClient),
migrate.New(persesClient),
prometheus.New(v1Client),
}

var allTools []*tools.Tool
for _, r := range resources {
allTools = append(allTools, r.GetTools()...)
}
return allTools
}

// Build allowed resources set for filtering
allowedResources := set.New(s.cfg.AllowedResources...)
filterByResource := len(s.cfg.AllowedResources) > 0
// toolSelection is the result of the read_only and resources filtering of the tools.
type toolSelection struct {
selected []*tools.Tool
skippedResource []*tools.Tool
skippedReadOnly []*tools.Tool
}

registeredCount := 0
skippedReadOnly := 0
skippedResource := 0
// selectTools returns the tools to register: the tools of the allowed resources (all when none is configured),
// without the write tools in read-only mode.
func selectTools(allTools []*tools.Tool, cfg Config) toolSelection {
// Build allowed resources set for filtering
allowedResources := set.New(cfg.AllowedResources...)
filterByResource := len(cfg.AllowedResources) > 0

var selection toolSelection
for _, tool := range allTools {
switch {
// Skip tools not in allowed resources (if filtering is enabled)
if filterByResource && !allowedResources.Contains(string(tool.ResourceType)) {
logrus.WithFields(logrus.Fields{
"tool": tool.MCPTool.Name,
"resourceType": tool.ResourceType,
}).Debug("Skipping tool which is not in allowed resources")
skippedResource++
continue
}

case filterByResource && !allowedResources.Contains(string(tool.ResourceType)):
selection.skippedResource = append(selection.skippedResource, tool)
// Skip write tools in read-only mode
if s.cfg.ReadOnly && tool.IsWriteTool {
logrus.WithField("tool", tool.MCPTool.Name).Debug("Skipping write tool in read-only mode")
skippedReadOnly++
continue
case cfg.ReadOnly && tool.IsWriteTool:
selection.skippedReadOnly = append(selection.skippedReadOnly, tool)
default:
selection.selected = append(selection.selected, tool)
}

tool.RegisterWith(s.mcpServer)
registeredCount++
}
return selection
}

func (t toolSelection) log() {
for _, tool := range t.skippedResource {
logrus.WithFields(logrus.Fields{
"tool": tool.MCPTool.Name,
"resourceType": tool.ResourceType,
}).Debug("Skipping tool which is not in allowed resources")
}
for _, tool := range t.skippedReadOnly {
logrus.WithField("tool", tool.MCPTool.Name).Debug("Skipping write tool in read-only mode")
}
logrus.WithFields(logrus.Fields{
"registered": registeredCount,
"skipped_readonly": skippedReadOnly,
"skipped_resource": skippedResource,
"total": len(allTools),
"registered": len(t.selected),
"skipped_readonly": len(t.skippedReadOnly),
"skipped_resource": len(t.skippedResource),
"total": len(t.selected) + len(t.skippedReadOnly) + len(t.skippedResource),
}).Info("Tools registered successfully")
}

Expand Down
Loading
Loading