@mcp-ts/sdk 1.2.0 → 1.3.1

package/src/client/react/agui-subscriber.ts

@@ -1,275 +0,0 @@
-/**
- * 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
- */
-
-import type { AgentSubscriber, AbstractAgent } from '@ag-ui/client';
-
-/**
- * MCP App UI event payload emitted from middleware
- */
-export 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
- */
-export type McpAppEventHandler = (event: McpAppEvent) => void;
-
-/**
- * Event handler for tool call events
- */
-export interface ToolCallEventData {
-  toolCallId: string;
-  toolName: string;
-  args?: Record<string, unknown>;
-  result?: any;
-  status: 'start' | 'args' | 'end' | 'result';
-}
-
-export type ToolCallEventHandler = (event: ToolCallEventData) => void;
-
-/**
- * Configuration for MCP app subscriber
- */
-export 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);
- * ```
- */
-export function createMcpAppSubscriber(
-  config: McpAppSubscriberConfig
-): AgentSubscriber {
-  const eventName = config.eventName || 'mcp-apps-ui';
-
-  const subscriber: AgentSubscriber = {
-    // Listen for custom MCP app events from middleware
-    onCustomEvent: ({ event }) => {
-      if (event.name === eventName && config.onMcpApp) {
-        const payload = event.value as McpAppEvent;
-        config.onMcpApp(payload);
-      }
-    },
-
-    // Listen for tool call lifecycle events
-    onToolCallStartEvent: (params) => {
-      if (config.onToolCall && params.event.toolCallName) {
-        config.onToolCall({
-          toolCallId: params.event.toolCallId || '',
-          toolName: params.event.toolCallName,
-          status: 'start',
-        });
-      }
-    },
-
-    onToolCallArgsEvent: (params) => {
-      if (config.onToolCall) {
-        // partialToolCallArgs contains the parsed args
-        const args = params.partialToolCallArgs;
-
-        config.onToolCall({
-          toolCallId: params.event.toolCallId || '',
-          toolName: params.toolCallName || '', // toolCallName is in params, not event
-          args,
-          status: 'args',
-        });
-      }
-    },
-
-    onToolCallEndEvent: (params) => {
-      if (config.onToolCall && params.event.toolCallId) {
-        config.onToolCall({
-          toolCallId: params.event.toolCallId,
-          toolName: params.toolCallName || '', // toolCallName is in params, not event
-          status: 'end',
-        });
-      }
-    },
-
-    onToolCallResultEvent: (params) => {
-      if (config.onToolCall && params.event.toolCallId) {
-        config.onToolCall({
-          toolCallId: params.event.toolCallId,
-          toolName: '', // Not available in result event
-          result: params.event.content, // content contains the result
-          status: 'result',
-        });
-      }
-    },
-  };
-
-  return subscriber;
-}
-
-/**
- * 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();
- * ```
- */
-export function subscribeMcpAppEvents(
-  agent: AbstractAgent,
-  config: McpAppSubscriberConfig
-): () => void {
-  const subscriber = createMcpAppSubscriber(config);
-  const { unsubscribe } = agent.subscribe(subscriber);
-  return unsubscribe;
-}
-
-/**
- * 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.
- */
-export class McpAppEventManager {
-  private events: Map<string, McpAppEvent> = new Map();
-  private toolCalls: Map<string, ToolCallEventData> = new Map();
-  private listeners: Set<() => void> = new Set();
-  private unsubscribe?: () => void;
-  private cachedSnapshot: Record<string, McpAppEvent> = {};
-
-  /**
-   * Attach to an AG-UI agent
-   */
-  attach(agent: AbstractAgent): void {
-    if (this.unsubscribe) {
-      this.unsubscribe();
-    }
-
-    this.unsubscribe = subscribeMcpAppEvents(agent, {
-      onMcpApp: (event) => {
-        this.events.set(event.toolName, event);
-        this.cachedSnapshot = Object.fromEntries(this.events);
-        this.notify();
-      },
-      onToolCall: (event) => {
-        if (event.toolCallId) {
-          this.toolCalls.set(event.toolCallId, event);
-          this.notify();
-        }
-      },
-    });
-  }
-
-  /**
-   * Detach from the current agent
-   */
-  detach(): void {
-    if (this.unsubscribe) {
-      this.unsubscribe();
-      this.unsubscribe = undefined;
-    }
-  }
-
-  /**
-   * Get MCP app event for a specific tool
-   */
-  getEvent(toolName: string): McpAppEvent | undefined {
-    return this.events.get(toolName);
-  }
-
-  /**
-   * Get all MCP app events (cached for useSyncExternalStore)
-   */
-  getAllEvents(): Record<string, McpAppEvent> {
-    return this.cachedSnapshot;
-  }
-
-  /**
-   * Get tool call event by ID
-   */
-  getToolCall(toolCallId: string): ToolCallEventData | undefined {
-    return this.toolCalls.get(toolCallId);
-  }
-
-  /**
-   * Subscribe to event changes
-   */
-  subscribe(listener: () => void): () => void {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
-  }
-
-  /**
-   * Clear all events
-   */
-  clear(): void {
-    this.events.clear();
-    this.toolCalls.clear();
-    this.cachedSnapshot = {};
-    this.notify();
-  }
-
-  private notify(): void {
-    this.listeners.forEach(listener => listener());
-  }
-}

