@mcp-ts/sdk 1.5.2 → 1.6.0

package/dist/shared/index.mjs

@@ -338,17 +338,17 @@ var ToolIndex = class _ToolIndex {
    *
    *   `score = keywordWeight × keyword_score + (1 - keywordWeight) × cosine_score`
    */
-  async search(query, topK = 5) {
+  async search(query, topK = 5, options = {}) {
     if (this.tools.size === 0) return [];
     const queryLower = query.toLowerCase().trim();
     const exactMatches = [...this.toolSummaries.values()].filter(
-      (summary) => summary.name.toLowerCase() === queryLower
+      (summary) => summary.name.toLowerCase() === queryLower && this.matchesServer(summary, options)
     );
     if (exactMatches.length > 0) {
       return exactMatches.slice(0, topK);
     }
     if (queryLower.startsWith("mcp__") && queryLower.length > 5) {
-      const prefixMatches = [...this.toolSummaries.values()].filter((t) => t.name.toLowerCase().startsWith(queryLower)).slice(0, topK);
+      const prefixMatches = [...this.toolSummaries.values()].filter((t) => t.name.toLowerCase().startsWith(queryLower) && this.matchesServer(t, options)).slice(0, topK);
       if (prefixMatches.length > 0) return prefixMatches;
     }
     const queryTermsRaw = queryLower.split(/\s+/).filter((t) => t.length > 0);
@@ -366,9 +366,10 @@ var ToolIndex = class _ToolIndex {
     const queryTokens = this.tokenize(allScoringTerms.join(" "));
     const candidateKeys = /* @__PURE__ */ new Set();
     for (const docKey of this.toolSummaries.keys()) {
+      const summary = this.toolSummaries.get(docKey);
+      if (!this.matchesServer(summary, options)) continue;
       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)
@@ -479,17 +480,66 @@ var ToolIndex = class _ToolIndex {
   // -----------------------------------------------------------------------
   /**
    * 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, namespace) {
+  getTool(name, namespace, options = {}) {
     const list = this.tools.get(name) ?? [];
     if (!namespace) return list;
-    return list.filter((t) => t.sessionId === namespace || t.serverId === namespace);
+    const exactMatches = list.filter(
+      (t) => t.sessionId === namespace || t.serverId === namespace
+    );
+    if (exactMatches.length > 0) return exactMatches;
+    if (!options.allowServerNameFragment) return [];
+    const namespaceLower = namespace.toLowerCase();
+    return list.filter((t) => t.serverName.toLowerCase().includes(namespaceLower));
   }
   /** All indexed tool names. */
   getToolNames() {
     return [...this.tools.keys()];
   }
+  /** List indexed servers with tool counts. */
+  listServers(options = {}) {
+    const servers = /* @__PURE__ */ new Map();
+    for (const summary of this.toolSummaries.values()) {
+      if (!this.matchesServer(summary, options)) continue;
+      const key = `${summary.sessionId}::${summary.serverId}`;
+      const existing = servers.get(key);
+      if (existing) {
+        existing.toolCount += 1;
+      } else {
+        servers.set(key, {
+          serverName: summary.serverName,
+          serverId: summary.serverId,
+          sessionId: summary.sessionId,
+          toolCount: 1
+        });
+      }
+    }
+    return [...servers.values()].sort((a, b) => {
+      const byName = a.serverName.localeCompare(b.serverName);
+      return byName !== 0 ? byName : a.serverId.localeCompare(b.serverId);
+    });
+  }
+  /** List tools deterministically, optionally scoped to a server. */
+  listTools(options = {}) {
+    const offset = Math.max(Number(options.cursor) || 0, 0);
+    const limit = Math.max(Number(options.limit) || 20, 1);
+    const tools = [...this.toolSummaries.values()].filter((summary) => this.matchesServer(summary, options)).sort((a, b) => {
+      const byServer = a.serverName.localeCompare(b.serverName);
+      if (byServer !== 0) return byServer;
+      return a.name.localeCompare(b.name);
+    });
+    const page = tools.slice(offset, offset + limit);
+    const nextOffset = offset + page.length;
+    return {
+      tools: page,
+      totalCount: tools.length,
+      returnedCount: page.length,
+      nextCursor: nextOffset < tools.length ? String(nextOffset) : void 0,
+      servers: this.listServers(options)
+    };
+  }
   /** Number of indexed tools (including duplicates). */
   get size() {
     let count = 0;
@@ -546,6 +596,20 @@ var ToolIndex = class _ToolIndex {
   getDocumentKey(tool) {
     return `${tool.sessionId}::${tool.serverId}::${tool.name}`;
   }
+  matchesServer(summary, options) {
+    if (options.serverId && summary.serverId !== options.serverId) {
+      return false;
+    }
+    if (options.serverName) {
+      const serverNameQuery = options.serverName.toLowerCase();
+      const serverName = summary.serverName.toLowerCase();
+      const serverId = summary.serverId.toLowerCase();
+      if (!serverName.includes(serverNameQuery) && !serverId.includes(serverNameQuery)) {
+        return false;
+      }
+    }
+    return true;
+  }
   /** Simple whitespace + camelCase + snake_case tokenizer. */
   tokenize(text) {
     return text.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_-]/g, " ").replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter((t) => t.length > 1);
@@ -629,7 +693,7 @@ var SchemaCompressor = class _SchemaCompressor {
 // src/shared/meta-tools.ts
 function createSearchToolDefinition() {
   return {
-    name: "mcp_search_tool_bm25",
+    name: "mcp_search_tools",
     description: 'Search the catalog of available tools. Returns tool names, descriptions, and server info. Use this FIRST to find relevant tools before calling them.\n\nQuery forms:\n- "select:Read,Edit,Grep" \u2014 fetch these exact tools by name\n- "notebook jupyter" \u2014 keyword search, up to limit best matches\n- "+slack send" \u2014 require "slack" in the name, rank by remaining terms',
     inputSchema: {
       type: "object",
@@ -638,15 +702,47 @@ function createSearchToolDefinition() {
           type: "string",
           description: 'Query to find tools. Use "select:<tool_name>" for direct selection, or keywords to search. Prefix keywords with + to require them.'
         },
+        operation: {
+          type: "string",
+          enum: ["search", "list"],
+          description: 'Operation to perform. Use "search" to find relevant tools by capability. Use "list" with serverId or serverName when the user asks for every tool from a connected MCP server.'
+        },
+        serverId: {
+          type: "string",
+          description: "Optional server ID to restrict search/list results to one MCP server."
+        },
+        serverName: {
+          type: "string",
+          description: 'Optional server name fragment to restrict search/list results to matching MCP servers, e.g. "supabase".'
+        },
         limit: {
           type: "number",
-          description: "Maximum number of results to return (default: 5, max: 20)."
+          description: "Maximum number of results to return (default: 5 for search, 20 for list; max: 20 for search, 100 for list)."
+        },
+        cursor: {
+          type: "string",
+          description: 'Optional pagination cursor returned by operation "list".'
         }
       },
       required: ["query"]
     }
   };
 }
+function createListServersToolDefinition() {
+  return {
+    name: "mcp_list_servers",
+    description: "List connected MCP servers and their tool counts. Use this when mcp_search_tools returns no matches, then retry mcp_search_tools with serverId or serverName.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: 'Optional server filter text. Matches server name or serverId, e.g. "web" or "supabase".'
+        }
+      }
+    }
+  };
+}
 function createRegexSearchToolDefinition() {
   return {
     name: "mcp_search_tool_regex",
@@ -670,17 +766,17 @@ function createRegexSearchToolDefinition() {
 function createGetSchemaToolDefinition() {
   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.",
+    description: "Get the full input schema (parameters) for a specific tool. Call this after mcp_search_tools to get the parameter details needed to call a tool correctly. Do NOT call the discovered tool directly; after reading the schema, call mcp_execute_tool.",
     inputSchema: {
       type: "object",
       properties: {
         toolName: {
           type: "string",
-          description: "The exact tool name returned by mcp_search_tool_bm25."
+          description: "The exact tool name returned by mcp_search_tools."
         },
         serverId: {
           type: "string",
-          description: "Optional: The server ID provided in mcp_search_tool_bm25. Required if multiple tools have the same name."
+          description: "Optional: The server ID provided in mcp_search_tools. Required if multiple tools have the same name."
         }
       },
       required: ["toolName"]
@@ -690,17 +786,17 @@ function createGetSchemaToolDefinition() {
 function createExecuteToolDefinition() {
   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.",
+    description: "Execute a tool that was discovered via mcp_search_tools. You MUST call mcp_get_tool_schema first to know the correct parameters. Pass the exact tool name and its arguments.",
     inputSchema: {
       type: "object",
       properties: {
         toolName: {
           type: "string",
-          description: "The exact tool name from mcp_search_tool_bm25 results."
+          description: "The exact tool name from mcp_search_tools results."
         },
         serverId: {
           type: "string",
-          description: "Optional: The server ID provided in mcp_search_tool_bm25. Required if multiple tools have the same name."
+          description: "Optional: The server ID provided in mcp_search_tools. Required if multiple tools have the same name."
         },
         args: {
           type: "object",
@@ -713,9 +809,9 @@ function createExecuteToolDefinition() {
   };
 }
 async function executeMetaTool(toolName, args, router, callToolFn) {
-  const resolveToolSchema = (name, namespace) => {
+  const resolveToolSchema = (name, namespace, options) => {
     try {
-      return { tool: router.getToolSchema(name, namespace) };
+      return { tool: router.getToolSchema(name, namespace, options) };
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : String(err);
       return {
@@ -727,23 +823,61 @@ async function executeMetaTool(toolName, args, router, callToolFn) {
     }
   };
   switch (toolName) {
-    case "mcp_search_tool_bm25": {
+    case "mcp_search_tools": {
       const query = String(args.query ?? "");
+      const operation = String(args.operation ?? "search");
+      const serverId = String(args.serverId ?? "") || void 0;
+      const serverName = String(args.serverName ?? "") || void 0;
+      if (operation === "list") {
+        const limit2 = Math.min(Number(args.limit) || 20, 100);
+        const cursor = String(args.cursor ?? "") || void 0;
+        const result = await router.listTools({
+          serverId,
+          serverName: serverName ?? (!serverId && query ? query : void 0),
+          limit: limit2,
+          cursor
+        });
+        const serverText = result.servers.length > 0 ? result.servers.map((server) => `${server.serverName} (serverId: ${server.serverId}, tools: ${server.toolCount})`).join(", ") : "none";
+        const lines = [
+          "operation: list",
+          `servers: ${serverText}`,
+          `totalCount: ${result.totalCount}`,
+          `returnedCount: ${result.returnedCount}`,
+          `nextCursor: ${result.nextCursor ?? "null"}`,
+          ""
+        ];
+        if (result.tools.length > 0) {
+          lines.push(...formatToolSummaries(result.tools));
+        } else {
+          lines.push(
+            serverId || serverName ? "No tools found for the requested server scope." : 'No tools found. Try operation "search" or provide serverId/serverName.'
+          );
+        }
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+          isError: false
+        };
+      }
       const limit = Math.min(Number(args.limit) || 5, 20);
+      const searchOptions = { serverId, serverName };
       const selectMatch = query.match(/^select:(.+)$/i);
       if (selectMatch) {
+        await router.listTools({ serverId, serverName, limit: 1 });
         const requested = selectMatch[1].split(",").map((s) => s.trim()).filter(Boolean);
         const found = [];
         const errors = [];
+        const namespace = serverId ?? serverName;
         for (const requestedToolName of requested) {
-          const { tool, error } = resolveToolSchema(requestedToolName);
+          const { tool, error } = resolveToolSchema(requestedToolName, namespace, {
+            allowServerNameFragment: Boolean(serverName && !serverId)
+          });
           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.`);
+            errors.push(`- **${requestedToolName}**: Tool not found. Try searching with mcp_search_tools.`);
           }
         }
         const lines = [];
@@ -764,11 +898,21 @@ async function executeMetaTool(toolName, args, router, callToolFn) {
           isError: found.length === 0
         };
       }
-      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}, serverId: ${t.serverId})
-   ${t.description}
-   Estimated tokens: ${t.estimatedTokens}`
+      const results = await router.searchTools(query, limit, searchOptions);
+      const text = results.length === 0 ? "No tools found matching your query. Call mcp_list_servers to inspect connected servers, then retry mcp_search_tools with serverId or serverName." : formatToolSummaries(results).join("\n");
+      return {
+        content: [{ type: "text", text }],
+        isError: false
+      };
+    }
+    case "mcp_list_servers": {
+      const query = String(args.query ?? "").trim();
+      const servers = await router.listServers({
+        serverName: query || void 0
+      });
+      const text = servers.length === 0 ? "No connected servers found." : servers.map(
+        (server, i) => `${i + 1}. **${server.serverName}** (serverId: ${server.serverId}, sessionId: ${server.sessionId})
+   Tool count: ${server.toolCount}`
       ).join("\n");
       return {
         content: [{ type: "text", text }],
@@ -779,11 +923,7 @@ async function executeMetaTool(toolName, args, router, callToolFn) {
       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}, serverId: ${t.serverId})
-   ${t.description}
-   Estimated tokens: ${t.estimatedTokens}`
-      ).join("\n");
+      const text = results.length === 0 ? "No tools matched your regex pattern. Try a broader pattern." : formatToolSummaries(results).join("\n");
       return {
         content: [{ type: "text", text }],
         isError: false
@@ -801,7 +941,7 @@ async function executeMetaTool(toolName, args, router, callToolFn) {
           content: [
             {
               type: "text",
-              text: `Tool "${name}" not found. Use mcp_search_tool_bm25 to find available tools first.`
+              text: `Tool "${name}" not found. Use mcp_search_tools to find available tools first.`
             }
           ],
           isError: true
@@ -810,7 +950,13 @@ async function executeMetaTool(toolName, args, router, callToolFn) {
       const schema = {
         name: tool.name,
         description: tool.description,
-        inputSchema: tool.inputSchema
+        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 {
         content: [{ type: "text", text: JSON.stringify(schema, null, 2) }],
@@ -836,7 +982,7 @@ async function executeMetaTool(toolName, args, router, callToolFn) {
           content: [
             {
               type: "text",
-              text: `Tool "${targetToolName}" not found. Use mcp_search_tool_bm25 to discover available tools first.`
+              text: `Tool "${targetToolName}" not found. Use mcp_search_tools to discover available tools first.`
             }
           ],
           isError: true
@@ -870,8 +1016,15 @@ async function executeMetaTool(toolName, args, router, callToolFn) {
       return null;
   }
 }
+function formatToolSummaries(tools) {
+  return tools.map(
+    (t, i) => `${i + 1}. **${t.name}** (server: ${t.serverName}, serverId: ${t.serverId})
+   ${t.description}
+   Estimated tokens: ${t.estimatedTokens}`
+  );
+}
 function isMetaTool(toolName) {
-  return toolName === "mcp_search_tool_bm25" || toolName === "mcp_search_tool_regex" || toolName === "mcp_get_tool_schema" || toolName === "mcp_execute_tool";
+  return toolName === "mcp_search_tools" || toolName === "mcp_list_servers" || toolName === "mcp_search_tool_regex" || toolName === "mcp_get_tool_schema" || toolName === "mcp_execute_tool";
 }
 function resolveMetaToolProxy(toolName, args) {
   if (toolName === "mcp_execute_tool") {
@@ -919,7 +1072,7 @@ var ToolRouter = class {
    * 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
    */
   async getFilteredTools() {
@@ -948,9 +1101,10 @@ var ToolRouter = class {
    * Search tools by natural-language query.
    * Works regardless of strategy.
    */
-  async searchTools(query, topK) {
+  async searchTools(query, topK, options = {}) {
     await this.ensureInitialized();
-    return this.index.search(query, topK ?? this.maxTools);
+    const limit = topK ?? this.maxTools;
+    return this.index.search(query, limit, options);
   }
   /**
    * Search tools by regex pattern.
@@ -960,12 +1114,22 @@ var ToolRouter = class {
     await this.ensureInitialized();
     return this.index.searchRegex(pattern, topK ?? this.maxTools);
   }
+  /** List connected MCP servers with indexed tool counts. */
+  async listServers(options = {}) {
+    await this.ensureInitialized();
+    return this.index.listServers(options);
+  }
+  /** List tools deterministically, optionally scoped to a server. */
+  async listTools(options = {}) {
+    await this.ensureInitialized();
+    return this.index.listTools(options);
+  }
   /**
    * Get the full tool definition by name.
    * If tool name is ambiguous, use namespace to specify the server.
    */
-  getToolSchema(toolName, namespace) {
-    const matches = this.index.getTool(toolName, namespace);
+  getToolSchema(toolName, namespace, options = {}) {
+    const matches = this.index.getTool(toolName, namespace, options);
     if (matches.length === 0) return void 0;
     if (matches.length > 1) {
       const servers = matches.map((m) => m.serverId).join(", ");
@@ -1044,7 +1208,7 @@ var ToolRouter = class {
     const indexedTool = this.getToolSchema(toolName, namespace);
     if (!indexedTool) {
       throw new Error(
-        `Tool "${toolName}" not found${namespace ? ` on server "${namespace}"` : ""}. Use mcp_search_tool_bm25 or mcp_search_tool_regex to discover available tools.`
+        `Tool "${toolName}" not found${namespace ? ` on server "${namespace}"` : ""}. Use mcp_search_tools or mcp_search_tool_regex to discover available tools.`
       );
     }
     const clients = this.getClients();
@@ -1156,6 +1320,7 @@ var ToolRouter = class {
   getMetaToolDefinitions() {
     return [
       createSearchToolDefinition(),
+      createListServersToolDefinition(),
       createRegexSearchToolDefinition(),
       createGetSchemaToolDefinition(),
       createExecuteToolDefinition()
@@ -1163,6 +1328,6 @@ var ToolRouter = class {
   }
 };
 
-export { AuthenticationError, ConfigurationError, ConnectionError, DEFAULT_CLIENT_NAME, DEFAULT_CLIENT_URI, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_LOGO_URI, DEFAULT_POLICY_URI, DisposableStore, Emitter, InvalidStateError, MCP_CLIENT_NAME, MCP_CLIENT_VERSION, McpError, NotConnectedError, REDIS_KEY_PREFIX, RpcErrorCodes, SESSION_TTL_SECONDS, SOFTWARE_ID, SOFTWARE_VERSION, STATE_EXPIRATION_MS, SchemaCompressor, SessionNotFoundError, SessionValidationError, TOKEN_EXPIRY_BUFFER_MS, ToolExecutionError, ToolIndex, ToolRouter, UnauthorizedError, createExecuteToolDefinition, createGetSchemaToolDefinition, createRegexSearchToolDefinition, createSearchToolDefinition, executeMetaTool, findToolByName, getToolUiResourceUri, isCallToolSuccess, isConnectAuthRequired, isConnectError, isConnectSuccess, isListToolsSuccess, isMetaTool, resolveMetaToolProxy, sanitizeServerLabel };
+export { AuthenticationError, ConfigurationError, ConnectionError, DEFAULT_CLIENT_NAME, DEFAULT_CLIENT_URI, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_LOGO_URI, DEFAULT_POLICY_URI, DisposableStore, Emitter, InvalidStateError, MCP_CLIENT_NAME, MCP_CLIENT_VERSION, McpError, NotConnectedError, REDIS_KEY_PREFIX, RpcErrorCodes, SESSION_TTL_SECONDS, SOFTWARE_ID, SOFTWARE_VERSION, STATE_EXPIRATION_MS, SchemaCompressor, SessionNotFoundError, SessionValidationError, TOKEN_EXPIRY_BUFFER_MS, ToolExecutionError, ToolIndex, ToolRouter, UnauthorizedError, createExecuteToolDefinition, createGetSchemaToolDefinition, createListServersToolDefinition, createRegexSearchToolDefinition, createSearchToolDefinition, executeMetaTool, findToolByName, getToolUiResourceUri, isCallToolSuccess, isConnectAuthRequired, isConnectError, isConnectSuccess, isListToolsSuccess, isMetaTool, resolveMetaToolProxy, sanitizeServerLabel };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map