@mcp-ts/sdk 2.5.2 → 2.6.0

package/dist/server/index.d.ts

@@ -1,13 +1,32 @@
-import { c as SessionMutationListener, e as SessionStore } from '../multi-session-client-CB4oDrQX.js';
-export { M as MCPClient, a as MultiSessionClient, S as Session, b as SessionMutationEvent, d as SessionMutationType, f as StorageOAuthClientProvider } from '../multi-session-client-CB4oDrQX.js';
+import { c as SessionMutationListener, e as SessionStore } from '../multi-session-client-CQzymvHl.js';
+export { M as MCPClient, a as MultiSessionClient, S as Session, b as SessionMutationEvent, d as SessionMutationType } from '../multi-session-client-CQzymvHl.js';
 export { U as UnauthorizedError, s as sanitizeServerLabel } from '../utils-DELRKQPU.js';
-import { M as McpConnectionEvent, t as McpObservabilityEvent, x as McpRpcResponse, w as McpRpcRequest } from '../types-6SmXege4.js';
-export { a as CallToolRequest, b as CallToolResponse, f as ConnectRequest, g as ConnectResponse, k as Disposable, E as Emitter, m as Event, q as ListToolsResponse, s as McpConnectionState, T as ToolClient, A as ToolClientProvider, B as ToolInfo } from '../types-6SmXege4.js';
+import { t as McpObservabilityEvent, M as McpConnectionEvent, x as McpRpcResponse, w as McpRpcRequest } from '../types-DX71u9gR.js';
+export { a as CallToolRequest, b as CallToolResponse, f as ConnectRequest, g as ConnectResponse, k as Disposable, E as Emitter, m as Event, q as ListToolsResponse, s as McpConnectionState, T as ToolClient, A as ToolClientProvider, B as ToolInfo } from '../types-DX71u9gR.js';
+import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import { OAuthTokens, OAuthClientMetadata, OAuthClientInformationMixed, OAuthClientInformationFull } from '@modelcontextprotocol/sdk/shared/auth.js';
 export { OAuthClientInformation, OAuthClientInformationFull, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
 export { CallToolResult, ListToolsResult, Tool } from '@modelcontextprotocol/sdk/types.js';
-import '@modelcontextprotocol/sdk/client/auth.js';
 
 declare function onSessionMutation(listener: SessionMutationListener): () => void;
+/**
+ * Wraps a SessionStore with a Proxy that emits an McpObservabilityEvent for every
+ * method call — reads (`db:read`) and writes (`db:write`) — including duration
+ * and any error. Useful for debugging connection flows end-to-end.
+ *
+ * Usage:
+ * ```ts
+ * import { sessions, withDbObservability } from '@mcp-ts/sdk/server/storage';
+ * const db = withDbObservability(sessions, (event) => console.log('[DB]', event));
+ * // Use `db` instead of `sessions` throughout the request
+ * ```
+ *
+ * @param store - The underlying SessionStore instance to wrap.
+ * @param emit  - Called synchronously after each store method completes
+ *                (or rejects) with a typed observability event.
+ * @returns A drop-in SessionStore replacement.
+ */
+declare function withDbObservability(store: SessionStore, emit: (event: McpObservabilityEvent) => void): SessionStore;
 /**
  * Global session store instance
  * Uses lazy initialization with a Proxy to handle async setup transparently
@@ -15,170 +34,390 @@ declare function onSessionMutation(listener: SessionMutationListener): () => voi
 declare const sessions: SessionStore;
 
 /**
- * SSE (Server-Sent Events) Handler for MCP Connections
+ * 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 StorageOAuthClientProviderOptions {
+    userId: string;
+    serverId: string;
+    sessionId: string;
+    redirectUrl: string;
+    clientName?: string;
+    clientUri?: string;
+    logoUri?: string;
+    policyUri?: string;
+    clientId?: string;
+    clientSecret?: string;
+    cachedTokens?: OAuthTokens;
+    sessionStore?: SessionStore;
+    onRedirect?: (url: string) => void;
+}
+/**
+ * Storage-backed OAuth provider implementation for MCP
+ * Stores OAuth tokens, client information, and PKCE verifiers using the configured SessionStore
+ */
+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 _store;
+    private _authUrl;
+    private _clientId;
+    private _cachedCodeVerifier;
+    private _hasCodeVerifier;
+    private _cachedTokens;
+    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
+     */
+    private getCredentials;
+    /**
+     * 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)
+     */
+    private patchCredentials;
+    /**
+     * Retrieves stored OAuth client information.
+     */
+    clientInformation(): Promise<OAuthClientInformationMixed | undefined>;
+    /**
+     * Stores OAuth client information
+     */
+    saveClientInformation(clientInformation: OAuthClientInformationFull): Promise<void>;
+    /**
+     * Stores OAuth tokens
+     */
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    /**
+     * Persists static client credentials to DB immediately on creation.
+     * Ensures getOrCreateClient() finds them on rehydration, even when the
+     * server allows anonymous connect and never triggers DCR.
+     */
+    initializeCredentials(): 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>;
+}
+
+/**
+ * SSE (Server-Sent Events) Handler for MCP Connections.
+ *
+ * Provides real-time bidirectional communication between browser clients and
+ * MCP servers via a single HTTP endpoint:
+ * - GET  → opens an SSE stream for server → client events
+ * - POST → delivers client → server RPC requests with direct HTTP response
  *
- * Manages real-time bidirectional communication with MCP clients:
- * - SSE stream for server → client events (connection state, tools, logs)
- * - HTTP POST for client → server RPC requests
+ * Built on {@link SSEConnectionManager} which handles the RPC dispatch logic,
+ * session lifecycle, OAuth 2.1 flows, tool-policy enforcement, and heartbeat
+ * keep-alive — all while remaining stateless across serverless invocations.
  *
- * Key features:
- * - Direct HTTP response for RPC calls (bypasses SSE latency)
- * - Automatic session restoration and validation
- * - OAuth 2.1 authentication flow support
- * - Heartbeat to keep connections alive
+ * @module sse-handler
  */
 
