@mcp-ts/sdk 1.0.1 → 1.2.0

package/dist/client/index.d.mts

@@ -1,119 +1,246 @@
-import { M as McpConnectionEvent, d as McpObservabilityEvent } from '../events-BP6WyRNh.mjs';
-export { D as Disposable, a as DisposableStore, E as Emitter, b as Event, c as McpConnectionState } from '../events-BP6WyRNh.mjs';
+import { M as McpConnectionEvent, d as McpObservabilityEvent, e as McpAppsUIEvent } from '../events-BgeztGYZ.mjs';
+export { D as Disposable, a as DisposableStore, E as Emitter, b as Event, c as McpConnectionState } from '../events-BgeztGYZ.mjs';
 import { s as SessionListResult, e as ConnectParams, h as ConnectResult, j as DisconnectResult, n as ListToolsRpcResult, r as RestoreSessionResult, k as FinishAuthResult, L as ListPromptsResult, l as ListResourcesResult } from '../types-CLccx9wW.mjs';
 export { p as McpRpcRequest, q as McpRpcResponse, T as ToolInfo } from '../types-CLccx9wW.mjs';
 import '@modelcontextprotocol/sdk/types.js';
 
 /**
  * SSE Client for MCP Connections
- * Browser-side client that connects to SSE endpoint
+ *
+ * Browser-side client that manages real-time communication with the MCP server
+ * using Server-Sent Events (SSE) for server→client streaming and HTTP POST for
+ * client→server RPC requests.
+ *
+ * Key features:
+ * - Direct HTTP response for RPC calls (bypasses SSE latency)
+ * - Resource preloading for instant MCP App UI loading
+ * - Automatic reconnection with exponential backoff
+ * - Type-safe RPC methods
  */
 
 interface SSEClientOptions {
-    /**
-     * SSE endpoint URL
-     */
+    /** SSE endpoint URL */
     url: string;
-    /**
-     * User/Client identifier
-     */
+    /** User/Client identifier */
     identity: string;
-    /**
-     * Optional auth token
-     */
+    /** Optional auth token for authenticated requests */
     authToken?: string;
-    /**
-     * Connection event callback
-     */
+    /** Callback for MCP connection state changes */
     onConnectionEvent?: (event: McpConnectionEvent) => void;
-    /**
-     * Observability event callback
-     */
+    /** Callback for observability/logging events */
     onObservabilityEvent?: (event: McpObservabilityEvent) => void;
-    /**
-     * Connection status callback
-     */
-    onStatusChange?: (status: 'connecting' | 'connected' | 'disconnected' | 'error') => void;
+    /** Callback for connection status changes */
+    onStatusChange?: (status: ConnectionStatus) => void;
+    /** Callback for MCP App UI events */
+    onEvent?: (event: McpAppsUIEvent) => void;
+    /** Request timeout in milliseconds @default 60000 */
+    requestTimeout?: number;
+    /** Enable debug logging @default false */
+    debug?: boolean;
 }
