@mcp-ts/sdk 1.2.0 → 1.3.1

package/dist/client/react.d.ts

@@ -4,7 +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.js';
 import { T as ToolInfo, k as FinishAuthResult, n as ListToolsRpcResult, L as ListPromptsResult, l as ListResourcesResult } from '../types-CLccx9wW.js';
 export { p as McpRpcRequest, q as McpRpcResponse } from '../types-CLccx9wW.js';
-import { AbstractAgent, AgentSubscriber } from '@ag-ui/client';
+import React$1 from 'react';
 import '@modelcontextprotocol/sdk/types.js';
 
 /**
@@ -66,7 +66,7 @@ interface McpConnection {
     error?: string;
     connectedAt?: Date;
 }
-interface McpClient {
+interface McpClient$1 {
     /**
      * All connections
      */
@@ -157,7 +157,7 @@ interface McpClient {
 /**
  * React hook for MCP connection management with SSE
  */
-declare function useMcp(options: UseMcpOptions): McpClient;
+declare function useMcp(options: UseMcpOptions): McpClient$1;
 
 /**
  * Hook to host an MCP App in a React component
@@ -184,350 +184,70 @@ declare function useAppHost(client: SSEClient, iframeRef: React.RefObject<HTMLIF
 };
 
 /**
- * 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,
- * });
+ * MCP Apps Hook
  *
- * return (
- *   <div className="my-custom-container">
- *     <iframe ref={iframeRef} className="my-iframe-style" />
- *     {!isLaunched && <p>Loading...</p>}
- *     {error && <p>Error: {error.message}</p>}
- *   </div>
- * );
+ * Provides utilities for rendering interactive UI components from MCP servers.
  */
-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';
+interface McpClient {
+    connections: Array<{
+        sessionId: string;
+        tools: Array<{
+            name: string;
+            mcpApp?: {
+                resourceUri: string;
+            };
+            _meta?: {
+                ui?: {
+                    resourceUri?: string;
+                };
+                'ui/resourceUri'?: string;
+            };
+        }>;
+    }>;
+    sseClient?: SSEClient | null;
 }
-/**
- * Event handler for MCP app events
- */
-type McpAppEventHandler = (event: McpAppEvent) => void;
-/**
- * Event handler for tool call events
- */
-interface ToolCallEventData {
-    toolCallId: string;
+interface McpAppMetadata {
     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;
+    resourceUri: string;
+    sessionId: 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;
+interface McpAppRendererProps {
+    metadata: McpAppMetadata;
+    input?: Record<string, unknown>;
+    result?: unknown;
+    status: 'executing' | 'inProgress' | 'complete' | 'idle';
+    sseClient?: SSEClient | null;
+    /** Custom CSS class for the container */
+    className?: string;
 }
-
 /**
- * React Hook for AG-UI Subscriber Pattern
+ * Simple hook to get MCP app metadata
  *
- * 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
+ * @param mcpClient - The MCP client from useMcp() or context
+ * @returns Object with getAppMetadata function and McpAppRenderer component
  *
  * @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);
+ * ```tsx
+ * function ToolRenderer(props) {
+ *   const { getAppMetadata, McpAppRenderer } = useMcpApps(mcpClient);
+ *   const metadata = getAppMetadata(props.name);
  *
+ *   if (!metadata) return null;
  *   return (
- *     <div>
- *       {Object.entries(toolCalls).map(([id, event]) => (
- *         <div key={id}>
- *           {event.toolName} - {event.status}
- *         </div>
- *       ))}
- *     </div>
+ *     <McpAppRenderer
+ *       metadata={metadata}
+ *       input={props.args}
+ *       result={props.result}
+ *       status={props.status}
+ *     />
  *   );
  * }
  * ```
  */
-declare function useToolCallEvents(agent: AbstractAgent | null | undefined): {
-    /** All tool call events indexed by tool call ID */
-    toolCalls: Record<string, ToolCallEventData>;
+declare function useMcpApps(mcpClient: McpClient | null): {
+    getAppMetadata: (toolName: string) => McpAppMetadata | undefined;
+    McpAppRenderer: React$1.NamedExoticComponent<McpAppRendererProps>;
 };
 
-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 };
+export { AppHost, type McpClient$1 as McpClient, type McpConnection, McpConnectionEvent, McpConnectionState, SSEClient, ToolInfo, type UseMcpOptions, useAppHost, useMcp, useMcpApps };