@mcp-ts/sdk 1.4.0 → 1.5.0

package/dist/tool-router-XnWVxPzv.d.mts

@@ -0,0 +1,325 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { u as ToolClientProvider, T as ToolClient } from './types-CfCoIsWI.mjs';
+
+/**
+ * SchemaCompressor — Utilities for reducing tool schema token overhead.
+ *
+ * Provides compact representations of tools (name + description only,
+ * no inputSchema) and token savings estimation.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A minimal tool representation containing only what an LLM needs to
+ * *decide whether* to use a tool.  The full `inputSchema` is deferred.
+ */
+interface CompactTool {
+    name: string;
+    description?: string;
+    /**
+     * Human-readable hint about the expected parameters.
+     * e.g. "(location: string, unit?: 'celsius' | 'fahrenheit')"
+     */
+    parameterHint?: string;
+}
+interface CompressionStats {
+    /** Estimated tokens for the *full* tool list. */
+    fullTokens: number;
+    /** Estimated tokens for the *compact* tool list. */
+    compactTokens: number;
+    /** Absolute token savings. */
+    savedTokens: number;
+    /** Percentage savings as a human-readable string, e.g. "82.3%". */
+    savingsPercent: string;
+}
+declare class SchemaCompressor {
+    /**
+     * Convert a full MCP Tool definition to a compact summary.
+     *
+     * The compact form omits `inputSchema` entirely and optionally generates
+     * a short `parameterHint` from the schema's top-level properties.
+     */
+    static toCompact(tool: Tool): CompactTool;
+    /**
+     * Convert an array of tools to compact form, optionally limiting the count.
+     */
+    static compactAll(tools: Tool[], options?: {
+        maxTools?: number;
+    }): CompactTool[];
+    /**
+     * Estimate token savings from using compact vs full tool schemas.
+     */
+    static estimateSavings(tools: Tool[]): CompressionStats;
+}
+
+/**
+ * ToolIndex — Lightweight in-memory search index for MCP tool discovery.
+ *
+ * Supports two search methods:
+ *   • BM25      – Okapi BM25 ranking over tokenized tool metadata (zero external deps)
+ *   • regex     – Pattern matching against tool names, descriptions, and parameters
+ *   • embedding – (optional) cosine-similarity over caller-supplied vectors,
+ *                 blended with BM25 scores
+ *
+ * @packageDocumentation
+ */
+
+/** Compact summary returned by search — intentionally lightweight. */
+interface ToolSummary {
+    /** Fully qualified tool name (e.g. "tool_github_create_pr") */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Server that owns this tool */
+    serverName: string;
+    /** Session the tool belongs to */
+    sessionId: string;
+    /** Estimated token cost of the full inputSchema */
+    estimatedTokens: number;
+}
+/** A tool with routing metadata attached during indexing. */
+interface IndexedTool extends Tool {
+    sessionId: string;
+    serverName: string;
+}
+/**
+ * An optional embedding function supplied by the consumer.
+ * Should accept an array of strings and return a matching array of
+ * float-number arrays (one embedding vector per input string).
+ */
+type EmbedFn = (texts: string[]) => Promise<number[][]>;
+interface ToolIndexOptions {
+    /**
+     * Custom embedding function for semantic search.
+     * When provided, `search()` uses cosine-similarity in addition to keywords.
+     * @example
+     * ```ts
+     * import { embed } from 'ai';
+     * const embedFn: EmbedFn = async (texts) => {
+     *   const { embeddings } = await embed({ model: openai('text-embedding-3-small'), values: texts });
+     *   return embeddings;
+     * };
+     * ```
+     */
+    embedFn?: EmbedFn;
+    /**
+     * Relative weight of keyword score vs embedding score when both are active.
+     * 0 = embedding only · 1 = keyword only · 0.4 (default) blends both.
+     * @default 0.4
+     */
+    keywordWeight?: number;
+}
+declare class ToolIndex {
+    /** All indexed tools keyed by name (supports duplicates). */
+    private tools;
+    /** Precomputed lightweight summaries keyed by document. */
+    private toolSummaries;
+    /** Pre-computed search text for keyword matching (lowercase), keyed by document. */
+    private searchTexts;
+    /** Pre-computed IDF values per token (computed once on build). */
+    private idf;
+    /** Per-tool TF vectors (Map<token, tf>). */
+    private tfVectors;
+    /** Optional: pre-computed embedding vectors per tool. */
+    private embeddings;
+    /** BM25: document lengths in tokens for each tool. */
+    private docLengths;
+    /** BM25: average document length across the entire index. */
+    private avgDocLength;
+    /** Cached total estimated token cost across all indexed tools. */
+    private totalTokenCost;
+    private options;
+    constructor(options?: ToolIndexOptions);
+    /**
+     * Build (or rebuild) the index from the given tool set.
+     * Call this after connecting / reconnecting to MCP servers.
+     */
+    buildIndex(tools: IndexedTool[]): Promise<void>;
+    /**
+     * Search the index and return the top-K most relevant tools.
+     *
+     * When an `embedFn` is configured the final score is a weighted blend of
+     * keyword TF-IDF similarity and embedding cosine-similarity:
+     *
+     *   `score = keywordWeight × keyword_score + (1 - keywordWeight) × cosine_score`
+     */
+    search(query: string, topK?: number): Promise<ToolSummary[]>;
+    /**
+     * Search tools using a regex pattern.
+     * Matches against name, description, and parameter metadata.
+     */
+    searchRegex(pattern: string, topK?: number): ToolSummary[];
+    /**
+     * Get tool definition(s) by name.
+     * If namespace is provided, it tries to match sessionId or serverName.
+     */
+    getTool(name: string, namespace?: string): IndexedTool[];
+    /** All indexed tool names. */
+    getToolNames(): string[];
+    /** Number of indexed tools (including duplicates). */
+    get size(): number;
+    /** Total estimated token cost of all indexed tool schemas. */
+    getTotalTokenCost(): number;
+    /**
+     * Estimate token count of a tool's full schema (name + description + inputSchema).
+     *
+     * Uses character-class weighted counting calibrated against cl100k_base.
+     * Accuracy is typically within ±10% for JSON Schema payloads.
+     */
+    static estimateTokens(tool: Tool): number;
+    /** Build a single searchable string from tool metadata. */
+    private buildSearchableText;
+    private getDocumentKey;
+    /** Simple whitespace + camelCase + snake_case tokenizer. */
+    private tokenize;
+    /** Cosine similarity between two vectors. */
+    private cosineSimilarity;
+}
+
+type ToolRouterStrategy = 'all' | 'search' | 'groups';
+interface ToolRouterOptions {
+    /**
+     * Strategy for tool selection.
+     *
+     *  • `all`    — Expose all tools (default, backward-compatible)
+     *  • `search` — Expose only meta-tools; LLM discovers real tools via search
+     *  • `groups` — Expose only tools from active groups
+     *
+     * @default 'all'
+     */
+    strategy?: ToolRouterStrategy;
+    /**
+     * Maximum tools to expose to the LLM at once.
+     * Only applies to `groups` strategy and search results.
+     * @default 40
+     */
+    maxTools?: number;
+    /**
+     * Tool groups configuration — map of group name to tool names.
+     * When not provided, groups are auto-generated from server names.
+     *
+     * @example
+     * ```ts
+     * groups: {
+     *   database: ['query_db', 'list_tables', 'describe_table'],
+     *   github: ['create_pr', 'list_issues', 'search_code'],
+     * }
+     * ```
+     */
+    groups?: Record<string, string[]>;
+    /**
+     * Active groups (when `strategy='groups'`).
+     * Only tools in these groups are exposed. Empty = all groups active.
+     */
+    activeGroups?: string[];
+    /**
+     * Whether to use compact schemas (name + description + parameterHint only, no inputSchema).
+     * Reduces token usage but requires 2-turn flow: LLM picks tool → get schema → call.
+     * @default false
+     */
+    compactSchemas?: boolean;
+    /**
+     * Optional embedding function for semantic search.
+     * When not provided, keyword TF-IDF matching is used.
+     */
+    embedFn?: EmbedFn;
+    /**
+     * Weight of keyword score vs embedding score (0–1).
+     * Only relevant when `embedFn` is provided.
+     * @default 0.4
+     */
+    keywordWeight?: number;
+}
+/** Information about a tool group. */
+interface ToolGroupInfo {
+    tools: string[];
+    active: boolean;
+}
+/**
+ * Accepted client input for ToolRouter.
+ * Pass a `ToolClientProvider` (e.g. MultiSessionClient), or an array of `ToolClient` instances.
+ */
+type ToolRouterClientInput = ToolClientProvider | ToolClient[];
+declare class ToolRouter {
+    private client;
+    private options;
+    private index;
+    private allTools;
+    private groupsMap;
+    private strategy;
+    private maxTools;
+    private compactSchemas;
+    private activeGroups;
+    private customGroups?;
+    private initialized;
+    constructor(client: ToolRouterClientInput, options?: ToolRouterOptions);
+    /**
+     * Get tools filtered by the current strategy.
+     * 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)
+     * - `groups` → returns tools from active groups only
+     */
+    getFilteredTools(): Promise<Tool[]>;
+    /**
+     * Search tools by natural-language query.
+     * Works regardless of strategy.
+     */
+    searchTools(query: string, topK?: number): Promise<ToolSummary[]>;
+    /**
+     * Search tools by regex pattern.
+     * Matches against name, description, and parameter metadata.
+     */
+    searchToolsRegex(pattern: string, topK?: number): Promise<ToolSummary[]>;
+    /**
+     * 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;
+    /**
+     * Get compact (schema-less) summaries for all tools.
+     */
+    getCompactTools(): CompactTool[];
+    /** Get all available groups with their tool lists and active status. */
+    getGroups(): Map<string, ToolGroupInfo>;
+    /** Activate specific groups. Pass empty array to activate all. */
+    setActiveGroups(groups: string[]): void;
+    /** Get the names of currently active groups. */
+    getActiveGroups(): string[];
+    /** Total token cost of all tools if loaded without filtering. */
+    getTotalTokenCost(): number;
+    /** Estimate token cost of the currently filtered tool set. */
+    getFilteredTokenCost(): Promise<number>;
+    /** Get compression stats showing savings from current strategy. */
+    getCompressionStats(): CompressionStats;
+    /** Number of total indexed tools. */
+    get totalToolCount(): number;
+    /** Change strategy at runtime. */
+    setStrategy(strategy: ToolRouterStrategy): void;
+    /**
+     * Force a re-index of tools from all connected clients.
+     * Call this after adding/removing MCP server connections.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Execute a tool by routing to the correct MCP client.
+     * Used by the `mcp_execute_tool` meta-tool to proxy tool calls.
+     */
+    callTool(toolName: string, args: Record<string, unknown>, namespace?: string): Promise<any>;
+    /** Lazy initialization — fetches tools from all connected clients. */
+    private ensureInitialized;
+    /** Fetch tools from all connected MCP clients. */
+    private fetchAllTools;
+    /** Resolve the client input to a flat array of ToolClient instances. */
+    private getClients;
+    /** Build group map from custom config or auto-detect from server names. */
+    private buildGroups;
+    /** Return only tools belonging to currently active groups. */
+    private getGroupFilteredTools;
+    /** The 4 meta-tool definitions exposed in `search` strategy. */
+    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 };

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

