@mcp-ts/sdk 1.3.5 → 1.3.7

package/dist/{multi-session-client-BYLarghq.d.ts → multi-session-client-CHE8QpVE.d.ts}

@@ -367,25 +367,95 @@ interface MultiSessionOptions {
     retryDelay?: number;
 }
 /**
- * Manages multiple MCP connections for a single user identity.
- * Allows aggregating tools from all connected servers.
+ * Manages multiple MCP client connections for a single user identity.
+ *
+ * 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 identity;
     private options;
+    /**
+     * Creates a new MultiSessionClient for the given user identity.
+     *
+     * @param identity - 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.
+     */
     constructor(identity: string, options?: MultiSessionOptions);
+    /**
+     * Fetches all sessions for this identity 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 `active` flag is not explicitly `false` — sessions with `active: false` are
+     *   either mid-OAuth flow, auth-pending, or previously failed. We skip those here
+     *   and let the OAuth flow complete separately before we try to reconnect them.
+     *
+     * Note: Sessions where `active` is `undefined` (legacy records) are included
+     * for backwards compatibility.
+     */
     private getActiveSessions;
+    /**
+     * 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.
+     */
     private connectInBatches;
+    private connectionPromises;
+    /**
+     * 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 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.
+     */
     private connectSession;
-    private createAndConnectClient;
+    /**
+     * 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.
+     */
+    private establishConnectionWithRetries;
+    /**
+     * The main entry point. Fetches all active sessions for this identity 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.
+     */
     connect(): Promise<void>;
     /**
-     * Returns the array of currently connected clients.
+     * 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[];
     /**
-     * Disconnects all clients.
+     * Gracefully disconnects all active MCP clients and clears the internal client list.
+     *
+     * Call this during server shutdown or when a user logs out to free up
+     * underlying transport resources (SSE streams, HTTP connections, etc.).
      */
     disconnect(): void;
 }

package/dist/{multi-session-client-CzhMkE0k.d.mts → multi-session-client-CQsRbxYI.d.mts}

@@ -367,25 +367,95 @@ interface MultiSessionOptions {
     retryDelay?: number;
 }
 /**
- * Manages multiple MCP connections for a single user identity.
- * Allows aggregating tools from all connected servers.
+ * Manages multiple MCP client connections for a single user identity.
+ *
+ * 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 identity;
     private options;
+    /**
+     * Creates a new MultiSessionClient for the given user identity.
+     *
+     * @param identity - 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.
+     */
     constructor(identity: string, options?: MultiSessionOptions);
+    /**
+     * Fetches all sessions for this identity 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 `active` flag is not explicitly `false` — sessions with `active: false` are
+     *   either mid-OAuth flow, auth-pending, or previously failed. We skip those here
+     *   and let the OAuth flow complete separately before we try to reconnect them.
+     *
+     * Note: Sessions where `active` is `undefined` (legacy records) are included
+     * for backwards compatibility.
+     */
     private getActiveSessions;
+    /**
+     * 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.
+     */
     private connectInBatches;
+    private connectionPromises;
+    /**
+     * 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 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.
+     */
     private connectSession;
-    private createAndConnectClient;
+    /**
+     * 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.
+     */
+    private establishConnectionWithRetries;
+    /**
+     * The main entry point. Fetches all active sessions for this identity 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.
+     */
     connect(): Promise<void>;
     /**
-     * Returns the array of currently connected clients.
+     * 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[];
     /**
-     * Disconnects all clients.
+     * Gracefully disconnects all active MCP clients and clears the internal client list.
+     *
+     * Call this during server shutdown or when a user logs out to free up
+     * underlying transport resources (SSE streams, HTTP connections, etc.).
      */
     disconnect(): void;
 }

package/dist/server/index.d.mts

@@ -1,4 +1,4 @@
-export { M as MCPClient, a as MultiSessionClient, S as StorageOAuthClientProvider } from '../multi-session-client-CzhMkE0k.mjs';
+export { M as MCPClient, a as MultiSessionClient, S as StorageOAuthClientProvider } from '../multi-session-client-CQsRbxYI.mjs';
 export { U as UnauthorizedError, s as sanitizeServerLabel } from '../utils-0qmYrqoa.mjs';
 import { OAuthClientInformationMixed, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
 export { OAuthClientInformation, OAuthClientInformationFull, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-export { M as MCPClient, a as MultiSessionClient, S as StorageOAuthClientProvider } from '../multi-session-client-BYLarghq.js';
+export { M as MCPClient, a as MultiSessionClient, S as StorageOAuthClientProvider } from '../multi-session-client-CHE8QpVE.js';
 export { U as UnauthorizedError, s as sanitizeServerLabel } from '../utils-0qmYrqoa.js';
 import { OAuthClientInformationMixed, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
 export { OAuthClientInformation, OAuthClientInformationFull, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';