From fc2860612c6398fbadec125f72a81794f0ff0942 Mon Sep 17 00:00:00 2001 From: Simon Date: Sat, 6 Jun 2026 19:14:25 -0700 Subject: [PATCH] fix: clarify mcp doc tool routing for glama --- packages/mcp/src/__tests__/docs.test.ts | 27 +++++++++++++++++++ packages/mcp/src/__tests__/translator.test.ts | 25 +++++++++++++++++ packages/mcp/src/tools/docs.ts | 4 +-- packages/mcp/src/tools/translator.ts | 2 +- 4 files changed, 55 insertions(+), 3 deletions(-) diff --git a/packages/mcp/src/__tests__/docs.test.ts b/packages/mcp/src/__tests__/docs.test.ts index b3f4f9c..da993eb 100644 --- a/packages/mcp/src/__tests__/docs.test.ts +++ b/packages/mcp/src/__tests__/docs.test.ts @@ -193,6 +193,33 @@ describe("MCP Docs Tools", () => { expect(toolNames).toContain("translate_api_docs"); expect(toolNames).toContain("create_bilingual_doc"); }); + + it("should describe markdown and API-doc routing clearly for MCP discovery", async () => { + const { registerDocsTools } = await import("../tools/docs.js"); + const mockServer = { + registerTool: vi.fn(), + tool: vi.fn(), + }; + + registerDocsTools(mockServer as any, { registry: mockRegistry }); + + const configs = new Map( + vi.mocked(mockServer.registerTool).mock.calls.map(([name, config]) => [ + name, + config as { description: string }, + ]) + ); + const markdown = configs.get("translate_markdown")!.description.toLowerCase(); + const apiDocs = configs.get("translate_api_docs")!.description.toLowerCase(); + + expect(markdown).toContain("ordinary markdown"); + expect(markdown).toContain("use translate_readme"); + expect(markdown).toContain("use translate_api_docs"); + expect(apiDocs).toContain("endpoint"); + expect(apiDocs).toContain("http methods"); + expect(apiDocs).toContain("status codes"); + expect(apiDocs).toContain("not general markdown"); + }); }); describe("translate_markdown tool", () => { diff --git a/packages/mcp/src/__tests__/translator.test.ts b/packages/mcp/src/__tests__/translator.test.ts index f736f44..2004a21 100644 --- a/packages/mcp/src/__tests__/translator.test.ts +++ b/packages/mcp/src/__tests__/translator.test.ts @@ -197,6 +197,31 @@ describe("MCP Translator Tools", () => { expect(toolNames).toContain("list_dialects"); expect(toolNames).toContain("research_regional_term"); }); + + it("should describe translate_readme as README-specific for MCP discovery", async () => { + const { registerTranslatorTools } = await import("../tools/translator.js"); + const mockServer = { + registerTool: vi.fn(), + tool: vi.fn(), + }; + + registerTranslatorTools(mockServer as any, { registry: mockRegistry }); + + const tools = new Map( + vi.mocked(mockServer.registerTool).mock.calls.map(([name, config]) => [ + name, + config as { description: string }, + ]) + ); + const description = tools.get("translate_readme")!.description.toLowerCase(); + + expect(description).toContain("repository readme"); + expect(description).toContain("badges"); + expect(description).toContain("install"); + expect(description).toContain("license"); + expect(description).toContain("use translate_markdown"); + expect(description).toContain("use translate_api_docs"); + }); }); describe("translate_text tool", () => { diff --git a/packages/mcp/src/tools/docs.ts b/packages/mcp/src/tools/docs.ts index 6b609cf..fd8dcbe 100644 --- a/packages/mcp/src/tools/docs.ts +++ b/packages/mcp/src/tools/docs.ts @@ -492,7 +492,7 @@ export function registerDocsTools( { title: "Translate Markdown file", description: - "Read a Markdown file, translate translatable prose into a Spanish dialect, and return reconstructed Markdown while preserving code blocks, links, and non-translatable sections. Reads the file only; it does not overwrite the source file.", + "Read an ordinary Markdown file, translate translatable prose into a Spanish dialect, and return reconstructed Markdown while preserving code blocks, links, and non-translatable sections. Use this for general Markdown pages, articles, or docs; use translate_readme for repository README files with badges/install/license sections, and use translate_api_docs for endpoint/reference documentation. Reads the file only, may call the selected translation provider under the configured rate limiter, and does not overwrite the source file.", inputSchema: { filePath: z.string().min(1).describe("Path to the Markdown file to read and translate."), dialect: dialectSchema.optional().describe("Target Spanish dialect code. Defaults to es-ES when omitted; examples include es-MX, es-AR, and es-CO."), @@ -542,7 +542,7 @@ export function registerDocsTools( { title: "Translate API documentation", description: - "Read API documentation Markdown and translate prose into a Spanish dialect with documentation context for tables, lists, endpoints, and technical terms. Returns translated Markdown and errors; it does not modify the file.", + "Read API documentation Markdown and translate prose into a Spanish dialect with documentation context for endpoints, HTTP methods, route paths, parameters, status codes, code examples, tables, lists, and technical terms. Use this for API/reference docs, not general Markdown or repository README pages. Returns translated Markdown and errors; it may call the selected translation provider under the configured rate limiter and does not modify the file.", inputSchema: { filePath: z.string().min(1).describe("Path to the API documentation Markdown file to read and translate."), dialect: dialectSchema.optional().describe("Target Spanish dialect code. Defaults to es-ES when omitted."), diff --git a/packages/mcp/src/tools/translator.ts b/packages/mcp/src/tools/translator.ts index 1f1637c..3998181 100644 --- a/packages/mcp/src/tools/translator.ts +++ b/packages/mcp/src/tools/translator.ts @@ -141,7 +141,7 @@ export function registerTranslatorTools( { title: "Translate README Markdown", description: - "Read a README Markdown file, translate translatable prose into a Spanish dialect, and return translated Markdown with code blocks and structure preserved. Reads the file only; it does not overwrite the README.", + "Read a repository README Markdown file, translate translatable prose into a Spanish dialect, and return translated Markdown while preserving badges, install commands, usage examples, contribution sections, license text, code blocks, and structure. Use translate_markdown for ordinary Markdown pages, and use translate_api_docs for endpoint/reference documentation. Reads the file only, may call the selected translation provider under the configured rate limiter, and does not overwrite the README.", inputSchema: { filePath: z.string().min(1).describe("Path to the README Markdown file to read and translate."), dialect: dialectSchema.optional().describe("Target Spanish dialect code. Defaults to es-ES when omitted."),