@mcp-ts/sdk 2.5.2 → 2.6.0

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, onSessionMutation, type SessionStore } from './storage/index.js';
+export { sessions, onSessionMutation, withDbObservability, type SessionStore } from './storage/index.js';
 export { StorageOAuthClientProvider } from './mcp/storage-oauth-provider.js';
 export { MultiSessionClient } from './mcp/multi-session-client.js';
 
@@ -20,6 +20,7 @@ export { createNextMcpHandler, type NextMcpHandlerOptions } from './handlers/nex
 
 /** Utilities */
 export { sanitizeServerLabel } from '../shared/utils';
+export { encryptObject, decryptObject } from './storage/crypto.js';
 
 /** Re-export shared types */
 export type {

package/src/server/mcp/multi-session-client.ts

@@ -1,5 +1,5 @@
 import { MCPClient } from './oauth-client.js';
-import { sessions, type Session } from '../storage/index.js';
+import { sessions, withDbObservability, type Session, type SessionStore } from '../storage/index.js';
 import type { ToolClient, ToolClientProvider } from '../../shared/types.js';
 import { createToolPolicyGateway } from './tool-policy-gateway.js';
 
@@ -35,6 +35,13 @@ export interface MultiSessionOptions {
      */
     retryDelay?: number;
 
+    /**
+     * Custom session store. When provided, all DB operations go through
+     * this store instead of the default global `sessions` singleton.
+     * Useful for wrapping with `withDbObservability()` for debugging.
+     */
+    sessionStore?: SessionStore;
+
     /**
      * Custom session provider. When provided, `connect()` calls this
      * instead of querying the storage backend. Useful when sessions are
@@ -45,6 +52,12 @@ export interface MultiSessionOptions {
      */
     sessionProvider?: () => Promise<Session[]>;
 
+    /**
+     * Attached to each MCPClient before connect() so all connection lifecycle
+     * events (INITIALIZING, CONNECTING, CONNECTED, etc.) are captured.
+     */
+    onObservabilityEvent?: McpObservabilityEventHandler;
+
     /**
      * Called after a session is successfully connected.
      */
@@ -62,6 +75,9 @@ export interface MultiSessionOptions {
     onSessionFailed?: (sessionId: string, error: unknown) => void;
 }
 
+/** @internal */
+type McpObservabilityEventHandler = (event: import('../../shared/events.js').McpObservabilityEvent) => void;
+
 // ---------------------------------------------------------------------------
 // MultiSessionClient
 // ---------------------------------------------------------------------------
@@ -81,7 +97,7 @@ export class MultiSessionClient implements ToolClientProvider {
     private connectionPromises = new Map<string, Promise<void>>();
     private userId: string;
     private options: Required<Pick<MultiSessionOptions, 'timeout' | 'maxRetries' | 'retryDelay'>> &
-        Pick<MultiSessionOptions, 'sessionProvider' | 'onSessionConnected' | 'onSessionEvicted' | 'onSessionFailed'>;
+        Pick<MultiSessionOptions, 'sessionProvider' | 'onObservabilityEvent' | 'onSessionConnected' | 'onSessionEvicted' | 'onSessionFailed'>;
 
     /**
      * @param userId - Unique identifier for the user (e.g. user ID or email).
@@ -95,8 +111,14 @@ export class MultiSessionClient implements ToolClientProvider {
             retryDelay: DEFAULT_RETRY_DELAY_MS,
             ...options,
         };
+
+        this._store = options.onObservabilityEvent
+            ? withDbObservability(options.sessionStore ?? sessions, options.onObservabilityEvent)
+            : (options.sessionStore ?? sessions);
     }
 
+    private _store: SessionStore;
+
     // -----------------------------------------------------------------------
     // Public API
     // -----------------------------------------------------------------------
@@ -112,12 +134,6 @@ export class MultiSessionClient implements ToolClientProvider {
         const sessions = await this.fetchActiveSessions();
         const activeSessionIds = new Set(sessions.map(s => s.sessionId));
 
-        // Evict clients whose sessions no longer appear in the active list.
-        // Without this, a stale MCPClient with a live SDK transport would
-        // stay in the clients array after its session was deleted externally
-        // (e.g. via the SSE handler's clearSession()), causing OAuth refreshes
-        // to fail with a FK violation when they try to patchCredentials()
-        // against the now-deleted session.
         for (const client of this.clients) {
             if (!activeSessionIds.has(client.getSessionId())) {
                 this.options.onSessionEvicted?.(client.getSessionId());
@@ -196,13 +212,14 @@ export class MultiSessionClient implements ToolClientProvider {
     private async fetchActiveSessions(): Promise<Session[]> {
         const sessionList = this.options.sessionProvider
             ? await this.options.sessionProvider()
-            : await sessions.list(this.userId);
+            : await this._store.list(this.userId);
 
         return sessionList.filter(s =>
             s.serverId &&
             s.serverUrl &&
             s.callbackUrl &&
-            s.status === 'active'
+            s.status === 'active' &&
+            s.enabled !== false
         );
     }
 
@@ -286,8 +303,15 @@ export class MultiSessionClient implements ToolClientProvider {
                     serverName: session.serverName,
                     transportType: session.transportType,
                     headers: session.headers,
+                    hasSession: true,
+                    sessionStore: this._store,
                 });
 
+                // Attach observability listener BEFORE connect to capture all lifecycle events
+                if (this.options.onObservabilityEvent) {
+                    client.onObservabilityEvent(this.options.onObservabilityEvent);
+                }
+
                 const timeoutMs = this.options.timeout;
                 let timeoutTimer: ReturnType<typeof setTimeout>;
                 const timeoutPromise = new Promise<never>((_, reject) => {