@mcp-ts/sdk 1.1.0 → 1.2.0

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

@@ -0,0 +1,275 @@
+/**
+ * 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/index.ts

@@ -3,9 +3,28 @@
  * React client-side exports for MCP connection management
  */
 
-// React Hook
-export { useMcp, type UseMcpOptions, type McpClient, type McpConnection } from './useMcp';
-export { useMcpApp } from './use-mcp-app';
+// React Hooks
+export { useMcp, type UseMcpOptions, type McpClient, type McpConnection } from './use-mcp.js';
+export { useAppHost } from './use-app-host.js';
+export { useMcpAppIframe, type McpAppIframeProps } from './use-mcp-app-iframe.js';
+
+// AG-UI Subscriber Pattern (Framework-agnostic)
+export {
+  useAguiSubscriber,
+  useMcpApps,
+  useToolCallEvents,
+} from './use-agui-subscriber.js';
+
+export {
+  createMcpAppSubscriber,
+  subscribeMcpAppEvents,
+  McpAppEventManager,
+  type McpAppEvent,
+  type McpAppEventHandler,
+  type ToolCallEventData,
+  type ToolCallEventHandler,
+  type McpAppSubscriberConfig,
+} from './agui-subscriber.js';
 
 // Re-export shared types and client from main entry
-export * from '../index';
+export * from '../index.js';

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

@@ -0,0 +1,270 @@
+/**
+ * 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.ts → use-app-host.ts}

@@ -15,7 +15,7 @@ import { AppHost } from '../core/app-host';
  * @param options - Optional configuration
  * @returns Object containing the AppHost instance (or null) and error state
  */
-export function useMcpApp(
+export function useAppHost(
     client: SSEClient,
     iframeRef: React.RefObject<HTMLIFrameElement>,
     options?: {
@@ -56,7 +56,7 @@ export function useMcpApp(
                 // Start bridge connection (this is fast, just sets up PostMessage)
                 await appHost.start();
             } catch (err) {
-                console.error('[useMcpApp] Failed to initialize AppHost:', err);
+                console.error('[useAppHost] Failed to initialize AppHost:', err);
                 setError(err instanceof Error ? err : new Error(String(err)));
             }
         };