@mcp-ts/sdk 2.4.1 → 2.4.2

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

@@ -1,54 +1,90 @@
-
-
 import { MCPClient } from './oauth-client.js';
 import { sessions, type Session } from '../storage/index.js';
+import type { ToolClientProvider } from '../../shared/types.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
 
 const DEFAULT_TIMEOUT_MS = 15000;
 const DEFAULT_MAX_RETRIES = 2;
 const DEFAULT_RETRY_DELAY_MS = 1000;
 const CONNECTION_BATCH_SIZE = 5;
 
-/**
- * Manages multiple MCP connections for a single user.
- * Allows aggregating tools from all connected servers.
- */
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
 export interface MultiSessionOptions {
     /**
-     * Connection timeout in milliseconds
+     * Connection timeout in milliseconds.
      * @default 15000
      */
     timeout?: number;
+
     /**
-     * Maximum number of retry attempts
+     * Maximum number of retry attempts per session.
      * @default 2
      */
     maxRetries?: number;
+
     /**
-     * Delay between retries in milliseconds
+     * Delay between retry attempts in milliseconds.
      * @default 1000
      */
     retryDelay?: number;
+
+    /**
+     * Custom session provider. When provided, `connect()` calls this
+     * instead of querying the storage backend. Useful when sessions are
+     * synced externally (e.g. via Supabase Realtime, WebSocket, or an
+     * in-memory cache).
+     *
+     * Default: reads from the storage backend via `sessions.list(userId)`.
+     */
+    sessionProvider?: () => Promise<Session[]>;
+
+    /**
+     * Called after a session is successfully connected.
+     */
+    onSessionConnected?: (sessionId: string, client: MCPClient) => void;
+
+    /**
+     * Called when a session is evicted from the in-memory client list
+     * because it no longer exists in the active sessions list.
+     */
+    onSessionEvicted?: (sessionId: string) => void;
+
+    /**
+     * Called when all retry attempts for a session have been exhausted.
+     */
+    onSessionFailed?: (sessionId: string, error: unknown) => void;
 }
 
+// ---------------------------------------------------------------------------
+// MultiSessionClient
+// ---------------------------------------------------------------------------
+
 /**
  * Manages multiple MCP client connections for a single user.
  *
- * On a traditional long-running server, you can cache this instance per user
- * so the connections stay alive between requests. On serverless, a new instance
- * will be created per invocation, but the underlying session data is always
- * read from the storage backend so nothing is lost between calls.
+ * Cached instances stay alive between requests on long-running servers.
+ * On serverless, the underlying session data persists in storage — the
+ * client rehydrates from `sessionProvider` (or the default storage backend)
+ * each time `connect()` is called.
+ *
+ * @implements {ToolClientProvider}
  */
