@mcp-ts/sdk 2.4.0 → 2.4.2

package/dist/{multi-session-client-CnvZEGPY.d.ts → multi-session-client-BluyCPo9.d.ts}

@@ -1,4 +1,4 @@
-import { b as Event, M as McpConnectionEvent, d as McpObservabilityEvent, c as McpConnectionState } from './events-CK3N--3g.js';
+import { m as Event, M as McpConnectionEvent, t as McpObservabilityEvent, s as McpConnectionState, A as ToolClientProvider } from './types-CjczQwNX.js';
 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';
@@ -282,10 +282,15 @@ declare class MCPClient {
      */
     isConnected(): boolean;
     /**
-     * Disconnects from the MCP server and cleans up resources
-     * Does not remove session from Redis - use clearSession() for that
+     * Disconnects from the MCP server and cleans up resources.
+     * Does not remove session from Redis — use clearSession() for that.
+     *
+     * For Streamable HTTP sessions, sends an HTTP DELETE to the MCP endpoint
+     * before closing, as recommended by the MCP Streamable HTTP spec
+     * (section "Session Management", rule 5). This is best-effort — errors
+     * (e.g. server already restarted, 404/405 responses) are silently ignored.
      */
-    disconnect(reason?: string): void;
+    disconnect(): Promise<void>;
     /**
      * Dispose of all event emitters
      * Call this when the client is no longer needed
@@ -323,115 +328,263 @@ 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;
+    /**
+     * 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;
 }
 /**
  * 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}
  */
-declare class MultiSessionClient {
+declare class MultiSessionClient implements ToolClientProvider {
     private clients;
+    private connectionPromises;
     private userId;
     private options;
     /**
-     * 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);
     /**
-     * Fetches all sessions for this userId from storage and returns only the
-     * ones that are ready to connect.
+     * Fetches active sessions and establishes connections to all of them.
      *
-     * 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.
+     * 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.
      */
-    private getActiveSessions;
+    connect(): Promise<void>;
     /**
-     * Connects to a list of sessions in controlled batches of `CONNECTION_BATCH_SIZE`.
+     * Drops all cached `MCPClient` instances and reconnects fresh from storage.
      *
-     * 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.
+     * 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.
      */
-    private connectInBatches;
-    private connectionPromises;
+    reconnect(): Promise<void>;
     /**
-     * Connects a single session, with built-in deduplication to prevent race conditions.
+     * Returns all currently connected `MCPClient` instances.
      *
-     * - If a client for this session already exists and is connected, returns immediately.
-     * - 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.
+     * Use this to enumerate available tools across all connected servers,
+     * or to route a tool call to the right client by `serverId`.
      */
-    private connectSession;
+    getClients(): MCPClient[];
     /**
-     * The core connection loop for a single session.
+     * Gracefully disconnects all active MCP clients and clears the internal list.
      *
-     * 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.
+     * 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.
      *
-     * 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.
+     * Call this during server shutdown or when a user logs out to free up
+     * underlying transport resources (SSE streams, HTTP connections, etc.).
      */
-    private establishConnectionWithRetries;
+    disconnect(): Promise<void>;
     /**
-     * The main entry point. Fetches all active sessions for this userId from
-     * storage and establishes connections to all of them in batches.
+     * Resolves the list of sessions to connect.
      *
-     * 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.
+     * Uses the custom `sessionProvider` when provided, otherwise falls back
+     * to querying the storage backend via `sessions.list(userId)`.
      */
-    connect(): Promise<void>;
+    private fetchActiveSessions;
     /**
-     * Returns all currently connected `MCPClient` instances.
+     * Connects a list of sessions in controlled batches.
      *
-     * Use this to enumerate available tools across all connected servers,
-     * or to route a tool call to the right client by `serverId`.
+     * 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`.
      */
-    getClients(): MCPClient[];
+    private connectInBatches;
     /**
-     * Gracefully disconnects all active MCP clients and clears the internal client list.
+     * Connects a single session, with deduplication to prevent race conditions.
      *
-     * Call this during server shutdown or when a user logs out to free up
-     * underlying transport resources (SSE streams, HTTP connections, etc.).
+     * - 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.
      */
-    disconnect(): void;
+    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 };