@mcp-ts/sdk 1.6.2 → 2.0.0

package/src/server/handlers/sse-handler.ts

@@ -26,7 +26,7 @@ import type {
   SessionListResult,
   ConnectResult,
   DisconnectResult,
-  RestoreSessionResult,
+  GetSessionResult,
   FinishAuthResult,
   ListToolsRpcResult,
   ListPromptsResult,
@@ -37,7 +37,7 @@ import { RpcErrorCodes } from '../../shared/errors.js';
 import { UnauthorizedError } from '../../shared/errors.js';
 import { isConnectionEvent, isRpcResponseEvent } from '../../shared/event-routing.js';
 import { MCPClient } from '../mcp/oauth-client.js';
-import { storage } from '../storage/index.js';
+import { sessions } from '../storage/index.js';
 
 // ============================================
 // Types & Interfaces
@@ -52,10 +52,10 @@ export interface ClientMetadata {
 
 export interface SSEHandlerOptions {
   /** User/Client identifier */
-  identity: string;
+  userId: string;
 
   /** Optional callback for authentication/authorization */
-  onAuth?: (identity: string) => Promise<boolean>;
+  onAuth?: (userId: string) => Promise<boolean>;
 
   /** Heartbeat interval in milliseconds @default 30000 */
   heartbeatInterval?: number;
@@ -92,7 +92,7 @@ function normalizeHeaders(headers?: Record<string, string>): Record<string, stri
  * Each instance corresponds to one connected browser client.
  */
 export class SSEConnectionManager {
-  private readonly identity: string;
+  private readonly userId: string;
   private readonly clients = new Map<string, MCPClient>();
   private heartbeatTimer?: NodeJS.Timeout;
   private isActive = true;
@@ -101,7 +101,7 @@ export class SSEConnectionManager {
     private readonly options: SSEHandlerOptions,
     private readonly sendEvent: (event: McpConnectionEvent | McpObservabilityEvent | McpRpcResponse) => void
   ) {
-    this.identity = options.identity;
+    this.userId = options.userId;
     this.startHeartbeat();
   }
 
@@ -148,11 +148,11 @@ export class SSEConnectionManager {
    */
   async handleRequest(request: McpRpcRequest): Promise<McpRpcResponse> {
     try {
-      let result: SessionListResult | ConnectResult | DisconnectResult | RestoreSessionResult | FinishAuthResult | ListToolsRpcResult | ListPromptsResult | ListResourcesResult | unknown;
+      let result: SessionListResult | ConnectResult | DisconnectResult | GetSessionResult | FinishAuthResult | ListToolsRpcResult | ListPromptsResult | ListResourcesResult | unknown;
 
       switch (request.method) {
-        case 'getSessions':
-          result = await this.getSessions();
+        case 'listSessions':
+          result = await this.listSessions();
           break;
 
         case 'connect':
@@ -171,8 +171,8 @@ export class SSEConnectionManager {
           result = await this.callTool(request.params as CallToolParams);
           break;
 
-        case 'restoreSession':
-          result = await this.restoreSession(request.params as SessionParams);
+        case 'getSession':
+          result = await this.getSession(request.params as SessionParams);
           break;
 
         case 'finishAuth':
@@ -225,13 +225,13 @@ export class SSEConnectionManager {
   }
 
   /**
-   * Get all sessions for the current identity
+   * Get all sessions for the current userId
    */
-  private async getSessions(): Promise<SessionListResult> {
-    const sessions = await storage.getIdentitySessionsData(this.identity);
+  private async listSessions(): Promise<SessionListResult> {
+    const sessionList = await sessions.list(this.userId);
 
     return {
-      sessions: sessions.map((s) => ({
+      sessions: sessionList.map((s) => ({
         sessionId: s.sessionId,
         serverId: s.serverId,
         serverName: s.serverName,
@@ -254,10 +254,10 @@ export class SSEConnectionManager {
     // Tool name format: tool_<serverId>_<toolName> - with 12 char serverId leaves 46 chars for tool name
     const serverId = params.serverId && params.serverId.length <= 12
       ? params.serverId
-      : await storage.generateSessionId();
+      : await sessions.generateSessionId();
 
     // Check for existing connections
-    const existingSessions = await storage.getIdentitySessionsData(this.identity);
+    const existingSessions = await sessions.list(this.userId);
     const duplicate = existingSessions.find(s =>
       s.serverId === serverId || s.serverUrl === serverUrl
     );
@@ -266,7 +266,7 @@ export class SSEConnectionManager {
       // If the existing session is still pending OAuth, treat connect as "resume auth"
       // instead of failing with duplicate connection error.
       if (duplicate.active === false) {
-        await this.restoreSession({ sessionId: duplicate.sessionId });
+        await this.getSession({ sessionId: duplicate.sessionId });
         return {
           sessionId: duplicate.sessionId,
           success: true,
@@ -276,7 +276,7 @@ export class SSEConnectionManager {
     }
 
     // Generate session ID
-    const sessionId = await storage.generateSessionId();
+    const sessionId = await sessions.generateSessionId();
 
     try {
       // Get resolved client metadata
@@ -284,7 +284,7 @@ export class SSEConnectionManager {
 
       // Create MCP client
       const client = new MCPClient({
-        identity: this.identity,
+        userId: this.userId,
         sessionId,
         serverId,
         serverName,
@@ -360,7 +360,7 @@ export class SSEConnectionManager {
     } else {
       // Handle orphaned sessions (e.g., OAuth flow failed before client was stored)
       // Directly remove from storage since there's no active client
-      await storage.removeSession(this.identity, sessionId);
+      await sessions.delete(this.userId, sessionId);
     }
 
     return { success: true };
@@ -375,13 +375,13 @@ export class SSEConnectionManager {
       return existing;
     }
 
-    const session = await storage.getSession(this.identity, sessionId);
+    const session = await sessions.get(this.userId, sessionId);
     if (!session) {
       throw new Error('Session not found');
     }
 
     const client = new MCPClient({
-      identity: this.identity,
+      userId: this.userId,
       sessionId,
       // These fields are optional in MCPClient, but when rehydrating a known
       // stored session on the server we pass them explicitly to preserve the
@@ -439,10 +439,10 @@ export class SSEConnectionManager {
   /**
    * Restore and validate an existing session
    */
-  private async restoreSession(params: SessionParams): Promise<RestoreSessionResult> {
+  private async getSession(params: SessionParams): Promise<GetSessionResult> {
     const { sessionId } = params;
 
-    const session = await storage.getSession(this.identity, sessionId);
+    const session = await sessions.get(this.userId, sessionId);
     if (!session) {
       throw new Error('Session not found');
     }
@@ -462,7 +462,7 @@ export class SSEConnectionManager {
       const clientMetadata = await this.getResolvedClientMetadata();
 
       const client = new MCPClient({
-        identity: this.identity,
+        userId: this.userId,
         sessionId,
         // These fields are optional in MCPClient, but when rehydrating a known
         // stored session on the server we pass them explicitly to preserve the
@@ -506,14 +506,14 @@ export class SSEConnectionManager {
   private async finishAuth(params: FinishAuthParams): Promise<FinishAuthResult> {
     const { sessionId, code } = params;
 
-    const session = await storage.getSession(this.identity, sessionId);
+    const session = await sessions.get(this.userId, sessionId);
     if (!session) {
       throw new Error('Session not found');
     }
 
     try {
       const client = new MCPClient({
-        identity: this.identity,
+        userId: this.userId,
         sessionId,
         // These fields are optional in MCPClient, but when rehydrating a known
         // stored session on the server we pass them explicitly to preserve the
@@ -524,7 +524,7 @@ export class SSEConnectionManager {
         serverUrl: session.serverUrl,
         callbackUrl: session.callbackUrl,
         // NOTE: transportType is intentionally omitted here.
-        // The session's stored transportType is a placeholder ('streamable_http')
+        // The session's stored transportType is a placeholder ('streamable-http')
         // set before transport negotiation. Omitting it lets MCPClient auto-negotiate
         // (try streamable_http → SSE fallback), which is critical for servers like
         // Neon that only support SSE transport.

package/src/server/index.ts

@@ -6,7 +6,7 @@
 /** Core MCP client and session management */
 export { MCPClient } from './mcp/oauth-client.js';
 export { UnauthorizedError } from '../shared/errors.js';
-export { storage, type StorageBackend } from './storage/index.js';
+export { sessions, type SessionStore } from './storage/index.js';
 export { StorageOAuthClientProvider } from './mcp/storage-oauth-provider.js';
 export { MultiSessionClient } from './mcp/multi-session-client.js';
 

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

@@ -1,7 +1,7 @@
 
 
 import { MCPClient } from './oauth-client.js';
-import { storage, type SessionData } from '../storage/index.js';
+import { sessions, type Session } from '../storage/index.js';
 
 const DEFAULT_TIMEOUT_MS = 15000;
 const DEFAULT_MAX_RETRIES = 2;
@@ -9,7 +9,7 @@ const DEFAULT_RETRY_DELAY_MS = 1000;
 const CONNECTION_BATCH_SIZE = 5;
 
 /**
- * Manages multiple MCP connections for a single user identity.
+ * Manages multiple MCP connections for a single user.
  * Allows aggregating tools from all connected servers.
  */
 export interface MultiSessionOptions {
@@ -31,7 +31,7 @@ export interface MultiSessionOptions {
 }
 
 /**
- * Manages multiple MCP client connections for a single user identity.
+ * 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
@@ -40,18 +40,18 @@ export interface MultiSessionOptions {
  */
 export class MultiSessionClient {
     private clients: MCPClient[] = [];
-    private identity: string;
+    private userId: string;
     private options: MultiSessionOptions;
 
     /**
-     * Creates a new MultiSessionClient for the given user identity.
+     * Creates a new MultiSessionClient for the given user userId.
      *
-     * @param identity - A unique string identifying the user (e.g. user ID or email).
+     * @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.
      */
-    constructor(identity: string, options: MultiSessionOptions = {}) {
-        this.identity = identity;
+    constructor(userId: string, options: MultiSessionOptions = {}) {
+        this.userId = userId;
         this.options = {
             timeout: DEFAULT_TIMEOUT_MS,
             maxRetries: DEFAULT_MAX_RETRIES,
@@ -61,7 +61,7 @@ export class MultiSessionClient {
     }
 
     /**
-     * Fetches all sessions for this identity from storage and returns only the
+     * Fetches all sessions for this userId from storage and returns only the
      * ones that are ready to connect.
      *
      * A session is considered connectable when:
@@ -73,9 +73,9 @@ export class MultiSessionClient {
      * Note: Sessions where `active` is `undefined` (legacy records) are included
      * for backwards compatibility.
      */
-    private async getActiveSessions(): Promise<SessionData[]> {
-        const sessions = await storage.getIdentitySessionsData(this.identity);
-        const valid = sessions.filter(s =>
+    private async getActiveSessions(): Promise<Session[]> {
+        const sessionList = await sessions.list(this.userId);
+        const valid = sessionList.filter(s =>
             s.serverId &&
             s.serverUrl &&
             s.callbackUrl &&
@@ -91,7 +91,7 @@ export class MultiSessionClient {
      * has many active MCP sessions (e.g. 20+ servers). Within each batch, sessions
      * are connected concurrently using `Promise.all` for speed.
      */
-    private async connectInBatches(sessions: SessionData[]): Promise<void> {
+    private async connectInBatches(sessions: Session[]): Promise<void> {
         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)));
@@ -110,7 +110,7 @@ export class MultiSessionClient {
      *   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 async connectSession(session: SessionData): Promise<void> {
+    private async connectSession(session: Session): Promise<void> {
         const existingClient = this.clients.find(c => c.getSessionId() === session.sessionId);
         if (existingClient?.isConnected()) {
             return;
@@ -146,7 +146,7 @@ export class MultiSessionClient {
      * 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 async establishConnectionWithRetries(session: SessionData): Promise<void> {
+    private async establishConnectionWithRetries(session: Session): Promise<void> {
         const maxRetries = this.options.maxRetries ?? DEFAULT_MAX_RETRIES;
         const retryDelay = this.options.retryDelay ?? DEFAULT_RETRY_DELAY_MS;
         let lastError: unknown;
@@ -154,7 +154,7 @@ export class MultiSessionClient {
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
                 const client = new MCPClient({
-                    identity: this.identity,
+                    userId: this.userId,
                     sessionId: session.sessionId,
                     serverId: session.serverId,
                     serverUrl: session.serverUrl,
@@ -192,7 +192,7 @@ export class MultiSessionClient {
     }
 
     /**
-     * The main entry point. Fetches all active sessions for this identity from
+     * 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

package/src/server/mcp/oauth-client.ts

@@ -33,7 +33,7 @@ import { StorageOAuthClientProvider, type AgentsOAuthProvider } from './storage-
 import { sanitizeServerLabel } from '../../shared/utils.js';
 import { Emitter, type McpConnectionEvent, type McpObservabilityEvent, type McpConnectionState } from '../../shared/events.js';
 import { UnauthorizedError } from '../../shared/errors.js';
-import { storage } from '../storage/index.js';
+import { sessions } from '../storage/index.js';
 import {
   MCP_CLIENT_NAME,
   MCP_CLIENT_VERSION,
@@ -44,7 +44,7 @@ import {
 /**
  * Supported MCP transport types
  */
-export type TransportType = 'sse' | 'streamable_http';
+export type TransportType = 'sse' | 'streamable-http';
 
 /**
  * Extended capabilities including MCP App support
@@ -65,7 +65,7 @@ export interface MCPOAuthClientOptions {
   serverName?: string;
   callbackUrl?: string;
   onRedirect?: (url: string) => void;
-  identity: string;
+  userId: string;
   serverId?: string; /** Optional - loaded from session if not provided */
   sessionId: string; /** Required - primary key for session lookup */
   transportType?: TransportType;
@@ -88,7 +88,7 @@ export class MCPClient {
   private client: Client | null = null;
   public oauthProvider: AgentsOAuthProvider | null = null;
   private transport: StreamableHTTPClientTransport | SSEClientTransport | null = null;
-  private identity: string;
+  private userId: string;
   private serverId?: string;
   private sessionId: string;
   private serverName?: string;
@@ -118,7 +118,7 @@ export class MCPClient {
 
   /**
    * Creates a new MCP client instance
-   * Can be initialized with minimal options (identity + sessionId) for session restoration
+   * Can be initialized with minimal options (userId + sessionId) for session restoration
    * @param options - Client configuration options
    */
   constructor(options: MCPOAuthClientOptions) {
@@ -126,7 +126,7 @@ export class MCPClient {
     this.serverName = options.serverName;
     this.callbackUrl = options.callbackUrl;
     this.onRedirect = options.onRedirect;
-    this.identity = options.identity;
+    this.userId = options.userId;
     this.serverId = options.serverId;
     this.sessionId = options.sessionId;
     this.transportType = options.transportType;
@@ -283,7 +283,7 @@ export class MCPClient {
     this.emitProgress('Loading session configuration...');
 
     if (!this.serverUrl || !this.callbackUrl || !this.serverId) {
-      const sessionData = await storage.getSession(this.identity, this.sessionId);
+      const sessionData = await sessions.get(this.userId, this.sessionId);
       if (!sessionData) {
         throw new Error(`Session not found: ${this.sessionId}`);
       }
@@ -310,7 +310,7 @@ export class MCPClient {
         throw new Error('serverId required for OAuth provider initialization');
       }
       this.oauthProvider = new StorageOAuthClientProvider({
-        identity: this.identity,
+        userId: this.userId,
         serverId: this.serverId,
         sessionId: this.sessionId,
         redirectUrl: this.callbackUrl!,
@@ -346,21 +346,21 @@ export class MCPClient {
       );
     }
 
-    // Create session in storage if it doesn't exist yet
+    // Create session in the session store if it doesn't exist yet
     // This is needed BEFORE OAuth flow starts because the OAuth provider
     // will call saveCodeVerifier() which requires the session to exist
-    const existingSession = await storage.getSession(this.identity, this.sessionId);
+    const existingSession = await sessions.get(this.userId, this.sessionId);
     if (!existingSession && this.serverId && this.serverUrl && this.callbackUrl) {
       this.createdAt = Date.now();
       console.log(`[MCPClient] Creating initial session ${this.sessionId} for OAuth flow`);
-      await storage.createSession({
+      await sessions.create({
         sessionId: this.sessionId,
-        identity: this.identity,
+        userId: this.userId,
         serverId: this.serverId,
         serverName: this.serverName,
         serverUrl: this.serverUrl,
         callbackUrl: this.callbackUrl,
-        transportType: this.transportType || 'streamable_http',
+        transportType: this.transportType || 'streamable-http',
         headers: this.headers,
         createdAt: this.createdAt,
         active: false,
@@ -369,7 +369,7 @@ export class MCPClient {
   }
 
   /**
-   * Saves current session state to storage
+   * Saves current session state to the session store
    * Creates new session if it doesn't exist, updates if it does
    * @param ttl - Time-to-live in seconds (defaults to 12hr for connected sessions)
    * @param active - Session status marker used to avoid unnecessary TTL rewrites
@@ -385,23 +385,23 @@ export class MCPClient {
 
     const sessionData = {
       sessionId: this.sessionId,
-      identity: this.identity,
+      userId: this.userId,
       serverId: this.serverId,
       serverName: this.serverName,
       serverUrl: this.serverUrl,
       callbackUrl: this.callbackUrl,
-      transportType: (this.transportType || 'streamable_http') as TransportType,
+      transportType: (this.transportType || 'streamable-http') as TransportType,
       headers: this.headers,
       createdAt: this.createdAt || Date.now(),
       active,
     };
 
     // Try to update first, create if doesn't exist
-    const existingSession = await storage.getSession(this.identity, this.sessionId);
+    const existingSession = await sessions.get(this.userId, this.sessionId);
     if (existingSession) {
-      await storage.updateSession(this.identity, this.sessionId, sessionData, ttl);
+      await sessions.update(this.userId, this.sessionId, sessionData, ttl);
     } else {
-      await storage.createSession(sessionData, ttl);
+      await sessions.create(sessionData, ttl);
     }
   }
 
@@ -417,7 +417,7 @@ export class MCPClient {
      */
     const transportsToTry: TransportType[] = this.transportType
       ? [this.transportType]
-      : ['streamable_http', 'sse'];
+      : ['streamable-http', 'sse'];
 
     let lastError: unknown;
 
@@ -505,7 +505,7 @@ export class MCPClient {
       this.emitProgress('Connected successfully');
 
       // Refresh session metadata on every successful connect so active sessions
-      // record ongoing usage and don't look dormant to storage cleanup jobs.
+      // record ongoing usage and don't look dormant to session cleanup jobs.
       console.log(`[MCPClient] Saving session ${this.sessionId} with 12hr TTL (connect success)`);
       await this.saveSession(SESSION_TTL_SECONDS, true);
     } catch (error) {
@@ -540,7 +540,7 @@ export class MCPClient {
           // We remove it now to ensure the database remains lean, bypassing the 
           // automated lifecycle sweep.
           try {
-            await storage.removeSession(this.identity, this.sessionId);
+            await sessions.delete(this.userId, this.sessionId);
           } catch {
             // Non-blocking: Proactive cleanup failures are suppressed to prioritize 
             // the original error context.
@@ -579,9 +579,9 @@ export class MCPClient {
       // Terminal Handshake Failure: only purge transient sessions. Active
       // sessions may still hold valid credentials for a later reconnect.
       try {
-        const existingSession = await storage.getSession(this.identity, this.sessionId);
+        const existingSession = await sessions.get(this.userId, this.sessionId);
         if (!existingSession || existingSession.active !== true) {
-          await storage.removeSession(this.identity, this.sessionId);
+          await sessions.delete(this.userId, this.sessionId);
         }
       } catch {
         // Non-blocking: Cleanup is performed on a best-effort basis and should
@@ -619,7 +619,7 @@ export class MCPClient {
      */
     const transportsToTry: TransportType[] = this.transportType
       ? [this.transportType]
-      : ['streamable_http', 'sse'];
+      : ['streamable-http', 'sse'];
 
     let lastError: unknown;
     let tokensExchanged = false;
@@ -1020,7 +1020,7 @@ export class MCPClient {
     );
 
     // Use default logic to get transport, defaulting to what's stored or auto
-    const tt = this.transportType || 'streamable_http';
+    const tt = this.transportType || 'streamable-http';
     this.transport = this.getTransport(tt);
 
     await this.client.connect(this.transport);
@@ -1041,7 +1041,7 @@ export class MCPClient {
       await (this.oauthProvider as any).invalidateCredentials('all');
     }
 
-    await storage.removeSession(this.identity, this.sessionId);
+    await sessions.delete(this.userId, this.sessionId);
     this.disconnect();
   }
 
@@ -1119,10 +1119,10 @@ export class MCPClient {
 
   /**
    * Gets the transport type being used
-   * @returns Transport type (defaults to 'streamable_http')
+   * @returns Transport type (defaults to 'streamable-http')
    */
   getTransportType(): TransportType {
-    return this.transportType || 'streamable_http';
+    return this.transportType || 'streamable-http';
   }
 
   /**
@@ -1156,16 +1156,16 @@ export class MCPClient {
    * Gets MCP server configuration for all active user sessions
    * Loads sessions from Redis, validates OAuth tokens, refreshes if expired
    * Returns ready-to-use configuration with valid auth headers
-   * @param identity - User ID to fetch sessions for
+   * @param userId - User ID to fetch sessions for
    * @returns Object keyed by sanitized server labels containing transport, url, headers, etc.
    * @static
    */
-  static async getMcpServerConfig(identity: string): Promise<Record<string, any>> {
+  static async getMcpServerConfig(userId: string): Promise<Record<string, any>> {
     const mcpConfig: Record<string, any> = {};
-    const sessions = await storage.getIdentitySessionsData(identity);
+    const sessionList = await sessions.list(userId);
 
     await Promise.all(
-      sessions.map(async (sessionData) => {
+      sessionList.map(async (sessionData) => {
         const { sessionId } = sessionData;
 
         try {
@@ -1176,16 +1176,16 @@ export class MCPClient {
             !sessionData.serverUrl ||
             !sessionData.callbackUrl
           ) {
-            await storage.removeSession(identity, sessionId);
+            await sessions.delete(userId, sessionId);
             return;
           }
 
           // Get OAuth headers if session requires authentication
           let headers: Record<string, string> | undefined;
           try {
-            // Inject existing session data to avoid redundant storage reads in initialize()
+            // Inject existing session data to avoid redundant session store reads in initialize()
             const client = new MCPClient({
-              identity,
+              userId,
               sessionId,
               serverId: sessionData.serverId,
               serverUrl: sessionData.serverUrl,
@@ -1223,7 +1223,7 @@ export class MCPClient {
             ...(headers && { headers }),
           };
         } catch (error) {
-          await storage.removeSession(identity, sessionId);
+          await sessions.delete(userId, sessionId);
           console.warn(`[MCP] Failed to process session ${sessionId}:`, error);
         }
       })