-export class MultiSessionClient {
+export class MultiSessionClient implements ToolClientProvider {
     private clients: MCPClient[] = [];
+    private connectionPromises = new Map<string, Promise<void>>();
     private userId: string;
-    private options: MultiSessionOptions;
+    private options: Required<Pick<MultiSessionOptions, 'timeout' | 'maxRetries' | 'retryDelay'>> &
+        Pick<MultiSessionOptions, 'sessionProvider' | 'onSessionConnected' | 'onSessionEvicted' | 'onSessionFailed'>;
 
     /**
-     * Creates a new MultiSessionClient for the given user userId.
-     *
-     * @param userId - A unique string identifying the user (e.g. user ID or email).
-     * @param options  - Optional tuning for connection timeout, retry count, and retry delay.
-     *                   Falls back to sensible defaults if not provided.
+     * @param userId - Unique identifier for the user (e.g. user ID or email).
+     * @param options - Optional tuning and lifecycle hooks.
      */
     constructor(userId: string, options: MultiSessionOptions = {}) {
         this.userId = userId;
@@ -56,36 +92,110 @@ export class MultiSessionClient {
             timeout: DEFAULT_TIMEOUT_MS,
             maxRetries: DEFAULT_MAX_RETRIES,
             retryDelay: DEFAULT_RETRY_DELAY_MS,
-            ...options
+            ...options,
         };
     }
 
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+
+    /**
+     * Fetches active sessions and establishes connections to all of them.
+     *
+     * Call this once after creating the client. On long-running servers you
+     * can cache the `MultiSessionClient` instance and call `connect()` on
+     * each request — already-connected sessions are skipped internally.
+     */
+    async connect(): Promise<void> {
+        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());
+            }
+        }
+        this.clients = this.clients.filter(c => activeSessionIds.has(c.getSessionId()));
+
+        await this.connectInBatches(sessions);
+    }
+
+    /**
+     * Drops all cached `MCPClient` instances and reconnects fresh from storage.
+     *
+     * Call this when downstream MCP servers have expired their transport sessions
+     * (e.g. after a remote server restart) and subsequent tool calls return
+     * "Session not found. Reconnect without session header." errors.
+     *
+     * OAuth tokens are preserved in the storage backend — no re-authentication
+     * is required. Only the in-memory transport sessions are cleared.
+     */
+    async reconnect(): Promise<void> {
+        await this.disconnect();
+        await this.connect();
+    }
+
+    /**
+     * Returns all currently connected `MCPClient` instances.
+     *
+     * Use this to enumerate available tools across all connected servers,
+     * or to route a tool call to the right client by `serverId`.
+     */
+    getClients(): MCPClient[] {
+        return this.clients;
+    }
+
+    /**
+     * Gracefully disconnects all active MCP clients and clears the internal list.
+     *
+     * For Streamable HTTP sessions, each client sends an HTTP DELETE to its MCP
+     * endpoint per the spec before closing locally. All disconnects run in
+     * parallel so shutdown is not serialised across many sessions.
+     *
+     * Call this during server shutdown or when a user logs out to free up
+     * underlying transport resources (SSE streams, HTTP connections, etc.).
+     */
+    async disconnect(): Promise<void> {
+        await Promise.all(this.clients.map((client) => client.disconnect()));
+        this.clients = [];
+    }
+
+    // -----------------------------------------------------------------------
+    // Internals
+    // -----------------------------------------------------------------------
+
     /**
-     * Fetches all sessions for this userId from storage and returns only the
-     * ones that are ready to connect.
+     * Resolves the list of sessions to connect.
      *
-     * A session is considered connectable when:
-     * - It has a `serverId`, `serverUrl`, and `callbackUrl` (i.e. it was fully initialized)
-     * - Its status is `active`. Pending sessions are skipped here
-     *   and let the OAuth flow complete separately before we try to reconnect them.
+     * Uses the custom `sessionProvider` when provided, otherwise falls back
+     * to querying the storage backend via `sessions.list(userId)`.
      */
