@mcp-ts/sdk 1.4.0 → 1.5.0

package/src/shared/meta-tools.ts

@@ -0,0 +1,387 @@
+/**
+ * Meta-tools — Injectable tool definitions that let the LLM discover and
+ * load MCP tools on-demand, following Anthropic's Tool Search pattern.
+ *
+ * Instead of injecting 50+ full tool schemas into the context window, you
+ * inject just these 4 meta-tools. The LLM calls them to find and load
+ * only the tools it actually needs.
+ *
+ * Meta-tools:
+ *   • `mcp_search_tool_bm25`  — BM25 natural language search
+ *   • `mcp_search_tool_regex` — Regex pattern search
+ *   • `mcp_get_tool_schema`   — Get full inputSchema for a discovered tool
+ *   • `mcp_execute_tool`      — Execute a discovered tool
+ *
+ * @packageDocumentation
+ */
+
+import type { Tool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolRouter } from './tool-router.js';
+
+// ---------------------------------------------------------------------------
+// Tool Definitions
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates the `mcp_search_tool_bm25` tool definition.
+ *
+ * This tool lets the LLM search the full catalog of available MCP tools
+ * using a BM25 natural-language query. Returns tool names and descriptions
+ * without the full inputSchema to save context space.
+ */
+export function createSearchToolDefinition(): Tool {
+  return {
+    name: 'mcp_search_tool_bm25',
+    description:
+      'Search the catalog of available tools using BM25 natural language ranking. ' +
+      'Returns tool names, descriptions, and server info. ' +
+      'Use this FIRST to find relevant tools before calling them. ' +
+      'Example queries: "database query", "send email", "github pull request".',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Natural language description of the capability you need.',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results to return (default: 5, max: 20).',
+        },
+      },
+      required: ['query'],
+    },
+  };
+}
+
+/**
+ * Creates the `mcp_search_tool_regex` tool definition.
+ * 
+ * Matches Anthropic's tool_search_tool_regex exactly (takes a 'query' regex pattern).
+ */
+export function createRegexSearchToolDefinition(): Tool {
+  return {
+    name: 'mcp_search_tool_regex',
+    description:
+      'Search the catalog of available tools using a Python-style regex pattern. ' +
+      'Matches against tool names, descriptions, and parameter descriptions. ' +
+      'Example patterns: "^github_", "weather", "(?i)slack".',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Regex pattern to search for (e.g., "^get_.*_data", "database").',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results to return (default: 5, max: 20).',
+        },
+      },
+      required: ['query'],
+    },
+  };
+}
+
+/**
+ * Creates the `mcp_get_tool_schema` tool definition.
+ *
+ * After discovering tools via `mcp_search_tool_bm25` or
+ * `mcp_search_tool_regex`, the LLM calls this to load the full
+ * inputSchema for a specific tool so it can construct the correct
+ * arguments.
+ */
+export function createGetSchemaToolDefinition(): Tool {
+  return {
+    name: 'mcp_get_tool_schema',
+    description:
+      'Get the full input schema (parameters) for a specific tool. ' +
+      'Call this after mcp_search_tool_bm25 to get the parameter details ' +
+      'needed to call a tool correctly.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        toolName: {
+          type: 'string',
+          description: 'The exact tool name returned by mcp_search_tool_bm25.',
+        },
+        serverName: {
+          type: 'string',
+          description:
+            'Optional: The server name provided in mcp_search_tool_bm25. Required if multiple tools have the same name.',
+        },
+      },
+      required: ['toolName'],
+    },
+  };
+}
+
+/**
+ * Creates the `mcp_execute_tool` tool definition.
+ *
+ * This is the execution meta-tool — the LLM calls this to execute any
+ * tool discovered via `mcp_search_tool_bm25` or `mcp_search_tool_regex`.
+ * The LLM should first call `mcp_get_tool_schema` to know the correct
+ * arguments.
+ *
+ * Instead of registering every real tool with the framework, we proxy
+ * all execution through a single meta-tool.
+ */
+export function createExecuteToolDefinition(): Tool {
+  return {
+    name: 'mcp_execute_tool',
+    description:
+      'Execute a tool that was discovered via mcp_search_tool_bm25. ' +
+      'You MUST call mcp_get_tool_schema first to know the correct parameters. ' +
+      'Pass the exact tool name and its arguments.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        toolName: {
+          type: 'string',
+          description: 'The exact tool name from mcp_search_tool_bm25 results.',
+        },
+        serverName: {
+          type: 'string',
+          description:
+            'Optional: The server name provided in mcp_search_tool_bm25. Required if multiple tools have the same name.',
+        },
+        args: {
+          type: 'object',
+          description:
+            "Arguments matching the tool's inputSchema. Omit or pass {} if the tool takes no parameters.",
+          additionalProperties: true,
+        },
+      },
+      required: ['toolName'],
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Meta-tool Executors
+// ---------------------------------------------------------------------------
+
+/**
+ * Callback for executing a real MCP tool via the correct client.
+ * Provided by adapters that wire up client routing.
+ */
+export type CallToolFn = (
+  toolName: string,
+  args: Record<string, unknown>,
+  namespace?: string
+) => Promise<any>;
+
+/**
+ * Execute a meta-tool call and return the result in MCP CallToolResult format.
+ *
+ * @param toolName - One of the meta-tool names (mcp_search_tool_bm25, mcp_search_tool_regex, etc.)
+ * @param args - The arguments from the LLM's tool call
+ * @param router - The ToolRouter to query
+ * @param callToolFn - Optional callback for executing real tools (required for mcp_execute_tool)
+ * @returns MCP-compatible CallToolResult, or null if this isn't a meta-tool
+ */
+export async function executeMetaTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  router: ToolRouter,
+  callToolFn?: CallToolFn
+): Promise<CallToolResult | null> {
+  const resolveToolSchema = (name: string, namespace?: string): { tool?: Tool; error?: CallToolResult } => {
+    try {
+      return { tool: router.getToolSchema(name, namespace) };
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      return {
+        error: {
+          content: [{ type: 'text', text: errorMessage }],
+          isError: true,
+        },
+      };
+    }
+  };
+
+  switch (toolName) {
+    case 'mcp_search_tool_bm25': {
+      const query = String(args.query ?? '');
+      const limit = Math.min(Number(args.limit) || 5, 20);
+
+      const results = await router.searchTools(query, limit);
+
+      const text = results.length === 0
+        ? 'No tools found matching your query. Try different keywords.'
+        : results
+            .map(
+              (t, i) =>
+                `${i + 1}. **${t.name}** (server: ${t.serverName})\n` +
+                `   ${t.description}\n` +
+                `   Estimated tokens: ${t.estimatedTokens}`
+            )
+            .join('\n');
+
+      return {
+        content: [{ type: 'text', text }],
+        isError: false,
+      };
+    }
+
+    case 'mcp_search_tool_regex': {
+      const pattern = String(args.query ?? '');
+      const limit = Math.min(Number(args.limit) || 5, 20);
+
+      const results = await router.searchToolsRegex(pattern, limit);
+
+      const text = results.length === 0
+        ? 'No tools matched your regex pattern. Try a broader pattern.'
+        : results
+            .map(
+              (t, i) =>
+                `${i + 1}. **${t.name}** (server: ${t.serverName})\n` +
+                `   ${t.description}\n` +
+                `   Estimated tokens: ${t.estimatedTokens}`
+            )
+            .join('\n');
+
+      return {
+        content: [{ type: 'text', text }],
+        isError: false,
+      };
+    }
+
+    case 'mcp_get_tool_schema': {
+      const name = String(args.toolName ?? '');
+      const namespace = String(args.serverName ?? '') || undefined;
+      const { tool, error } = resolveToolSchema(name, namespace);
+
+      if (error) {
+        return error;
+      }
+
+      if (!tool) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Tool "${name}" not found. Use mcp_search_tool_bm25 to find available tools first.`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const schema = {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      };
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(schema, null, 2) }],
+        isError: false,
+      };
+    }
+
+    case 'mcp_execute_tool': {
+      const targetToolName = String(args.toolName ?? '');
+      const namespace = String(args.serverName ?? '') || undefined;
+      const toolArgs = (args.args as Record<string, unknown>) ?? {};
+
+      if (!targetToolName) {
+        return {
+          content: [{ type: 'text', text: 'Missing required parameter "toolName". Specify which tool to execute.' }],
+          isError: true,
+        };
+      }
+
+      // Verify the tool exists in our index
+      const { tool, error } = resolveToolSchema(targetToolName, namespace);
+      if (error) {
+        return error;
+      }
+
+      if (!tool) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Tool "${targetToolName}" not found. Use mcp_search_tool_bm25 to discover available tools first.`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      if (!callToolFn) {
+        return {
+          content: [{ type: 'text', text: 'Tool execution is not available. No callToolFn was configured.' }],
+          isError: true,
+        };
+      }
+
+      try {
+        const result = await callToolFn(targetToolName, toolArgs, namespace);
+
+        // Normalize result to text
+        if (result && typeof result === 'object' && 'content' in result) {
+          // Already MCP CallToolResult format
+          return result as CallToolResult;
+        }
+
+        const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+        return {
+          content: [{ type: 'text', text }],
+          isError: false,
+        };
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: 'text', text: `Tool execution failed: ${errorMessage}` }],
+          isError: true,
+        };
+      }
+    }
+
+    default:
+      return null;
+  }
+}
+
+/** Check if a tool name is one of the meta-tools. */
+export function isMetaTool(toolName: string): boolean {
+  return (
+    toolName === 'mcp_search_tool_bm25' ||
+    toolName === 'mcp_search_tool_regex' ||
+    toolName === 'mcp_get_tool_schema' ||
+    toolName === 'mcp_execute_tool'
+  );
+}
+
+/**
+ * Unwraps a meta-tool proxy call (like mcp_execute_tool) to find the real target tool name and arguments.
+ * Also automatically strips routing prefixes like tool_{serverId}_.
+ * 
+ * Useful for frontend components that need to determine the actual tool being executed by an AI agent.
+ */
+export function resolveMetaToolProxy(
+  toolName: string,
+  args: Record<string, unknown> | null | undefined
+): { toolName: string; args: Record<string, unknown> } {
+  // Unwrap mcp_execute_tool proxy arguments
+  if (toolName === 'mcp_execute_tool') {
+    const innerName = args?.toolName;
+    const innerArgs = args?.args;
+    return {
+      toolName: typeof innerName === 'string' && innerName ? innerName : toolName,
+      args: innerArgs && typeof innerArgs === 'object' && !Array.isArray(innerArgs)
+        ? (innerArgs as Record<string, unknown>)
+        : {},
+    };
+  }
+
+  // Strip tool_<serverId>_ prefix used by AIAdapter
+  const match = toolName.match(/(?:tool_[^_]+_)?(.+)$/);
+  const resolvedName = match?.[1] ?? toolName;
+
+  return { toolName: resolvedName, args: args ?? {} };
+}
+