+type ConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
 /**
  * SSE Client for real-time MCP connection management
  */
 declare class SSEClient {
-    private options;
+    private readonly options;
     private eventSource;
     private pendingRequests;
+    private resourceCache;
     private reconnectAttempts;
-    private maxReconnectAttempts;
-    private reconnectDelay;
     private isManuallyDisconnected;
     private connectionPromise;
     private connectionResolver;
     constructor(options: SSEClientOptions);
     /**
-     * Connect to SSE endpoint
+     * Connect to the SSE endpoint
      */
     connect(): void;
     /**
-     * Disconnect from SSE endpoint
+     * Disconnect from the SSE endpoint
      */
     disconnect(): void;
     /**
-     * Send RPC request via SSE
-     * Note: SSE is unidirectional (server->client), so we need to send requests via POST
+     * Check if connected to the SSE endpoint
+     */
+    isConnected(): boolean;
+    getSessions(): Promise<SessionListResult>;
+    connectToServer(params: ConnectParams): Promise<ConnectResult>;
+    disconnectFromServer(sessionId: string): Promise<DisconnectResult>;
+    listTools(sessionId: string): Promise<ListToolsRpcResult>;
+    callTool(sessionId: string, toolName: string, toolArgs: Record<string, unknown>): Promise<unknown>;
+    restoreSession(sessionId: string): Promise<RestoreSessionResult>;
+    finishAuth(sessionId: string, code: string): Promise<FinishAuthResult>;
+    listPrompts(sessionId: string): Promise<ListPromptsResult>;
+    getPrompt(sessionId: string, name: string, args?: Record<string, string>): Promise<unknown>;
+    listResources(sessionId: string): Promise<ListResourcesResult>;
+    readResource(sessionId: string, uri: string): Promise<unknown>;
+    /**
+     * Preload UI resources for tools that have UI metadata.
+     * Call this when tools are discovered to enable instant MCP App UI loading.
+     */
+    preloadToolUiResources(sessionId: string, tools: Array<{
+        name: string;
+        _meta?: unknown;
+    }>): void;
+    /**
+     * Get a preloaded resource from cache, or fetch if not cached.
+     */
+    getOrFetchResource(sessionId: string, uri: string): Promise<unknown>;
+    /**
+     * Check if a resource is already cached
+     */
+    hasPreloadedResource(uri: string): boolean;
+    /**
+     * Clear the resource cache
+     */
+    clearResourceCache(): void;
+    /**
+     * Send an RPC request and return the response directly from HTTP.
+     * This bypasses SSE latency by returning results in the HTTP response body.
      */
     private sendRequest;
     /**
-     * Handle RPC response
+     * Parse RPC response and handle different response formats
      */
-    private handleRpcResponse;
+    private parseRpcResponse;
     /**
-     * Get all user sessions
+     * Wait for RPC response via SSE (legacy fallback)
      */
-    getSessions(): Promise<SessionListResult>;
+    private waitForSseResponse;
     /**
-     * Connect to an MCP server
+     * Handle RPC response received via SSE (legacy)
      */
-    connectToServer(params: ConnectParams): Promise<ConnectResult>;
+    private handleRpcResponse;
+    private setupEventListeners;
+    private attemptReconnect;
+    private buildUrl;
+    private buildHeaders;
+    private rejectAllPendingRequests;
+    private extractUiResourceUri;
+    private emitUiEventIfPresent;
+    private log;
+}
+
+/**
+ * Abstraction layer for the AppHost's network communication.
+ *
+ * This interface decouples the `AppHost` from the concrete networking implementation (like `SSEClient`).
+ * Implementation can be:
+ * 1. `SSEClient`: Direct connection to MCP Server (Browser -> Server).
+ * 2. `ProxyClient`: Connection via an intermediary API (Browser -> Next.js API -> Server).
+ */
+interface AppHostClient {
     /**
-     * Disconnect from an MCP server
+     * Check if the client is connected
      */
-    disconnectFromServer(sessionId: string): Promise<DisconnectResult>;
+    isConnected(): boolean;
     /**
-     * List tools from a session
+     * Get list of active sessions
      */
-    listTools(sessionId: string): Promise<ListToolsRpcResult>;
+    getSessions(): Promise<SessionListResult>;
     /**
-     * Call a tool
+     * Call a tool on a specific session
      */
     callTool(sessionId: string, toolName: string, toolArgs: Record<string, unknown>): Promise<unknown>;
     /**
-     * Refresh/validate a session
+     * Read a resource from a specific session
      */
-    restoreSession(sessionId: string): Promise<RestoreSessionResult>;
+    readResource(sessionId: string, uri: string): Promise<unknown>;
+}
+
+/**
+ * MCP App Host
+ *
+ * Bridges the gap between an iframe (MCP App) and the SSEClient (MCP Server).
+ * Handles secure iframe sandboxing, resource loading, and bi-directional
+ * communication via the AppBridge protocol.
+ *
+ * Key features:
+ * - Secure iframe sandboxing with minimal permissions
+ * - Resource preloading for instant MCP App UI loading
+ * - Cache-aware resource fetching (SSEClient cache → local cache → direct fetch)
+ * - Support for ui:// and mcp-app:// resource URIs
+ */
+
+interface AppHostOptions {
+    /** Enable debug logging @default false */
+    debug?: boolean;
+}
+interface AppMessageParams {
+    role: string;
+    content: unknown;
+}
+/**
+ * Host for MCP Apps embedded in iframes.
+ * Manages secure communication between the app and the MCP server.
+ */
+declare class AppHost {
+    private readonly client;
+    private readonly iframe;
+    private bridge;
+    private sessionId?;
+    private resourceCache;
+    private debug;
+    /** Callback for app messages (e.g., chat messages from the app) */
+    onAppMessage?: (params: AppMessageParams) => void;
+    constructor(client: AppHostClient, iframe: HTMLIFrameElement, options?: AppHostOptions);
     /**
-     * Complete OAuth authorization
+     * Start the host. This prepares the bridge handlers but doesn't connect yet.
+     * The actual connection happens in launch() after HTML is loaded.
+     * @returns Promise that resolves immediately (bridge connects during launch)
      */
-    finishAuth(sessionId: string, code: string): Promise<FinishAuthResult>;
+    start(): Promise<void>;
     /**
-     * List available prompts
+     * Preload UI resources to enable instant app loading.
+     * Call this when tools are discovered to cache their UI resources.
      */
-    listPrompts(sessionId: string): Promise<ListPromptsResult>;
+    preload(tools: Array<{
+        _meta?: unknown;
+    }>): void;
     /**
-     * Get a specific prompt with arguments
+     * Launch an MCP App from a URL or MCP resource URI.
+     * Loads the HTML first, then establishes bridge connection.
      */
-    getPrompt(sessionId: string, name: string, args?: Record<string, string>): Promise<unknown>;
+    launch(url: string, sessionId?: string): Promise<void>;
     /**
-     * List available resources
+     * Wait for app to signal initialization complete
      */
-    listResources(sessionId: string): Promise<ListResourcesResult>;
+    private onAppReady;
     /**
-     * Read a specific resource
+     * Wait for iframe to finish loading
      */
-    readResource(sessionId: string, uri: string): Promise<unknown>;
+    private onIframeReady;
     /**
-     * Check if connected
+     * Send tool input arguments to the MCP App.
+     * Call this after launch() when tool input is available.
      */
-    isConnected(): boolean;
+    sendToolInput(args: Record<string, unknown>): void;
+    /**
+     * Send tool result to the MCP App.
+     * Call this when the tool call completes.
+     */
+    sendToolResult(result: unknown): void;
+    /**
+     * Send tool cancellation to the MCP App.
+     * Call this when the tool call is cancelled or fails.
+     */
+    sendToolCancelled(reason: string): void;
+    private configureSandbox;
+    private initializeBridge;
+    private connectBridge;
+    private handleToolCall;
+    private handleOpenLink;
+    private handleMessage;
+    private launchMcpApp;
+    private fetchResourceWithCache;
+    private preloadResource;
+    private getSessionId;
+    private isMcpUri;
+    private hasClientCache;
+    private extractUiResourceUri;
+    private decodeContent;
+    private log;
 }
 
