@mcp-ts/sdk 2.1.0 → 2.3.0

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

@@ -274,6 +274,11 @@ interface ToolRouterOptions {
      * 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.
      */
@@ -306,6 +311,7 @@ declare class ToolRouter {
     private index;
     private allTools;
     private pinnedTools;
+    private deferredTools;
     private discoverableTools;
     private groupsMap;
     private strategy;
@@ -314,6 +320,7 @@ declare class ToolRouter {
     private activeGroups;
     private customGroups?;
     private pinnedToolNames;
+    private deferredToolNames;
     private excludeToolMatchers;
     private initialized;
     constructor(client: ToolRouterClientInput, options?: ToolRouterOptions);
@@ -385,7 +392,9 @@ declare class ToolRouter {
     /** 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-BP8TT9mI.d.ts → tool-router-CdX8e9bk.d.ts}

@@ -274,6 +274,11 @@ interface ToolRouterOptions {
      * 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.
      */
@@ -306,6 +311,7 @@ declare class ToolRouter {
     private index;
     private allTools;
     private pinnedTools;
+    private deferredTools;
     private discoverableTools;
     private groupsMap;
     private strategy;
@@ -314,6 +320,7 @@ declare class ToolRouter {
     private activeGroups;
     private customGroups?;
     private pinnedToolNames;
+    private deferredToolNames;
     private excludeToolMatchers;
     private initialized;
     constructor(client: ToolRouterClientInput, options?: ToolRouterOptions);
@@ -385,7 +392,9 @@ declare class ToolRouter {
     /** 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/package.json

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

package/src/server/index.ts

@@ -6,7 +6,7 @@
 /** Core MCP client and session management */
 export { MCPClient } from './mcp/oauth-client.js';
 export { UnauthorizedError } from '../shared/errors.js';
-export { sessions, type SessionStore } from './storage/index.js';
+export { sessions, onSessionMutation, type SessionStore } from './storage/index.js';
 export { StorageOAuthClientProvider } from './mcp/storage-oauth-provider.js';
 export { MultiSessionClient } from './mcp/multi-session-client.js';
 
@@ -44,6 +44,13 @@ export type {
   CallToolResponse,
 } from '../shared/types';
 
+export type {
+  Session,
+  SessionMutationEvent,
+  SessionMutationListener,
+  SessionMutationType,
+} from './storage/types.js';
+
 /** Re-export MCP SDK types for convenience */
 export type {
   OAuthClientMetadata,

package/src/server/storage/index.ts

@@ -5,7 +5,7 @@ import { FileStorageBackend } from './file-backend';
 import { SqliteStorage } from './sqlite-backend.js';
 import { SupabaseStorageBackend } from './supabase-backend.js';
 import { NeonStorageBackend, type NeonStorageOptions } from './neon-backend.js';
-import type { SessionStore } from './types.js';
+import type { SessionStore, Session, SessionMutationEvent, SessionMutationListener } from './types.js';
 
 // Re-export types
 export * from './types.js';
@@ -42,6 +42,65 @@ function warnIfNeonConnectionStringIsInsecure(connectionString: string): void {
 
 let storageInstance: SessionStore | null = null;
 let storagePromise: Promise<SessionStore> | null = null;
+const sessionMutationListeners = new Set<SessionMutationListener>();
+
+function emitSessionMutation(event: SessionMutationEvent): void {
+    for (const listener of sessionMutationListeners) {
+        try {
+            const result = listener(event);
+            if (result && typeof (result as Promise<void>).catch === 'function') {
+                void (result as Promise<void>).catch((error) => {
+                    console.error('[mcp-ts][Storage] Session mutation listener failed:', error);
+                });
+            }
+        } catch (error) {
+            console.error('[mcp-ts][Storage] Session mutation listener failed:', error);
+        }
+    }
+}
+
+function createSessionMutationEvent(prop: PropertyKey, args: any[]): SessionMutationEvent | null {
+    const timestamp = Date.now();
+
+    if (prop === 'create') {
+        const [session, ttl] = args as [Session, number | undefined];
+        if (!session?.userId || !session?.sessionId) return null;
+        return {
+            type: 'create',
+            userId: session.userId,
+            sessionId: session.sessionId,
+            session,
+            ttl,
+            timestamp,
+        };
+    }
+
+    if (prop === 'update') {
+        const [userId, sessionId, patch, ttl] = args as [string, string, Partial<Session>, number | undefined];
+        if (!userId || !sessionId) return null;
+        return {
+            type: 'update',
+            userId,
+            sessionId,
+            patch,
+            ttl,
+            timestamp,
+        };
+    }
+
+    if (prop === 'delete') {
+        const [userId, sessionId] = args as [string, string];
+        if (!userId || !sessionId) return null;
+        return {
+            type: 'delete',
+            userId,
+            sessionId,
+            timestamp,
+        };
+    }
+
+    return null;
+}
 
 async function initializeStorage<T extends SessionStore>(store: T): Promise<T> {
     if (typeof store.init === 'function') {
@@ -215,6 +274,17 @@ export function _setStorageInstanceForTesting(instance: SessionStore | null): vo
     }
 }
 
+export function onSessionMutation(listener: SessionMutationListener): () => void {
+    sessionMutationListeners.add(listener);
+    return () => {
+        sessionMutationListeners.delete(listener);
+    };
+}
+
+export function _resetSessionMutationListenersForTesting(): void {
+    sessionMutationListeners.clear();
+}
+
 /**
  * Global session store instance
  * Uses lazy initialization with a Proxy to handle async setup transparently
@@ -225,7 +295,12 @@ export const sessions: SessionStore = new Proxy({} as SessionStore, {
             const instance = await getStorage();
             const value = (instance as any)[prop];
             if (typeof value === 'function') {
-                return value.apply(instance, args);
+                const result = await value.apply(instance, args);
+                const event = createSessionMutationEvent(prop, args);
+                if (event) {
+                    emitSessionMutation(event);
+                }
+                return result;
             }
             return value;
         };

package/src/server/storage/types.ts

@@ -29,6 +29,20 @@ export interface Session {
     clientId?: string;
 }
 
+export type SessionMutationType = 'create' | 'update' | 'delete';
+
+export interface SessionMutationEvent {
+    type: SessionMutationType;
+    userId: string;
+    sessionId: string;
+    timestamp: number;
+    session?: Session;
+    patch?: Partial<Session>;
+    ttl?: number;
+}
+
+export type SessionMutationListener = (event: SessionMutationEvent) => void | Promise<void>;
+
 export interface SetClientOptions {
     sessionId: string;
     serverId?: string; // Database server ID

package/src/shared/tool-router.ts

@@ -105,6 +105,12 @@ export interface ToolRouterOptions {
    */
   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.
    */
@@ -148,6 +154,7 @@ 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;
@@ -156,6 +163,7 @@ export class ToolRouter {
   private activeGroups: Set<string>;
   private customGroups?: Record<string, string[]>;
   private pinnedToolNames: Set<string>;
+  private deferredToolNames: Set<string>;
   private excludeToolMatchers: RegExp[];
   private initialized = false;
 
@@ -169,6 +177,7 @@ export class ToolRouter {
     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)
     );
@@ -203,9 +212,10 @@ export class ToolRouter {
 
       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,
@@ -216,7 +226,7 @@ export class ToolRouter {
             };
           });
         }
-        return [...this.allTools];
+        return [...directlyVisibleTools];
     }
   }
 
@@ -374,6 +384,9 @@ export class ToolRouter {
     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();
@@ -469,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) => {
@@ -502,9 +515,24 @@ export class ToolRouter {
     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 {