@mcp-ts/sdk 1.3.10 → 1.5.0

package/src/client/vue/use-mcp.ts

@@ -285,22 +285,33 @@ export function useMcp(options: UseMcpOptions): McpClient {
             }
 
             case 'auth_required': {
-                // Handle OAuth redirect
-                if (event.authUrl) {
-                    onLog?.('info', `OAuth required - redirecting to ${event.authUrl}`, { authUrl: event.authUrl });
-
-                    // Suppress redirects/popups for background auto-restore on page load.
-                    if (!suppressAuthRedirectSessions.value.has(event.sessionId)) {
-                        if (onRedirect) {
-                            onRedirect(event.authUrl);
-                        } else if (typeof window !== 'undefined') {
-                            window.location.href = event.authUrl;
-                        }
+                const url = (event.authUrl || '').trim();
+                if (!url) {
+                    onLog?.('error', 'OAuth required but authorization URL is missing', { sessionId: event.sessionId });
+                    const index = connections.value.findIndex((c) => c.sessionId === event.sessionId);
+                    if (index !== -1) {
+                        connections.value[index] = {
+                            ...connections.value[index],
+                            state: 'FAILED',
+                            error: 'OAuth authorization URL not available',
+                            authUrl: undefined,
+                        };
+                    }
+                    break;
+                }
+                onLog?.('info', `OAuth required - redirecting to ${url}`, { authUrl: url });
+
+                // Suppress redirects/popups for background auto-restore on page load.
+                if (!suppressAuthRedirectSessions.value.has(event.sessionId)) {
+                    if (onRedirect) {
+                        onRedirect(url);
+                    } else if (typeof window !== 'undefined') {
+                        window.location.href = url;
                     }
                 }
                 const index = connections.value.findIndex((c) => c.sessionId === event.sessionId);
                 if (index !== -1) {
-                    connections.value[index] = { ...connections.value[index], state: 'AUTHENTICATING', authUrl: event.authUrl };
+                    connections.value[index] = { ...connections.value[index], state: 'AUTHENTICATING', authUrl: url };
                 }
                 break;
             }

package/src/server/index.ts

@@ -32,6 +32,8 @@ export type {
 } from '../shared/events';
 
 export type {
+  ToolClient,
+  ToolClientProvider,
   ToolInfo,
   McpRpcRequest,
   McpRpcResponse,

package/src/server/mcp/oauth-client.ts

@@ -51,12 +51,12 @@ export type TransportType = 'sse' | 'streamable_http';
  */
 import type { ClientCapabilities } from '@modelcontextprotocol/sdk/types.js';
 
-interface McpAppClientCapabilities extends ClientCapabilities {
+interface McpAppClientCapabilities extends Omit<ClientCapabilities, 'extensions'> {
   extensions?: {
     'io.modelcontextprotocol/ui'?: {
       mimeTypes: string[];
     };
-    [key: string]: unknown;
+    [key: string]: any;
   };
 }
 
@@ -516,17 +516,40 @@ export class MCPClient {
         error instanceof SDKUnauthorizedError ||
         (error instanceof Error && error.message.toLowerCase().includes('unauthorized'))
       ) {
+        /** Set when the SDK calls redirectToAuthorization on the OAuth provider */
+        let authUrl = '';
+        if (this.oauthProvider) {
+          authUrl = (this.oauthProvider.authUrl || '').trim();
+        }
+
+        /**
+         * 401 without a usable URL means metadata/DCR failed or the server never started
+         * an interactive OAuth flow — not recoverable as "pending OAuth".
+         */
+        if (!authUrl) {
+          const detail =
+            error instanceof Error && error.message.trim().length > 0
+              ? error.message.trim()
+              : 'Unauthorized';
+          const message =
+            detail.toLowerCase() === 'unauthorized'
+              ? 'OAuth authorization URL not available'
+              : `OAuth authorization URL not available: ${detail}`;
+          this.emitError(message, 'auth');
+          this.emitStateChange('FAILED');
+          try {
+            await storage.removeSession(this.identity, this.sessionId);
+          } catch {
+            // best-effort cleanup
+          }
+          throw new Error(message);
+        }
+
         this.emitStateChange('AUTHENTICATING');
         // Save session with 10min TTL for OAuth pending state
         console.log(`[MCPClient] Saving session ${this.sessionId} with 10min TTL (OAuth pending)`);
         await this.saveSession(Math.floor(STATE_EXPIRATION_MS / 1000), false);
 
-        /** Get OAuth authorization URL if available */
-        let authUrl = '';
-        if (this.oauthProvider) {
-          authUrl = this.oauthProvider.authUrl || '';
-        }
-
         if (this.serverId) {
           this._onConnectionEvent.fire({
             type: 'auth_required',
@@ -1085,7 +1108,9 @@ export class MCPClient {
    * @returns Server name or undefined
    */
   getServerName(): string | undefined {
-    return this.serverName;
+    const info = (this.client as any)?.getServerVersion();
+    console.log('server info ->', info);
+    return info?.title ?? info?.name ?? this.serverName;
   }
 
   /**

package/src/shared/index.ts

@@ -22,6 +22,8 @@ export * from './errors';
 
 // Types
 export type {
+  ToolClient,
+  ToolClientProvider,
   ToolInfo,
   McpRpcRequest,
   McpRpcResponse,
@@ -73,3 +75,37 @@ export {
   type ToolUiConfig,
 } from './tool-utils.js';
 
+// Tool Router — Context window optimization
+export {
+  ToolRouter,
+  type ToolRouterOptions,
+  type ToolRouterStrategy,
+  type ToolRouterClientInput,
+  type ToolGroupInfo,
+} from './tool-router.js';
+
+export {
+  ToolIndex,
+  type ToolSummary,
+  type IndexedTool,
+  type ToolIndexOptions,
+  type EmbedFn,
+} from './tool-index.js';
+
+export {
+  SchemaCompressor,
+  type CompactTool,
+  type CompressionStats,
+} from './schema-compressor.js';
+
+export {
+  createSearchToolDefinition,
+  createRegexSearchToolDefinition,
+  createGetSchemaToolDefinition,
+  createExecuteToolDefinition,
+  executeMetaTool,
+  isMetaTool,
+  resolveMetaToolProxy,
+  type CallToolFn,
+} from './meta-tools.js';
+

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}%`,
+    };
+  }
+}