@mcp-ts/sdk 1.5.2 → 1.6.0

package/dist/shared/index.d.mts

@@ -2,8 +2,8 @@ export { D as Disposable, a as DisposableStore, E as Emitter, b as Event, M as M
 export { A as AuthenticationError, C as ConfigurationError, a as ConnectionError, I as InvalidStateError, M as McpError, N as NotConnectedError, R as RpcErrorCode, b as RpcErrorCodes, S as SessionNotFoundError, c as SessionValidationError, T as ToolExecutionError, U as UnauthorizedError, s as sanitizeServerLabel } from '../utils-0qmYrqoa.mjs';
 import { v as ToolInfo } from '../types-CfCoIsWI.mjs';
 export { C as CallToolParams, a as CallToolRequest, b as CallToolResponse, c as ConnectAuthRequiredResponse, d as ConnectErrorResponse, e as ConnectParams, f as ConnectRequest, g as ConnectResponse, h as ConnectResult, i as ConnectSuccessResponse, D as DisconnectParams, j as DisconnectResult, F as FinishAuthParams, k as FinishAuthResult, G as GetPromptParams, L as ListPromptsResult, l as ListResourcesResult, m as ListToolsResponse, n as ListToolsRpcResult, M as McpRpcMethod, o as McpRpcParams, p as McpRpcRequest, q as McpRpcResponse, R as ReadResourceParams, r as RestoreSessionResult, S as SessionInfo, s as SessionListResult, t as SessionParams, T as ToolClient, u as ToolClientProvider, w as TransportType, x as isCallToolSuccess, y as isConnectAuthRequired, z as isConnectError, A as isConnectSuccess, B as isListToolsSuccess } from '../types-CfCoIsWI.mjs';
-import { d as ToolRouter } from '../tool-router-DK0RJblO.mjs';
-export { C as CompactTool, a as CompressionStats, E as EmbedFn, I as IndexedTool, S as SchemaCompressor, T as ToolGroupInfo, b as ToolIndex, c as ToolIndexOptions, e as ToolRouterClientInput, f as ToolRouterOptions, g as ToolRouterStrategy, h as ToolSummary } from '../tool-router-DK0RJblO.mjs';
+import { e as ToolRouter } from '../tool-router-_O2tIwf7.mjs';
+export { C as CompactTool, a as CompressionStats, E as EmbedFn, I as IndexedTool, S as SchemaCompressor, T as ToolGroupInfo, b as ToolIndex, c as ToolIndexOptions, d as ToolListResult, f as ToolRouterClientInput, g as ToolRouterOptions, h as ToolRouterStrategy, i as ToolSearchOptions, j as ToolServerSummary, k as ToolSummary } from '../tool-router-_O2tIwf7.mjs';
 import { Tool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 
 /**
@@ -68,7 +68,7 @@ declare function findToolByName(connections: Array<{
  * only the tools it actually needs.
  *
  * Meta-tools:
- *   • `mcp_search_tool_bm25`  — BM25 natural language search
+ *   • `mcp_search_tools`      — Search/list available tools
  *   • `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
@@ -77,13 +77,20 @@ declare function findToolByName(connections: Array<{
  */
 
 /**
- * Creates the `mcp_search_tool_bm25` tool definition.
+ * Creates the `mcp_search_tools` 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.
  */
 declare function createSearchToolDefinition(): Tool;
+/**
+ * Creates the `mcp_list_servers` tool definition.
+ *
+ * This tool lets the LLM inspect connected MCP servers before doing
+ * server-scoped tool discovery.
+ */
+declare function createListServersToolDefinition(): Tool;
 /**
  * Creates the `mcp_search_tool_regex` tool definition.
  *
@@ -93,7 +100,7 @@ declare function createRegexSearchToolDefinition(): Tool;
 /**
  * Creates the `mcp_get_tool_schema` tool definition.
  *
- * After discovering tools via `mcp_search_tool_bm25` or
+ * After discovering tools via `mcp_search_tools` 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.
@@ -103,7 +110,7 @@ declare function createGetSchemaToolDefinition(): Tool;
  * 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`.
+ * tool discovered via `mcp_search_tools` or `mcp_search_tool_regex`.
  * The LLM should first call `mcp_get_tool_schema` to know the correct
  * arguments.
  *
@@ -119,7 +126,7 @@ type CallToolFn = (toolName: string, args: Record<string, unknown>, namespace?:
 /**
  * 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 toolName - One of the meta-tool names (mcp_search_tools, mcp_list_servers, 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)
@@ -139,4 +146,4 @@ declare function resolveMetaToolProxy(toolName: string, args: Record<string, unk
     args: Record<string, unknown>;
 };
 
-export { type CallToolFn, DEFAULT_CLIENT_NAME, DEFAULT_CLIENT_URI, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_LOGO_URI, DEFAULT_POLICY_URI, MCP_CLIENT_NAME, MCP_CLIENT_VERSION, REDIS_KEY_PREFIX, SESSION_TTL_SECONDS, SOFTWARE_ID, SOFTWARE_VERSION, STATE_EXPIRATION_MS, TOKEN_EXPIRY_BUFFER_MS, ToolInfo, ToolRouter, type ToolUiConfig, createExecuteToolDefinition, createGetSchemaToolDefinition, createRegexSearchToolDefinition, createSearchToolDefinition, executeMetaTool, findToolByName, getToolUiResourceUri, isMetaTool, resolveMetaToolProxy };
+export { type CallToolFn, DEFAULT_CLIENT_NAME, DEFAULT_CLIENT_URI, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_LOGO_URI, DEFAULT_POLICY_URI, MCP_CLIENT_NAME, MCP_CLIENT_VERSION, REDIS_KEY_PREFIX, SESSION_TTL_SECONDS, SOFTWARE_ID, SOFTWARE_VERSION, STATE_EXPIRATION_MS, TOKEN_EXPIRY_BUFFER_MS, ToolInfo, ToolRouter, type ToolUiConfig, createExecuteToolDefinition, createGetSchemaToolDefinition, createListServersToolDefinition, createRegexSearchToolDefinition, createSearchToolDefinition, executeMetaTool, findToolByName, getToolUiResourceUri, isMetaTool, resolveMetaToolProxy };

package/dist/shared/index.d.ts

@@ -2,8 +2,8 @@ export { D as Disposable, a as DisposableStore, E as Emitter, b as Event, M as M
 export { A as AuthenticationError, C as ConfigurationError, a as ConnectionError, I as InvalidStateError, M as McpError, N as NotConnectedError, R as RpcErrorCode, b as RpcErrorCodes, S as SessionNotFoundError, c as SessionValidationError, T as ToolExecutionError, U as UnauthorizedError, s as sanitizeServerLabel } from '../utils-0qmYrqoa.js';
 import { v as ToolInfo } from '../types-CfCoIsWI.js';
 export { C as CallToolParams, a as CallToolRequest, b as CallToolResponse, c as ConnectAuthRequiredResponse, d as ConnectErrorResponse, e as ConnectParams, f as ConnectRequest, g as ConnectResponse, h as ConnectResult, i as ConnectSuccessResponse, D as DisconnectParams, j as DisconnectResult, F as FinishAuthParams, k as FinishAuthResult, G as GetPromptParams, L as ListPromptsResult, l as ListResourcesResult, m as ListToolsResponse, n as ListToolsRpcResult, M as McpRpcMethod, o as McpRpcParams, p as McpRpcRequest, q as McpRpcResponse, R as ReadResourceParams, r as RestoreSessionResult, S as SessionInfo, s as SessionListResult, t as SessionParams, T as ToolClient, u as ToolClientProvider, w as TransportType, x as isCallToolSuccess, y as isConnectAuthRequired, z as isConnectError, A as isConnectSuccess, B as isListToolsSuccess } from '../types-CfCoIsWI.js';
-import { d as ToolRouter } from '../tool-router-DsKhRmJm.js';
-export { C as CompactTool, a as CompressionStats, E as EmbedFn, I as IndexedTool, S as SchemaCompressor, T as ToolGroupInfo, b as ToolIndex, c as ToolIndexOptions, e as ToolRouterClientInput, f as ToolRouterOptions, g as ToolRouterStrategy, h as ToolSummary } from '../tool-router-DsKhRmJm.js';
+import { e as ToolRouter } from '../tool-router-Bn9R0KWr.js';
+export { C as CompactTool, a as CompressionStats, E as EmbedFn, I as IndexedTool, S as SchemaCompressor, T as ToolGroupInfo, b as ToolIndex, c as ToolIndexOptions, d as ToolListResult, f as ToolRouterClientInput, g as ToolRouterOptions, h as ToolRouterStrategy, i as ToolSearchOptions, j as ToolServerSummary, k as ToolSummary } from '../tool-router-Bn9R0KWr.js';
 import { Tool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 
 /**
@@ -68,7 +68,7 @@ declare function findToolByName(connections: Array<{
  * only the tools it actually needs.
  *
  * Meta-tools:
- *   • `mcp_search_tool_bm25`  — BM25 natural language search
+ *   • `mcp_search_tools`      — Search/list available tools
  *   • `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
@@ -77,13 +77,20 @@ declare function findToolByName(connections: Array<{
  */
 
 /**
- * Creates the `mcp_search_tool_bm25` tool definition.
+ * Creates the `mcp_search_tools` 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.
  */
 declare function createSearchToolDefinition(): Tool;
+/**
+ * Creates the `mcp_list_servers` tool definition.
+ *
+ * This tool lets the LLM inspect connected MCP servers before doing
+ * server-scoped tool discovery.
+ */
+declare function createListServersToolDefinition(): Tool;
 /**
  * Creates the `mcp_search_tool_regex` tool definition.
  *
@@ -93,7 +100,7 @@ declare function createRegexSearchToolDefinition(): Tool;
 /**
  * Creates the `mcp_get_tool_schema` tool definition.
  *
- * After discovering tools via `mcp_search_tool_bm25` or
+ * After discovering tools via `mcp_search_tools` 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.
@@ -103,7 +110,7 @@ declare function createGetSchemaToolDefinition(): Tool;
  * 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`.
+ * tool discovered via `mcp_search_tools` or `mcp_search_tool_regex`.
  * The LLM should first call `mcp_get_tool_schema` to know the correct
  * arguments.
  *
@@ -119,7 +126,7 @@ type CallToolFn = (toolName: string, args: Record<string, unknown>, namespace?:
 /**
  * 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 toolName - One of the meta-tool names (mcp_search_tools, mcp_list_servers, 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)
@@ -139,4 +146,4 @@ declare function resolveMetaToolProxy(toolName: string, args: Record<string, unk
     args: Record<string, unknown>;
 };
 
-export { type CallToolFn, DEFAULT_CLIENT_NAME, DEFAULT_CLIENT_URI, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_LOGO_URI, DEFAULT_POLICY_URI, MCP_CLIENT_NAME, MCP_CLIENT_VERSION, REDIS_KEY_PREFIX, SESSION_TTL_SECONDS, SOFTWARE_ID, SOFTWARE_VERSION, STATE_EXPIRATION_MS, TOKEN_EXPIRY_BUFFER_MS, ToolInfo, ToolRouter, type ToolUiConfig, createExecuteToolDefinition, createGetSchemaToolDefinition, createRegexSearchToolDefinition, createSearchToolDefinition, executeMetaTool, findToolByName, getToolUiResourceUri, isMetaTool, resolveMetaToolProxy };
+export { type CallToolFn, DEFAULT_CLIENT_NAME, DEFAULT_CLIENT_URI, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_LOGO_URI, DEFAULT_POLICY_URI, MCP_CLIENT_NAME, MCP_CLIENT_VERSION, REDIS_KEY_PREFIX, SESSION_TTL_SECONDS, SOFTWARE_ID, SOFTWARE_VERSION, STATE_EXPIRATION_MS, TOKEN_EXPIRY_BUFFER_MS, ToolInfo, ToolRouter, type ToolUiConfig, createExecuteToolDefinition, createGetSchemaToolDefinition, createListServersToolDefinition, createRegexSearchToolDefinition, createSearchToolDefinition, executeMetaTool, findToolByName, getToolUiResourceUri, isMetaTool, resolveMetaToolProxy };

package/dist/shared/index.js

@@ -340,17 +340,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);
@@ -368,9 +368,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)
@@ -481,17 +482,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;
@@ -548,6 +598,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);
@@ -631,7 +695,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",
@@ -640,15 +704,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",
@@ -672,17 +768,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"]
@@ -692,17 +788,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",
@@ -715,9 +811,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 {
@@ -729,23 +825,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 = [];
@@ -766,11 +900,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 }],
@@ -781,11 +925,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
@@ -803,7 +943,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
@@ -812,7 +952,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) }],
@@ -838,7 +984,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
@@ -872,8 +1018,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") {
@@ -921,7 +1074,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() {
@@ -950,9 +1103,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.
@@ -962,12 +1116,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(", ");
@@ -1046,7 +1210,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();
@@ -1158,6 +1322,7 @@ var ToolRouter = class {
   getMetaToolDefinitions() {
     return [
       createSearchToolDefinition(),
+      createListServersToolDefinition(),
       createRegexSearchToolDefinition(),
       createGetSchemaToolDefinition(),
       createExecuteToolDefinition()
@@ -1196,6 +1361,7 @@ exports.ToolRouter = ToolRouter;
 exports.UnauthorizedError = UnauthorizedError;
 exports.createExecuteToolDefinition = createExecuteToolDefinition;
 exports.createGetSchemaToolDefinition = createGetSchemaToolDefinition;
+exports.createListServersToolDefinition = createListServersToolDefinition;
 exports.createRegexSearchToolDefinition = createRegexSearchToolDefinition;
 exports.createSearchToolDefinition = createSearchToolDefinition;
 exports.executeMetaTool = executeMetaTool;