-export { McpConnectionEvent, McpObservabilityEvent, SSEClient, type SSEClientOptions };
+export { AppHost, McpConnectionEvent, McpObservabilityEvent, SSEClient, type SSEClientOptions };

package/dist/client/index.d.ts

@@ -1,119 +1,246 @@
-import { M as McpConnectionEvent, d as McpObservabilityEvent } from '../events-BP6WyRNh.js';
-export { D as Disposable, a as DisposableStore, E as Emitter, b as Event, c as McpConnectionState } from '../events-BP6WyRNh.js';
+import { M as McpConnectionEvent, d as McpObservabilityEvent, e as McpAppsUIEvent } from '../events-BgeztGYZ.js';
+export { D as Disposable, a as DisposableStore, E as Emitter, b as Event, c as McpConnectionState } from '../events-BgeztGYZ.js';
 import { s as SessionListResult, e as ConnectParams, h as ConnectResult, j as DisconnectResult, n as ListToolsRpcResult, r as RestoreSessionResult, k as FinishAuthResult, L as ListPromptsResult, l as ListResourcesResult } from '../types-CLccx9wW.js';
 export { p as McpRpcRequest, q as McpRpcResponse, T as ToolInfo } from '../types-CLccx9wW.js';
 import '@modelcontextprotocol/sdk/types.js';
 
 /**
  * SSE Client for MCP Connections
- * Browser-side client that connects to SSE endpoint
+ *
+ * Browser-side client that manages real-time communication with the MCP server
+ * using Server-Sent Events (SSE) for server→client streaming and HTTP POST for
+ * client→server RPC requests.
+ *
+ * Key features:
+ * - Direct HTTP response for RPC calls (bypasses SSE latency)
+ * - Resource preloading for instant MCP App UI loading
+ * - Automatic reconnection with exponential backoff
+ * - Type-safe RPC methods
  */
 
 interface SSEClientOptions {
-    /**
-     * SSE endpoint URL
-     */
+    /** SSE endpoint URL */
     url: string;
-    /**
-     * User/Client identifier
-     */
+    /** User/Client identifier */
     identity: string;
-    /**
-     * Optional auth token
-     */
+    /** Optional auth token for authenticated requests */
     authToken?: string;
-    /**
-     * Connection event callback
-     */
+    /** Callback for MCP connection state changes */
     onConnectionEvent?: (event: McpConnectionEvent) => void;
-    /**
-     * Observability event callback
-     */
+    /** Callback for observability/logging events */
     onObservabilityEvent?: (event: McpObservabilityEvent) => void;
-    /**
-     * Connection status callback
-     */
-    onStatusChange?: (status: 'connecting' | 'connected' | 'disconnected' | 'error') => void;
+    /** Callback for connection status changes */
+    onStatusChange?: (status: ConnectionStatus) => void;
+    /** Callback for MCP App UI events */
+    onEvent?: (event: McpAppsUIEvent) => void;
+    /** Request timeout in milliseconds @default 60000 */
+    requestTimeout?: number;
+    /** Enable debug logging @default false */
+    debug?: boolean;
 }
