@mcp-ts/sdk 1.5.3 → 1.6.0

package/src/shared/tool-index.ts

@@ -32,6 +32,43 @@ export interface ToolSummary {
   estimatedTokens: number;
 }
 
+/** Server-level summary derived from indexed tools. */
+export 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. */
+export 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. */
+export interface ToolListResult {
+  tools: ToolSummary[];
+  totalCount: number;
+  returnedCount: number;
+  nextCursor?: string;
+  servers: ToolServerSummary[];
+}
+
+export 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. */
 export interface IndexedTool extends Tool {
   sessionId: string;
@@ -259,14 +296,14 @@ export class ToolIndex {
    *
    *   `score = keywordWeight × keyword_score + (1 - keywordWeight) × cosine_score`
    */
-  async search(query: string, topK = 5): Promise<ToolSummary[]> {
+  async search(query: string, topK = 5, options: ToolSearchOptions = {}): Promise<ToolSummary[]> {
     if (this.tools.size === 0) return [];
 
     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
+      (summary) => summary.name.toLowerCase() === queryLower && this.matchesServer(summary, options)
     );
     if (exactMatches.length > 0) {
       return exactMatches.slice(0, topK);
@@ -275,7 +312,7 @@ export class ToolIndex {
     // 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))
+        .filter((t) => t.name.toLowerCase().startsWith(queryLower) && this.matchesServer(t, options))
         .slice(0, topK);
       if (prefixMatches.length > 0) return prefixMatches;
     }
@@ -300,9 +337,11 @@ export class ToolIndex {
     // Pre-filter: only keep documents that contain ALL required terms
     const candidateKeys = new Set<string>();
     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)
@@ -456,13 +495,22 @@ export 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: string, namespace?: string): IndexedTool[] {
+  getTool(name: string, namespace?: string, options: ToolLookupOptions = {}): IndexedTool[] {
     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. */
@@ -470,6 +518,57 @@ export class ToolIndex {
     return [...this.tools.keys()];
   }
 
+  /** List indexed servers with tool counts. */
+  listServers(options: ToolSearchOptions = {}): ToolServerSummary[] {
+    const servers = new Map<string, ToolServerSummary>();
+
+    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: ToolSearchOptions & { limit?: number; cursor?: string } = {}): ToolListResult {
+    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) : undefined,
+      servers: this.listServers(options),
+    };
+  }
+
   /** Number of indexed tools (including duplicates). */
   get size(): number {
     let count = 0;
@@ -539,6 +638,23 @@ export class ToolIndex {
     return `${tool.sessionId}::${tool.serverId}::${tool.name}`;
   }
 
+  private matchesServer(summary: ToolSummary, options: ToolSearchOptions): boolean {
+    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. */
   private tokenize(text: string): string[] {
     return text

package/src/shared/tool-router.ts

@@ -28,10 +28,20 @@
 
 import type { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { ToolClient, ToolClientProvider } from './types.js';
-import { ToolIndex, type IndexedTool, type ToolSummary, type EmbedFn } from './tool-index.js';
+import {
+  ToolIndex,
+  type IndexedTool,
+  type ToolLookupOptions,
+  type ToolListResult,
+  type ToolSearchOptions,
+  type ToolServerSummary,
+  type ToolSummary,
+  type EmbedFn,
+} from './tool-index.js';
 import { SchemaCompressor, type CompactTool } from './schema-compressor.js';
 import {
   createSearchToolDefinition,
+  createListServersToolDefinition,
   createRegexSearchToolDefinition,
   createGetSchemaToolDefinition,
   createExecuteToolDefinition,
@@ -159,7 +169,7 @@ export 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
    */
   async getFilteredTools(): Promise<Tool[]> {
@@ -195,9 +205,14 @@ export class ToolRouter {
    * Search tools by natural-language query.
    * Works regardless of strategy.
    */
-  async searchTools(query: string, topK?: number): Promise<ToolSummary[]> {
+  async searchTools(
+    query: string,
+    topK?: number,
+    options: ToolSearchOptions = {}
+  ): Promise<ToolSummary[]> {
     await this.ensureInitialized();
-    return this.index.search(query, topK ?? this.maxTools);
+    const limit = topK ?? this.maxTools;
+    return this.index.search(query, limit, options);
   }
 
   /**
@@ -209,12 +224,28 @@ export class ToolRouter {
     return this.index.searchRegex(pattern, topK ?? this.maxTools);
   }
 
+  /** List connected MCP servers with indexed tool counts. */
+  async listServers(options: ToolSearchOptions = {}): Promise<ToolServerSummary[]> {
+    await this.ensureInitialized();
+    return this.index.listServers(options);
+  }
+
+  /** List tools deterministically, optionally scoped to a server. */
+  async listTools(options: ToolSearchOptions & { limit?: number; cursor?: string } = {}): Promise<ToolListResult> {
+    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: string, namespace?: string): IndexedTool | undefined {
-    const matches = this.index.getTool(toolName, namespace);
+  getToolSchema(
+    toolName: string,
+    namespace?: string,
+    options: ToolLookupOptions = {}
+  ): IndexedTool | undefined {
+    const matches = this.index.getTool(toolName, namespace, options);
 
     if (matches.length === 0) return undefined;
 
@@ -318,7 +349,7 @@ export class ToolRouter {
       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.`
+        }. Use mcp_search_tools or mcp_search_tool_regex to discover available tools.`
       );
     }
 
@@ -462,9 +493,11 @@ export class ToolRouter {
   private getMetaToolDefinitions(): Tool[] {
     return [
       createSearchToolDefinition(),
+      createListServersToolDefinition(),
       createRegexSearchToolDefinition(),
       createGetSchemaToolDefinition(),
       createExecuteToolDefinition(),
     ];
   }
+
 }