package/src/shared/schema-compressor.ts

@@ -0,0 +1,124 @@
+/**
+ * SchemaCompressor — Utilities for reducing tool schema token overhead.
+ *
+ * Provides compact representations of tools (name + description only,
+ * no inputSchema) and token savings estimation.
+ *
+ * @packageDocumentation
+ */
+
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { ToolIndex } from './tool-index.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A minimal tool representation containing only what an LLM needs to
+ * *decide whether* to use a tool.  The full `inputSchema` is deferred.
+ */
+export interface CompactTool {
+  name: string;
+  description?: string;
+  /**
+   * Human-readable hint about the expected parameters.
+   * e.g. "(location: string, unit?: 'celsius' | 'fahrenheit')"
+   */
+  parameterHint?: string;
+}
+
+export interface CompressionStats {
+  /** Estimated tokens for the *full* tool list. */
+  fullTokens: number;
+  /** Estimated tokens for the *compact* tool list. */
+  compactTokens: number;
+  /** Absolute token savings. */
+  savedTokens: number;
+  /** Percentage savings as a human-readable string, e.g. "82.3%". */
+  savingsPercent: string;
+}
+
+// ---------------------------------------------------------------------------
+// SchemaCompressor
+// ---------------------------------------------------------------------------
+
+export class SchemaCompressor {
+  /**
+   * Convert a full MCP Tool definition to a compact summary.
+   *
+   * The compact form omits `inputSchema` entirely and optionally generates
+   * a short `parameterHint` from the schema's top-level properties.
+   */
+  static toCompact(tool: Tool): CompactTool {
+    const compact: CompactTool = {
+      name: tool.name,
+      description: tool.description,
+    };
+
+    // Build parameter hint from schema
+    if (tool.inputSchema && typeof tool.inputSchema === 'object') {
+      const schema = tool.inputSchema as {
+        properties?: Record<string, { type?: string; enum?: unknown[] }>;
+        required?: string[];
+      };
+
+      if (schema.properties) {
+        const required = new Set(schema.required ?? []);
+        const parts: string[] = [];
+
+        for (const [key, val] of Object.entries(schema.properties)) {
+          const type = val?.type ?? 'any';
+          const enumSuffix =
+            val?.enum && Array.isArray(val.enum)
+              ? `: ${val.enum.map((e) => `'${e}'`).join(' | ')}`
+              : `: ${type}`;
+
+          parts.push(required.has(key) ? `${key}${enumSuffix}` : `${key}?${enumSuffix}`);
+        }
+
+        if (parts.length > 0) {
+          compact.parameterHint = `(${parts.join(', ')})`;
+        }
+      }
+    }
+
+    return compact;
+  }
+
+  /**
+   * Convert an array of tools to compact form, optionally limiting the count.
+   */
+  static compactAll(tools: Tool[], options?: { maxTools?: number }): CompactTool[] {
+    const limited = options?.maxTools ? tools.slice(0, options.maxTools) : tools;
+    return limited.map((t) => SchemaCompressor.toCompact(t));
+  }
+
+  /**
+   * Estimate token savings from using compact vs full tool schemas.
+   */
+  static estimateSavings(tools: Tool[]): CompressionStats {
+    let fullTokens = 0;
+    let compactTokens = 0;
+
+    for (const tool of tools) {
+      fullTokens += ToolIndex.estimateTokens(tool);
+
+      // Compact form: name + description + parameterHint
+      const compact = SchemaCompressor.toCompact(tool);
+      const text = [compact.name, compact.description ?? '', compact.parameterHint ?? ''].join(' ');
+      // Simple estimation for compact: ~4 chars per token for plain text
+      compactTokens += Math.ceil(text.length / 4);
+    }
+
+    const saved = fullTokens - compactTokens;
+    const pct = fullTokens > 0 ? ((saved / fullTokens) * 100).toFixed(1) : '0.0';
+
+    return {
+      fullTokens,
+      compactTokens,
+      savedTokens: saved,
+      savingsPercent: `${pct}%`,
+    };
+  }
+}