@mcp-ts/sdk 1.3.6 → 1.3.9

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';

package/dist/server/index.js

@@ -169,7 +169,8 @@ var SOFTWARE_VERSION = "1.3.4";
 var MCP_CLIENT_NAME = "mcp-ts-oauth-client";
 var MCP_CLIENT_VERSION = "2.0";
 
-// src/server/storage/redis-backend.ts
+// src/shared/utils.ts
+init_cjs_shims();
 var firstChar = nanoid.customAlphabet(
   "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
   1
@@ -178,6 +179,18 @@ var rest = nanoid.customAlphabet(
   "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
   11
 );
+function sanitizeServerLabel(name) {
+  let sanitized = name.replace(/[^a-zA-Z0-9-_]/g, "_").replace(/_{2,}/g, "_").toLowerCase();
+  if (!/^[a-zA-Z]/.test(sanitized)) {
+    sanitized = "s_" + sanitized;
+  }
+  return sanitized;
+}
+function generateSessionId() {
+  return firstChar() + rest();
+}
+
+// src/server/storage/redis-backend.ts
 var RedisStorageBackend = class {
   constructor(redis2) {
     this.redis = redis2;
@@ -236,7 +249,7 @@ var RedisStorageBackend = class {
     return Array.from(keys);
   }
   generateSessionId() {
-    return firstChar() + rest();
+    return generateSessionId();
   }
   async createSession(session, ttl) {
     const { sessionId, identity } = session;
@@ -407,14 +420,6 @@ var RedisStorageBackend = class {
 
 // src/server/storage/memory-backend.ts
 init_cjs_shims();
-var firstChar2 = nanoid.customAlphabet(
-  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
-  1
-);
-var rest2 = nanoid.customAlphabet(
-  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
-  11
-);
 var MemoryStorageBackend = class {
   constructor() {
     // Map<identity:sessionId, SessionData>
@@ -429,7 +434,7 @@ var MemoryStorageBackend = class {
     return `${identity}:${sessionId}`;
   }
   generateSessionId() {
-    return firstChar2() + rest2();
+    return generateSessionId();
   }
   async createSession(session, ttl) {
     const { sessionId, identity } = session;
@@ -503,14 +508,6 @@ var MemoryStorageBackend = class {
 
 // src/server/storage/file-backend.ts
 init_cjs_shims();
-var firstChar3 = nanoid.customAlphabet(
-  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
-  1
-);
-var rest3 = nanoid.customAlphabet(
-  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
-  11
-);
 var FileStorageBackend = class {
   /**
    * @param options.path Path to the JSON file storage (default: ./sessions.json)
@@ -561,7 +558,7 @@ var FileStorageBackend = class {
     return `${identity}:${sessionId}`;
   }
   generateSessionId() {
-    return firstChar3() + rest3();
+    return generateSessionId();
   }
   async createSession(session, ttl) {
     await this.ensureInitialized();
@@ -671,12 +668,7 @@ var SqliteStorage = class {
     }
   }
   generateSessionId() {
-    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
-    let result = "";
-    for (let i = 0; i < 32; i++) {
-      result += chars.charAt(Math.floor(Math.random() * chars.length));
-    }
-    return result;
+    return generateSessionId();
   }
   async createSession(session, ttl) {
     this.ensureInitialized();
@@ -791,7 +783,7 @@ var SupabaseStorageBackend = class {
     console.log('[mcp-ts][Storage] Supabase: \u2713 "mcp_sessions" table verified.');
   }
   generateSessionId() {
-    return crypto.randomUUID();
+    return generateSessionId();
   }
   mapRowToSessionData(row) {
     return {
@@ -1232,16 +1224,6 @@ var StorageOAuthClientProvider = class {
   }
 };
 
-// src/shared/utils.ts
-init_cjs_shims();
-function sanitizeServerLabel(name) {
-  let sanitized = name.replace(/[^a-zA-Z0-9-_]/g, "_").replace(/_{2,}/g, "_").toLowerCase();
-  if (!/^[a-zA-Z]/.test(sanitized)) {
-    sanitized = "s_" + sanitized;
-  }
-  return sanitized;
-}
-
 // src/shared/events.ts
 init_cjs_shims();
 var Emitter = class {
@@ -2207,47 +2189,132 @@ var MCPClient = class _MCPClient {
 
 // src/server/mcp/multi-session-client.ts
 init_cjs_shims();
+var DEFAULT_TIMEOUT_MS = 15e3;
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_RETRY_DELAY_MS = 1e3;
+var CONNECTION_BATCH_SIZE = 5;
 var MultiSessionClient = class {
+  /**
+   * 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, options = {}) {
     __publicField(this, "clients", []);
     __publicField(this, "identity");
     __publicField(this, "options");
+    __publicField(this, "connectionPromises", /* @__PURE__ */ new Map());
     this.identity = identity;
     this.options = {
-      timeout: 15e3,
-      maxRetries: 2,
-      retryDelay: 1e3,
+      timeout: DEFAULT_TIMEOUT_MS,
+      maxRetries: DEFAULT_MAX_RETRIES,
+      retryDelay: DEFAULT_RETRY_DELAY_MS,
       ...options
     };
   }
+  /**
+   * 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.
+   */
   async getActiveSessions() {
     const sessions = await storage.getIdentitySessionsData(this.identity);
-    console.log(
-      `[MultiSessionClient] All sessions for ${this.identity}:`,
-      sessions.map((s) => ({ sessionId: s.sessionId, serverId: s.serverId }))
+    const valid = sessions.filter(
+      (s) => s.serverId && s.serverUrl && s.callbackUrl && s.active !== false
+      // exclude OAuth-pending / failed sessions
     );
-    const valid = sessions.filter((s) => s.serverId && s.serverUrl && s.callbackUrl);
-    console.log(`[MultiSessionClient] Filtered valid sessions:`, valid.length);
     return valid;
   }
+  /**
+   * 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.
+   */
   async connectInBatches(sessions) {
-    const BATCH_SIZE = 5;
-    for (let i = 0; i < sessions.length; i += BATCH_SIZE) {
-      const batch = sessions.slice(i, i + BATCH_SIZE);
+    for (let i = 0; i < sessions.length; i += CONNECTION_BATCH_SIZE) {
+      const batch = sessions.slice(i, i + CONNECTION_BATCH_SIZE);
       await Promise.all(batch.map((session) => this.connectSession(session)));
     }
   }
+  /**
+   * 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.
+   */
   async connectSession(session) {
     const existingClient = this.clients.find((c) => c.getSessionId() === session.sessionId);
     if (existingClient?.isConnected()) {
       return;
     }
-    const maxRetries = this.options.maxRetries ?? 2;
-    const retryDelay = this.options.retryDelay ?? 1e3;
+    if (this.connectionPromises.has(session.sessionId)) {
+      return this.connectionPromises.get(session.sessionId);
+    }
+    const connectPromise = this.establishConnectionWithRetries(session);
+    this.connectionPromises.set(session.sessionId, connectPromise);
+    try {
+      await connectPromise;
+    } finally {
+      this.connectionPromises.delete(session.sessionId);
+    }
+  }
+  /**
+   * 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.
+   */
+  async establishConnectionWithRetries(session) {
+    const maxRetries = this.options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const retryDelay = this.options.retryDelay ?? DEFAULT_RETRY_DELAY_MS;
     let lastError;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       try {
-        const client = await this.createAndConnectClient(session);
+        const client = new MCPClient({
+          identity: this.identity,
+          sessionId: session.sessionId,
+          serverId: session.serverId,
+          serverUrl: session.serverUrl,
+          callbackUrl: session.callbackUrl,
+          serverName: session.serverName,
+          transportType: session.transportType,
+          headers: session.headers
+        });
+        const timeoutMs = this.options.timeout ?? DEFAULT_TIMEOUT_MS;
+        let timeoutTimer;
+        const timeoutPromise = new Promise((_, reject) => {
+          timeoutTimer = setTimeout(() => reject(new Error(`Connection timed out after ${timeoutMs}ms`)), timeoutMs);
+        });
+        try {
+          await Promise.race([client.connect(), timeoutPromise]);
+        } finally {
+          clearTimeout(timeoutTimer);
+        }
+        this.clients = this.clients.filter((c) => c.getSessionId() !== session.sessionId);
         this.clients.push(client);
         return;
       } catch (error) {
@@ -2259,36 +2326,32 @@ var MultiSessionClient = class {
     }
     console.error(`[MultiSessionClient] Failed to connect to session ${session.sessionId} after ${maxRetries + 1} attempts:`, lastError);
   }
-  async createAndConnectClient(session) {
-    const client = new MCPClient({
-      identity: this.identity,
-      sessionId: session.sessionId,
-      serverId: session.serverId,
-      serverUrl: session.serverUrl,
-      callbackUrl: session.callbackUrl,
-      serverName: session.serverName,
-      transportType: session.transportType,
-      headers: session.headers
-    });
-    const timeoutMs = this.options.timeout ?? 15e3;
-    const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(() => reject(new Error(`Connection timed out after ${timeoutMs}ms`)), timeoutMs);
-    });
-    await Promise.race([client.connect(), timeoutPromise]);
-    return client;
-  }
+  /**
+   * 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.
+   */
   async connect() {
     const sessions = await this.getActiveSessions();
     await this.connectInBatches(sessions);
   }
   /**
-   * 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() {
     return this.clients;
   }
   /**
-   * 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() {
     this.clients.forEach((client) => client.disconnect());