From d5a67b1efa76c6b83480495dba3bc45e9af369c5 Mon Sep 17 00:00:00 2001 From: triepod-ai Date: Sun, 21 Dec 2025 13:24:00 -0600 Subject: [PATCH 1/2] feat: Add tool annotations for improved LLM tool understanding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add readOnlyHint and title annotations to all 13 tools to help LLMs better understand tool behavior and make safer decisions. Changes: - Added annotations property to Tool interface - Added readOnlyHint: true to all read-only tools - Added title annotations for human-readable display - Updated server.tool() call to pass annotations to MCP SDK All tools are read-only operations: - fetch_documentation / fetch_*_docs (fetches docs) - search_documentation / search_*_docs (searches docs) - search_code / search_*_code (searches code) - fetch_generic_url_content (fetches URL content) - match_common_libs_owner_repo_mapping (library lookup) - ThreeJS-specific tools (reference docs, content fetch) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- src/api/tools/index.ts | 5 +++++ .../tools/repoHandlers/DefaultRepoHandler.ts | 13 +++++++++++++ .../tools/repoHandlers/GenericRepoHandler.ts | 17 +++++++++++++++++ .../repoHandlers/ReactRouterRepoHandler.ts | 5 +++++ src/api/tools/repoHandlers/RepoHandler.ts | 2 ++ .../tools/repoHandlers/ThreejsRepoHandler.ts | 17 +++++++++++++++++ src/index.ts | 1 + 7 files changed, 60 insertions(+) diff --git a/src/api/tools/index.ts b/src/api/tools/index.ts index 6da182b..36469b6 100644 --- a/src/api/tools/index.ts +++ b/src/api/tools/index.ts @@ -3,6 +3,7 @@ import { getRepoData } from "../../shared/repoData.js"; import { fetchUrlContent } from "./commonTools.js"; import { getHandlerByRepoData } from "./repoHandlers/handlers.js"; import type { Tool } from "./repoHandlers/RepoHandler.js"; +import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js"; export function getMcpTools( env: Env, @@ -25,6 +26,10 @@ export function getMcpTools( cb: async ({ url }) => { return fetchUrlContent({ url, env }); }, + annotations: { + title: "Fetch URL Content", + readOnlyHint: true, + } as ToolAnnotations, }, ]; } diff --git a/src/api/tools/repoHandlers/DefaultRepoHandler.ts b/src/api/tools/repoHandlers/DefaultRepoHandler.ts index e7c6a25..7e1f5b8 100644 --- a/src/api/tools/repoHandlers/DefaultRepoHandler.ts +++ b/src/api/tools/repoHandlers/DefaultRepoHandler.ts @@ -13,6 +13,7 @@ import { import { z } from "zod"; import type { RepoData } from "../../../shared/repoData.js"; import type { RepoHandler, Tool } from "./RepoHandler.js"; +import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js"; class DefaultRepoHandler implements RepoHandler { name = "default"; @@ -34,6 +35,10 @@ class DefaultRepoHandler implements RepoHandler { cb: async () => { return fetchDocumentation({ repoData, env, ctx }); }, + annotations: { + title: "Fetch Documentation", + readOnlyHint: true, + } as ToolAnnotations, }, { name: searchToolName, @@ -51,6 +56,10 @@ class DefaultRepoHandler implements RepoHandler { ctx, }); }, + annotations: { + title: "Search Documentation", + readOnlyHint: true, + } as ToolAnnotations, }, { name: codeSearchToolName, @@ -75,6 +84,10 @@ class DefaultRepoHandler implements RepoHandler { ctx, }); }, + annotations: { + title: "Search Code", + readOnlyHint: true, + } as ToolAnnotations, }, ]; } diff --git a/src/api/tools/repoHandlers/GenericRepoHandler.ts b/src/api/tools/repoHandlers/GenericRepoHandler.ts index 05a1c66..a243ab2 100644 --- a/src/api/tools/repoHandlers/GenericRepoHandler.ts +++ b/src/api/tools/repoHandlers/GenericRepoHandler.ts @@ -8,6 +8,7 @@ import { } from "../commonTools.js"; import { incrementRepoViewCount } from "../../utils/badge.js"; import rawMapping from "./generic/static-mapping.json"; +import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js"; const badgeCountAllowedRepos = ["mcp-ui", "git-mcp"]; @@ -82,6 +83,10 @@ class GenericRepoHandler implements RepoHandler { ], }; }, + annotations: { + title: "Match Library to Repository", + readOnlyHint: true, + } as ToolAnnotations, }, { name: "fetch_generic_documentation", @@ -102,6 +107,10 @@ class GenericRepoHandler implements RepoHandler { }; return fetchDocumentation({ repoData, env, ctx }); }, + annotations: { + title: "Fetch Generic Documentation", + readOnlyHint: true, + } as ToolAnnotations, }, { name: "search_generic_documentation", @@ -125,6 +134,10 @@ class GenericRepoHandler implements RepoHandler { }; return searchRepositoryDocumentation({ repoData, query, env, ctx }); }, + annotations: { + title: "Search Generic Documentation", + readOnlyHint: true, + } as ToolAnnotations, }, { name: "search_generic_code", @@ -154,6 +167,10 @@ class GenericRepoHandler implements RepoHandler { }; return searchRepositoryCode({ repoData, query, page, env, ctx }); }, + annotations: { + title: "Search Generic Code", + readOnlyHint: true, + } as ToolAnnotations, }, ]; } diff --git a/src/api/tools/repoHandlers/ReactRouterRepoHandler.ts b/src/api/tools/repoHandlers/ReactRouterRepoHandler.ts index 3252531..c43e89f 100644 --- a/src/api/tools/repoHandlers/ReactRouterRepoHandler.ts +++ b/src/api/tools/repoHandlers/ReactRouterRepoHandler.ts @@ -8,6 +8,7 @@ import type { RepoData } from "../../../shared/repoData.js"; import type { RepoHandler, Tool } from "./RepoHandler.js"; import { getDefaultRepoHandler } from "./DefaultRepoHandler.js"; import { z } from "zod"; +import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js"; class ReactRouterRepoHandler implements RepoHandler { name = "react-router"; @@ -34,6 +35,10 @@ class ReactRouterRepoHandler implements RepoHandler { ctx, }); }, + annotations: { + title: "Search Documentation", + readOnlyHint: true, + } as ToolAnnotations, }; // Filter out the default search tool and add our specific implementation diff --git a/src/api/tools/repoHandlers/RepoHandler.ts b/src/api/tools/repoHandlers/RepoHandler.ts index e86e0f3..1250fc5 100644 --- a/src/api/tools/repoHandlers/RepoHandler.ts +++ b/src/api/tools/repoHandlers/RepoHandler.ts @@ -1,10 +1,12 @@ import type { RepoData } from "../../../shared/repoData.js"; +import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js"; export interface Tool { name: string; description: string; paramsSchema: any; cb: (args: any) => Promise; + annotations?: ToolAnnotations; } export interface RepoHandler { diff --git a/src/api/tools/repoHandlers/ThreejsRepoHandler.ts b/src/api/tools/repoHandlers/ThreejsRepoHandler.ts index f257e53..661ab95 100644 --- a/src/api/tools/repoHandlers/ThreejsRepoHandler.ts +++ b/src/api/tools/repoHandlers/ThreejsRepoHandler.ts @@ -7,6 +7,7 @@ import { fetchThreeJsUrlsAsMarkdown, } from "./threejs/utils.js"; import { searchRepositoryDocumentation } from "../commonTools.js"; +import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js"; const GET_REFERENCE_DOCS_LIST_TOOL_NAME = "get_threejs_reference_docs_list"; const GET_SPECIFIC_DOCS_CONTENT_TOOL_NAME = "get_threejs_specific_docs_content"; @@ -25,6 +26,10 @@ class ThreejsRepoHandler implements RepoHandler { cb: async () => { return await getReferenceDocsListAsMarkdown({ env }); }, + annotations: { + title: "Get Three.js Reference Docs List", + readOnlyHint: true, + } as ToolAnnotations, }, { name: GET_SPECIFIC_DOCS_CONTENT_TOOL_NAME, @@ -47,6 +52,10 @@ class ThreejsRepoHandler implements RepoHandler { documents: args.documents, }); }, + annotations: { + title: "Get Three.js Specific Docs Content", + readOnlyHint: true, + } as ToolAnnotations, }, { name: "search_threejs_documentation", @@ -66,6 +75,10 @@ class ThreejsRepoHandler implements RepoHandler { fallbackSearch: noopFallbackSearch, }); }, + annotations: { + title: "Search Three.js Documentation", + readOnlyHint: true, + } as ToolAnnotations, }, { name: "fetch_threejs_urls_inside_docs", @@ -87,6 +100,10 @@ class ThreejsRepoHandler implements RepoHandler { cb: async ({ urls }) => { return await fetchThreeJsUrlsAsMarkdown(urls); }, + annotations: { + title: "Fetch Three.js URLs Inside Docs", + readOnlyHint: true, + } as ToolAnnotations, }, ]; } diff --git a/src/index.ts b/src/index.ts index 26cdbf1..c48b26e 100644 --- a/src/index.ts +++ b/src/index.ts @@ -103,6 +103,7 @@ export class MyMCP extends McpAgent { withViewTracking(env, ctx, repoData, async (args: any) => { return tool.cb(args); }), + tool.annotations ? { annotations: tool.annotations } : undefined, ); }); } From 020445461897c8e668b79938c3ec013fccafea86 Mon Sep 17 00:00:00 2001 From: triepod-ai Date: Sun, 21 Dec 2025 14:25:36 -0600 Subject: [PATCH 2/2] refactor: Remove unnecessary type assertions per review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove explicit 'as ToolAnnotations' type casts that TypeScript can infer from the Tool interface. This follows best practices by letting TypeScript handle type checking naturally rather than using explicit assertions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- src/api/tools/index.ts | 2 +- src/api/tools/repoHandlers/DefaultRepoHandler.ts | 6 +++--- src/api/tools/repoHandlers/GenericRepoHandler.ts | 8 ++++---- src/api/tools/repoHandlers/ReactRouterRepoHandler.ts | 2 +- src/api/tools/repoHandlers/ThreejsRepoHandler.ts | 8 ++++---- 5 files changed, 13 insertions(+), 13 deletions(-) diff --git a/src/api/tools/index.ts b/src/api/tools/index.ts index 36469b6..4fd9fba 100644 --- a/src/api/tools/index.ts +++ b/src/api/tools/index.ts @@ -29,7 +29,7 @@ export function getMcpTools( annotations: { title: "Fetch URL Content", readOnlyHint: true, - } as ToolAnnotations, + }, }, ]; } diff --git a/src/api/tools/repoHandlers/DefaultRepoHandler.ts b/src/api/tools/repoHandlers/DefaultRepoHandler.ts index 7e1f5b8..354d736 100644 --- a/src/api/tools/repoHandlers/DefaultRepoHandler.ts +++ b/src/api/tools/repoHandlers/DefaultRepoHandler.ts @@ -38,7 +38,7 @@ class DefaultRepoHandler implements RepoHandler { annotations: { title: "Fetch Documentation", readOnlyHint: true, - } as ToolAnnotations, + }, }, { name: searchToolName, @@ -59,7 +59,7 @@ class DefaultRepoHandler implements RepoHandler { annotations: { title: "Search Documentation", readOnlyHint: true, - } as ToolAnnotations, + }, }, { name: codeSearchToolName, @@ -87,7 +87,7 @@ class DefaultRepoHandler implements RepoHandler { annotations: { title: "Search Code", readOnlyHint: true, - } as ToolAnnotations, + }, }, ]; } diff --git a/src/api/tools/repoHandlers/GenericRepoHandler.ts b/src/api/tools/repoHandlers/GenericRepoHandler.ts index a243ab2..db5b57a 100644 --- a/src/api/tools/repoHandlers/GenericRepoHandler.ts +++ b/src/api/tools/repoHandlers/GenericRepoHandler.ts @@ -86,7 +86,7 @@ class GenericRepoHandler implements RepoHandler { annotations: { title: "Match Library to Repository", readOnlyHint: true, - } as ToolAnnotations, + }, }, { name: "fetch_generic_documentation", @@ -110,7 +110,7 @@ class GenericRepoHandler implements RepoHandler { annotations: { title: "Fetch Generic Documentation", readOnlyHint: true, - } as ToolAnnotations, + }, }, { name: "search_generic_documentation", @@ -137,7 +137,7 @@ class GenericRepoHandler implements RepoHandler { annotations: { title: "Search Generic Documentation", readOnlyHint: true, - } as ToolAnnotations, + }, }, { name: "search_generic_code", @@ -170,7 +170,7 @@ class GenericRepoHandler implements RepoHandler { annotations: { title: "Search Generic Code", readOnlyHint: true, - } as ToolAnnotations, + }, }, ]; } diff --git a/src/api/tools/repoHandlers/ReactRouterRepoHandler.ts b/src/api/tools/repoHandlers/ReactRouterRepoHandler.ts index c43e89f..4a1c0c2 100644 --- a/src/api/tools/repoHandlers/ReactRouterRepoHandler.ts +++ b/src/api/tools/repoHandlers/ReactRouterRepoHandler.ts @@ -38,7 +38,7 @@ class ReactRouterRepoHandler implements RepoHandler { annotations: { title: "Search Documentation", readOnlyHint: true, - } as ToolAnnotations, + }, }; // Filter out the default search tool and add our specific implementation diff --git a/src/api/tools/repoHandlers/ThreejsRepoHandler.ts b/src/api/tools/repoHandlers/ThreejsRepoHandler.ts index 661ab95..ff99505 100644 --- a/src/api/tools/repoHandlers/ThreejsRepoHandler.ts +++ b/src/api/tools/repoHandlers/ThreejsRepoHandler.ts @@ -29,7 +29,7 @@ class ThreejsRepoHandler implements RepoHandler { annotations: { title: "Get Three.js Reference Docs List", readOnlyHint: true, - } as ToolAnnotations, + }, }, { name: GET_SPECIFIC_DOCS_CONTENT_TOOL_NAME, @@ -55,7 +55,7 @@ class ThreejsRepoHandler implements RepoHandler { annotations: { title: "Get Three.js Specific Docs Content", readOnlyHint: true, - } as ToolAnnotations, + }, }, { name: "search_threejs_documentation", @@ -78,7 +78,7 @@ class ThreejsRepoHandler implements RepoHandler { annotations: { title: "Search Three.js Documentation", readOnlyHint: true, - } as ToolAnnotations, + }, }, { name: "fetch_threejs_urls_inside_docs", @@ -103,7 +103,7 @@ class ThreejsRepoHandler implements RepoHandler { annotations: { title: "Fetch Three.js URLs Inside Docs", readOnlyHint: true, - } as ToolAnnotations, + }, }, ]; }