@mcp-ts/sdk 1.1.0 → 1.2.0

package/dist/client/react.d.mts

@@ -4,6 +4,7 @@ import { c as McpConnectionState, M as McpConnectionEvent } from '../events-Bgez
 export { D as Disposable, a as DisposableStore, E as Emitter, b as Event, d as McpObservabilityEvent } from '../events-BgeztGYZ.mjs';
 import { T as ToolInfo, k as FinishAuthResult, n as ListToolsRpcResult, L as ListPromptsResult, l as ListResourcesResult } from '../types-CLccx9wW.mjs';
 export { p as McpRpcRequest, q as McpRpcResponse } from '../types-CLccx9wW.mjs';
+import { AbstractAgent, AgentSubscriber } from '@ag-ui/client';
 import '@modelcontextprotocol/sdk/types.js';
 
 /**
@@ -151,7 +152,7 @@ interface McpClient {
     /**
      * Access the underlying SSEClient instance (for advanced usage like AppHost)
      */
-    client: SSEClient | null;
+    sseClient: SSEClient | null;
 }
 /**
  * React hook for MCP connection management with SSE
@@ -171,7 +172,7 @@ declare function useMcp(options: UseMcpOptions): McpClient;
  * @param options - Optional configuration
  * @returns Object containing the AppHost instance (or null) and error state
  */
