@mcp-ts/sdk 1.0.0

package/dist/multi-session-client-DMF3ED2O.d.mts

@@ -0,0 +1,389 @@
+import { b as Event, M as McpConnectionEvent, d as McpObservabilityEvent, c as McpConnectionState } from './events-BP6WyRNh.mjs';
+import { ListToolsResult, CallToolResult, ListPromptsResult, GetPromptResult, ListResourcesResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+import { OAuthClientMetadata, OAuthClientInformation, OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/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>;
+    isTokenExpired(): boolean;
+    setTokenExpiresAt(expiresAt: number): void;
+}
+/**
+ * Storage-backed OAuth provider implementation for MCP
+ * Stores OAuth tokens, client information, and PKCE verifiers using the configured StorageBackend
+ */
+declare class StorageOAuthClientProvider implements AgentsOAuthProvider {
+    identity: string;
+    serverId: string;
+    sessionId: string;
+    clientName: string;
+    baseRedirectUrl: string;
+    private _authUrl;
+    private _clientId;
+    private onRedirectCallback?;
+    private tokenExpiresAt?;
+    /**
+     * Creates a new Storage-backed OAuth provider
+     * @param identity - User/Client identifier
+     * @param serverId - Server identifier (for tracking which server this OAuth session belongs to)
+     * @param sessionId - Session identifier (used as OAuth state)
+     * @param clientName - OAuth client name
+     * @param baseRedirectUrl - OAuth callback URL
+     * @param onRedirect - Optional callback when redirect to authorization is needed
+     */
+    constructor(identity: string, serverId: string, sessionId: string, clientName: string, baseRedirectUrl: string, onRedirect?: (url: string) => void);
+    get clientMetadata(): OAuthClientMetadata;
+    get clientUri(): string;
+    get redirectUrl(): string;
+    get clientId(): string | undefined;
+    set clientId(clientId_: string | undefined);
+    /**
+     * Loads OAuth data from storage session
+     * @private
+     */
+    private getSessionData;
+    /**
+     * Saves OAuth data to storage
+     * @param data - Partial OAuth data to save
+     * @private
+     * @throws Error if session doesn't exist (session must be created by controller layer)
+     */
+    private saveSessionData;
+    /**
+     * Retrieves stored OAuth client information
+     */
+    clientInformation(): Promise<OAuthClientInformation | undefined>;
+    /**
+     * Stores OAuth client information
+     */
+    saveClientInformation(clientInformation: OAuthClientInformationFull): Promise<void>;
+    /**
+     * Stores OAuth tokens
+     */
+    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>;
+    isTokenExpired(): boolean;
+    setTokenExpiresAt(expiresAt: number): void;
+}
+
+/**
+ * Supported MCP transport types
+ */
+type TransportType = 'sse' | 'streamable_http';
+interface MCPOAuthClientOptions {
+    serverUrl?: string;
+    serverName?: string;
+    callbackUrl?: string;
+    onRedirect?: (url: string) => void;
+    identity: string;
+    serverId?: string; /** Optional - loaded from session if not provided */
+    sessionId: string; /** Required - primary key for session lookup */
+    transportType?: TransportType;
+    tokens?: OAuthTokens;
+    tokenExpiresAt?: number;
+    clientInformation?: OAuthClientInformationFull;
+    clientId?: string;
+    clientSecret?: string;
+    onSaveTokens?: (tokens: OAuthTokens) => void;
+    headers?: Record<string, string>;
+    /** OAuth Client Metadata (optional - user application info) */
+    clientName?: string;
+    clientUri?: string;
+    logoUri?: string;
+    policyUri?: string;
+}
+/**
+ * MCP Client with OAuth 2.1 authentication support
+ * Manages connections to MCP servers with automatic token refresh and session restoration
+ * Emits connection lifecycle events for observability
+ */
+declare class MCPClient {
+    private client;
+    oauthProvider: AgentsOAuthProvider | null;
+    private transport;
+    private identity;
+    private serverId?;
+    private sessionId;
+    private serverName?;
+    private transportType;
+    private serverUrl;
+    private callbackUrl;
+    private onRedirect;
+    private tokens?;
+    private tokenExpiresAt?;
+    private clientInformation?;
+    private clientId?;
+    private clientSecret?;
+    private onSaveTokens?;
+    private headers?;
+    /** OAuth Client Metadata */
+    private clientName?;
+    private clientUri?;
+    private logoUri?;
+    private policyUri?;
+    /** Event emitters for connection lifecycle */
+    private readonly _onConnectionEvent;
+    readonly onConnectionEvent: Event<McpConnectionEvent>;
+    private readonly _onObservabilityEvent;
+    readonly onObservabilityEvent: Event<McpObservabilityEvent>;
+    private currentState;
+    /**
+     * Creates a new MCP client instance
+     * Can be initialized with minimal options (identity + sessionId) for session restoration
+     * @param options - Client configuration options
+     */
+    constructor(options: MCPOAuthClientOptions);
+    /**
+     * Emit a connection state change event
+     * @private
+     */
+    private emitStateChange;
+    /**
+     * Emit an error event
+     * @private
+     */
+    private emitError;
+    /**
+     * Emit a progress event
+     * @private
+     */
+    private emitProgress;
+    /**
+     * Get current connection state
+     */
+    getConnectionState(): McpConnectionState;
+    /**
+     * Helper to create a transport instance
+     * @param type - The transport type to create
+     * @returns Configured transport instance
+     * @private
+     */
+    private getTransport;
+    /**
+     * Initializes client components (client, transport, OAuth provider)
+     * Loads missing configuration from Redis session store if needed
+     * This method is idempotent and safe to call multiple times
+     * @private
+     */
+    private initialize;
+    /**
+     * Saves current session state to storage
+     * 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)
+     * @private
+     */
+    private saveSession;
+    /**
+     * Try to connect using available transports
+     * @returns The corrected transport type object if successful
+     * @private
+     */
+    private tryConnect;
+    /**
+     * Connects to the MCP server
+     * Automatically validates and refreshes OAuth tokens if needed
+     * Saves session to Redis on first successful connection
+     * @throws {UnauthorizedError} When OAuth authorization is required
+     * @throws {Error} When connection fails for other reasons
+     */
+    connect(): Promise<void>;
+    /**
+     * Completes OAuth authorization flow by exchanging authorization code for tokens
+     * Creates new authenticated client and transport, then establishes connection
+     * Saves active session to Redis after successful authentication
+     * @param authCode - Authorization code received from OAuth callback
+     */
+    finishAuth(authCode: string): Promise<void>;
+    /**
+     * Lists all available tools from the connected MCP server
+     * @returns List of tools with their schemas and descriptions
+     * @throws {Error} When client is not connected
+     */
+    listTools(): Promise<ListToolsResult>;
+    /**
+     * Executes a tool on the connected MCP server
+     * @param toolName - Name of the tool to execute
+     * @param toolArgs - Arguments to pass to the tool
+     * @returns Tool execution result
+     * @throws {Error} When client is not connected
+     */
+    callTool(toolName: string, toolArgs: Record<string, unknown>): Promise<CallToolResult>;
+    /**
+     * Lists all available prompts from the connected MCP server
+     * @returns List of available prompts
+     * @throws {Error} When client is not connected
+     */
+    listPrompts(): Promise<ListPromptsResult>;
+    /**
+     * Gets a specific prompt with arguments
+     * @param name - Name of the prompt
+     * @param args - Arguments for the prompt
+     * @returns Prompt content
+     * @throws {Error} When client is not connected
+     */
+    getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult>;
+    /**
+     * Lists all available resources from the connected MCP server
+     * @returns List of available resources
+     * @throws {Error} When client is not connected
+     */
+    listResources(): Promise<ListResourcesResult>;
+    /**
+     * Reads a specific resource
+     * @param uri - URI of the resource to read
+     * @returns Resource content
+     * @throws {Error} When client is not connected
+     */
+    readResource(uri: string): Promise<ReadResourceResult>;
+    /**
+     * Refreshes the OAuth access token using the refresh token
+     * Discovers OAuth metadata from server and exchanges refresh token for new access token
+     * @returns True if refresh was successful, false otherwise
+     */
+    refreshToken(): Promise<boolean>;
+    /**
+     * Ensures OAuth tokens are valid, refreshing them if expired
+     * Called automatically by connect() - rarely needs to be called manually
+     * @returns True if valid tokens are available, false otherwise
+     */
+    getValidTokens(): Promise<boolean>;
+    /**
+     * Reconnects to MCP server using existing OAuth provider from Redis
+     * Used for session restoration in serverless environments
+     * Creates new client and transport without re-initializing OAuth provider
+     * @throws {Error} When OAuth provider is not initialized
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Completely removes the session from Redis including all OAuth data
+     * Invalidates credentials and disconnects the client
+     */
+    clearSession(): Promise<void>;
+    /**
+     * Checks if the client is currently connected to an MCP server
+     * @returns True if connected, false otherwise
+     */
+    isConnected(): boolean;
+    /**
+     * Disconnects from the MCP server and cleans up resources
+     * Does not remove session from Redis - use clearSession() for that
+     */
+    disconnect(reason?: string): void;
+    /**
+     * Dispose of all event emitters
+     * Call this when the client is no longer needed
+     */
+    dispose(): void;
+    /**
+     * Gets the server URL
+     * @returns Server URL or empty string if not set
+     */
+    getServerUrl(): string;
+    /**
+     * Gets the OAuth callback URL
+     * @returns Callback URL or empty string if not set
+     */
+    getCallbackUrl(): string;
+    /**
+     * Gets the transport type being used
+     * @returns Transport type (defaults to 'streamable_http')
+     */
+    getTransportType(): TransportType;
+    /**
+     * Gets the human-readable server name
+     * @returns Server name or undefined
+     */
+    getServerName(): string | undefined;
+    /**
+     * Gets the server ID
+     * @returns Server ID or undefined
+     */
+    getServerId(): string | undefined;
+    /**
+     * Gets the session ID
+     * @returns Session ID
+     */
+    getSessionId(): string;
+    /**
+     * 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
+     * @returns Object keyed by sanitized server labels containing transport, url, headers, etc.
+     * @static
+     */
+    static getMcpServerConfig(identity: string): Promise<Record<string, any>>;
+}
+
+/**
+ * Manages multiple MCP connections for a single user identity.
+ * Allows aggregating tools from all connected servers.
+ */
+interface MultiSessionOptions {
+    /**
+     * Connection timeout in milliseconds
+     * @default 15000
+     */
+    timeout?: number;
+    /**
+     * Maximum number of retry attempts
+     * @default 2
+     */
+    maxRetries?: number;
+    /**
+     * Delay between retries in milliseconds
+     * @default 1000
+     */
+    retryDelay?: number;
+}
+/**
+ * Manages multiple MCP connections for a single user identity.
+ * Allows aggregating tools from all connected servers.
+ */
+declare class MultiSessionClient {
+    private clients;
+    private identity;
+    private options;
+    constructor(identity: string, options?: MultiSessionOptions);
+    private getActiveSessions;
+    private connectInBatches;
+    private connectSession;
+    private createAndConnectClient;
+    connect(): Promise<void>;
+    /**
+     * Returns the array of currently connected clients.
+     */
+    getClients(): MCPClient[];
+    /**
+     * Disconnects all clients.
+     */
+    disconnect(): void;
+}
+
+export { MCPClient as M, StorageOAuthClientProvider as S, MultiSessionClient as a };

package/dist/server/index.d.mts

@@ -0,0 +1,269 @@
+export { M as MCPClient, a as MultiSessionClient, S as StorageOAuthClientProvider } from '../multi-session-client-DMF3ED2O.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';
+import { M as McpConnectionEvent, d as McpObservabilityEvent } from '../events-BP6WyRNh.mjs';
+export { D as Disposable, E as Emitter, b as Event, c as McpConnectionState } from '../events-BP6WyRNh.mjs';
+import { q as McpRpcResponse, p as McpRpcRequest } from '../types-SbDlA2VX.mjs';
+export { a as CallToolRequest, b as CallToolResponse, f as ConnectRequest, g as ConnectResponse, m as ListToolsResponse, T as ToolInfo } from '../types-SbDlA2VX.mjs';
+export { CallToolResult, ListToolsResult, Tool } from '@modelcontextprotocol/sdk/types.js';
+import '@modelcontextprotocol/sdk/client/auth.js';
+
+interface SessionData {
+    sessionId: string;
+    serverId?: string;
+    serverName?: string;
+    serverUrl: string;
+    transportType: 'sse' | 'streamable_http';
+    callbackUrl: string;
+    createdAt: number;
+    identity?: string;
+    headers?: Record<string, string>;
+    clientInformation?: OAuthClientInformationMixed;
+    tokens?: OAuthTokens;
+    codeVerifier?: string;
+    clientId?: string;
+}
+/**
+ * Interface for MCP Session Storage Backends
+ */
+interface StorageBackend {
+    /**
+     * Optional initialization (e.g., database connection)
+     */
+    init?(): Promise<void>;
+    /**
+     * Generates a unique session ID
+     */
+    generateSessionId(): string;
+    /**
+     * Stores or updates a session
+     */
+    /**
+     * Creates a new session. Throws if session already exists.
+     * @param session - Session data to create
+     * @param ttl - Optional TTL in seconds (defaults to backend's default)
+     */
+    createSession(session: SessionData, ttl?: number): Promise<void>;
+    /**
+     * Updates an existing session with partial data. Throws if session does not exist.
+     * @param identity - User identity
+     * @param sessionId - Session identifier
+     * @param data - Partial session data to update
+     * @param ttl - Optional TTL in seconds (defaults to backend's default)
+     */
+    updateSession(identity: string, sessionId: string, data: Partial<SessionData>, ttl?: number): Promise<void>;
+    /**
+     * Retrieves a session
+     */
+    getSession(identity: string, sessionId: string): Promise<SessionData | null>;
+    /**
+     * Gets full session data for all of an identity's sessions
+     */
+    getIdentitySessionsData(identity: string): Promise<SessionData[]>;
+    /**
+     * Removes a session
+     */
+    removeSession(identity: string, sessionId: string): Promise<void>;
+    /**
+     * Gets all sessions IDs of an identity
+     */
+    getIdentityMcpSessions(identity: string): Promise<string[]>;
+    /**
+     * Gets all session IDs across all users (Admin)
+     */
+    getAllSessionIds(): Promise<string[]>;
+    /**
+     * Clears all sessions (Admin)
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Clean up expired sessions
+     */
+    cleanupExpiredSessions(): Promise<void>;
+    /**
+     * Disconnect from storage backend
+     */
+    disconnect(): Promise<void>;
+}
+
+/**
+ * Global session store instance
+ * Uses lazy initialization with a Proxy to handle async setup transparently
+ */
+declare const storage: StorageBackend;
+
+/**
+ * SSE (Server-Sent Events) Handler for MCP Connections
+ * Provides real-time connection state updates to clients
+ * Based on Cloudflare's agents pattern but adapted for HTTP/SSE
+ */
+
+interface ClientMetadata {
+    clientName?: string;
+    clientUri?: string;
+    logoUri?: string;
+    policyUri?: string;
+}
+interface SSEHandlerOptions {
+    /**
+     * User/Client identifier
+     */
+    identity: string;
+    /**
+     * Optional callback for authentication/authorization
+     */
+    onAuth?: (identity: string) => Promise<boolean>;
+    /**
+     * Heartbeat interval in ms (default: 30000)
+     */
+    heartbeatInterval?: number;
+    /**
+     * Static OAuth client metadata defaults (for all connections)
+     */
+    clientDefaults?: ClientMetadata;
+    /**
+     * Dynamic OAuth client metadata getter (per-request, useful for multi-tenant)
+     * Takes precedence over clientDefaults
+     */
+    getClientMetadata?: (request?: any) => ClientMetadata | Promise<ClientMetadata>;
+}
+/**
+ * SSE Connection Manager
+ * Handles a single SSE connection and manages MCP operations
+ */
+declare class SSEConnectionManager {
+    private options;
+    private sendEvent;
+    private identity;
+    private clients;
+    private heartbeatTimer?;
+    private isActive;
+    constructor(options: SSEHandlerOptions, sendEvent: (event: McpConnectionEvent | McpObservabilityEvent | McpRpcResponse) => void);
+    /**
+     * Get resolved client metadata (dynamic > static > defaults)
+     */
+    private getResolvedClientMetadata;
+    /**
+     * Start heartbeat to keep connection alive
+     */
+    private startHeartbeat;
+    /**
+     * Handle incoming RPC requests
+     */
+    handleRequest(request: McpRpcRequest): Promise<void>;
+    /**
+     * Get all user sessions
+     */
+    private getSessions;
+    /**
+     * Connect to an MCP server
+     */
+    private connect;
+    /**
+     * Disconnect from an MCP server
+     */
+    private disconnect;
+    /**
+     * Helper to get or restore a client
+     */
+    private getOrCreateClient;
+    /**
+     * List tools from a session
+     */
+    private listTools;
+    /**
+     * Call a tool
+     */
+    private callTool;
+    /**
+     * Refresh/validate a session
+     */
+    private restoreSession;
+    /**
+     * Complete OAuth authorization
+     */
+    private finishAuth;
+    /**
+     * List prompts from a session
+     */
+    private listPrompts;
+    /**
+     * Get a specific prompt
+     */
+    private getPrompt;
+    /**
+     * List resources from a session
+     */
+    private listResources;
+    /**
+     * Read a specific resource
+     */
+    private readResource;
+    /**
+     * Emit connection event
+     */
+    private emitConnectionEvent;
+    /**
+     * Cleanup and close all connections
+     */
+    dispose(): void;
+}
+/**
+ * Create SSE endpoint handler
+ * Compatible with various Node.js frameworks
+ */
+declare function createSSEHandler(options: SSEHandlerOptions): (req: any, res: any) => Promise<void>;
+
+/**
+ * Next.js App Router Handler for MCP SSE
+ * Provides a clean, zero-boilerplate API for Next.js applications
+ */
+
+interface NextMcpHandlerOptions {
+    /**
+     * Extract identity from request (default: from 'identity' query param)
+     */
+    getIdentity?: (request: Request) => string | null;
+    /**
+     * Extract auth token from request (default: from 'token' query param or Authorization header)
+     */
+    getAuthToken?: (request: Request) => string | null;
+    /**
+     * Authenticate user and verify access (optional)
+     * Return true if user is authenticated, false otherwise
+     */
+    authenticate?: (identity: string, token: string | null) => Promise<boolean> | boolean;
+    /**
+     * Heartbeat interval in milliseconds (default: 30000)
+     */
+    heartbeatInterval?: number;
+    /**
+     * Static OAuth client metadata defaults (for all connections)
+     * Use this for single-tenant applications with fixed branding
+     */
+    clientDefaults?: ClientMetadata;
+    /**
+     * Dynamic OAuth client metadata getter (per-request, useful for multi-tenant)
+     * Use this when you need different branding based on request (tenant, domain, etc.)
+     * Takes precedence over clientDefaults
+     */
+    getClientMetadata?: (request: Request) => ClientMetadata | Promise<ClientMetadata>;
+}
+/**
+ * Creates Next.js App Router handlers (GET and POST) for MCP SSE endpoint
+ *
+ * @example
+ * ```typescript
+ * // app/api/mcp/route.ts
+ * import { createNextMcpHandler } from '@mcp-ts/core/server';
+ *
+ * export const { GET, POST } = createNextMcpHandler();
+ * ```
+ */
+declare function createNextMcpHandler(options?: NextMcpHandlerOptions): {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+};
+
+export { type ClientMetadata, McpConnectionEvent, McpObservabilityEvent, McpRpcRequest, McpRpcResponse, type NextMcpHandlerOptions, SSEConnectionManager, type SSEHandlerOptions, type StorageBackend, createNextMcpHandler, createSSEHandler, storage };