@mcp-ts/sdk 2.0.0 → 2.2.0

package/dist/{tool-router-Dnd6IOKC.d.mts → tool-router-C8hIA-tg.d.mts}

@@ -1,5 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { u as ToolClientProvider, T as ToolClient } from './types-BCAG20P6.mjs';
+import { u as ToolClientProvider, T as ToolClient } from './types-CxFaaZrM.mjs';
 
 /**
  * ToolIndex — Lightweight in-memory search index for MCP tool discovery.
@@ -64,6 +64,7 @@ interface IndexedTool extends Tool {
     sessionId: string;
     serverId: string;
     serverName: string;
+    outputSchema?: Tool['outputSchema'];
 }
 /**
  * An optional embedding function supplied by the consumer.
@@ -268,6 +269,20 @@ interface ToolRouterOptions {
      * @default false
      */
     compactSchemas?: boolean;
+    /**
+     * Tool names to expose directly when using `search` strategy.
+     * Pinned tools are removed from discovery results and should be called directly.
+     */
+    pinnedTools?: string[];
+    /**
+     * Tool names to omit from direct exposure while keeping them indexed for
+     * search/schema lookup/calls through meta-tools.
+     */
+    deferredTools?: string[];
+    /**
+     * Tool names or glob-style patterns to omit entirely from the router catalog.
+     */
+    excludeTools?: string[];
     /**
      * Optional embedding function for semantic search.
      * When not provided, keyword TF-IDF matching is used.
@@ -295,12 +310,18 @@ declare class ToolRouter {
     private options;
     private index;
     private allTools;
+    private pinnedTools;
+    private deferredTools;
+    private discoverableTools;
     private groupsMap;
     private strategy;
     private maxTools;
     private compactSchemas;
     private activeGroups;
     private customGroups?;
+    private pinnedToolNames;
+    private deferredToolNames;
+    private excludeToolMatchers;
     private initialized;
     constructor(client: ToolRouterClientInput, options?: ToolRouterOptions);
     /**
@@ -370,6 +391,10 @@ declare class ToolRouter {
     private getGroupFilteredTools;
     /** The 4 meta-tool definitions exposed in `search` strategy. */
     private getMetaToolDefinitions;
+    private matchesPinnedTool;
+    private matchesDeferredTool;
+    private matchesExcludedTool;
+    private getDirectlyVisibleTools;
 }
 
 export { type CompactTool as C, type EmbedFn as E, type IndexedTool as I, SchemaCompressor as S, type ToolGroupInfo as T, ToolIndex as a, type ToolIndexOptions as b, type ToolListResult as c, ToolRouter as d, type ToolRouterClientInput as e, type ToolRouterOptions as f, type ToolRouterStrategy as g, type ToolSearchOptions as h, type ToolServerSummary as i, type ToolSummary as j };

package/dist/{tool-router-Ddtybmr0.d.ts → tool-router-CdX8e9bk.d.ts}

@@ -1,5 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { u as ToolClientProvider, T as ToolClient } from './types-BCAG20P6.js';
+import { u as ToolClientProvider, T as ToolClient } from './types-CxFaaZrM.js';
 
 /**
  * ToolIndex — Lightweight in-memory search index for MCP tool discovery.
@@ -64,6 +64,7 @@ interface IndexedTool extends Tool {
     sessionId: string;
     serverId: string;
     serverName: string;
+    outputSchema?: Tool['outputSchema'];
 }
 /**
  * An optional embedding function supplied by the consumer.
@@ -268,6 +269,20 @@ interface ToolRouterOptions {
      * @default false
      */
     compactSchemas?: boolean;
+    /**
+     * Tool names to expose directly when using `search` strategy.
+     * Pinned tools are removed from discovery results and should be called directly.
+     */
+    pinnedTools?: string[];
+    /**
+     * Tool names to omit from direct exposure while keeping them indexed for
+     * search/schema lookup/calls through meta-tools.
+     */
+    deferredTools?: string[];
+    /**
+     * Tool names or glob-style patterns to omit entirely from the router catalog.
+     */
+    excludeTools?: string[];
     /**
      * Optional embedding function for semantic search.
      * When not provided, keyword TF-IDF matching is used.
@@ -295,12 +310,18 @@ declare class ToolRouter {
     private options;
     private index;
     private allTools;
+    private pinnedTools;
+    private deferredTools;
+    private discoverableTools;
     private groupsMap;
     private strategy;
     private maxTools;
     private compactSchemas;
     private activeGroups;
     private customGroups?;
+    private pinnedToolNames;
+    private deferredToolNames;
+    private excludeToolMatchers;
     private initialized;
     constructor(client: ToolRouterClientInput, options?: ToolRouterOptions);
     /**
@@ -370,6 +391,10 @@ declare class ToolRouter {
     private getGroupFilteredTools;
     /** The 4 meta-tool definitions exposed in `search` strategy. */
     private getMetaToolDefinitions;
