From dccb1d6d2c974062976e8b8841c46bbddb06d226 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 10 Oct 2026 01:53:55 +0000 Subject: [PATCH] fix(mcp): stop advertising read-only endpoint tools as destructive mcp.NewTool defaults destructiveHint and openWorldHint to true. The built-in endpoint only set readOnlyHint, so clients that refuse destructive tools could not call search or wiki reads. Co-authored-by: fight for you --- internal/mcpserver/tools_annotations_test.go | 53 ++++++++++++++++++++ internal/mcpserver/tools_retrieve.go | 22 ++++++-- internal/mcpserver/tools_wiki.go | 6 +-- 3 files changed, 73 insertions(+), 8 deletions(-) create mode 100644 internal/mcpserver/tools_annotations_test.go diff --git a/internal/mcpserver/tools_annotations_test.go b/internal/mcpserver/tools_annotations_test.go new file mode 100644 index 00000000..0faf3173 --- /dev/null +++ b/internal/mcpserver/tools_annotations_test.go @@ -0,0 +1,53 @@ +package mcpserver + +import ( + "testing" + + "github.com/mark3labs/mcp-go/mcp" +) + +func TestReadOnlyEndpointToolsAreNotDestructive(t *testing.T) { + for _, tool := range []mcp.Tool{ + listKnowledgeBasesTool(), + searchKnowledgeTool(), + grepChunksTool(), + listDocumentsTool(), + readDocumentTool(), + wikiSearchTool(), + wikiReadPageTool(), + wikiIndexTool(), + } { + ann := tool.Annotations + if ann.ReadOnlyHint == nil || !*ann.ReadOnlyHint { + t.Fatalf("%s must be read-only", tool.Name) + } + if ann.DestructiveHint == nil || *ann.DestructiveHint { + t.Fatalf("%s must not be destructive", tool.Name) + } + if ann.IdempotentHint == nil || !*ann.IdempotentHint { + t.Fatalf("%s must be idempotent", tool.Name) + } + if ann.OpenWorldHint == nil || *ann.OpenWorldHint { + t.Fatalf("%s must not be open-world", tool.Name) + } + } +} + +func TestMutatingEndpointToolsStayDestructive(t *testing.T) { + ask := askTool() + if ask.Annotations.ReadOnlyHint == nil || *ask.Annotations.ReadOnlyHint { + t.Fatal("ask must not be read-only") + } + if ask.Annotations.DestructiveHint == nil || !*ask.Annotations.DestructiveHint { + t.Fatal("ask keeps the default destructive hint") + } + for _, tool := range []mcp.Tool{ + addDocumentTool(), + updateDocumentTool(), + deleteDocumentTool(), + } { + if tool.Annotations.DestructiveHint == nil || !*tool.Annotations.DestructiveHint { + t.Fatalf("%s must stay destructive", tool.Name) + } + } +} diff --git a/internal/mcpserver/tools_retrieve.go b/internal/mcpserver/tools_retrieve.go index 5a2fd0bb..6d8aa6c7 100644 --- a/internal/mcpserver/tools_retrieve.go +++ b/internal/mcpserver/tools_retrieve.go @@ -19,12 +19,24 @@ const ( maxChunkLimit = 100 ) +// readOnlyEndpointAnnotations overrides mcp.NewTool's defaults. Those defaults +// set destructiveHint and openWorldHint to true, so a read-only hint alone +// still advertises the tool as destructive. +func readOnlyEndpointAnnotations() mcp.ToolOption { + return func(t *mcp.Tool) { + mcp.WithReadOnlyHintAnnotation(true)(t) + mcp.WithDestructiveHintAnnotation(false)(t) + mcp.WithIdempotentHintAnnotation(true)(t) + mcp.WithOpenWorldHintAnnotation(false)(t) + } +} + func listKnowledgeBasesTool() mcp.Tool { return mcp.NewTool(types.MCPEndpointToolListKnowledgeBases, mcp.WithDescription("List the knowledge bases this endpoint can access, with their id, name, description "+ "and which retrieval modes (semantic, keyword, wiki) each supports. Call this first to learn what is in "+ "scope; other tools accept either the id or the exact name."), - mcp.WithReadOnlyHintAnnotation(true), + readOnlyEndpointAnnotations(), ) } @@ -41,7 +53,7 @@ func searchKnowledgeTool() mcp.Tool { mcp.WithArray("knowledge_base_ids", mcp.WithStringItems(), mcp.Description("Optional knowledge base ids or names to restrict the search; defaults to every "+ "knowledge base in scope")), - mcp.WithReadOnlyHintAnnotation(true), + readOnlyEndpointAnnotations(), ) } @@ -56,7 +68,7 @@ func grepChunksTool() mcp.Tool { mcp.WithNumber("limit", mcp.Description("Maximum passages to return, default 10, max 30")), mcp.WithArray("knowledge_base_ids", mcp.WithStringItems(), mcp.Description("Optional knowledge base ids or names to restrict the search")), - mcp.WithReadOnlyHintAnnotation(true), + readOnlyEndpointAnnotations(), ) } @@ -68,7 +80,7 @@ func listDocumentsTool() mcp.Tool { mcp.WithString("keyword", mcp.Description("Optional substring to filter document titles")), mcp.WithNumber("page", mcp.Description("1-based page number, default 1")), mcp.WithNumber("page_size", mcp.Description("Documents per page, default 20, max 100")), - mcp.WithReadOnlyHintAnnotation(true), + readOnlyEndpointAnnotations(), ) } @@ -82,7 +94,7 @@ func readDocumentTool() mcp.Tool { mcp.WithNumber("offset", mcp.Description("Chunk offset to start from, default 0")), mcp.WithNumber("limit", mcp.Description("Number of chunks to return, default 20, max 100")), mcp.WithString("query", mcp.Description("Optional case-insensitive phrase to find inside the document")), - mcp.WithReadOnlyHintAnnotation(true), + readOnlyEndpointAnnotations(), ) } diff --git a/internal/mcpserver/tools_wiki.go b/internal/mcpserver/tools_wiki.go index b8f34253..37378f7b 100644 --- a/internal/mcpserver/tools_wiki.go +++ b/internal/mcpserver/tools_wiki.go @@ -29,7 +29,7 @@ func wikiSearchTool() mcp.Tool { mcp.WithArray("knowledge_base_ids", mcp.WithStringItems(), mcp.Description("Optional knowledge base ids or names to restrict the search")), mcp.WithNumber("limit", mcp.Description("Maximum pages to return, default 10, max 50")), - mcp.WithReadOnlyHintAnnotation(true), + readOnlyEndpointAnnotations(), ) } @@ -40,7 +40,7 @@ func wikiReadPageTool() mcp.Tool { "concept/rag")), mcp.WithString("knowledge_base_id", mcp.Description("Knowledge base id or name, required only when the same "+ "slug exists in several wikis")), - mcp.WithReadOnlyHintAnnotation(true), + readOnlyEndpointAnnotations(), ) } @@ -50,7 +50,7 @@ func wikiIndexTool() mcp.Tool { "grouped by type (summary, entity, concept, ...)."), mcp.WithString("knowledge_base_id", mcp.Required(), mcp.Description("Knowledge base id or exact name")), mcp.WithNumber("limit", mcp.Description("Maximum entries per page type, default 50, max 200")), - mcp.WithReadOnlyHintAnnotation(true), + readOnlyEndpointAnnotations(), ) }