-declare function useMcpApp(client: SSEClient, iframeRef: React.RefObject<HTMLIFrameElement>, options?: {
+declare function useAppHost(client: SSEClient, iframeRef: React.RefObject<HTMLIFrameElement>, options?: {
     /** Callback when the App sends a message (e.g. to chat) */
     onMessage?: (params: {
         role: string;
@@ -182,4 +183,351 @@ declare function useMcpApp(client: SSEClient, iframeRef: React.RefObject<HTMLIFr
     error: Error | null;
 };
 
-export { AppHost, type McpClient, type McpConnection, McpConnectionEvent, McpConnectionState, SSEClient, ToolInfo, type UseMcpOptions, useMcp, useMcpApp };
+/**
+ * useMcpAppIframe Hook
+ * Manages iframe lifecycle, app host communication, and tool data flow
+ */
+
+interface McpAppIframeProps {
+    /**
+     * The resource URI of the MCP app to load
+     */
+    resourceUri: string;
+    /**
+     * The session ID for the MCP connection
+     */
+    sessionId: string;
+    /**
+     * Tool input arguments to send to the app
+     */
+    toolInput?: Record<string, unknown>;
+    /**
+     * Tool execution result to send to the app
+     */
+    toolResult?: unknown;
+    /**
+     * Current status of the tool execution
+     */
+    toolStatus?: 'executing' | 'inProgress' | 'complete';
+    /**
+     * SSE client instance for MCP operations
+     */
+    sseClient: SSEClient;
+}
+interface McpAppIframeResult {
+    /**
+     * Ref to attach to the iframe element
+     */
+    iframeRef: React.RefObject<HTMLIFrameElement>;
+    /**
+     * Whether the app has been successfully launched
+     */
+    isLaunched: boolean;
+    /**
+     * Error that occurred during initialization or execution
+     */
+    error: Error | null;
+}
+/**
+ * Hook to manage MCP app iframe lifecycle and communication
+ *
+ * Handles:
+ * - Iframe setup and host initialization
+ * - App launching with resource preloading
+ * - Tool input and result communication
+ * - Error tracking
+ *
+ * Returns refs and state for UI rendering - styling is left to the user.
+ *
+ * @param props - Configuration for the iframe
+ * @returns Iframe ref, launch state, and error state
+ *
+ * @example
+ * const { iframeRef, isLaunched, error } = useMcpAppIframe({
+ *   resourceUri: "https://example.com/app",
+ *   sessionId: "session-123",
+ *   toolInput: myInput,
+ *   toolResult: myResult,
+ *   toolStatus: "complete",
+ *   sseClient: sseClient,
+ * });
+ *
+ * return (
+ *   <div className="my-custom-container">
+ *     <iframe ref={iframeRef} className="my-iframe-style" />
+ *     {!isLaunched && <p>Loading...</p>}
+ *     {error && <p>Error: {error.message}</p>}
+ *   </div>
+ * );
+ */
+declare function useMcpAppIframe({ resourceUri, sessionId, toolInput, toolResult, toolStatus, sseClient, }: McpAppIframeProps): McpAppIframeResult;
+
+/**
+ * AG-UI Subscriber for MCP Apps
+ *
+ * Provides a standalone subscriber pattern for listening to AG-UI agent events
+ * without depending on CopilotKit components. This allows MCP apps to be rendered
+ * based on tool call events from any AG-UI agent.
+ *
+ * @requires @ag-ui/client - Peer dependency for AG-UI types
+ */
+
+/**
+ * MCP App UI event payload emitted from middleware
+ */
+interface McpAppEvent {
+    /** Tool call ID that triggered this UI */
+    toolCallId: string;
+    /** Resource URI for the MCP app */
+    resourceUri: string;
+    /** Session ID for the MCP connection */
+    sessionId?: string;
+    /** Name of the tool that was called */
+    toolName: string;
+    /** Tool execution result (if available) */
+    result?: any;
+    /** Tool input arguments */
+    input?: Record<string, unknown>;
+    /** Tool execution status */
+    status?: 'executing' | 'inProgress' | 'complete';
+}
+/**
+ * Event handler for MCP app events
+ */
+type McpAppEventHandler = (event: McpAppEvent) => void;
+/**
+ * Event handler for tool call events
+ */
+interface ToolCallEventData {
+    toolCallId: string;
+    toolName: string;
+    args?: Record<string, unknown>;
+    result?: any;
+    status: 'start' | 'args' | 'end' | 'result';
+}
+type ToolCallEventHandler = (event: ToolCallEventData) => void;
+/**
+ * Configuration for MCP app subscriber
+ */
+interface McpAppSubscriberConfig {
+    /** Handler for MCP app UI events */
+    onMcpApp?: McpAppEventHandler;
+    /** Handler for general tool call events */
+    onToolCall?: ToolCallEventHandler;
+    /** Custom event name to listen for (default: 'mcp-apps-ui') */
+    eventName?: string;
+}
+/**
+ * Creates an AG-UI AgentSubscriber that listens for MCP app events
+ *
+ * This subscriber can be attached to any AG-UI agent instance using agent.subscribe()
+ * and will call the provided handlers when MCP app events are detected.
+ *
+ * @param config - Configuration with event handlers
+ * @returns AgentSubscriber that can be passed to agent.subscribe()
+ *
+ * @example
+ * ```typescript
+ * import { createMcpAppSubscriber } from '@mcp-ts/sdk/client/react';
+ * import { HttpAgent } from '@ag-ui/client';
+ *
+ * const agent = new HttpAgent({ url: '/api/agent' });
+ *
+ * const subscriber = createMcpAppSubscriber({
+ *   onMcpApp: (event) => {
+ *     console.log('MCP App:', event.resourceUri);
+ *     // Render MCP app UI
+ *   },
+ *   onToolCall: (event) => {
+ *     console.log('Tool Call:', event.toolName, event.status);
+ *   }
+ * });
+ *
+ * const { unsubscribe } = agent.subscribe(subscriber);
+ * ```
+ */
+declare function createMcpAppSubscriber(config: McpAppSubscriberConfig): AgentSubscriber;
+/**
+ * Subscribes to MCP app events from an AG-UI agent
+ *
+ * Convenience function that creates a subscriber and attaches it to an agent.
+ * Returns an unsubscribe function to clean up the subscription.
+ *
+ * @param agent - AG-UI agent instance
+ * @param config - Configuration with event handlers
+ * @returns Unsubscribe function
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = subscribeMcpAppEvents(agent, {
+ *   onMcpApp: (event) => {
+ *     renderMcpApp(event.resourceUri, event.sessionId);
+ *   }
+ * });
+ *
+ * // Later, to cleanup:
+ * unsubscribe();
+ * ```
+ */
+declare function subscribeMcpAppEvents(agent: AbstractAgent, config: McpAppSubscriberConfig): () => void;
+/**
+ * Manager for MCP app events with built-in state management
+ *
+ * Provides a higher-level API for managing MCP app events with automatic
+ * state tracking. Useful for React contexts or state management systems.
+ */
+declare class McpAppEventManager {
+    private events;
+    private toolCalls;
+    private listeners;
+    private unsubscribe?;
+    private cachedSnapshot;
+    /**
+     * Attach to an AG-UI agent
+     */
+    attach(agent: AbstractAgent): void;
+    /**
+     * Detach from the current agent
+     */
+    detach(): void;
+    /**
+     * Get MCP app event for a specific tool
+     */
+    getEvent(toolName: string): McpAppEvent | undefined;
+    /**
+     * Get all MCP app events (cached for useSyncExternalStore)
+     */
+    getAllEvents(): Record<string, McpAppEvent>;
+    /**
+     * Get tool call event by ID
+     */
+    getToolCall(toolCallId: string): ToolCallEventData | undefined;
+    /**
+     * Subscribe to event changes
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Clear all events
+     */
+    clear(): void;
+    private notify;
+}
+
+/**
+ * React Hook for AG-UI Subscriber Pattern
+ *
+ * Provides React hooks for subscribing to AG-UI agent events without
+ * depending on CopilotKit components. Works with any AG-UI agent instance.
+ */
+
+/**
+ * React hook to subscribe to MCP app events from an AG-UI agent
+ *
+ * This hook manages the subscription lifecycle and provides event state.
+ * It's completely independent of CopilotKit and works with any AG-UI agent.
+ *
+ * @param agent - AG-UI agent instance (can be from HttpAgent, LangGraphAgent, etc.)
+ * @param config - Configuration with event handlers
+ *
+ * @example
+ * ```typescript
+ * import { useAguiSubscriber } from '@mcp-ts/sdk/client/react';
+ * import { HttpAgent } from '@ag-ui/client';
+ *
+ * function MyComponent() {
+ *   const [agent] = useState(() => new HttpAgent({ url: '/api/agent' }));
+ *
+ *   useAguiSubscriber(agent, {
+ *     onMcpApp: (event) => {
+ *       console.log('MCP App:', event.resourceUri);
+ *     },
+ *     onToolCall: (event) => {
+ *       console.log('Tool:', event.toolName, event.status);
+ *     }
+ *   });
+ *
+ *   // Your UI code...
+ * }
+ * ```
+ */
+declare function useAguiSubscriber(agent: AbstractAgent | null | undefined, config: McpAppSubscriberConfig): void;
+/**
+ * React hook for managing MCP apps
+ *
+ * Returns MCP apps that need to be rendered. Automatically combines:
+ * 1. Tool metadata (instant, synchronous)
+ * 2. AG-UI agent events (async, after tool execution)
+ *
+ * Prioritizes tool metadata for instant loading.
+ *
+ * @param agent - AG-UI agent instance (optional)
+ * @param mcpClient - MCP client with tool metadata (optional)
+ * @returns Object with MCP apps and helper functions
+ *
+ * @example
+ * ```typescript
+ * import { useMcpApps } from '@mcp-ts/sdk/client/react';
+ *
+ * function ToolRenderer() {
+ *   const { agent } = useAgent({ agentId: "myAgent" });
+ *   const { mcpClient } = useMcpContext();
+ *   const { apps } = useMcpApps(agent, mcpClient);
+ *
+ *   return (
+ *     <>
+ *       {Object.entries(apps).map(([toolName, app]) => (
+ *         <McpAppUI key={toolName} {...app} />
+ *       ))}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function useMcpApps(agent?: AbstractAgent | null, mcpClient?: {
+    connections: Array<{
+        tools: any[];
+        sessionId: string;
+    }>;
+} | null): {
+    /** All MCP apps indexed by tool name */
+    apps: Record<string, McpAppEvent>;
+    /** Get app for a specific tool */
+    getApp: (toolName: string) => McpAppEvent | undefined;
+    /** Clear all apps */
+    clear: () => void;
+};
+/**
+ * React hook for tracking tool call lifecycle events
+ *
+ * Provides access to detailed tool call events (start, args, end, result)
+ * for debugging or custom UI rendering.
+ *
+ * @param agent - AG-UI agent instance
+ * @returns Object with tool call events and helper functions
+ *
+ * @example
+ * ```typescript
+ * import { useToolCallEvents } from '@mcp-ts/sdk/client/react';
+ *
+ * function ToolCallDebugger() {
+ *   const [agent] = useState(() => new HttpAgent({ url: '/api/agent' }));
+ *   const { toolCalls } = useToolCallEvents(agent);
+ *
+ *   return (
+ *     <div>
+ *       {Object.entries(toolCalls).map(([id, event]) => (
+ *         <div key={id}>
+ *           {event.toolName} - {event.status}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useToolCallEvents(agent: AbstractAgent | null | undefined): {
+    /** All tool call events indexed by tool call ID */
+    toolCalls: Record<string, ToolCallEventData>;
+};
+
+export { AppHost, type McpAppEvent, type McpAppEventHandler, McpAppEventManager, type McpAppIframeProps, type McpAppSubscriberConfig, type McpClient, type McpConnection, McpConnectionEvent, McpConnectionState, SSEClient, type ToolCallEventData, type ToolCallEventHandler, ToolInfo, type UseMcpOptions, createMcpAppSubscriber, subscribeMcpAppEvents, useAguiSubscriber, useAppHost, useMcp, useMcpAppIframe, useMcpApps, useToolCallEvents };