@@ -4,6 +4,32 @@ import { Tool } from '@modelcontextprotocol/sdk/types.js';
  * Type definitions for MCP operations
  */
 
+/**
+ * A client that can list and execute MCP tools.
+ *
+ * This is the structural interface that `ToolRouter`, adapters, and other
+ * consumers use to interact with any MCP client implementation.
+ * Both `MCPClient` and `createMcpClient()` satisfy this interface.
+ */
+interface ToolClient {
+    isConnected(): boolean;
+    listTools(): Promise<{
+        tools: Tool[];
+    }>;
+    callTool(name: string, args: Record<string, unknown>): Promise<any>;
+    getServerId?(): string | undefined;
+    getServerName?(): string | undefined;
+    getSessionId?(): string;
+}
+/**
+ * A provider that manages multiple `ToolClient` instances.
+ *
+ * `MultiSessionClient` satisfies this interface. Pass it directly
+ * to `ToolRouter` or adapters to aggregate tools from all connected servers.
+ */
+interface ToolClientProvider {
+    getClients(): ToolClient[];
+}
 interface ConnectRequest {
     serverUrl: string;
     callbackUrl: string;
@@ -156,4 +182,4 @@ interface ListResourcesResult {
     }>;
 }
 
-export { type CallToolParams as C, type DisconnectParams as D, type FinishAuthParams as F, type GetPromptParams as G, type ListPromptsResult as L, type McpRpcMethod as M, type ReadResourceParams as R, type SessionInfo as S, type ToolInfo as T, type CallToolRequest as a, type CallToolResponse as b, type ConnectAuthRequiredResponse as c, type ConnectErrorResponse as d, type ConnectParams as e, type ConnectRequest as f, type ConnectResponse as g, type ConnectResult as h, type ConnectSuccessResponse as i, type DisconnectResult as j, type FinishAuthResult as k, type ListResourcesResult as l, type ListToolsResponse as m, type ListToolsRpcResult as n, type McpRpcParams as o, type McpRpcRequest as p, type McpRpcResponse as q, type RestoreSessionResult as r, type SessionListResult as s, type SessionParams as t, type TransportType as u, isCallToolSuccess as v, isConnectAuthRequired as w, isConnectError as x, isConnectSuccess as y, isListToolsSuccess as z };
+export { isConnectSuccess as A, isListToolsSuccess as B, type CallToolParams as C, type DisconnectParams as D, type FinishAuthParams as F, type GetPromptParams as G, type ListPromptsResult as L, type McpRpcMethod as M, type ReadResourceParams as R, type SessionInfo as S, type ToolClient as T, type CallToolRequest as a, type CallToolResponse as b, type ConnectAuthRequiredResponse as c, type ConnectErrorResponse as d, type ConnectParams as e, type ConnectRequest as f, type ConnectResponse as g, type ConnectResult as h, type ConnectSuccessResponse as i, type DisconnectResult as j, type FinishAuthResult as k, type ListResourcesResult as l, type ListToolsResponse as m, type ListToolsRpcResult as n, type McpRpcParams as o, type McpRpcRequest as p, type McpRpcResponse as q, type RestoreSessionResult as r, type SessionListResult as s, type SessionParams as t, type ToolClientProvider as u, type ToolInfo as v, type TransportType as w, isCallToolSuccess as x, isConnectAuthRequired as y, isConnectError as z };

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

