@mcp-ts/sdk 2.4.1 → 2.4.3

package/dist/{multi-session-client-k-9RvWvi.d.mts → multi-session-client-B6hsYO8V.d.mts}

@@ -1,4 +1,4 @@
-import { b as Event, M as McpConnectionEvent, d as McpObservabilityEvent, c as McpConnectionState } from './events-C4m7tK1U.mjs';
+import { m as Event, M as McpConnectionEvent, t as McpObservabilityEvent, s as McpConnectionState, A as ToolClientProvider } from './types-CjczQwNX.mjs';
 import { ListToolsResult, CallToolResult, ListPromptsResult, GetPromptResult, ListResourcesResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
 import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
 import { OAuthClientMetadata, OAuthClientInformationMixed, OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
@@ -264,6 +264,17 @@ declare class MCPClient {
      * @throws {Error} When client is not connected
      */
     readResource(uri: string): Promise<ReadResourceResult>;
+    /**
+     * Wraps an MCP request with automatic transport-session recovery.
+     *
+     * When the downstream MCP server rejects the request with a 404 indicating
+     * the transport session has expired, this method tears down the stale SDK
+     * client and transport, calls {@link reconnect} to negotiate a fresh session,
+     * and retries the request once.
+     *
+     * Non-transient errors (network failures, auth errors, etc.) propagate as-is.
+     */
+    private withRetry;
     /**
      * Reconnects to MCP server using existing OAuth provider from Redis
      * Used for session restoration in serverless environments
@@ -328,102 +339,192 @@ declare class MCPClient {
     getSessionId(): string;
 }
 
+interface OAuthState {
+    nonce: string;
+    sessionId: string;
+    serverId: string;
+    createdAt: number;
+}
+type SessionStatus = 'pending' | 'active';
+interface Session {
+    sessionId: string;
+    serverId?: string;
+    serverName?: string;
+    serverUrl: string;
+    transportType: 'sse' | 'streamable-http';
+    callbackUrl: string;
+    createdAt: number;
+    updatedAt?: number;
+    /**
+     * Storage-owned expiration timestamp for pending/inactive sessions.
+     * Active sessions use updatedAt-based dormancy cleanup instead.
+     */
+    expiresAt?: number | null;
+    userId: string;
+    headers?: Record<string, string>;
+    authUrl?: string | null;
+    /**
+     * Session status marker used for lifecycle cleanup:
+     * - pending: short-lived intermediate/auth-pending session state
+     * - active: restorable session after successful connection/auth completion
+     */
+    status?: SessionStatus;
+}
+interface SessionCredentials {
+    sessionId: string;
+    userId: string;
+    clientInformation?: OAuthClientInformationMixed | null;
+    tokens?: OAuthTokens | null;
+    codeVerifier?: string | null;
+    clientId?: string | null;
+    oauthState?: OAuthState | null;
+}
+type SessionMutationType = 'create' | 'update' | 'delete';
+interface SessionMutationEvent {
+    type: SessionMutationType;
+    userId: string;
+    sessionId: string;
+    timestamp: number;
+    session?: Session;
+    patch?: Partial<Session>;
+}
+type SessionMutationListener = (event: SessionMutationEvent) => void | Promise<void>;
 /**
- * Manages multiple MCP connections for a single user.
- * Allows aggregating tools from all connected servers.
+ * Interface for MCP session stores.
  */
+interface SessionStore {
+    /**
+     * Optional initialization (e.g., database connection)
+     */
+    init?(): Promise<void>;
+    /**
+     * Generates a unique session ID
+     */
+    generateSessionId(): string;
+    /**
+     * Creates a new session. Throws if session already exists.
+     * @param session - Session data to create
+     */
+    create(session: Session): Promise<void>;
+    /**
+     * Updates an existing session with partial data. Throws if session does not exist.
+     * @param userId - User identifier
+     * @param sessionId - Session identifier
+     * @param data - Partial session data to update
+     */
+    update(userId: string, sessionId: string, data: Partial<Session>): Promise<void>;
+    /**
+     * Patches runtime credentials for an existing session.
+     * These values are separated from connection metadata in durable SQL stores.
+     */
+    patchCredentials(userId: string, sessionId: string, data: Partial<SessionCredentials>): Promise<void>;
+    /**
+     * Retrieves a session
+     */
+    get(userId: string, sessionId: string): Promise<Session | null>;
+    /**
+     * Retrieves runtime credentials for a session.
+     */
+    getCredentials(userId: string, sessionId: string): Promise<SessionCredentials | null>;
+    /**
+     * Clears runtime credentials without removing connection metadata.
+     */
+    clearCredentials(userId: string, sessionId: string): Promise<void>;
+    /**
+     * Gets full session data for all sessions owned by a user
+     */
+    list(userId: string): Promise<Session[]>;
+    /**
+     * Removes a session
+     */
+    delete(userId: string, sessionId: string): Promise<void>;
+    /**
+     * Gets all session IDs owned by a user
+     */
+    listIds(userId: string): Promise<string[]>;
+    /**
+     * Gets all session IDs across all users (Admin)
+     */
+    listAllIds(): Promise<string[]>;
+    /**
+     * Clears all sessions (Admin)
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Clean up expired sessions
+     */
+    cleanupExpired(): Promise<void>;
+    /**
+     * Disconnect from storage backend
+     */
+    disconnect(): Promise<void>;
+}
+
 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;
-}
-/**
- * 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.
- */
-declare class MultiSessionClient {
-    private clients;
-    private userId;
-    private options;
     /**
-     * Creates a new MultiSessionClient for the given user userId.
+     * 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).
      *
-     * @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.
+     * Default: reads from the storage backend via `sessions.list(userId)`.
      */
-    constructor(userId: string, options?: MultiSessionOptions);
+    sessionProvider?: () => Promise<Session[]>;
     /**
-     * Fetches all sessions for this userId from storage and returns only the
-     * ones that are ready 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.
+     * Called after a session is successfully connected.
      */
-    private getActiveSessions;
+    onSessionConnected?: (sessionId: string, client: MCPClient) => void;
     /**
-     * Connects to a list of sessions in controlled batches of `CONNECTION_BATCH_SIZE`.
-     *
-     * 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.
+     * Called when a session is evicted from the in-memory client list
+     * because it no longer exists in the active sessions list.
      */
-    private connectInBatches;
-    private connectionPromises;
+    onSessionEvicted?: (sessionId: string) => void;
     /**
-     * Connects a single session, with built-in 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.
+     * Called when all retry attempts for a session have been exhausted.
      */
-    private connectSession;
+    onSessionFailed?: (sessionId: string, error: unknown) => void;
+}
+/**
+ * Manages multiple MCP client connections for a single user.
+ *
+ * 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}
+ */
+declare class MultiSessionClient implements ToolClientProvider {
+    private clients;
+    private connectionPromises;
+    private userId;
+    private options;
     /**
-     * The core connection loop for a single session.
-     *
-     * 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.
-     * 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.
+     * @param userId - Unique identifier for the user (e.g. user ID or email).
+     * @param options - Optional tuning and lifecycle hooks.
      */
-    private establishConnectionWithRetries;
+    constructor(userId: string, options?: MultiSessionOptions);
     /**
-     * The main entry point. Fetches all active sessions for this userId from
-     * storage and establishes connections to all of them in batches.
+     * Fetches active sessions and establishes connections to all of them.
      *
-     * 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.
+     * 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.
      */
     connect(): Promise<void>;
     /**
@@ -445,7 +546,13 @@ declare class MultiSessionClient {
      */
     getClients(): MCPClient[];
     /**
-     * Gracefully disconnects all active MCP clients and clears the internal client list.
+     * Removes and disconnects a single session by ID.
+     *
+     * @returns `true` if the session was found and removed, `false` if not found.
+     */
+    removeSession(sessionId: string): Promise<boolean>;
+    /**
+     * 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
@@ -455,6 +562,46 @@ declare class MultiSessionClient {
      * underlying transport resources (SSE streams, HTTP connections, etc.).
      */
     disconnect(): Promise<void>;
+    /**
+     * Resolves the list of sessions to connect.
+     *
+     * Uses the custom `sessionProvider` when provided, otherwise falls back
+     * to querying the storage backend via `sessions.list(userId)`.
+     */
+    private fetchActiveSessions;
+    /**
+     * 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. Within each batch, sessions are
+     * connected concurrently using `Promise.all`.
+     */
+    private connectInBatches;
+    /**
+     * 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. 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 connectSession;
+    /**
+     * Core connection loop for a single session with retry logic.
+     *
+     * 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 so
+     * a single bad server doesn't block the rest of the batch.
+     */
+    private establishConnectionWithRetries;
 }
 
-export { MCPClient as M, StorageOAuthClientProvider as S, MultiSessionClient as a };
+export { MCPClient as M, type Session as S, MultiSessionClient as a, type SessionMutationEvent as b, type SessionMutationListener as c, type SessionMutationType as d, type SessionStore as e, StorageOAuthClientProvider as f };