-    private async getActiveSessions(): Promise<Session[]> {
-        const sessionList = await sessions.list(this.userId);
-        const valid = sessionList.filter(s =>
+    private async fetchActiveSessions(): Promise<Session[]> {
+        const sessionList = this.options.sessionProvider
+            ? await this.options.sessionProvider()
+            : await sessions.list(this.userId);
+
+        return sessionList.filter(s =>
             s.serverId &&
             s.serverUrl &&
             s.callbackUrl &&
             s.status === 'active'
         );
-        return valid;
     }
 
     /**
-     * Connects to a list of sessions in controlled batches of `CONNECTION_BATCH_SIZE`.
+     * Connects a list of sessions in controlled batches.
      *
-     * Batching prevents overwhelming the event loop or external servers when a user
-     * has many active MCP sessions (e.g. 20+ servers). Within each batch, sessions
-     * are connected concurrently using `Promise.all` for speed.
+     * Batching prevents overwhelming the event loop or external servers when
+     * a user has many active MCP sessions. Within each batch, sessions are
+     * connected concurrently using `Promise.all`.
      */
     private async connectInBatches(sessions: Session[]): Promise<void> {
         for (let i = 0; i < sessions.length; i += CONNECTION_BATCH_SIZE) {
@@ -94,38 +204,30 @@ export class MultiSessionClient {
         }
     }
 
-    private connectionPromises = new Map<string, Promise<void>>();
-
     /**
-     * Connects a single session, with built-in deduplication to prevent race conditions.
+     * Connects a single session, with deduplication to prevent race conditions.
      *
-     * - If a client for this session already exists and is connected, returns immediately.
-     * - If the existing client entry is no longer connected (e.g. it was explicitly
-     *   disconnected), it is evicted so that `establishConnectionWithRetries` creates a
-     *   fresh transport — preventing "Client already connected" errors from the SDK.
-     * - If a connection attempt for this session is already in-flight (e.g. from a
-     *   concurrent call), it joins the existing promise instead of starting a new one.
-     *   This is the key concurrency lock — the `connectionPromises` map acts as a
-     *   per-session mutex so we never spin up two physical connections for the same session.
-     * - On completion (success or failure), the promise is cleaned up from the map.
+     * - If a client for this session already exists and is connected, returns
+     *   immediately.
+     * - If the existing client entry is no longer connected (e.g. explicit
+     *   disconnect), it is evicted so a fresh transport is created.
+     * - If a connection attempt for this session is already in-flight, the
+     *   existing promise is reused as a per-session mutex.
+     * - On completion (success or failure), the promise is cleaned up from
+     *   the connectionPromises map.
      */
     private async connectSession(session: Session): Promise<void> {
         const existing = this.clients.find(c => c.getSessionId() === session.sessionId);
 
         if (existing) {
             if (existing.isConnected()) {
-                // Genuinely connected — nothing to do.
                 return;
             }
 
-            // Client entry exists but is no longer connected (explicit disconnect or
-            // a prior failed reconnect attempt). Remove it so the fresh connect below
-            // starts with a clean slate and the underlying SDK Client doesn't complain
-            // about an already-attached transport.
+            this.options.onSessionEvicted?.(existing.getSessionId());
             this.clients = this.clients.filter(c => c !== existing);
         }
 
-        // Avoid concurrent connection attempts for the same session
         if (this.connectionPromises.has(session.sessionId)) {
             return this.connectionPromises.get(session.sessionId)!;
         }
@@ -142,22 +244,19 @@ export class MultiSessionClient {
     }
 
     /**
-     * The core connection loop for a single session.
+     * Core connection loop for a single session with retry logic.
      *
-     * Attempts to establish a physical MCP connection, retrying up to `maxRetries` times
-     * if the connection fails. Each attempt:
-     * 1. Creates a fresh `MCPClient` instance from the session data.
-     * 2. Races the connect call against a timeout promise — if the server doesn't respond
-     *    within `timeoutMs`, the attempt is aborted and counted as a failure.
-     * 3. On success, replaces any stale client entry for this session in the `clients` array.
+     * 1. Creates a fresh `MCPClient` from the session data.
+     * 2. Races `client.connect()` against a timeout.
+     * 3. On success, replaces any stale entry and fires `onSessionConnected`.
      * 4. On failure, waits `retryDelay` ms before the next attempt.
      *
-     * If all attempts are exhausted, logs an error and returns silently (does not throw),
-     * so a single bad server doesn't block the rest of the batch from connecting.
+     * If all attempts are exhausted, logs an error and returns silently so
+     * a single bad server doesn't block the rest of the batch.
      */
     private async establishConnectionWithRetries(session: Session): Promise<void> {
-        const maxRetries = this.options.maxRetries ?? DEFAULT_MAX_RETRIES;
-        const retryDelay = this.options.retryDelay ?? DEFAULT_RETRY_DELAY_MS;
+        const maxRetries = this.options.maxRetries;
+        const retryDelay = this.options.retryDelay;
         let lastError: unknown;
 
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
@@ -173,10 +272,13 @@ export class MultiSessionClient {
                     headers: session.headers,
                 });
 
-                const timeoutMs = this.options.timeout ?? DEFAULT_TIMEOUT_MS;
+                const timeoutMs = this.options.timeout;
                 let timeoutTimer: ReturnType<typeof setTimeout>;
                 const timeoutPromise = new Promise<never>((_, reject) => {
-                    timeoutTimer = setTimeout(() => reject(new Error(`Connection timed out after ${timeoutMs}ms`)), timeoutMs);
+                    timeoutTimer = setTimeout(
+                        () => reject(new Error(`Connection timed out after ${timeoutMs}ms`)),
+                        timeoutMs,
+                    );
                 });
 
                 try {
@@ -185,10 +287,11 @@ export class MultiSessionClient {
                     clearTimeout(timeoutTimer!);
                 }
 
-                // Always replace the disconnected client entry
                 this.clients = this.clients.filter(c => c.getSessionId() !== session.sessionId);
                 this.clients.push(client);
-                return; // successfully connected
+                this.options.onSessionConnected?.(session.sessionId, client);
+                return;
+
             } catch (error) {
                 lastError = error;
                 if (attempt < maxRetries) {
@@ -197,69 +300,11 @@ export class MultiSessionClient {
             }
         }
 
-        console.error(`[MultiSessionClient] Failed to connect to session ${session.sessionId} after ${maxRetries + 1} attempts:`, lastError);
-    }
-
-    /**
-     * The main entry point. Fetches all active sessions for this userId from
-     * storage and establishes connections to all of them in batches.
-     *
-     * Call this once after creating the client. On traditional servers, you can
-     * cache the `MultiSessionClient` instance after calling `connect()` to avoid
-     * re-fetching and re-connecting on every request.
-     */
-    async connect(): Promise<void> {
-        const sessions = await this.getActiveSessions();
-        const activeSessionIds = new Set(sessions.map(s => s.sessionId));
-
-        // Prune stale clients whose sessions no longer exist in storage.
-        // Otherwise a lingering MCPClient with a still-alive SDK Client
-        // transport triggers OAuth refreshes on listTools(), and the
-        // StorageOAuthClientProvider.state() -> patchCredentials() call
-        // fails with a FK violation because the session was deleted.
-        this.clients = this.clients.filter(c => activeSessionIds.has(c.getSessionId()));
-
-        await this.connectInBatches(sessions);
-    }
-
-    /**
-     * Drops all cached `MCPClient` instances and reconnects fresh from storage.
-     *
-     * Call this when downstream MCP servers have expired their transport sessions
-     * (e.g. after a remote server restart) and subsequent tool calls return
-     * "Session not found. Reconnect without session header." errors.
-     *
-     * OAuth tokens are preserved in the storage backend — no re-authentication
-     * is required. Only the in-memory transport sessions are cleared.
-     */
-    async reconnect(): Promise<void> {
-        await this.disconnect();
-        await this.connect();
-    }
-
-    /**
-     * Returns all currently connected `MCPClient` instances.
-     *
-     * Use this to enumerate available tools across all connected servers,
-     * or to route a tool call to the right client by `serverId`.
-     */
-    getClients(): MCPClient[] {
-        return this.clients;
-    }
-
-    /**
-     * Gracefully disconnects all active MCP clients and clears the internal client list.
-     *
-     * For Streamable HTTP sessions, each client sends an HTTP DELETE to its MCP
-     * endpoint per the spec before closing locally. All disconnects run in
-     * parallel so shutdown is not serialised across many sessions.
-     *
-     * Call this during server shutdown or when a user logs out to free up
-     * underlying transport resources (SSE streams, HTTP connections, etc.).
-     */
-    async disconnect(): Promise<void> {
-        await Promise.all(this.clients.map((client) => client.disconnect()));
-        this.clients = [];
+        this.options.onSessionFailed?.(session.sessionId, lastError);
+        console.error(
+            `[MultiSessionClient] Failed to connect to session ${session.sessionId} ` +
+            `after ${maxRetries + 1} attempts:`,
+            lastError,
+        );
     }
 }
-

package/dist/events-C4m7tK1U.d.mts

@@ -1,122 +0,0 @@
-/**
- * Simple event emitter pattern for MCP connection events
- * Inspired by Cloudflare's agents pattern but adapted for serverless
- */
-type Disposable = {
-    dispose(): void;
-};
-type Event<T> = (listener: (event: T) => void) => Disposable;
-/**
- * Event emitter class for type-safe event handling
- * Similar to Cloudflare's Emitter but simplified for our use case
- */
-declare class Emitter<T> {
-    private listeners;
-    /**
-     * Subscribe to events
-     * @param listener - Callback function to handle events
-     * @returns Disposable to unsubscribe
-     */
-    get event(): Event<T>;
-    /**
-     * Fire an event to all listeners
-     * @param event - Event data to emit
-     */
-    fire(event: T): void;
-    /**
-     * Clear all listeners
-     */
-    dispose(): void;
-    /**
-     * Get number of active listeners
-     */
-    get listenerCount(): number;
-}
-/**
- * Connection state types matching your existing ConnectionStatus
- * Extended with more granular states for better observability
- */
-type McpConnectionState = 'DISCONNECTED' | 'CONNECTING' | 'AUTHENTICATING' | 'AUTHENTICATED' | 'DISCOVERING' | 'CONNECTED' | 'READY' | 'VALIDATING' | 'RECONNECTING' | 'INITIALIZING' | 'FAILED';
-/**
- * MCP Connection Event Types
- * Discriminated union for type-safe event handling
- */
-type McpConnectionEvent = {
-    type: 'state_changed';
-    sessionId: string;
-    serverId: string;
-    serverName: string;
-    serverUrl: string;
-    createdAt?: number;
-    state: McpConnectionState;
-    previousState: McpConnectionState;
-    timestamp: number;
-} | {
-    type: 'tools_discovered';
-    sessionId: string;
-    serverId: string;
-    toolCount: number;
-    tools: any[];
-    timestamp: number;
-} | {
-    type: 'auth_required';
-    sessionId: string;
-    serverId: string;
-    authUrl: string;
-    timestamp: number;
-} | {
-    type: 'error';
-    sessionId: string;
-    serverId: string;
-    error: string;
-    errorType: 'connection' | 'auth' | 'validation' | 'unknown';
-    timestamp: number;
-} | {
-    type: 'disconnected';
-    sessionId: string;
-    serverId: string;
-    timestamp: number;
-} | {
-    type: 'progress';
-    sessionId: string;
-    serverId: string;
-    message: string;
-    timestamp: number;
-};
-/**
- * Event fired when a tool execution returns a UI resource URI
- */
-interface McpAppsUIEvent {
-    type: 'mcp-apps-ui';
-    sessionId: string;
-    resourceUri: string;
-    toolName: string;
-    result: unknown;
-    timestamp: number;
-}
-/**
- * Observability event for debugging and monitoring
- */
-interface McpObservabilityEvent {
-    type?: string;
-    level?: 'debug' | 'info' | 'warn' | 'error';
-    message?: string;
-    displayMessage?: string;
-    sessionId?: string;
-    serverId?: string;
-    payload?: Record<string, any>;
-    metadata?: Record<string, any>;
-    timestamp: number;
-    id?: string;
-}
-/**
- * DisposableStore for managing multiple disposables
- * Useful for cleanup in React hooks
- */
-declare class DisposableStore {
-    private disposables;
-    add(disposable: Disposable): void;
-    dispose(): void;
-}
-
-export { type Disposable as D, Emitter as E, type McpConnectionEvent as M, DisposableStore as a, type Event as b, type McpConnectionState as c, type McpObservabilityEvent as d, type McpAppsUIEvent as e };

package/dist/events-C4m7tK1U.d.ts

@@ -1,122 +0,0 @@
-/**
- * Simple event emitter pattern for MCP connection events
- * Inspired by Cloudflare's agents pattern but adapted for serverless
- */
-type Disposable = {
-    dispose(): void;
-};
-type Event<T> = (listener: (event: T) => void) => Disposable;
-/**
- * Event emitter class for type-safe event handling
- * Similar to Cloudflare's Emitter but simplified for our use case
- */
-declare class Emitter<T> {
-    private listeners;
-    /**
-     * Subscribe to events
-     * @param listener - Callback function to handle events
-     * @returns Disposable to unsubscribe
-     */
-    get event(): Event<T>;
-    /**
-     * Fire an event to all listeners
-     * @param event - Event data to emit
-     */
-    fire(event: T): void;
-    /**
-     * Clear all listeners
-     */
-    dispose(): void;
-    /**
-     * Get number of active listeners
-     */
-    get listenerCount(): number;
-}
-/**
- * Connection state types matching your existing ConnectionStatus
- * Extended with more granular states for better observability
- */
-type McpConnectionState = 'DISCONNECTED' | 'CONNECTING' | 'AUTHENTICATING' | 'AUTHENTICATED' | 'DISCOVERING' | 'CONNECTED' | 'READY' | 'VALIDATING' | 'RECONNECTING' | 'INITIALIZING' | 'FAILED';
-/**
- * MCP Connection Event Types
- * Discriminated union for type-safe event handling
- */
-type McpConnectionEvent = {
-    type: 'state_changed';
-    sessionId: string;
-    serverId: string;
-    serverName: string;
-    serverUrl: string;
-    createdAt?: number;
-    state: McpConnectionState;
-    previousState: McpConnectionState;
-    timestamp: number;
-} | {
-    type: 'tools_discovered';
-    sessionId: string;
-    serverId: string;
-    toolCount: number;
-    tools: any[];
-    timestamp: number;
-} | {
-    type: 'auth_required';
-    sessionId: string;
-    serverId: string;
-    authUrl: string;
-    timestamp: number;
-} | {
-    type: 'error';
-    sessionId: string;
-    serverId: string;
-    error: string;
-    errorType: 'connection' | 'auth' | 'validation' | 'unknown';
-    timestamp: number;
-} | {
-    type: 'disconnected';
-    sessionId: string;
-    serverId: string;
-    timestamp: number;
-} | {
-    type: 'progress';
-    sessionId: string;
-    serverId: string;
-    message: string;
-    timestamp: number;
-};
-/**
- * Event fired when a tool execution returns a UI resource URI
- */
-interface McpAppsUIEvent {
-    type: 'mcp-apps-ui';
-    sessionId: string;
-    resourceUri: string;
-    toolName: string;
-    result: unknown;
-    timestamp: number;
-}
-/**
- * Observability event for debugging and monitoring
- */
-interface McpObservabilityEvent {
-    type?: string;
-    level?: 'debug' | 'info' | 'warn' | 'error';
-    message?: string;
-    displayMessage?: string;
-    sessionId?: string;
-    serverId?: string;
-    payload?: Record<string, any>;
-    metadata?: Record<string, any>;
-    timestamp: number;
-    id?: string;
-}
-/**
- * DisposableStore for managing multiple disposables
- * Useful for cleanup in React hooks
- */
-declare class DisposableStore {
-    private disposables;
-    add(disposable: Disposable): void;
-    dispose(): void;
-}
-
-export { type Disposable as D, Emitter as E, type McpConnectionEvent as M, DisposableStore as a, type Event as b, type McpConnectionState as c, type McpObservabilityEvent as d, type McpAppsUIEvent as e };