@@ -4,6 +4,32 @@ import { Tool } from '@modelcontextprotocol/sdk/types.js';
  * Type definitions for MCP operations
  */
 
+/**
+ * A client that can list and execute MCP tools.
+ *
+ * This is the structural interface that `ToolRouter`, adapters, and other
+ * consumers use to interact with any MCP client implementation.
+ * Both `MCPClient` and `createMcpClient()` satisfy this interface.
+ */
+interface ToolClient {
+    isConnected(): boolean;
+    listTools(): Promise<{
+        tools: Tool[];
+    }>;
+    callTool(name: string, args: Record<string, unknown>): Promise<any>;
+    getServerId?(): string | undefined;
+    getServerName?(): string | undefined;
+    getSessionId?(): string;
+}
+/**
+ * A provider that manages multiple `ToolClient` instances.
+ *
+ * `MultiSessionClient` satisfies this interface. Pass it directly
+ * to `ToolRouter` or adapters to aggregate tools from all connected servers.
+ */
+interface ToolClientProvider {
+    getClients(): ToolClient[];
+}
 interface ConnectRequest {
     serverUrl: string;
     callbackUrl: string;
@@ -156,4 +182,4 @@ interface ListResourcesResult {
     }>;
 }
 
-export { type CallToolParams as C, type DisconnectParams as D, type FinishAuthParams as F, type GetPromptParams as G, type ListPromptsResult as L, type McpRpcMethod as M, type ReadResourceParams as R, type SessionInfo as S, type ToolInfo as T, type CallToolRequest as a, type CallToolResponse as b, type ConnectAuthRequiredResponse as c, type ConnectErrorResponse as d, type ConnectParams as e, type ConnectRequest as f, type ConnectResponse as g, type ConnectResult as h, type ConnectSuccessResponse as i, type DisconnectResult as j, type FinishAuthResult as k, type ListResourcesResult as l, type ListToolsResponse as m, type ListToolsRpcResult as n, type McpRpcParams as o, type McpRpcRequest as p, type McpRpcResponse as q, type RestoreSessionResult as r, type SessionListResult as s, type SessionParams as t, type TransportType as u, isCallToolSuccess as v, isConnectAuthRequired as w, isConnectError as x, isConnectSuccess as y, isListToolsSuccess as z };
+export { isConnectSuccess as A, isListToolsSuccess as B, type CallToolParams as C, type DisconnectParams as D, type FinishAuthParams as F, type GetPromptParams as G, type ListPromptsResult as L, type McpRpcMethod as M, type ReadResourceParams as R, type SessionInfo as S, type ToolClient as T, type CallToolRequest as a, type CallToolResponse as b, type ConnectAuthRequiredResponse as c, type ConnectErrorResponse as d, type ConnectParams as e, type ConnectRequest as f, type ConnectResponse as g, type ConnectResult as h, type ConnectSuccessResponse as i, type DisconnectResult as j, type FinishAuthResult as k, type ListResourcesResult as l, type ListToolsResponse as m, type ListToolsRpcResult as n, type McpRpcParams as o, type McpRpcRequest as p, type McpRpcResponse as q, type RestoreSessionResult as r, type SessionListResult as s, type SessionParams as t, type ToolClientProvider as u, type ToolInfo as v, type TransportType as w, isCallToolSuccess as x, isConnectAuthRequired as y, isConnectError as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-ts/sdk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -86,7 +86,8 @@
     "test:debug": "npx playwright test --debug",
     "supabase:push": "supabase db push",
     "supabase:reset": "supabase db reset",
-    "supabase:status": "supabase status"
+    "supabase:status": "supabase status",
+    "mcp-docs": "npm run start --prefix packages/mcp-server-docs"
   },
   "keywords": [
     "mcp",

package/src/adapters/agui-adapter.ts

@@ -28,6 +28,8 @@
 
 import { MCPClient } from '../server/mcp/oauth-client.js';
 import { MultiSessionClient } from '../server/mcp/multi-session-client.js';
+import { ToolRouter } from '../shared/tool-router.js';
+import { executeMetaTool, isMetaTool } from '../shared/meta-tools.js';
 
 /**
  * Extended JSON Schema properties that Pydantic's strict validation rejects.
@@ -96,6 +98,11 @@ export interface AguiAdapterOptions {
      * @default serverId or 'mcp'
      */
     prefix?: string;
+
+    /**
+     * Optional ToolRouter for intelligent tool selection.
+     */
+    toolRouter?: ToolRouter;
 }
 
 /**
@@ -132,6 +139,10 @@ export class AguiAdapter {
      * Get tools with handlers for MCP tool execution.
      */
     async getTools(): Promise<AguiTool[]> {
+        if (this.options.toolRouter) {
+            return this.getToolsViaRouter(this.options.toolRouter);
+        }
+
         if (this.isMultiSession()) {
             const clients = (this.client as MultiSessionClient).getClients();
             const allTools: AguiTool[] = [];
@@ -147,6 +158,10 @@ export class AguiAdapter {
      * Get tool definitions in JSON Schema format for passing to remote agents.
      */
     async getToolDefinitions(): Promise<AguiToolDefinition[]> {
+        if (this.options.toolRouter) {
+            return this.getToolDefinitionsViaRouter(this.options.toolRouter);
+        }
+
         if (this.isMultiSession()) {
             const clients = (this.client as MultiSessionClient).getClients();
             const allTools: AguiToolDefinition[] = [];
@@ -219,4 +234,68 @@ export class AguiAdapter {
             };
         });
     }
+
+    /**
+     * Build AG-UI tools from a ToolRouter's filtered output.
+     *
+     * In `search` strategy, only meta-tools are registered with the framework.
+     * Real tool execution is proxied through `mcp_execute_tool` which uses
+     * `router.callTool()` to route to the correct MCP client.
+     */
+    private async getToolsViaRouter(router: ToolRouter): Promise<AguiTool[]> {
+        const filteredTools = await router.getFilteredTools();
+
+        return filteredTools.map(tool => {
+            const routedTool = tool as typeof tool & { sessionId?: string; serverName?: string };
+            const namespace = routedTool.serverName ?? routedTool.sessionId;
+            return {
+                name: isMetaTool(tool.name)
+                    ? tool.name
+                    : this.getRouterToolKey(tool.name, routedTool.sessionId, routedTool.serverName),
+                description: tool.description || `Execute ${tool.name}`,
+                parameters: cleanSchema(tool.inputSchema),
+                handler: async (args: any) => {
+                    if (isMetaTool(tool.name)) {
+                        const result = await executeMetaTool(
+                            tool.name,
+                            args,
+                            router,
+                            (name, toolArgs, namespace) => router.callTool(name, toolArgs, namespace)
+                        );
+                        if (result) {
+                            return result.content.map((c: any) => c.text ?? '').join('\n');
+                        }
+                        return "Failed to execute meta-tool";
+                    }
+
+                    // For non-meta tools in 'all' or 'groups' strategy,
+                    // route directly to the correct MCP client
+                    return await router.callTool(tool.name, args, namespace);
+                }
+            };
+        });
+    }
+
+    private async getToolDefinitionsViaRouter(router: ToolRouter): Promise<AguiToolDefinition[]> {
+        const filteredTools = await router.getFilteredTools();
+        return filteredTools.map(tool => {
+            const routedTool = tool as typeof tool & { sessionId?: string; serverName?: string };
+            return {
+                name: isMetaTool(tool.name)
+                    ? tool.name
+                    : this.getRouterToolKey(tool.name, routedTool.sessionId, routedTool.serverName),
+                description: tool.description || `Execute ${tool.name}`,
+                parameters: cleanSchema(tool.inputSchema)
+            };
+        });
+    }
+
+    private getRouterToolKey(toolName: string, sessionId?: string, serverName?: string): string {
+        const namespace = sessionId ?? serverName ?? 'mcp';
+        const normalized = namespace
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '_')
+            .replace(/^_+|_+$/g, '') || 'mcp';
+        return `tool_${normalized}_${toolName}`;
+    }
 }

