feat: implement tool name sanitization and enhance tool tag processing functionality

Author: yaonyan

packages/core/src/plugins/built-in/tool-name-mapping-plugin.ts

@@ -3,27 +3,35 @@ import type { ToolPlugin, TransformContext } from "../../plugin-types.ts";
 /**
  * Built-in plugin that handles tool name mapping between dot and underscore notation
  * Allows tools to be referenced with both formats (e.g., "server.tool" and "server_tool")
+ * Also sanitizes tool names to comply with API restrictions
  */
 export const createToolNameMappingPlugin = (): ToolPlugin => ({
   name: "built-in-tool-name-mapping",
   version: "1.0.0",
   enforce: "pre", // Apply early to establish mappings
   transformTool: (tool, context: TransformContext) => {
     const server = context.server;
-    const toolName = context.toolName;
+    const toolName = context.toolName; // Sanitized name (e.g., "_c_desktop-commander_start_process")
+
+    // Get original name if available (e.g., "@c/desktop-commander.start_process")
+    const originalName = (tool as any)._originalName || toolName;
 
     // Create bidirectional mapping between dot and underscore notation
-    const dotNotation = toolName.replace(/_/g, ".");
-    const underscoreNotation = toolName.replace(/\./g, "_");
+    // Based on ORIGINAL name to support both @scope/server.tool and @scope/server_tool
+    const dotNotation = originalName.replace(/_/g, ".");
+    const underscoreNotation = originalName.replace(/\./g, "_");
 
-    if (dotNotation !== toolName && server.toolNameMapping) {
+    if (dotNotation !== originalName && server.toolNameMapping) {
       server.toolNameMapping.set(dotNotation, toolName);
-      server.toolNameMapping.set(toolName, dotNotation);
     }
 
-    if (underscoreNotation !== toolName && server.toolNameMapping) {
+    if (underscoreNotation !== originalName && server.toolNameMapping) {
       server.toolNameMapping.set(underscoreNotation, toolName);
-      server.toolNameMapping.set(toolName, underscoreNotation);
+    }
+
+    // Also map the original name to sanitized name
+    if (originalName !== toolName && server.toolNameMapping) {
+      server.toolNameMapping.set(originalName, toolName);
     }
 
     return tool;

packages/core/src/utils/common/mcp.ts

@@ -8,6 +8,7 @@ import type {
 } from "../../service/tools.ts";
 import type z from "zod";
 import { smitheryToolNameCompatibale } from "./registory.ts";
+import { sanitizePropertyKey } from "./provider.ts";
 import { cwd } from "node:process";
 import process from "node:process";
 import { createHash } from "node:crypto";
@@ -179,7 +180,9 @@ export async function composeMcpDepTools(
       tools.forEach((tool) => {
         const { toolNameWithScope, toolName: internalToolName } =
           smitheryToolNameCompatibale(tool.name, name);
-        const toolId = `${serverId}_${internalToolName}`;
+        // Sanitize toolId to ensure it only contains valid characters
+        const rawToolId = `${serverId}_${internalToolName}`;
+        const toolId = sanitizePropertyKey(rawToolId);
         if (
           filterIn &&
           !filterIn({
@@ -206,7 +209,12 @@ export async function composeMcpDepTools(
             },
           );
 
-        allTools[toolId] = { ...tool, execute };
+        // Store the original toolNameWithScope for mapping purposes
+        allTools[toolId] = {
+          ...tool,
+          execute,
+          _originalName: toolNameWithScope,
+        };
       });
     } catch (error) {
       console.error(`Error creating MCP client for ${name}:`, error);

packages/core/src/utils/common/provider.ts

@@ -10,6 +10,17 @@ import { optionalObject } from "./json.ts";
  */
 export const ToolNameRegex = /^[a-zA-Z0-9_-]{1,64}$/;
 
+/**
+ * Sanitize tool name to match provider requirements
+ * Replaces any character that's not alphanumeric, underscore, or dash with underscore
+ * Truncates to 64 characters max
+ */
+export function sanitizePropertyKey(name: string): string {
+  return name
+    .replace(/[^a-zA-Z0-9_-]/g, "_") // Replace invalid characters with underscore
+    .substring(0, 64); // Truncate to max length
+}
+
 /**
  * Conditionally adds additionalProperties to schema based on provider support
  *

packages/core/src/utils/common/tool-tag-processor.ts

@@ -71,6 +71,9 @@ export function processToolTags({
       if (toolId) {
         // Replace <tool> with <action action="..."/> in the DOM
         $(toolEl).replaceWith(`<action action="${toolId}"/>`);
+      } else {
+        // Tool not found, remove the tag completely
+        $(toolEl).remove();
       }
     }
   });

packages/core/src/utils/compose-helpers.ts

@@ -9,6 +9,7 @@ import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { JSONSchema } from "../types.ts";
 import { updateRefPaths } from "./common/schema.ts";
 import { jsonSchema } from "./schema.ts";
+import { sanitizePropertyKey } from "./common/provider.ts";
 
 /**
  * Process tools with plugin transformations
@@ -123,7 +124,10 @@ export function buildDependencyGroups(
 
     const updatedProperties = updateRefPaths(baseProperties, toolName);
 
-    depGroups[toolName] = {
+    // Sanitize tool name for use as schema property key
+    const sanitizedKey = sanitizePropertyKey(toolName);
+
+    depGroups[sanitizedKey] = {
       type: "object",
       description: tool.description,
       properties: updatedProperties,

packages/core/tests/unit/tool_name_sanitization_test.ts

@@ -0,0 +1,22 @@
+/**
+ * Test tool name sanitization - core functionality
+ *
+ * Verifies that sanitizePropertyKey properly handles special characters.
+ */
+
+import { assertEquals } from "@std/assert";
+import { sanitizePropertyKey } from "../../src/utils/common/provider.ts";
+
+Deno.test("sanitizePropertyKey removes special characters", () => {
+  // Test real-world MCP tool name: @c/desktop-commander.start_process
+  assertEquals(
+    sanitizePropertyKey("@c/desktop-commander.start_process"),
+    "_c_desktop-commander_start_process",
+  );
+
+  // Verify dash is preserved
+  assertEquals(
+    sanitizePropertyKey("server-tool-name"),
+    "server-tool-name",
+  );
+});

packages/core/tests/unit/tool_tag_processor_test.ts

@@ -0,0 +1,48 @@
+/**
+ * Test tool tag processing - core functionality
+ *
+ * Verifies that processToolTags properly handles tool tags.
+ */
+
+import { assertEquals } from "@std/assert";
+import { processToolTags } from "../../src/utils/common/tool-tag-processor.ts";
+import { load } from "cheerio";
+
+Deno.test("processToolTags replaces existing tools and removes missing ones", () => {
+  const description =
+    'Use <tool name="existing"/> and <tool name="missing"/> tools';
+  const $ = load(description);
+  const tagToResults = { tool: $("tool").toArray() };
+
+  const tools = {
+    "existing": {
+      name: "existing",
+      description: "Existing tool",
+      inputSchema: { type: "object" as const },
+      execute: () => {},
+    },
+  } as any;
+
+  const result = processToolTags({
+    description,
+    tagToResults,
+    $,
+    tools,
+    toolOverrides: new Map(),
+    toolNameMapping: new Map([["existing", "existing"]]),
+  });
+
+  // Should replace existing tool
+  assertEquals(
+    result.includes('action="existing"'),
+    true,
+    "Should replace existing tool with action tag",
+  );
+
+  // Should remove missing tool tag
+  assertEquals(
+    result.includes('name="missing"'),
+    false,
+    "Should remove missing tool tag",
+  );
+});