feat: add MCP tool name handling with API-safe names

Author: qorzj

src/mcp/mcp-manager.ts

@@ -1,10 +1,13 @@
+import { createHash } from "crypto";
 import { McpClient, type McpToolDefinition, type McpPromptDefinition, type McpResourceDefinition } from "./mcp-client";
 import type { McpServerConfig } from "../settings";
 
 const MCP_STARTUP_TIMEOUT_MS = process.env.DEEPCODE_MCP_TIMEOUT
   ? parseInt(process.env.DEEPCODE_MCP_TIMEOUT, 10)
   : 30_000;
 const MCP_CALL_TOOL_TIMEOUT_MS = 60_000;
+const API_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+const API_TOOL_NAME_MAX_LENGTH = 64;
 
 type McpToolEntry = {
   serverName: string;
@@ -27,6 +30,32 @@ export type McpServerStatus = {
   resources: string[];
 };
 
+function buildMcpNamespacedName(
+  serverName: string,
+  toolName: string,
+  usedNames: ReadonlySet<string> = new Set()
+): string {
+  const rawName = buildRawMcpNamespacedName(serverName, toolName);
+  const sanitizedName = `mcp__${sanitizeApiToolNamePart(serverName)}__${sanitizeApiToolNamePart(toolName)}`;
+  let candidate = fitApiToolName(sanitizedName, rawName);
+  if (!usedNames.has(candidate)) {
+    return candidate;
+  }
+
+  const hash = hashToolName(rawName);
+  candidate = fitApiToolNameWithSuffix(sanitizedName, `_${hash}`);
+  if (!usedNames.has(candidate)) {
+    return candidate;
+  }
+
+  for (let index = 2; ; index += 1) {
+    candidate = fitApiToolNameWithSuffix(sanitizedName, `_${hash}_${index}`);
+    if (!usedNames.has(candidate)) {
+      return candidate;
+    }
+  }
+}
+
 export class McpManager {
   private clients: McpClient[] = [];
   private tools: McpToolEntry[] = [];
@@ -151,8 +180,10 @@ export class McpManager {
       const serverTools = await client.listTools(MCP_STARTUP_TIMEOUT_MS);
       if (this.disposed) return;
       const toolNamespacedNames: string[] = [];
+      const usedToolNames = new Set(this.tools.map((tool) => tool.namespacedName));
       for (const tool of serverTools) {
-        const namespacedName = `mcp__${name}__${tool.name}`;
+        const namespacedName = buildMcpNamespacedName(name, tool.name, usedToolNames);
+        usedToolNames.add(namespacedName);
         this.tools.push({
           serverName: name,
           originalName: tool.name,
@@ -289,7 +320,7 @@ export class McpManager {
       type: "function" as const,
       function: {
         name: t.namespacedName,
-        description: t.definition.description ?? `${t.serverName}: ${t.originalName}`,
+        description: this.buildMcpToolDescription(t),
         parameters: {
           type: "object" as const,
           properties: t.definition.inputSchema.properties,
@@ -413,8 +444,10 @@ export class McpManager {
     const serverTools = await client.listTools(MCP_STARTUP_TIMEOUT_MS);
     this.tools = this.tools.filter((t) => t.serverName !== serverName);
     const toolNamespacedNames: string[] = [];
+    const usedToolNames = new Set(this.tools.map((tool) => tool.namespacedName));
     for (const tool of serverTools) {
-      const namespacedName = `mcp__${serverName}__${tool.name}`;
+      const namespacedName = buildMcpNamespacedName(serverName, tool.name, usedToolNames);
+      usedToolNames.add(namespacedName);
       this.tools.push({
         serverName,
         originalName: tool.name,
@@ -450,4 +483,42 @@ export class McpManager {
     }
     this.onStatusChanged?.();
   }
+
+  private buildMcpToolDescription(tool: McpToolEntry): string {
+    const description = tool.definition.description?.trim();
+    const source = `${tool.serverName}: ${tool.originalName}`;
+    if (!description) {
+      return source;
+    }
+    if (tool.namespacedName === buildRawMcpNamespacedName(tool.serverName, tool.originalName)) {
+      return description;
+    }
+    return `${description}\nMCP source: ${source}`;
+  }
+}
+
+function buildRawMcpNamespacedName(serverName: string, toolName: string): string {
+  return `mcp__${serverName}__${toolName}`;
+}
+
+function sanitizeApiToolNamePart(value: string): string {
+  const sanitized = value.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return sanitized || "unnamed";
+}
+
+function fitApiToolName(name: string, rawName: string): string {
+  if (API_TOOL_NAME_PATTERN.test(name) && name.length <= API_TOOL_NAME_MAX_LENGTH) {
+    return name;
+  }
+  return fitApiToolNameWithSuffix(name, `_${hashToolName(rawName)}`);
+}
+
+function fitApiToolNameWithSuffix(name: string, suffix: string): string {
+  const maxPrefixLength = API_TOOL_NAME_MAX_LENGTH - suffix.length;
+  const prefix = name.slice(0, Math.max(1, maxPrefixLength));
+  return `${prefix}${suffix}`;
+}
+
+function hashToolName(value: string): string {
+  return createHash("sha256").update(value).digest("hex").slice(0, 8);
 }

src/tests/session.test.ts

@@ -542,6 +542,64 @@ rl.on("line", (line) => {
   assert.deepEqual(manager.getMcpStatus(), []);
 });
 
+test("SessionManager exposes MCP tools with API-safe names and preserves original dispatch names", async () => {
+  const workspace = createTempDir("deepcode-mcp-safe-name-workspace-");
+  const serverPath = path.join(workspace, "mcp-invalid-name-server.cjs");
+  fs.writeFileSync(
+    serverPath,
+    `
+const readline = require("readline");
+const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+function send(message) {
+  process.stdout.write(JSON.stringify(message) + "\\n");
+}
+rl.on("line", (line) => {
+  const request = JSON.parse(line);
+  if (!("id" in request)) {
+    return;
+  }
+  if (request.method === "initialize") {
+    send({ jsonrpc: "2.0", id: request.id, result: { protocolVersion: "2024-11-05", capabilities: { tools: {} } } });
+    return;
+  }
+  if (request.method === "tools/list") {
+    send({ jsonrpc: "2.0", id: request.id, result: { tools: [
+      { name: "speak.text", description: "Speak text", inputSchema: { type: "object", properties: { text: { type: "string" } }, required: ["text"] } },
+      { name: "speak/text", description: "Speak text using a slash name", inputSchema: { type: "object", properties: {} } }
+    ] } });
+    return;
+  }
+  if (request.method === "tools/call") {
+    send({ jsonrpc: "2.0", id: request.id, result: { content: [{ type: "text", text: request.params.name + ":" + (request.params.arguments.text || "") }] } });
+    return;
+  }
+  send({ jsonrpc: "2.0", id: request.id, result: { content: [] } });
+});
+`,
+    "utf8"
+  );
+
+  const manager = createSessionManager(workspace, "machine-id-mcp-safe-name");
+  await manager.initMcpServers({ "voice.box": { command: process.execPath, args: [serverPath] } });
+
+  const status = manager.getMcpStatus()[0];
+  assert.equal(status?.status, "ready");
+  assert.deepEqual(status?.tools, ["mcp__voice_box__speak_text", "mcp__voice_box__speak_text_59a610ad"]);
+
+  const mcpManager = (manager as any).mcpManager;
+  const definitions = mcpManager.getMcpToolDefinitions();
+  assert.equal(definitions[0].function.name, "mcp__voice_box__speak_text");
+  assert.match(definitions[0].function.name, /^[a-zA-Z0-9_-]+$/);
+  assert.match(definitions[0].function.description, /MCP source: voice\.box: speak\.text/);
+  assert.deepEqual(await mcpManager.executeMcpTool("mcp__voice_box__speak_text", { text: "ok" }), {
+    ok: true,
+    name: "mcp__voice_box__speak_text",
+    output: "speak.text:ok",
+  });
+
+  manager.dispose();
+});
+
 test("SessionManager dispose kills live processes without timeout controls", (t) => {
   if (process.platform === "win32") {
     t.skip("process group kill assertion is non-Windows specific");