+    private matchesPinnedTool;
+    private matchesDeferredTool;
+    private matchesExcludedTool;
+    private getDirectlyVisibleTools;
 }
 
 export { type CompactTool as C, type EmbedFn as E, type IndexedTool as I, SchemaCompressor as S, type ToolGroupInfo as T, ToolIndex as a, type ToolIndexOptions as b, type ToolListResult as c, ToolRouter as d, type ToolRouterClientInput as e, type ToolRouterOptions as f, type ToolRouterStrategy as g, type ToolSearchOptions as h, type ToolServerSummary as i, type ToolSummary as j };

package/dist/{types-BCAG20P6.d.mts → types-CxFaaZrM.d.mts}

@@ -79,7 +79,8 @@ declare function isCallToolSuccess(response: CallToolResponse): response is Call
 type ToolInfo = {
     name: string;
     description?: string;
-    inputSchema?: unknown;
+    inputSchema?: Tool['inputSchema'];
+    outputSchema?: Tool['outputSchema'];
 };
 type TransportType = 'sse' | 'streamable-http';
 type McpRpcMethod = 'connect' | 'disconnect' | 'listTools' | 'callTool' | 'listSessions' | 'getSession' | 'finishAuth' | 'listPrompts' | 'getPrompt' | 'listResources' | 'readResource';

package/dist/{types-BCAG20P6.d.ts → types-CxFaaZrM.d.ts}

@@ -79,7 +79,8 @@ declare function isCallToolSuccess(response: CallToolResponse): response is Call
 type ToolInfo = {
     name: string;
     description?: string;
-    inputSchema?: unknown;
+    inputSchema?: Tool['inputSchema'];
+    outputSchema?: Tool['outputSchema'];
 };
 type TransportType = 'sse' | 'streamable-http';
 type McpRpcMethod = 'connect' | 'disconnect' | 'listTools' | 'callTool' | 'listSessions' | 'getSession' | 'finishAuth' | 'listPrompts' | 'getPrompt' | 'listResources' | 'readResource';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-ts/sdk",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "publishConfig": {
     "access": "public"
   },

package/src/shared/meta-tools.ts