package/src/client/react/use-agui-subscriber.ts

@@ -1,270 +0,0 @@
-/**
- * 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.
- */
-
-import { useEffect, useState, useSyncExternalStore, useMemo } from 'react';
-import type { AbstractAgent } from '@ag-ui/client';
-import {
-  createMcpAppSubscriber,
-  McpAppEventManager,
-  type McpAppEvent,
-  type McpAppSubscriberConfig,
-  type ToolCallEventData,
-} from './agui-subscriber.js';
-
-/**
- * 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...
- * }
- * ```
- */
-export function useAguiSubscriber(
-  agent: AbstractAgent | null | undefined,
-  config: McpAppSubscriberConfig
-): void {
-  useEffect(() => {
-    if (!agent) return;
-
-    const subscriber = createMcpAppSubscriber(config);
-    const { unsubscribe } = agent.subscribe(subscriber);
-
-    return () => unsubscribe();
-  }, [agent, config]);
-}
-
-/**
- * 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} />
- *       ))}
- *     </>
- *   );
- * }
- * ```
- */
-export 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;
-} {
-  // Create manager instance once
-  const [manager] = useState(() => new McpAppEventManager());
-
-  // Attach/detach manager when agent changes
-  useEffect(() => {
-    if (!agent) {
-      manager.detach();
-      return;
-    }
-
-    manager.attach(agent);
-    return () => manager.detach();
-  }, [agent, manager]);
-
-  // Subscribe to manager state changes using useSyncExternalStore
-  const agentApps = useSyncExternalStore(
-    (callback) => manager.subscribe(callback),
-    () => manager.getAllEvents(),
-    () => ({}) // Server-side snapshot
-  );
-
-  // Combine tool metadata with agent events
-  const apps: Record<string, McpAppEvent> = useMemo(() => {
-    const combined: Record<string, McpAppEvent> = {};
-
-    // First, add tool metadata (instant, synchronous - prioritized!)
-    if (mcpClient) {
-      for (const conn of mcpClient.connections) {
-        for (const tool of conn.tools) {
-          const meta = (tool as any)._meta;
-          if (!meta?.ui) continue;
-
-          const ui = meta.ui;
-          if (typeof ui !== 'object' || !ui) continue;
-          if (ui.visibility && !ui.visibility.includes('app')) continue;
-
-          const resourceUri =
-            typeof ui.resourceUri === 'string'
-              ? ui.resourceUri
-              : typeof ui.uri === 'string'
-              ? ui.uri
-              : undefined;
-
-          if (resourceUri) {
-            combined[tool.name] = {
-              toolCallId: '',
-              resourceUri,
-              sessionId: conn.sessionId,
-              toolName: tool.name,
-            };
-          }
-        }
-      }
-    }
-
-    // Then, merge in agent events (may have additional data like toolCallId, result)
-    for (const [toolName, event] of Object.entries(agentApps) as [string, McpAppEvent][]) {
-      if (combined[toolName]) {
-        // Merge: keep metadata's resourceUri/sessionId, add event's toolCallId/result
-        combined[toolName] = {
-          ...combined[toolName],
-          toolCallId: event.toolCallId || combined[toolName].toolCallId,
-          result: event.result,
-          input: event.input,
-          status: event.status,
-        };
-      } else {
-        // No metadata, just use the event
-        combined[toolName] = event;
-      }
-    }
-
-    // Return a Proxy that handles both base and prefixed tool names transparently
-    // This allows users to lookup apps with either format:
-    // - apps["get-time"] (base name)
-    // - apps["tool_abc123_get-time"] (prefixed name from CopilotKit)
-    return new Proxy(combined, {
-      get(target, prop: string | symbol) {
-        if (typeof prop !== 'string') return undefined;
-
-        // Try exact match first (base name)
-        if (prop in target) return target[prop];
-
-        // Extract base name from prefixed format: "tool_xxx_baseName" -> "baseName"
-        const match = prop.match(/^tool_[^_]+_(.+)$/);
-        if (match && match[1] in target) {
-          return target[match[1]];
-        }
-
-        return undefined;
-      },
-      // Support Object.entries, Object.keys, etc. by returning base names
-      ownKeys(target) {
-        return Reflect.ownKeys(target);
-      },
-      getOwnPropertyDescriptor(target, prop) {
-        return Reflect.getOwnPropertyDescriptor(target, prop);
-      }
-    });
-  }, [agentApps, mcpClient]);
-
-  return {
-    apps,
-    // getApp handles both base and prefixed names transparently via the Proxy
-    getApp: (toolName: string) => apps[toolName] as McpAppEvent | undefined,
-    clear: () => manager.clear(),
-  };
-}
-
-/**
- * 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>
- *   );
- * }
- * ```
- */
-export function useToolCallEvents(agent: AbstractAgent | null | undefined): {
-  /** All tool call events indexed by tool call ID */
-  toolCalls: Record<string, ToolCallEventData>;
-} {
-  const [toolCalls, setToolCalls] = useState<Record<string, ToolCallEventData>>({});
-
-  useEffect(() => {
-    if (!agent) {
-      setToolCalls({});
-      return;
-    }
-
-    const subscriber = createMcpAppSubscriber({
-      onToolCall: (event) => {
-        setToolCalls((prev) => ({
-          ...prev,
-          [event.toolCallId]: event,
-        }));
-      },
-    });
-
-    const { unsubscribe } = agent.subscribe(subscriber);
-
-    return () => unsubscribe();
-  }, [agent]);
-
-  return { toolCalls };
-}

