@mcp-ts/sdk 1.5.3 → 1.6.1

package/dist/{tool-router-DsKhRmJm.d.ts → tool-router-BVaV1udm.d.mts}

@@ -1,5 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { u as ToolClientProvider, T as ToolClient } from './types-CfCoIsWI.js';
+import { u as ToolClientProvider, T as ToolClient } from './types-rIuN1CQi.mjs';
 
 /**
  * SchemaCompressor — Utilities for reducing tool schema token overhead.
@@ -80,6 +80,39 @@ interface ToolSummary {
     /** Estimated token cost of the full inputSchema */
     estimatedTokens: number;
 }
+/** Server-level summary derived from indexed tools. */
+interface ToolServerSummary {
+    /** Human-readable server name */
+    serverName: string;
+    /** Stable server identifier */
+    serverId: string;
+    /** Session the server belongs to */
+    sessionId: string;
+    /** Number of indexed tools for this server */
+    toolCount: number;
+}
+/** Optional filters for search and listing. */
+interface ToolSearchOptions {
+    /** Restrict results to this server ID. */
+    serverId?: string;
+    /** Restrict results to servers whose name or ID matches this value. */
+    serverName?: string;
+}
+/** Paginated tool listing result. */
+interface ToolListResult {
+    tools: ToolSummary[];
+    totalCount: number;
+    returnedCount: number;
+    nextCursor?: string;
+    servers: ToolServerSummary[];
+}
+interface ToolLookupOptions {
+    /**
+     * Allow namespace to match a fragment of serverName after exact
+     * sessionId/serverId matching fails.
+     */
+    allowServerNameFragment?: boolean;
+}
 /** A tool with routing metadata attached during indexing. */
 interface IndexedTool extends Tool {
     sessionId: string;
@@ -147,7 +180,7 @@ declare class ToolIndex {
      *
      *   `score = keywordWeight × keyword_score + (1 - keywordWeight) × cosine_score`
      */
-    search(query: string, topK?: number): Promise<ToolSummary[]>;
+    search(query: string, topK?: number, options?: ToolSearchOptions): Promise<ToolSummary[]>;
     /**
      * Search tools using a regex pattern.
      * Matches against name, description, and parameter metadata.
@@ -155,11 +188,19 @@ declare class ToolIndex {
     searchRegex(pattern: string, topK?: number): ToolSummary[];
     /**
      * Get tool definition(s) by name.
-     * If namespace is provided, it tries to match sessionId or serverName.
+     * If namespace is provided, exact sessionId/serverId matches take precedence.
+     * Falls back to serverName fragment matching only when explicitly allowed.
      */
-    getTool(name: string, namespace?: string): IndexedTool[];
+    getTool(name: string, namespace?: string, options?: ToolLookupOptions): IndexedTool[];
     /** All indexed tool names. */
     getToolNames(): string[];
+    /** List indexed servers with tool counts. */
+    listServers(options?: ToolSearchOptions): ToolServerSummary[];
+    /** List tools deterministically, optionally scoped to a server. */
+    listTools(options?: ToolSearchOptions & {
+        limit?: number;
+        cursor?: string;
+    }): ToolListResult;
     /** Number of indexed tools (including duplicates). */
     get size(): number;
     /** Total estimated token cost of all indexed tool schemas. */
@@ -174,6 +215,7 @@ declare class ToolIndex {
     /** Build a single searchable string from tool metadata. */
     private buildSearchableText;
     private getDocumentKey;
+    private matchesServer;
     /** Simple whitespace + camelCase + snake_case tokenizer. */
     private tokenize;
     /** Cosine similarity between two vectors. */
@@ -262,7 +304,7 @@ declare class ToolRouter {
      * This is the main method adapters should call.
      *
      * - `all`    → returns all tools (unchanged behavior)
-     * - `search` → returns only meta-tools (mcp_search_tool_bm25, mcp_get_tool_schema, mcp_execute_tool)
+     * - `search` → returns only meta-tools (mcp_search_tools, mcp_get_tool_schema, mcp_execute_tool)
      * - `groups` → returns tools from active groups only
      */
     getFilteredTools(): Promise<Tool[]>;
@@ -270,17 +312,24 @@ declare class ToolRouter {
      * Search tools by natural-language query.
      * Works regardless of strategy.
      */
-    searchTools(query: string, topK?: number): Promise<ToolSummary[]>;
+    searchTools(query: string, topK?: number, options?: ToolSearchOptions): Promise<ToolSummary[]>;
     /**
      * Search tools by regex pattern.
      * Matches against name, description, and parameter metadata.
      */
     searchToolsRegex(pattern: string, topK?: number): Promise<ToolSummary[]>;
+    /** List connected MCP servers with indexed tool counts. */
+    listServers(options?: ToolSearchOptions): Promise<ToolServerSummary[]>;
+    /** List tools deterministically, optionally scoped to a server. */
+    listTools(options?: ToolSearchOptions & {
+        limit?: number;
+        cursor?: string;
+    }): Promise<ToolListResult>;
     /**
      * Get the full tool definition by name.
      * If tool name is ambiguous, use namespace to specify the server.
      */
-    getToolSchema(toolName: string, namespace?: string): IndexedTool | undefined;
+    getToolSchema(toolName: string, namespace?: string, options?: ToolLookupOptions): IndexedTool | undefined;
     /**
      * Get compact (schema-less) summaries for all tools.
      */
@@ -325,4 +374,4 @@ declare class ToolRouter {
     private getMetaToolDefinitions;
 }
 
-export { type CompactTool as C, type EmbedFn as E, type IndexedTool as I, SchemaCompressor as S, type ToolGroupInfo as T, type CompressionStats as a, ToolIndex as b, type ToolIndexOptions as c, ToolRouter as d, type ToolRouterClientInput as e, type ToolRouterOptions as f, type ToolRouterStrategy as g, type ToolSummary as h };
+export { type CompactTool as C, type EmbedFn as E, type IndexedTool as I, SchemaCompressor as S, type ToolGroupInfo as T, type CompressionStats as a, ToolIndex as b, type ToolIndexOptions as c, type ToolListResult as d, ToolRouter as e, type ToolRouterClientInput as f, type ToolRouterOptions as g, type ToolRouterStrategy as h, type ToolSearchOptions as i, type ToolServerSummary as j, type ToolSummary as k };

package/dist/{tool-router-DK0RJblO.d.mts → tool-router-Dh2804tM.d.ts}

@@ -1,5 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { u as ToolClientProvider, T as ToolClient } from './types-CfCoIsWI.mjs';
+import { u as ToolClientProvider, T as ToolClient } from './types-rIuN1CQi.js';
 
 /**
  * SchemaCompressor — Utilities for reducing tool schema token overhead.
@@ -80,6 +80,39 @@ interface ToolSummary {
     /** Estimated token cost of the full inputSchema */
     estimatedTokens: number;
 }
+/** Server-level summary derived from indexed tools. */
+interface ToolServerSummary {
+    /** Human-readable server name */
+    serverName: string;
+    /** Stable server identifier */
+    serverId: string;
+    /** Session the server belongs to */
+    sessionId: string;
+    /** Number of indexed tools for this server */
+    toolCount: number;
+}
+/** Optional filters for search and listing. */
+interface ToolSearchOptions {
+    /** Restrict results to this server ID. */
+    serverId?: string;
+    /** Restrict results to servers whose name or ID matches this value. */
+    serverName?: string;
+}
+/** Paginated tool listing result. */
+interface ToolListResult {
+    tools: ToolSummary[];
+    totalCount: number;
+    returnedCount: number;
+    nextCursor?: string;
+    servers: ToolServerSummary[];
+}
+interface ToolLookupOptions {
+    /**
+     * Allow namespace to match a fragment of serverName after exact
+     * sessionId/serverId matching fails.
+     */
+    allowServerNameFragment?: boolean;
+}
 /** A tool with routing metadata attached during indexing. */
 interface IndexedTool extends Tool {
     sessionId: string;
@@ -147,7 +180,7 @@ declare class ToolIndex {
      *
      *   `score = keywordWeight × keyword_score + (1 - keywordWeight) × cosine_score`
      */
-    search(query: string, topK?: number): Promise<ToolSummary[]>;
+    search(query: string, topK?: number, options?: ToolSearchOptions): Promise<ToolSummary[]>;
     /**
      * Search tools using a regex pattern.
      * Matches against name, description, and parameter metadata.
@@ -155,11 +188,19 @@ declare class ToolIndex {
     searchRegex(pattern: string, topK?: number): ToolSummary[];
     /**
      * Get tool definition(s) by name.
-     * If namespace is provided, it tries to match sessionId or serverName.
+     * If namespace is provided, exact sessionId/serverId matches take precedence.
+     * Falls back to serverName fragment matching only when explicitly allowed.
      */
-    getTool(name: string, namespace?: string): IndexedTool[];
+    getTool(name: string, namespace?: string, options?: ToolLookupOptions): IndexedTool[];
     /** All indexed tool names. */
     getToolNames(): string[];
+    /** List indexed servers with tool counts. */
+    listServers(options?: ToolSearchOptions): ToolServerSummary[];
+    /** List tools deterministically, optionally scoped to a server. */
+    listTools(options?: ToolSearchOptions & {
+        limit?: number;
+        cursor?: string;
+    }): ToolListResult;
     /** Number of indexed tools (including duplicates). */
     get size(): number;
     /** Total estimated token cost of all indexed tool schemas. */
@@ -174,6 +215,7 @@ declare class ToolIndex {
     /** Build a single searchable string from tool metadata. */
     private buildSearchableText;
     private getDocumentKey;
+    private matchesServer;
     /** Simple whitespace + camelCase + snake_case tokenizer. */
     private tokenize;
     /** Cosine similarity between two vectors. */
@@ -262,7 +304,7 @@ declare class ToolRouter {
      * This is the main method adapters should call.
      *
      * - `all`    → returns all tools (unchanged behavior)
-     * - `search` → returns only meta-tools (mcp_search_tool_bm25, mcp_get_tool_schema, mcp_execute_tool)
+     * - `search` → returns only meta-tools (mcp_search_tools, mcp_get_tool_schema, mcp_execute_tool)
      * - `groups` → returns tools from active groups only
      */
     getFilteredTools(): Promise<Tool[]>;
@@ -270,17 +312,24 @@ declare class ToolRouter {
      * Search tools by natural-language query.
      * Works regardless of strategy.
      */
-    searchTools(query: string, topK?: number): Promise<ToolSummary[]>;
+    searchTools(query: string, topK?: number, options?: ToolSearchOptions): Promise<ToolSummary[]>;
     /**
      * Search tools by regex pattern.
      * Matches against name, description, and parameter metadata.
      */
     searchToolsRegex(pattern: string, topK?: number): Promise<ToolSummary[]>;
+    /** List connected MCP servers with indexed tool counts. */
+    listServers(options?: ToolSearchOptions): Promise<ToolServerSummary[]>;
+    /** List tools deterministically, optionally scoped to a server. */
+    listTools(options?: ToolSearchOptions & {
+        limit?: number;
+        cursor?: string;
+    }): Promise<ToolListResult>;
     /**
      * Get the full tool definition by name.
      * If tool name is ambiguous, use namespace to specify the server.
      */
-    getToolSchema(toolName: string, namespace?: string): IndexedTool | undefined;
+    getToolSchema(toolName: string, namespace?: string, options?: ToolLookupOptions): IndexedTool | undefined;
     /**
      * Get compact (schema-less) summaries for all tools.
      */
@@ -325,4 +374,4 @@ declare class ToolRouter {
     private getMetaToolDefinitions;
 }
 
-export { type CompactTool as C, type EmbedFn as E, type IndexedTool as I, SchemaCompressor as S, type ToolGroupInfo as T, type CompressionStats as a, ToolIndex as b, type ToolIndexOptions as c, ToolRouter as d, type ToolRouterClientInput as e, type ToolRouterOptions as f, type ToolRouterStrategy as g, type ToolSummary as h };
+export { type CompactTool as C, type EmbedFn as E, type IndexedTool as I, SchemaCompressor as S, type ToolGroupInfo as T, type CompressionStats as a, ToolIndex as b, type ToolIndexOptions as c, type ToolListResult as d, ToolRouter as e, type ToolRouterClientInput as f, type ToolRouterOptions as g, type ToolRouterStrategy as h, type ToolSearchOptions as i, type ToolServerSummary as j, type ToolSummary as k };

package/dist/{types-CfCoIsWI.d.mts → types-rIuN1CQi.d.mts}

@@ -102,6 +102,7 @@ interface ConnectParams {
     serverUrl: string;
     callbackUrl: string;
     transportType?: TransportType;
+    headers?: Record<string, string>;
 }
 interface DisconnectParams {
     sessionId: string;

package/dist/{types-CfCoIsWI.d.ts → types-rIuN1CQi.d.ts}

@@ -102,6 +102,7 @@ interface ConnectParams {
     serverUrl: string;
     callbackUrl: string;
     transportType?: TransportType;
+    headers?: Record<string, string>;
 }
 interface DisconnectParams {
     sessionId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-ts/sdk",
-  "version": "1.5.3",
+  "version": "1.6.1",
   "publishConfig": {
     "access": "public"
   },
@@ -84,6 +84,8 @@
     "test": "npx playwright test",
     "test:ui": "npx playwright test --ui",
     "test:debug": "npx playwright test --debug",
+    "benchmark:toolrouter": "npm run build && node benchmarks/toolrouter-efficiency.mjs",
+    "benchmark:toolrouter:live": "npm run build && node benchmarks/toolrouter-live.mjs",
     "supabase:push": "supabase db push",
     "supabase:reset": "supabase db reset",
     "supabase:status": "supabase status",

package/src/server/handlers/sse-handler.ts

@@ -73,6 +73,16 @@ export interface SSEHandlerOptions {
 
 const DEFAULT_HEARTBEAT_INTERVAL = 30000;
 
+function normalizeHeaders(headers?: Record<string, string>): Record<string, string> | undefined {
+  if (!headers || typeof headers !== 'object') return undefined;
+
+  const entries = Object.entries(headers)
+    .map(([key, value]) => [key.trim(), String(value).trim()] as const)
+    .filter(([key, value]) => key.length > 0 && value.length > 0);
+
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
 // ============================================
 // SSEConnectionManager Class
 // ============================================
@@ -238,6 +248,7 @@ export class SSEConnectionManager {
    */
   private async connect(params: ConnectParams): Promise<ConnectResult> {
     const { serverName, serverUrl, callbackUrl, transportType } = params;
+    const headers = normalizeHeaders(params.headers);
 
     // Normalize serverId to max 12 chars to keep tool names under 64 chars (DeepSeek/OpenAI limits)
     // Tool name format: tool_<serverId>_<toolName> - with 12 char serverId leaves 46 chars for tool name
@@ -280,6 +291,7 @@ export class SSEConnectionManager {
         serverUrl,
         callbackUrl,
         transportType,
+        headers,
         ...clientMetadata, // Spread client metadata (clientName, clientUri, logoUri, policyUri)
       });
 

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

@@ -238,9 +238,11 @@ export class MCPClient {
     }
 
     const baseUrl = new URL(this.serverUrl);
+    const hasAuthorizationHeader = Object.keys(this.headers || {})
+      .some((key) => key.toLowerCase() === 'authorization');
     const transportOptions = {
-      authProvider: this.oauthProvider!,
-      ...(this.headers && { headers: this.headers }),
+      ...(!hasAuthorizationHeader && { authProvider: this.oauthProvider! }),
+      ...(this.headers && { requestInit: { headers: this.headers } }),
       /**
        * Custom fetch implementation to handle connection timeouts.
        * Observation: SDK 1.24.0+ connections may hang indefinitely in some environments.
@@ -359,6 +361,7 @@ export class MCPClient {
         serverUrl: this.serverUrl,
         callbackUrl: this.callbackUrl,
         transportType: this.transportType || 'streamable_http',
+        headers: this.headers,
         createdAt: this.createdAt,
         active: false,
       }, Math.floor(STATE_EXPIRATION_MS / 1000)); // Short TTL until connection succeeds
@@ -388,6 +391,7 @@ export class MCPClient {
       serverUrl: this.serverUrl,
       callbackUrl: this.callbackUrl,
       transportType: (this.transportType || 'streamable_http') as TransportType,
+      headers: this.headers,
       createdAt: this.createdAt || Date.now(),
       active,
     };
@@ -1126,9 +1130,10 @@ export class MCPClient {
    * @returns Server name or undefined
    */
   getServerName(): string | undefined {
-    const info = (this.client as any)?.getServerVersion();
-    console.log('server info ->', info);
-    return info?.title ?? info?.name ?? this.serverName;
+    // Temporarily avoid deriving serverName from serverVersion metadata.
+    // const info = (this.client as any)?.getServerVersion();
+    // return info?.title ?? info?.name ?? this.serverName;
+    return this.serverName;
   }
 
   /**
@@ -1228,4 +1233,3 @@ export class MCPClient {
   }
 
 }
-

package/src/shared/index.ts

@@ -87,6 +87,9 @@ export {
 export {
   ToolIndex,
   type ToolSummary,
+  type ToolServerSummary,
+  type ToolSearchOptions,
+  type ToolListResult,
   type IndexedTool,
   type ToolIndexOptions,
   type EmbedFn,
@@ -100,6 +103,7 @@ export {
 
 export {
   createSearchToolDefinition,
+  createListServersToolDefinition,
   createRegexSearchToolDefinition,
   createGetSchemaToolDefinition,
   createExecuteToolDefinition,