+/** OAuth client metadata surfaced during connection and authorization. */
 interface ClientMetadata {
     clientName?: string;
     clientUri?: string;
     logoUri?: string;
     policyUri?: string;
 }
+/** Options passed to {@link createSSEHandler}. */
 interface SSEHandlerOptions {
-    /** User/Client identifier */
+    /** Authenticated user / tenant identifier. */
     userId: string;
-    /** Optional callback for authentication/authorization */
+    /** Optional auth check — called per-request before any RPC dispatch. */
     onAuth?: (userId: string) => Promise<boolean>;
-    /** Heartbeat interval in milliseconds @default 30000 */
+    /** SSE heartbeat interval in milliseconds. @default 30000 */
     heartbeatInterval?: number;
-    /** Static OAuth client metadata defaults (for all connections) */
+    /** Static OAuth client metadata applied to all connections. */
     clientDefaults?: ClientMetadata;
-    /** Dynamic OAuth client metadata getter (per-request, useful for multi-tenant) */
+    /**
+     * Dynamic OAuth client metadata resolver, called once per connection.
+     * Overrides `clientDefaults`. Useful for multi-tenant scenarios where
+     * metadata varies by request (headers, subdomain, etc.).
+     */
     getClientMetadata?: (request?: unknown) => ClientMetadata | Promise<ClientMetadata>;
 }
 /**
- * Manages a single SSE connection and handles MCP operations.
- * Each instance corresponds to one connected browser client.
+ * Manages a single browser-facing SSE connection and all MCP server sessions
+ * owned by the associated user.
+ *
+ * ## Responsibilities
+ * - RPC method dispatch (`connect`, `disconnect`, `callTool`, `listTools`, …)
+ * - Session lifecycle: create, restore, re-validate, OAuth completion
+ * - In-memory client cache (`Map<string, MCPClient>`) for active transports
+ * - SSE event emission for connection state, tool discovery, and errors
+ * - Periodic heartbeat to prevent proxy/CDN timeouts
+ * - Unified observability: RPC timing, DB operations, connection lifecycle
+ *
+ * Each instance is tied to one browser client. It is **not** a singleton —
+ * a new instance is created per incoming SSE connection.
  */
 declare class SSEConnectionManager {
     private readonly options;
     private readonly sendEvent;
     private readonly userId;
+    /** Active MCP transports keyed by sessionId. */
     private readonly clients;
-    private heartbeatTimer?;
-    private isActive;
+    /** Instrumented session store — always wraps `sessions` with DB observability. */
+    private readonly observedStore;
+    private heartbeatTimer;
+    private active;
+    /**
+     * @param options  - Handler configuration (userId, auth, metadata, heartbeat, observability).
+     * @param sendEvent - Callback that writes a typed event onto the SSE stream.
+     */
     constructor(options: SSEHandlerOptions, sendEvent: (event: McpConnectionEvent | McpObservabilityEvent | McpRpcResponse) => void);
     /**
-     * Get resolved client metadata (dynamic > static > defaults)
+     * Dispatches an incoming RPC request, emits timing observability,
+     * and returns the response.
+     *
+     * Emits `rpc:start` before dispatch and `rpc:end` on completion
+     * (success or error), each carrying the method name, sessionId, and
+     * duration. All events flow through the unified `onObservability`
+     * and the SSE stream.
+     *
+     * @param request - The deserialized RPC envelope.
+     * @returns The RPC response (success or error).
      */
-    private getResolvedClientMetadata;
+    handleRequest(request: McpRpcRequest): Promise<McpRpcResponse>;
     /**
-     * Start heartbeat to keep connection alive
+     * Tears down all active MCP transports and stops the heartbeat timer.
+     *
+     * Disconnects are issued in parallel across all sessions. After calling
+     * this method the manager instance should be discarded.
      */
-    private startHeartbeat;
+    dispose(): Promise<void>;
     /**
-     * Handle incoming RPC requests
-     * Returns the RPC response directly for immediate HTTP response (bypassing SSE latency)
+     * Routes an RPC method name to the appropriate private handler.
+     *
+     * @throws {Error} When the method name is unrecognized.
      */
-    handleRequest(request: McpRpcRequest): Promise<McpRpcResponse>;
+    private dispatchImpl;
     /**
-     * Get all sessions for the current userId
+     * Lists all sessions owned by the current user.
+     *
+     * Returns a lightweight view — session metadata only, no credential fields.
      */
     private listSessions;
     /**
-     * Connect to an MCP server
+     * Restores and validates a previously persisted session.
+     *
+     * Loads the full session row (including credentials) from storage, creates
+     * a new MCP transport, connects to the remote server, and emits the
+     * discovered (policy-filtered) tool list via SSE.
+     */
+    private getSession;
+    /**
+     * Initiates a connection to a new MCP server.
+     *
+     * If a session for the same `serverId` or `serverUrl` already exists and
+     * is still in a `pending` (OAuth) state, the existing session is resumed
+     * instead of creating a duplicate.
+     *
+     * `UnauthorizedError` is treated as a pending-auth state and returned as
+     * a successful result (the client will then redirect to the auth URL).
      */
     private connect;
     /**
-     * Reconnect to an MCP server — tears down the active client transport/connection
-     * and creates a fresh connection while reusing the existing session credentials in a single RPC call.
+     * Reconnects to an MCP server by tearing down the active transport if one
+     * exists and instantiating a fresh connection, reusing the existing session
+     * (and its stored credentials / DCR client info) from the database.
      */
     private reconnect;
     /**
-     * Disconnect from an MCP server
+     * Disconnects from an MCP server.
+     *
+     * If an active in-memory transport exists it delegates to `clearSession()`
+     * (which sends the server an HTTP DELETE per the Streamable spec). If no
+     * active transport is available (orphaned session from a failed OAuth flow),
+     * the session row is removed directly from storage.
      */
     private disconnect;
     /**
-     * Get an existing client or create and connect a new one for the session.
+     * Completes the OAuth 2.1 authorization code flow for a pending session.
+     *
+     * Loads the stored session (with credentials), creates a fresh `MCPClient`,
+     * and calls `finishAuth` inside a {@link runWithCodeVerifierState} context
+     * so the PKCE code verifier is available without a DB read.
+     *
+     * The session's stored `transportType` is intentionally **omitted** from the
+     * client config — this lets `MCPClient` auto-negotiate (try Streamable HTTP
+     * first, fall back to SSE), which is required for servers like Neon that
+     * only support SSE transport.
      */
-    private getOrCreateClient;
+    private finishAuth;
     /**
-     * Fetches all tools from the remote MCP server and emits a `tools_discovered` event.
+     * Fetches the complete tool list from the remote MCP server and emits a
+     * `tools_discovered` SSE event with two lists:
      *
-     * Two lists are always published together:
-     * - `tools`    — policy-filtered list that agents are allowed to call.
-     * - `allTools` — the complete, unfiltered list used by the management UI so
-     *                that blocked tools still appear as checkboxes in the dialog.
+     * - `tools`     — policy-filtered (what agents are allowed to call)
+     * - `allTools`  — complete, unfiltered (used by the management UI)
      *
-     * `fetchTools()` is called first (populates the in-memory cache), then
-     * `gateway.listTools()` re-uses that cache internally — so only one remote
-     * network round-trip is made regardless of how many callers follow.
+     * Only a single network round-trip is made: `fetchTools()` populates the
+     * in-memory cache, then `gateway.listTools()` reuses that cache.
      *
-     * @param sessionId - The session whose tools should be discovered.
-     * @returns The session record and the policy-filtered tool list.
-     * @throws {Error} When the session does not exist in the store.
+     * @param sessionId - The session to discover tools for.
+     * @returns The session record and the filtered tool result.
+     * @throws {Error} If the session does not exist in storage.
      */
     private listPolicyFilteredTools;
     /**
-     * Returns the policy-filtered tool list for a session (agent-facing).
-     * Internally re-uses `listPolicyFilteredTools` which also emits a
-     * `tools_discovered` SSE event to keep client state up to date.
+     * Returns the policy-filtered tool list for a session.
+     *
+     * Delegates to {@link listPolicyFilteredTools}, which also emits a
+     * `tools_discovered` SSE event to keep the client state current.
      */
     private listTools;
     /**
-     * Get all raw tools with effective access state for management UI.
+     * Returns all raw tools annotated with their effective policy state
+     * for display in the management UI.
      */
     private getToolPolicy;
     /**
-     * Persists a new tool access policy for a session and broadcasts the updated
-     * filtered tool list to all connected browser clients via a `tools_discovered` event.
+     * Persists a new tool access policy and broadcasts the updated filtered
+     * tool list via a `tools_discovered` SSE event.
      *
-     * Both `tools` (policy-filtered) and `allTools` (complete list) are emitted
-     * so the management UI can immediately reflect the new checkbox states without
-     * an additional round-trip to the server.
-     *
-     * @param params - Session ID and the new `{ mode, toolIds }` policy to apply.
-     * @throws {Error} When the session does not exist or the policy references unknown tool IDs.
+     * @throws {Error} If the session does not exist or the policy references
+     *                 tool IDs that don't match any known tool.
      */
     private setToolPolicy;
     /**
-     * Proxies a tool invocation to the remote MCP server.
-     * Resolves the client for the given session and delegates to the tool router.
-     */
-    private callTool;
-    /**
-     * Restore and validate an existing session
-     */
-    private getSession;
-    /**
-     * Complete OAuth authorization flow
+     * Enables or disables a session for agent tool discovery.
+     *
+     * Disabled sessions retain their OAuth tokens and connection metadata
+     * but are hidden from `MultiSessionClient.connect()` and blocked from
+     * RPC tool access. Re-enabling does not require re-authentication.
+     *
+     * @param params - `{ sessionId, enabled: boolean }`
+     * @returns `{ success: true }`
+     * @throws {Error} If the session does not exist.
      */
-    private finishAuth;
+    private updateSession;
     /**
-     * List prompts from a session
+     * Proxies a tool invocation to the remote MCP server.
+     *
+     * Resolves (or creates) the transport for the given session, runs the call
+     * through the tool-policy gateway, and injects `sessionId` into the result
+     * metadata so the client can route the response without scanning all sessions.
      */
+    private callTool;
+    /** Lists all prompts exposed by the remote MCP server. */
     private listPrompts;
+    /** Retrieves a specific prompt by name with optional arguments. */
+    private getPrompt;
+    /** Lists all resources exposed by the remote MCP server. */
+    private listResources;
+    /** Reads a specific resource identified by URI. */
+    private readResource;
+    /** Resolves client metadata: `getClientMetadata()` → `clientDefaults` → `{}`. */
+    private getResolvedClientMetadata;
+    /** Ensures the given session exists in storage and throws otherwise. */
+    private requireSession;
+    /** Finds an existing session matching the given serverId or serverUrl. */
+    private findExistingSession;
+    /** Normalizes a serverId to max 12 chars (DeepSeek/OpenAI 64-char tool-name limit). */
+    private normalizeServerId;
     /**
-     * Get a specific prompt
+     * Returns the cached in-memory transport for `sessionId`, or creates one
+     * from the persisted session row (with credentials) and connects it.
      */
-    private getPrompt;
+    private getOrCreateClient;
     /**
-     * List resources from a session
+     * Builds an `MCPClient` from a stored session row.
+     *
+     * Extracts `clientId` and `clientSecret` from the session's credential
+     * fields and passes `hasSession: true` + `cachedCredentials` so the client
+     * can skip redundant existence checks and credential reads.
      */
-    private listResources;
+    private restoreClient;
     /**
-     * Read a specific resource
+     * Wires connection and observability events from the client into the
+     * unified observability channel. Connection events go to `sendEvent`
+     * (SSE stream); observability events go to `emitObs` (user callback
+     * + SSE stream).
      */
-    private readResource;
+    private attachClientEvents;
     /**
-     * Emit connection event
+     * Registers the client in the in-memory cache and attaches its event
+     * listeners to the unified observability channel.
      */
-    private emitConnectionEvent;
+    private cacheClient;
     /**
-     * Cleanup and close all connections
+     * Attempts a `client.connect()` and, on success, discovers tools.
+     *
+     * If the server responds with `UnauthorizedError`, the session is
+     * treated as pending OAuth — a successful result is returned with
+     * the sessionId so the browser client can redirect to the auth URL.
+     *
+     * For any other error an `error` connection event is emitted and the
+     * client is removed from the in-memory cache before re-throwing.
      */
-    dispose(): Promise<void>;
+    private connectAndDiscover;
+    /** Starts the periodic heartbeat timer. */
+    private startHeartbeat;
 }
 /**
- * Create an SSE endpoint handler compatible with Node.js HTTP frameworks.
- * Handles both SSE streaming (GET) and RPC requests (POST).
+ * Creates a Node.js-compatible HTTP handler that serves an SSE stream (GET)
+ * and accepts RPC calls (POST) for a single browser client.
+ *
+ * @example
+ * ```ts
+ * import { createSSEHandler } from '@mcp-ts/sdk/server';
+ *
+ * const handler = createSSEHandler({ userId: 'user-123' });
+ * // Mount `handler` on both GET and POST for your HTTP framework.
+ * ```
+ *
+ * @param options - Handler configuration (userId, optional auth check, metadata).
+ * @returns An async function `(req, res) => void` suitable as an HTTP handler.
  */
 declare function createSSEHandler(options: SSEHandlerOptions): (req: {
     method?: string;
-    on: Function;
+    on: (event: string, cb: (...args: any[]) => void) => void;
 }, res: {
-    writeHead: Function;
-    write: Function;
+    writeHead: (status: number, headers: Record<string, string>) => void;
+    write: (chunk: string) => void;
 }) => Promise<void>;
 
 /**
@@ -220,4 +459,15 @@ declare function createNextMcpHandler(options?: NextMcpHandlerOptions): {
     POST: (request: Request) => Promise<Response>;
 };
 
-export { type ClientMetadata, McpConnectionEvent, McpObservabilityEvent, McpRpcRequest, McpRpcResponse, type NextMcpHandlerOptions, SSEConnectionManager, type SSEHandlerOptions, SessionMutationListener, SessionStore, createNextMcpHandler, createSSEHandler, onSessionMutation, sessions };
+/**
+ * Encrypts an object into a secure string.
+ * Falls back to returning the original object if the encryption key is missing or encryption fails.
+ */
+declare function encryptObject(data: any): any;
+/**
+ * Decrypts a secure string back into an object.
+ * Returns the original data if it is unencrypted or if decryption fails.
+ */
+declare function decryptObject(data: any): any;
+
+export { type ClientMetadata, McpConnectionEvent, McpObservabilityEvent, McpRpcRequest, McpRpcResponse, type NextMcpHandlerOptions, SSEConnectionManager, type SSEHandlerOptions, SessionMutationListener, SessionStore, StorageOAuthClientProvider, createNextMcpHandler, createSSEHandler, decryptObject, encryptObject, onSessionMutation, sessions, withDbObservability };