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 <wangrui19971019@users.noreply.github.com>
main
Cursor Agent 2026-10-10 01:53:55 +00:00 committed by lyingbug
parent 54e8d7ffde
commit dccb1d6d2c
3 changed files with 73 additions and 8 deletions

View File

@ -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)
}
}
}

View File

@ -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(),
)
}

View File

@ -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(),
)
}