@mcp-ts/sdk 1.5.1 → 1.5.3

package/src/shared/meta-tools.ts

@@ -17,6 +17,7 @@
 
 import type { Tool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { ToolRouter } from './tool-router.js';
+import type { IndexedTool } from './tool-index.js';
 
 // ---------------------------------------------------------------------------
 // Tool Definitions
@@ -33,16 +34,18 @@ 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".',
+      'Search the catalog of available tools. Returns tool names, descriptions, and server info. ' +
+      'Use this FIRST to find relevant tools before calling them.\n\n' +
+      'Query forms:\n' +
+      '- "select:Read,Edit,Grep" — fetch these exact tools by name\n' +
+      '- "notebook jupyter" — keyword search, up to limit best matches\n' +
+      '- "+slack send" — require "slack" in the name, rank by remaining terms',
     inputSchema: {
       type: 'object' as const,
       properties: {
         query: {
           type: 'string',
-          description: 'Natural language description of the capability you need.',
+          description: 'Query to find tools. Use "select:<tool_name>" for direct selection, or keywords to search. Prefix keywords with + to require them.',
         },
         limit: {
           type: 'number',
@@ -97,7 +100,8 @@ export function createGetSchemaToolDefinition(): Tool {
     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.',
+      'needed to call a tool correctly. ' +
+      'Do NOT call the discovered tool directly; after reading the schema, call mcp_execute_tool.',
     inputSchema: {
       type: 'object' as const,
       properties: {
@@ -105,10 +109,10 @@ export function createGetSchemaToolDefinition(): Tool {
           type: 'string',
           description: 'The exact tool name returned by mcp_search_tool_bm25.',
         },
-        serverName: {
+        serverId: {
           type: 'string',
           description:
-            'Optional: The server name provided in mcp_search_tool_bm25. Required if multiple tools have the same name.',
+            'Optional: The server ID provided in mcp_search_tool_bm25. Required if multiple tools have the same name.',
         },
       },
       required: ['toolName'],
@@ -141,10 +145,10 @@ export function createExecuteToolDefinition(): Tool {
           type: 'string',
           description: 'The exact tool name from mcp_search_tool_bm25 results.',
         },
-        serverName: {
+        serverId: {
           type: 'string',
           description:
-            'Optional: The server name provided in mcp_search_tool_bm25. Required if multiple tools have the same name.',
+            'Optional: The server ID provided in mcp_search_tool_bm25. Required if multiple tools have the same name.',
         },
         args: {
           type: 'object',
@@ -187,7 +191,7 @@ export async function executeMetaTool(
   router: ToolRouter,
   callToolFn?: CallToolFn
 ): Promise<CallToolResult | null> {
-  const resolveToolSchema = (name: string, namespace?: string): { tool?: Tool; error?: CallToolResult } => {
+  const resolveToolSchema = (name: string, namespace?: string): { tool?: IndexedTool; error?: CallToolResult } => {
     try {
       return { tool: router.getToolSchema(name, namespace) };
     } catch (err) {
@@ -206,6 +210,53 @@ export async function executeMetaTool(
       const query = String(args.query ?? '');
       const limit = Math.min(Number(args.limit) || 5, 20);
 
+      // Fast path: Check for select: prefix
+      const selectMatch = query.match(/^select:(.+)$/i);
+      if (selectMatch) {
+        const requested = selectMatch[1]!
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean);
+
+        const found: any[] = [];
+        const errors: string[] = [];
+        
+        for (const requestedToolName of requested) {
+          const { tool, error } = resolveToolSchema(requestedToolName);
+          if (error) {
+            const errorMsg = error.content[0]?.type === 'text' ? error.content[0].text : 'Unknown error';
+            errors.push(`- **${requestedToolName}**: ${errorMsg}`);
+          } else if (tool) {
+            found.push(tool);
+          } else {
+            errors.push(`- **${requestedToolName}**: Tool not found. Try searching with mcp_search_tool_bm25.`);
+          }
+        }
+
+        const lines: string[] = [];
+
+        if (found.length > 0) {
+          lines.push(...found.map((t, i) =>
+            `${i + 1}. **${t.name}** (server: ${t.serverName}, serverId: ${t.serverId})\n   ${t.description}`
+          ));
+        }
+        
+        if (errors.length > 0) {
+          if (lines.length > 0) lines.push(""); // Add empty line spacing
+          lines.push("Errors resolving some tools:");
+          lines.push(...errors);
+        }
+
+        const text = lines.length > 0 
+          ? lines.join('\n') 
+          : `No tools found matching select query: ${requested.join(', ')}`;
+
+        return {
+          content: [{ type: 'text', text }],
+          isError: found.length === 0,
+        };
+      }
+
       const results = await router.searchTools(query, limit);
 
       const text = results.length === 0
@@ -213,7 +264,7 @@ export async function executeMetaTool(
         : results
             .map(
               (t, i) =>
-                `${i + 1}. **${t.name}** (server: ${t.serverName})\n` +
+                `${i + 1}. **${t.name}** (server: ${t.serverName}, serverId: ${t.serverId})\n` +
                 `   ${t.description}\n` +
                 `   Estimated tokens: ${t.estimatedTokens}`
             )
@@ -236,7 +287,7 @@ export async function executeMetaTool(
         : results
             .map(
               (t, i) =>
-                `${i + 1}. **${t.name}** (server: ${t.serverName})\n` +
+                `${i + 1}. **${t.name}** (server: ${t.serverName}, serverId: ${t.serverId})\n` +
                 `   ${t.description}\n` +
                 `   Estimated tokens: ${t.estimatedTokens}`
             )
@@ -250,7 +301,7 @@ export async function executeMetaTool(
 
     case 'mcp_get_tool_schema': {
       const name = String(args.toolName ?? '');
-      const namespace = String(args.serverName ?? '') || undefined;
+      const namespace = String(args.serverId ?? '') || undefined;
       const { tool, error } = resolveToolSchema(name, namespace);
 
       if (error) {
@@ -273,6 +324,13 @@ export async function executeMetaTool(
         name: tool.name,
         description: tool.description,
         inputSchema: tool.inputSchema,
+        executionInstructions: {
+          nextTool: 'mcp_execute_tool',
+          toolName: tool.name,
+          serverId: tool.serverId,
+          note:
+            'Do not call this discovered tool directly unless it was explicitly registered as a runtime tool. Execute it via mcp_execute_tool and pass these parameters inside args.',
+        },
       };
 
       return {
@@ -283,7 +341,7 @@ export async function executeMetaTool(
 
     case 'mcp_execute_tool': {
       const targetToolName = String(args.toolName ?? '');
-      const namespace = String(args.serverName ?? '') || undefined;
+      const namespace = String(args.serverId ?? '') || undefined;
       const toolArgs = (args.args as Record<string, unknown>) ?? {};
 
       if (!targetToolName) {

package/src/shared/tool-index.ts

@@ -24,6 +24,8 @@ export interface ToolSummary {
   description: string;
   /** Server that owns this tool */
   serverName: string;
+  /** Unique ID of the server */
+  serverId: string;
   /** Session the tool belongs to */
   sessionId: string;
   /** Estimated token cost of the full inputSchema */
@@ -33,6 +35,7 @@ export interface ToolSummary {
 /** A tool with routing metadata attached during indexing. */
 export interface IndexedTool extends Tool {
   sessionId: string;
+  serverId: string;
   serverName: string;
 }
 
@@ -177,6 +180,7 @@ export class ToolIndex {
         name: tool.name,
         description: tool.description ?? '',
         serverName: tool.serverName,
+        serverId: tool.serverId,
         sessionId: tool.sessionId,
         estimatedTokens,
       });
@@ -258,8 +262,55 @@ export class ToolIndex {
   async search(query: string, topK = 5): Promise<ToolSummary[]> {
     if (this.tools.size === 0) return [];
 
-    const queryLower = query.toLowerCase();
-    const queryTokens = this.tokenize(queryLower);
+    const queryLower = query.toLowerCase().trim();
+
+    // Fast path: Exact tool name match (supports duplicate names across servers)
+    const exactMatches = [...this.toolSummaries.values()].filter(
+      (summary) => summary.name.toLowerCase() === queryLower
+    );
+    if (exactMatches.length > 0) {
+      return exactMatches.slice(0, topK);
+    }
+
+    // Fast path: MCP prefix match (e.g. "mcp__github")
+    if (queryLower.startsWith('mcp__') && queryLower.length > 5) {
+      const prefixMatches = [...this.toolSummaries.values()]
+        .filter((t) => t.name.toLowerCase().startsWith(queryLower))
+        .slice(0, topK);
+      if (prefixMatches.length > 0) return prefixMatches;
+    }
+
+    const queryTermsRaw = queryLower.split(/\s+/).filter((t) => t.length > 0);
+    const requiredTerms: string[] = [];
+    const optionalTerms: string[] = [];
+
+    for (const term of queryTermsRaw) {
+      if (term.startsWith('+') && term.length > 1) {
+        requiredTerms.push(term.slice(1));
+      } else {
+        optionalTerms.push(term);
+      }
+    }
+
+    const allScoringTerms =
+      requiredTerms.length > 0 ? [...requiredTerms, ...optionalTerms] : queryTermsRaw;
+    const normalizedQueryText = allScoringTerms.join(' ').trim();
+    const queryTokens = this.tokenize(allScoringTerms.join(' '));
+
+    // Pre-filter: only keep documents that contain ALL required terms
+    const candidateKeys = new Set<string>();
+    for (const docKey of this.toolSummaries.keys()) {
+      if (requiredTerms.length > 0) {
+        const text = this.searchTexts.get(docKey) || '';
+        const summary = this.toolSummaries.get(docKey)!;
+        const nameLower = summary.name.toLowerCase();
+        const matchesAll = requiredTerms.every(
+          (term) => text.includes(term) || nameLower.includes(term)
+        );
+        if (!matchesAll) continue;
+      }
+      candidateKeys.add(docKey);
+    }
 
     // 1. Keyword scores (BM25)
     const keywordScores = new Map<string, number>();
@@ -267,7 +318,12 @@ export class ToolIndex {
     const k1 = 1.2;
     const b = 0.75;
 
-    for (const [docKey, docTf] of this.tfVectors) {
+    for (const docKey of candidateKeys) {
+      const docTf = this.tfVectors.get(docKey);
+      if (!docTf) continue;
+      
+      const summary = this.toolSummaries.get(docKey)!;
+
       let score = 0;
       const docLen = this.docLengths.get(docKey) ?? 0;
 
@@ -276,16 +332,30 @@ export class ToolIndex {
         if (tfVal === 0) continue;
 
         const idf = this.idf.get(tok) ?? 0;
-
         // BM25 formula:
         // score = idf * (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * (docLen / avgDocLength)))
         const numerator = tfVal * (k1 + 1);
         const denominator = tfVal + k1 * (1 - b + b * (docLen / this.avgDocLength));
-        
+
         score += idf * (numerator / denominator);
       }
 
-      keywordScores.set(docKey, score);
+      // Name heuristics: give massive boosts for exact server/tool name matches
+      const serverLower = (summary.serverName || summary.serverId || '').toLowerCase();
+      const toolLower = summary.name.toLowerCase();
+
+      for (const term of allScoringTerms) {
+        if (serverLower.includes(term)) {
+          score += 10;
+        }
+        if (toolLower.includes(term)) {
+          score += 5;
+        }
+      }
+
+      if (score > 0) {
+        keywordScores.set(docKey, score);
+      }
     }
 
     // 2. Embedding scores (optional)
@@ -293,11 +363,14 @@ export class ToolIndex {
 
     if (this.options.embedFn && this.embeddings.size > 0) {
       try {
-        const [queryEmbedding] = await this.options.embedFn([queryLower]);
+        const [queryEmbedding] = await this.options.embedFn([normalizedQueryText]);
         if (queryEmbedding) {
           embeddingScores = new Map();
-          for (const [docKey, vec] of this.embeddings) {
-            embeddingScores.set(docKey, this.cosineSimilarity(queryEmbedding, vec));
+          for (const docKey of candidateKeys) {
+            const vec = this.embeddings.get(docKey);
+            if (vec) {
+              embeddingScores.set(docKey, this.cosineSimilarity(queryEmbedding, vec));
+            }
           }
         }
       } catch {
@@ -309,7 +382,7 @@ export class ToolIndex {
     const kw = this.options.keywordWeight;
     const finalScores: Array<{ docKey: string; score: number }> = [];
 
-    for (const docKey of this.toolSummaries.keys()) {
+    for (const docKey of candidateKeys) {
       const kwScore = keywordScores.get(docKey) ?? 0;
       const embScore = embeddingScores?.get(docKey) ?? 0;
 
@@ -389,7 +462,7 @@ export class ToolIndex {
     const list = this.tools.get(name) ?? [];
     if (!namespace) return list;
 
-    return list.filter((t) => t.sessionId === namespace || t.serverName === namespace);
+    return list.filter((t) => t.sessionId === namespace || t.serverId === namespace);
   }
 
   /** All indexed tool names. */
@@ -463,7 +536,7 @@ export class ToolIndex {
   }
 
   private getDocumentKey(tool: IndexedTool): string {
-    return `${tool.sessionId}::${tool.serverName}::${tool.name}`;
+    return `${tool.sessionId}::${tool.serverId}::${tool.name}`;
   }
 
   /** Simple whitespace + camelCase + snake_case tokenizer. */

package/src/shared/tool-router.ts

@@ -219,10 +219,10 @@ export class ToolRouter {
     if (matches.length === 0) return undefined;
 
     if (matches.length > 1) {
-      const servers = matches.map((m) => m.serverName).join(', ');
+      const servers = matches.map((m) => m.serverId).join(', ');
       throw new Error(
         `Tool "${toolName}" is provided by multiple servers: [${servers}]. ` +
-          `Please specify the desired "serverName" as a namespace.`
+          `Please specify the desired "serverId" as a namespace.`
       );
     }
 
@@ -372,6 +372,7 @@ export class ToolRouter {
         for (const tool of tools) {
           result.push({
             ...tool,
+            serverId,
             serverName: serverName,
             sessionId,
           });
@@ -409,20 +410,20 @@ export class ToolRouter {
         });
       }
     } else {
-      // Auto-group by server name
+      // Auto-group by server ID
       const serverTools = new Map<string, string[]>();
       for (const tool of this.allTools) {
-        const group = tool.serverName;
+        const group = tool.serverId;
         if (!serverTools.has(group)) {
           serverTools.set(group, []);
         }
         serverTools.get(group)!.push(tool.name);
       }
 
-      for (const [serverName, tools] of serverTools) {
-        this.groupsMap.set(serverName, {
+      for (const [serverId, tools] of serverTools) {
+        this.groupsMap.set(serverId, {
           tools,
-          active: this.activeGroups.size === 0 || this.activeGroups.has(serverName),
+          active: this.activeGroups.size === 0 || this.activeGroups.has(serverId),
         });
       }
     }