+type ConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
 /**
  * SSE Client for real-time MCP connection management
  */
 declare class SSEClient {
-    private options;
+    private readonly options;
     private eventSource;
     private pendingRequests;
+    private resourceCache;
     private reconnectAttempts;
-    private maxReconnectAttempts;
-    private reconnectDelay;
     private isManuallyDisconnected;
     private connectionPromise;
     private connectionResolver;
     constructor(options: SSEClientOptions);
     /**
-     * Connect to SSE endpoint
+     * Connect to the SSE endpoint
      */
     connect(): void;
     /**
-     * Disconnect from SSE endpoint
+     * Disconnect from the SSE endpoint
      */
     disconnect(): void;
     /**
-     * Send RPC request via SSE
-     * Note: SSE is unidirectional (server->client), so we need to send requests via POST
+     * Check if connected to the SSE endpoint
+     */
+    isConnected(): boolean;
+    getSessions(): Promise<SessionListResult>;
+    connectToServer(params: ConnectParams): Promise<ConnectResult>;
+    disconnectFromServer(sessionId: string): Promise<DisconnectResult>;
+    listTools(sessionId: string): Promise<ListToolsRpcResult>;
+    callTool(sessionId: string, toolName: string, toolArgs: Record<string, unknown>): Promise<unknown>;
+    restoreSession(sessionId: string): Promise<RestoreSessionResult>;
+    finishAuth(sessionId: string, code: string): Promise<FinishAuthResult>;
+    listPrompts(sessionId: string): Promise<ListPromptsResult>;
+    getPrompt(sessionId: string, name: string, args?: Record<string, string>): Promise<unknown>;
+    listResources(sessionId: string): Promise<ListResourcesResult>;
+    readResource(sessionId: string, uri: string): Promise<unknown>;
+    /**
+     * Preload UI resources for tools that have UI metadata.
+     * Call this when tools are discovered to enable instant MCP App UI loading.
+     */
+    preloadToolUiResources(sessionId: string, tools: Array<{
+        name: string;
+        _meta?: unknown;
+    }>): void;
+    /**
+     * Get a preloaded resource from cache, or fetch if not cached.
+     */
+    getOrFetchResource(sessionId: string, uri: string): Promise<unknown>;
+    /**
+     * Check if a resource is already cached
+     */
+    hasPreloadedResource(uri: string): boolean;
+    /**
+     * Clear the resource cache
+     */
+    clearResourceCache(): void;
+    /**
+     * Send an RPC request and return the response directly from HTTP.
+     * This bypasses SSE latency by returning results in the HTTP response body.
      */
     private sendRequest;
     /**
-     * Handle RPC response
+     * Parse RPC response and handle different response formats
      */
-    private handleRpcResponse;
+    private parseRpcResponse;
     /**
-     * Get all user sessions
+     * Wait for RPC response via SSE (legacy fallback)
      */
-    getSessions(): Promise<SessionListResult>;
+    private waitForSseResponse;
     /**
-     * Connect to an MCP server
+     * Handle RPC response received via SSE (legacy)
      */
-    connectToServer(params: ConnectParams): Promise<ConnectResult>;
+    private handleRpcResponse;
+    private setupEventListeners;
+    private attemptReconnect;
+    private buildUrl;
+    private buildHeaders;
+    private rejectAllPendingRequests;
+    private extractUiResourceUri;
+    private emitUiEventIfPresent;
+    private log;
+}
+
+/**
+ * Abstraction layer for the AppHost's network communication.
+ *
+ * This interface decouples the `AppHost` from the concrete networking implementation (like `SSEClient`).
+ * Implementation can be:
+ * 1. `SSEClient`: Direct connection to MCP Server (Browser -> Server).
+ * 2. `ProxyClient`: Connection via an intermediary API (Browser -> Next.js API -> Server).
+ */
+interface AppHostClient {
     /**
-     * Disconnect from an MCP server
+     * Check if the client is connected
      */
-    disconnectFromServer(sessionId: string): Promise<DisconnectResult>;
+    isConnected(): boolean;
     /**
-     * List tools from a session
+     * Get list of active sessions
      */
-    listTools(sessionId: string): Promise<ListToolsRpcResult>;
+    getSessions(): Promise<SessionListResult>;
     /**
-     * Call a tool
+     * Call a tool on a specific session
      */
     callTool(sessionId: string, toolName: string, toolArgs: Record<string, unknown>): Promise<unknown>;
     /**
-     * Refresh/validate a session
+     * Read a resource from a specific session
      */
-    restoreSession(sessionId: string): Promise<RestoreSessionResult>;
+    readResource(sessionId: string, uri: string): Promise<unknown>;
+}
+
+/**
+ * MCP App Host
+ *
+ * Bridges the gap between an iframe (MCP App) and the SSEClient (MCP Server).
+ * Handles secure iframe sandboxing, resource loading, and bi-directional
+ * communication via the AppBridge protocol.
+ *
+ * Key features:
+ * - Secure iframe sandboxing with minimal permissions
+ * - Resource preloading for instant MCP App UI loading
+ * - Cache-aware resource fetching (SSEClient cache → local cache → direct fetch)
+ * - Support for ui:// and mcp-app:// resource URIs
+ */
+
+interface AppHostOptions {
+    /** Enable debug logging @default false */
+    debug?: boolean;
+}
+interface AppMessageParams {
+    role: string;
+    content: unknown;
+}
+/**
+ * Host for MCP Apps embedded in iframes.
+ * Manages secure communication between the app and the MCP server.
+ */
+declare class AppHost {
+    private readonly client;
+    private readonly iframe;
+    private bridge;
+    private sessionId?;
+    private resourceCache;
+    private debug;
+    /** Callback for app messages (e.g., chat messages from the app) */
+    onAppMessage?: (params: AppMessageParams) => void;
+    constructor(client: AppHostClient, iframe: HTMLIFrameElement, options?: AppHostOptions);
     /**
-     * Complete OAuth authorization
+     * Start the host. This prepares the bridge handlers but doesn't connect yet.
+     * The actual connection happens in launch() after HTML is loaded.
+     * @returns Promise that resolves immediately (bridge connects during launch)
      */
-    finishAuth(sessionId: string, code: string): Promise<FinishAuthResult>;
+    start(): Promise<void>;
     /**
-     * List available prompts
+     * Preload UI resources to enable instant app loading.
+     * Call this when tools are discovered to cache their UI resources.
      */
-    listPrompts(sessionId: string): Promise<ListPromptsResult>;
+    preload(tools: Array<{
+        _meta?: unknown;
+    }>): void;
     /**
-     * Get a specific prompt with arguments
+     * Launch an MCP App from a URL or MCP resource URI.
+     * Loads the HTML first, then establishes bridge connection.
      */
-    getPrompt(sessionId: string, name: string, args?: Record<string, string>): Promise<unknown>;
+    launch(url: string, sessionId?: string): Promise<void>;
     /**
-     * List available resources
+     * Wait for app to signal initialization complete
      */
-    listResources(sessionId: string): Promise<ListResourcesResult>;
+    private onAppReady;
     /**
-     * Read a specific resource
+     * Wait for iframe to finish loading
      */
-    readResource(sessionId: string, uri: string): Promise<unknown>;
+    private onIframeReady;
     /**
-     * Check if connected
+     * Send tool input arguments to the MCP App.
+     * Call this after launch() when tool input is available.
      */
-    isConnected(): boolean;
+    sendToolInput(args: Record<string, unknown>): void;
+    /**
+     * Send tool result to the MCP App.
+     * Call this when the tool call completes.
+     */
+    sendToolResult(result: unknown): void;
+    /**
+     * Send tool cancellation to the MCP App.
+     * Call this when the tool call is cancelled or fails.
+     */
+    sendToolCancelled(reason: string): void;
+    private configureSandbox;
+    private initializeBridge;
+    private connectBridge;
+    private handleToolCall;
+    private handleOpenLink;
+    private handleMessage;
+    private launchMcpApp;
+    private fetchResourceWithCache;
+    private preloadResource;
+    private getSessionId;
+    private isMcpUri;
+    private hasClientCache;
+    private extractUiResourceUri;
+    private decodeContent;
+    private log;
 }
 
-export { McpConnectionEvent, McpObservabilityEvent, SSEClient, type SSEClientOptions };
+export { AppHost, McpConnectionEvent, McpObservabilityEvent, SSEClient, type SSEClientOptions };