@mcp-ts/sdk 2.5.3 → 2.6.0

package/dist/{multi-session-client-DqzT8Oo7.d.mts → multi-session-client-C_Ja2TuV.d.mts}

@@ -1,100 +1,152 @@
-import { m as Event, M as McpConnectionEvent, t as McpObservabilityEvent, s as McpConnectionState, A as ToolClientProvider, T as ToolClient } from './types-BkJ_rgzo.mjs';
-import { ListToolsResult, CallToolResult, ListPromptsResult, GetPromptResult, ListResourcesResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+import { m as Event, M as McpConnectionEvent, t as McpObservabilityEvent, s as McpConnectionState, A as ToolClientProvider, T as ToolClient } from './types-DX71u9gR.mjs';
+import { ListToolsResult, CallToolResult, ListPromptsResult, GetPromptResult, ListResourcesResult, ReadResourceResult, Implementation } from '@modelcontextprotocol/sdk/types.js';
+import { OAuthClientInformationMixed, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
 import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
-import { OAuthClientMetadata, OAuthClientInformationMixed, OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
 
-/**
- * Extension of OAuthClientProvider interface with additional methods
- * Enables server-specific tracking and state management
- */
-interface AgentsOAuthProvider extends OAuthClientProvider {
-    authUrl: string | undefined;
-    clientId: string | undefined;
-    serverId: string | undefined;
-    checkState(state: string): Promise<{
-        valid: boolean;
-        serverId?: string;
-        error?: string;
-    }>;
-    consumeState(state: string): Promise<void>;
-    deleteCodeVerifier(): Promise<void>;
+interface OAuthState {
+    nonce: string;
+    sessionId: string;
+    serverId: string;
+    createdAt: number;
 }
-interface StorageOAuthClientProviderOptions {
+type SessionStatus = 'pending' | 'active';
+type ToolPolicyMode = 'all' | 'allowlist' | 'denylist';
+interface ToolPolicy {
+    mode: ToolPolicyMode;
+    toolIds: string[];
+    updatedAt: number;
+}
+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;
-    serverId: 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;
+    toolPolicy?: ToolPolicy;
+    /** When false, the session is excluded from agent tool discovery and RPC access. Defaults to true. */
+    enabled?: boolean;
+    clientInformation?: OAuthClientInformationMixed | null;
+    tokens?: OAuthTokens | null;
+    codeVerifier?: string | null;
+    codeVerifierChallenge?: string | null;
+    codeVerifierNonce?: string | null;
+    clientId?: string | null;
+    oauthState?: OAuthState | null;
+}
+interface SessionCredentials {
     sessionId: string;
-    redirectUrl: string;
-    clientName?: string;
-    clientUri?: string;
-    logoUri?: string;
-    policyUri?: string;
-    clientId?: string;
-    clientSecret?: string;
-    onRedirect?: (url: string) => void;
+    userId: string;
+    clientInformation?: OAuthClientInformationMixed | null;
+    tokens?: OAuthTokens | null;
+    codeVerifier?: string | null;
+    codeVerifierChallenge?: string | null;
+    codeVerifierNonce?: 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>;
 /**
- * Storage-backed OAuth provider implementation for MCP
- * Stores OAuth tokens, client information, and PKCE verifiers using the configured SessionStore
+ * Interface for MCP session stores.
  */
-declare class StorageOAuthClientProvider implements AgentsOAuthProvider {
-    readonly userId: string;
-    readonly serverId: string;
-    readonly sessionId: string;
-    readonly redirectUrl: string;
-    private readonly clientName?;
-    private readonly clientUri?;
-    private readonly logoUri?;
-    private readonly policyUri?;
-    private readonly clientSecret?;
-    private _authUrl;
-    private _clientId;
-    private onRedirectCallback?;
-    /**
-     * Creates a new session-backed OAuth provider
-     * @param options - Provider configuration
-     */
-    constructor(options: StorageOAuthClientProviderOptions);
-    get clientMetadata(): OAuthClientMetadata;
-    get clientId(): string | undefined;
-    set clientId(clientId_: string | undefined);
-    /**
-     * Loads OAuth credentials from the session store
-     * @private
+type GetOptions = {
+    includeCredentials?: boolean;
+};
+type SessionResult = Session;
+interface SessionStore {
+    /**
+     * Optional initialization (e.g., database connection)
      */
-    private getCredentials;
+    init?(): Promise<void>;
     /**
-     * Saves OAuth credentials to the session store
-     * @param data - Partial OAuth credentials to save
-     * @private
-     * @throws Error if session doesn't exist (session must be created by controller layer)
+     * 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, optionally including its credential fields in one round-trip.
+     * When includeCredentials is true, the returned session has credential fields
+     * (clientInformation, tokens, codeVerifier, etc.) populated from storage.
+     * When false or undefined, credential fields are left as undefined.
+     */
+    get(userId: string, sessionId: string, options?: GetOptions): Promise<SessionResult | null>;
+    /**
+     * Retrieves runtime credentials for a session.
+     */
+    getCredentials(userId: string, sessionId: string): Promise<SessionCredentials | null>;
+    /**
+     * Clears runtime credentials without removing connection metadata.
      */
-    private patchCredentials;
+    clearCredentials(userId: string, sessionId: string): Promise<void>;
     /**
-     * Retrieves stored OAuth client information
+     * Gets full session data for all sessions owned by a user
      */
-    clientInformation(): Promise<OAuthClientInformationMixed | undefined>;
+    list(userId: string): Promise<Session[]>;
     /**
-     * Stores OAuth client information
+     * Removes a session
      */
-    saveClientInformation(clientInformation: OAuthClientInformationFull): Promise<void>;
+    delete(userId: string, sessionId: string): Promise<void>;
     /**
-     * Stores OAuth tokens
+     * 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)
      */
-    saveTokens(tokens: OAuthTokens): Promise<void>;
-    get authUrl(): string | undefined;
-    state(): Promise<string>;
-    checkState(state: string): Promise<{
-        valid: boolean;
-        serverId?: string;
-        error?: string;
-    }>;
-    consumeState(state: string): Promise<void>;
-    redirectToAuthorization(authUrl: URL): Promise<void>;
-    invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier"): Promise<void>;
-    saveCodeVerifier(verifier: string): Promise<void>;
-    codeVerifier(): Promise<string>;
-    deleteCodeVerifier(): Promise<void>;
-    tokens(): Promise<OAuthTokens | undefined>;
+    clearAll(): Promise<void>;
+    /**
+     * Clean up expired sessions
+     */
+    cleanupExpired(): Promise<void>;
+    /**
+     * Disconnect from storage backend
+     */
+    disconnect(): Promise<void>;
 }
 
 /**
@@ -118,6 +170,27 @@ interface MCPOAuthClientOptions {
     clientUri?: string;
     logoUri?: string;
     policyUri?: string;
+    /**
+     * Credentials already loaded by the caller (e.g. via get({includeCredentials: true})).
+     * When provided, the StorageOAuthClientProvider uses these cached values to
+     * skip redundant DB reads for tokens() calls during reconnection.
+     */
+    cachedCredentials?: {
+        tokens?: OAuthTokens;
+    };
+    /**
+     * When true, skips the redundant session-existence check in ensureSession().
+     * Set by callers that have already confirmed the session exists in storage
+     * (e.g. getOrCreateClient, getSession, finishAuth in sse-handler).
+     * Saves one round-trip per reconnection.
+     */
+    hasSession?: boolean;
+    /**
+     * Custom session store override. When provided, all storage operations
+     * (get/create/update/delete) use this store instead of the default global.
+     * Used for wrapping with DB observability or other decorators.
+     */
+    sessionStore?: SessionStore;
 }
 /**
  * MCP Client with OAuth 2.1 authentication support
@@ -126,25 +199,12 @@ interface MCPOAuthClientOptions {
  */
 declare class MCPClient {
     private client;
-    oauthProvider: AgentsOAuthProvider | null;
+    oauthProvider: OAuthClientProvider | null;
     private transport;
-    private userId;
-    private serverId?;
-    private sessionId;
-    private serverName?;
-    private transportType;
-    private serverUrl;
-    private callbackUrl;
-    private onRedirect;
-    private clientId?;
-    private clientSecret?;
-    private headers?;
-    /** OAuth Client Metadata */
-    private clientName?;
-    private clientUri?;
-    private logoUri?;
-    private policyUri?;
+    private config;
     private createdAt?;
+    private _serverInfo;
+    private _store;
     /** Event emitters for connection lifecycle */
     private readonly _onConnectionEvent;
     readonly onConnectionEvent: Event<McpConnectionEvent>;
@@ -157,6 +217,8 @@ declare class MCPClient {
      * @param options - Client configuration options
      */
     constructor(options: MCPOAuthClientOptions);
+    /** Shared session-shaped data for ensureSession and saveSession */
+    private get session();
     /**
      * Emit a connection state change event
      * @private
@@ -353,7 +415,15 @@ declare class MCPClient {
      */
     getTransportType(): TransportType;
     /**
-     * Gets the human-readable server name
+     * Gets the full server metadata from the MCP initialize response.
+     * Includes name, version, icons, title, description, and website URL.
+     * Returns undefined if the client hasn't connected yet.
+     */
+    getServerInfo(): Implementation | undefined;
+    /**
+     * Gets the human-readable server name.
+     * Prefers the server's reported title/name from the initialize response,
+     * falling back to the name provided at construction or session metadata.
      * @returns Server name or undefined
      */
     getServerName(): string | undefined;
@@ -369,134 +439,6 @@ declare class MCPClient {
     getSessionId(): string;
 }
 
-interface OAuthState {
-    nonce: string;
-    sessionId: string;
-    serverId: string;
-    createdAt: number;
-}
-type SessionStatus = 'pending' | 'active';
-type ToolPolicyMode = 'all' | 'allowlist' | 'denylist';
-interface ToolPolicy {
-    mode: ToolPolicyMode;
-    toolIds: string[];
-    updatedAt: number;
-}
-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;
-    toolPolicy?: ToolPolicy;
-}
-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>;
-/**
- * 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.
@@ -513,6 +455,12 @@ interface MultiSessionOptions {
      * @default 1000
      */
     retryDelay?: number;
+    /**
+     * Custom session store. When provided, all DB operations go through
+     * this store instead of the default global `sessions` singleton.
+     * Useful for wrapping with `withDbObservability()` for debugging.
+     */
+    sessionStore?: SessionStore;
     /**
      * Custom session provider. When provided, `connect()` calls this
      * instead of querying the storage backend. Useful when sessions are
@@ -522,6 +470,11 @@ interface MultiSessionOptions {
      * Default: reads from the storage backend via `sessions.list(userId)`.
      */
     sessionProvider?: () => Promise<Session[]>;
+    /**
+     * Attached to each MCPClient before connect() so all connection lifecycle
+     * events (INITIALIZING, CONNECTING, CONNECTED, etc.) are captured.
+     */
+    onObservabilityEvent?: McpObservabilityEventHandler;
     /**
      * Called after a session is successfully connected.
      */
@@ -536,6 +489,8 @@ interface MultiSessionOptions {
      */
     onSessionFailed?: (sessionId: string, error: unknown) => void;
 }
+/** @internal */
+type McpObservabilityEventHandler = (event: McpObservabilityEvent) => void;
 /**
  * Manages multiple MCP client connections for a single user.
  *
@@ -556,6 +511,7 @@ declare class MultiSessionClient implements ToolClientProvider {
      * @param options - Optional tuning and lifecycle hooks.
      */
     constructor(userId: string, options?: MultiSessionOptions);
+    private _store;
     /**
      * Fetches active sessions and establishes connections to all of them.
      *
@@ -641,4 +597,4 @@ declare class MultiSessionClient implements ToolClientProvider {
     private establishConnectionWithRetries;
 }
 
-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 };
+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 };