Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(mcp): stop advertising read-only endpoint tools as destructive

Cursor Agentdccb1d6d2c97
diff --git a/internal/mcpserver/tools_annotations_test.go b/internal/mcpserver/tools_annotations_test.go
new file mode 100644
index 000000000..0faf31731
--- /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 5a2fd0bb8..6d8aa6c72 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 b8f342537..37378f7b9 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(),
)
}