@@ -135,16 +135,16 @@ export function createRegexSearchToolDefinition(): Tool {
  *
  * 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.
+ * input and output schemas for a specific tool so it can construct the
+ * correct arguments and plan around the result shape.
  */
 export function createGetSchemaToolDefinition(): Tool {
   return {
     name: 'mcp_get_tool_schema',
     description:
-      'Get the full input schema (parameters) for a specific tool. ' +
+      'Get the full input schema (parameters) and output schema (result shape) for a specific tool. ' +
       'Call this after mcp_search_tools to get the parameter details ' +
-      'needed to call a tool correctly. ' +
+      'needed to call a tool correctly and understand what it returns. ' +
       'Do NOT call the discovered tool directly; after reading the schema, call mcp_execute_tool.',
     inputSchema: {
       type: 'object' as const,
@@ -432,6 +432,7 @@ export async function executeMetaTool(
         name: tool.name,
         description: tool.description,
         inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
         executionInstructions: {
           nextTool: 'mcp_execute_tool',
           toolName: tool.name,

package/src/shared/tool-index.ts

@@ -72,6 +72,7 @@ export interface IndexedTool extends Tool {
   sessionId: string;
   serverId: string;
   serverName: string;
+  outputSchema?: Tool['outputSchema'];
 }
 
 /**

package/src/shared/tool-router.ts

@@ -99,6 +99,23 @@ export interface ToolRouterOptions {
    */
   compactSchemas?: boolean;
 
+  /**
+   * Tool names to expose directly when using `search` strategy.
+   * Pinned tools are removed from discovery results and should be called directly.
+   */
+  pinnedTools?: string[];
+
+  /**
+   * Tool names to omit from direct exposure while keeping them indexed for
+   * search/schema lookup/calls through meta-tools.
+   */
+  deferredTools?: string[];
+
+  /**
+   * Tool names or glob-style patterns to omit entirely from the router catalog.
+   */
+  excludeTools?: string[];
+
   /**
    * Optional embedding function for semantic search.
    * When not provided, keyword TF-IDF matching is used.
@@ -136,12 +153,18 @@ export type ToolRouterClientInput = ToolClientProvider | ToolClient[];
 export class ToolRouter {
   private index: ToolIndex;
   private allTools: IndexedTool[] = [];
+  private pinnedTools: IndexedTool[] = [];
+  private deferredTools: IndexedTool[] = [];
+  private discoverableTools: IndexedTool[] = [];
   private groupsMap = new Map<string, ToolGroupInfo>();
   private strategy: ToolRouterStrategy;
   private maxTools: number;
   private compactSchemas: boolean;
   private activeGroups: Set<string>;
   private customGroups?: Record<string, string[]>;
+  private pinnedToolNames: Set<string>;
+  private deferredToolNames: Set<string>;
+  private excludeToolMatchers: RegExp[];
   private initialized = false;
 
   constructor(
@@ -153,6 +176,11 @@ export class ToolRouter {
     this.compactSchemas = options.compactSchemas ?? false;
     this.activeGroups = new Set(options.activeGroups ?? []);
     this.customGroups = options.groups;
+    this.pinnedToolNames = new Set(options.pinnedTools ?? []);
+    this.deferredToolNames = new Set(options.deferredTools ?? []);
+    this.excludeToolMatchers = (options.excludeTools ?? []).map((pattern) =>
+      globToRegExp(pattern)
+    );
 
     this.index = new ToolIndex({
       embedFn: options.embedFn,
@@ -177,16 +205,17 @@ export class ToolRouter {
 
     switch (this.strategy) {
       case 'search':
-        return this.getMetaToolDefinitions();
+        return [...this.getMetaToolDefinitions(), ...this.pinnedTools];
 
       case 'groups':
         return this.getGroupFilteredTools();
 
       case 'all':
       default:
+        const directlyVisibleTools = this.getDirectlyVisibleTools();
         if (this.compactSchemas) {
           // Return tools with inputSchema stripped
-          return this.allTools.map((t) => {
+          return directlyVisibleTools.map((t) => {
             const compact = SchemaCompressor.toCompact(t);
             return {
               name: compact.name,
@@ -197,7 +226,7 @@ export class ToolRouter {
             };
           });
         }
-        return [...this.allTools];
+        return [...directlyVisibleTools];
     }
   }
 
@@ -352,8 +381,14 @@ export class ToolRouter {
   private async ensureInitialized(): Promise<void> {
     if (this.initialized) return;
 
-    this.allTools = await this.fetchAllTools();
-    await this.index.buildIndex(this.allTools);
+    const fetchedTools = await this.fetchAllTools();
+    this.allTools = fetchedTools.filter((tool) => !this.matchesExcludedTool(tool.name));
+    this.pinnedTools = this.allTools.filter((tool) => this.matchesPinnedTool(tool.name));
+    this.deferredTools = this.allTools.filter(
+      (tool) => !this.matchesPinnedTool(tool.name) && this.matchesDeferredTool(tool)
+    );
+    this.discoverableTools = this.allTools.filter((tool) => !this.matchesPinnedTool(tool.name));
+    await this.index.buildIndex(this.discoverableTools);
     this.buildGroups();
     this.initialized = true;
   }
@@ -447,7 +482,7 @@ export class ToolRouter {
       }
     }
 
-    const filtered = this.allTools.filter((t) => activeToolNames.has(t.name));
+    const filtered = this.getDirectlyVisibleTools().filter((t) => activeToolNames.has(t.name));
 
     if (this.compactSchemas) {
       return filtered.slice(0, this.maxTools).map((t) => {
@@ -476,4 +511,32 @@ export class ToolRouter {
     ];
   }
 
+  private matchesPinnedTool(toolName: string): boolean {
+    return this.pinnedToolNames.has(toolName);
+  }
+
+  private matchesDeferredTool(tool: Tool): boolean {
+    if (this.deferredToolNames.has(tool.name)) {
+      return true;
+    }
+
+    const meta = (tool as Tool & {
+      _meta?: { toolRouter?: { deferred?: boolean } };
+    })._meta;
+    return meta?.toolRouter?.deferred === true;
+  }
+
+  private matchesExcludedTool(toolName: string): boolean {
+    return this.excludeToolMatchers.some((matcher) => matcher.test(toolName));
+  }
+
+  private getDirectlyVisibleTools(): IndexedTool[] {
+    return this.allTools.filter((tool) => !this.matchesDeferredTool(tool) || this.matchesPinnedTool(tool.name));
+  }
+}
+
+function globToRegExp(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  const regexPattern = `^${escaped.replace(/\*/g, '.*')}$`;
+  return new RegExp(regexPattern);
 }

package/src/shared/types.ts

@@ -162,7 +162,8 @@ export function isCallToolSuccess(
 export type ToolInfo = {
   name: string;
   description?: string;
-  inputSchema?: unknown;
+  inputSchema?: Tool['inputSchema'];
+  outputSchema?: Tool['outputSchema'];
 };
 
 // Transport type