package/src/adapters/ai-adapter.ts

@@ -2,6 +2,8 @@ import { MCPClient } from '../server/mcp/oauth-client';
 import { MultiSessionClient } from '../server/mcp/multi-session-client';
 import type { JSONSchema7 } from 'json-schema';
 import type { ToolSet } from 'ai';
+import { ToolRouter } from '../shared/tool-router.js';
+import { executeMetaTool, isMetaTool } from '../shared/meta-tools.js';
 
 export interface AIAdapterOptions {
     /** 
@@ -9,6 +11,17 @@ export interface AIAdapterOptions {
      * Defaults to the client's serverId.
      */
     prefix?: string;
+
+    /**
+     * Optional ToolRouter for intelligent tool selection.
+     *
+     * When provided with `strategy: 'search'`, the adapter exposes only
+     * meta-tools (search_tools, get_tool_schema) instead of all tool schemas,
+     * reducing context window usage by 80–95%.
+     *
+     * When not provided, all tools are returned as before (backward-compatible).
+     */
+    toolRouter?: ToolRouter;
 }
 
 /**
@@ -80,6 +93,11 @@ export class AIAdapter {
     async getTools(): Promise<ToolSet> {
         await this.ensureJsonSchema();
 
+        // If a ToolRouter is provided, use its filtered output
+        if (this.options.toolRouter) {
+            return this.getToolsViaRouter(this.options.toolRouter);
+        }
+
         // Use duck typing instead of instanceof to handle module bundling issues
         // MultiSessionClient has getClients(), MCPClient does not
         const isMultiSession = typeof (this.client as any).getClients === 'function';
@@ -106,6 +124,63 @@ export class AIAdapter {
         return results.reduce((acc, tools) => ({ ...acc, ...tools }), {});
     }
 
+    /**
+     * Build a ToolSet from a ToolRouter's filtered output.
+     *
+     * In `search` strategy, only meta-tools are registered with the framework.
+     * Real tool execution is proxied through `mcp_execute_tool` which uses
+     * `router.callTool()` to route to the correct MCP client.
+     */
+    private async getToolsViaRouter(router: ToolRouter): Promise<ToolSet> {
+        const filteredTools = await router.getFilteredTools();
+
+        // @ts-ignore: ToolSet type inference can be tricky with dynamic imports
+        return Object.fromEntries(
+            filteredTools.map((tool) => {
+                const routedTool = tool as typeof tool & { sessionId?: string; serverName?: string };
+                const namespace = routedTool.serverName ?? routedTool.sessionId;
+                const toolKey = isMetaTool(tool.name)
+                    ? tool.name
+                    : this.getRouterToolKey(tool.name, routedTool.sessionId, routedTool.serverName);
+
+                return [
+                    toolKey,
+                    {
+                        description: tool.description,
+                        inputSchema: this.jsonSchema!(tool.inputSchema as JSONSchema7),
+                        execute: async (args: any) => {
+                            // Handle meta-tool calls via the router
+                            if (isMetaTool(tool.name)) {
+                                const result = await executeMetaTool(
+                                    tool.name,
+                                    args,
+                                    router,
+                                    (name, toolArgs, targetNamespace) => router.callTool(name, toolArgs, targetNamespace)
+                                );
+                                if (result) {
+                                  return result;
+                                }
+                            }
+
+                            // For non-meta tools in 'all' or 'groups' strategy,
+                            // route directly to the correct MCP client
+                            return await router.callTool(tool.name, args, namespace);
+                        },
+                    },
+                ];
+            })
+        );
+    }
+
+    private getRouterToolKey(toolName: string, sessionId?: string, serverName?: string): string {
+        const namespace = sessionId ?? serverName ?? 'mcp';
+        const normalized = namespace
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '_')
+            .replace(/^_+|_+$/g, '') || 'mcp';
+        return `tool_${normalized}_${toolName}`;
+    }
+
     /**
      * Convenience static method to fetch tools in a single line.
      */