package/src/client/react/use-mcp-app-iframe.ts

@@ -1,164 +0,0 @@
-/**
- * useMcpAppIframe Hook
- * Manages iframe lifecycle, app host communication, and tool data flow
- */
-
-import { useEffect, useRef, useState } from 'react';
-import type { SSEClient } from '../core/sse-client.js';
-import { useAppHost } from './use-app-host.js';
-
-export 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>
- * );
- */
-export function useMcpAppIframe({
-  resourceUri,
-  sessionId,
-  toolInput,
-  toolResult,
-  toolStatus,
-  sseClient,
-}: McpAppIframeProps): McpAppIframeResult {
-  const iframeRef = useRef<HTMLIFrameElement>(null!);
-  const { host, error: hostError } = useAppHost(sseClient, iframeRef);
-
-  const [isLaunched, setIsLaunched] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
-  // Track attempt flags to ensure operations run only once
-  const launchAttemptedRef = useRef(false);
-  const toolInputSentRef = useRef(false);
-  const toolResultSentRef = useRef(false);
-
-  // Report host initialization errors
-  useEffect(() => {
-    if (hostError) {
-      setError(hostError);
-    }
-  }, [hostError]);
-
-  // Launch the app when host is ready
-  // The resource should be preloaded, so this resolves instantly
-  useEffect(() => {
-    if (!host || !resourceUri || !sessionId || launchAttemptedRef.current) return;
-
-    launchAttemptedRef.current = true;
-
-    host
-      .launch(resourceUri, sessionId)
-      .then(() => {
-        setIsLaunched(true);
-      })
-      .catch((err) => {
-        const error = err instanceof Error ? err : new Error(String(err));
-        setError(error);
-      });
-  }, [host, resourceUri, sessionId]);
-
-  // Send tool input to the app when available and launched
-  useEffect(() => {
-    if (!host || !isLaunched || !toolInput || toolInputSentRef.current) return;
-
-    toolInputSentRef.current = true;
-    host.sendToolInput(toolInput);
-  }, [host, isLaunched, toolInput]);
-
-  // Send tool result to the app when available and complete
-  useEffect(() => {
-    if (!host || !isLaunched || toolResult === undefined || toolResultSentRef.current) return;
-    if (toolStatus !== 'complete') return;
-
-    toolResultSentRef.current = true;
-
-    // Format result - wrap string results in content array for MCP compatibility
-    const formattedResult =
-      typeof toolResult === 'string'
-        ? { content: [{ type: 'text', text: toolResult }] }
-        : toolResult;
-
-    host.sendToolResult(formattedResult);
-  }, [host, isLaunched, toolResult, toolStatus]);
-
-  return {
-    iframeRef,
-    isLaunched,
-    error,
-  };
-}