@ai-sdk/react 4.0.0-canary.125 → 4.0.0-canary.127

package/src/mcp-apps/bridge.ts

@@ -0,0 +1,405 @@
+import { isJSONObject } from '@ai-sdk/provider';
+import type {
+  MCPAppBridgeHandlers,
+  MCPAppHostContext,
+  MCPAppJsonRpcMessage,
+  MCPAppJsonRpcNotification,
+  MCPAppJsonRpcRequest,
+  MCPAppJsonRpcResponse,
+  MCPAppToolCallParams,
+} from './types';
+
+const MCP_APP_PROTOCOL_VERSION = '2026-01-26';
+
+/**
+ * Checks whether an iframe message looks like a JSON-RPC 2.0 message.
+ */
+function isJsonRpcMessage(value: unknown): value is MCPAppJsonRpcMessage {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    'jsonrpc' in value &&
+    value.jsonrpc === '2.0'
+  );
+}
+
+/**
+ * Checks whether a JSON-RPC message expects a response.
+ */
+function isRequest(
+  message: MCPAppJsonRpcMessage,
+): message is MCPAppJsonRpcRequest {
+  return 'method' in message && 'id' in message;
+}
+
+/**
+ * Checks whether a JSON-RPC message is a fire-and-forget notification.
+ */
+function isNotification(
+  message: MCPAppJsonRpcMessage,
+): message is MCPAppJsonRpcNotification {
+  return 'method' in message && !('id' in message);
+}
+
+/**
+ * Normalizes unknown thrown values into an `Error`.
+ */
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * Validates the params for app-initiated `tools/call` requests.
+ */
+function assertToolCallParams(params: unknown): MCPAppToolCallParams {
+  if (!isJSONObject(params) || typeof params.name !== 'string') {
+    throw new Error('Invalid tools/call params');
+  }
+
+  return {
+    name: params.name,
+    arguments: isJSONObject(params.arguments) ? params.arguments : undefined,
+  };
+}
+
+/**
+ * Host-side JSON-RPC bridge for one MCP App iframe.
+ *
+ * It handles the MCP Apps initialization handshake, sends tool input/result
+ * notifications to the iframe, and proxies allowed iframe requests through
+ * host-provided callbacks.
+ *
+ * @example
+ * ```ts
+ * const bridge = new MCPAppBridge({
+ *   targetWindow: iframe.contentWindow!,
+ *   handlers: {
+ *     allowedTools: ['refreshDashboardData'],
+ *     callTool: params => client.callTool(params),
+ *   },
+ * });
+ *
+ * window.addEventListener('message', event => bridge.handleMessage(event));
+ * bridge.sendToolInput({ topic: 'usage' });
+ * ```
+ */
+export class MCPAppBridge {
+  private initialized = false;
+  private pendingNotifications: MCPAppJsonRpcNotification[] = [];
+  private nextRequestId = 0;
+  private pendingResponses = new Map<
+    string | number,
+    {
+      resolve: (value: unknown) => void;
+      reject: (error: Error) => void;
+    }
+  >();
+
+  constructor({
+    targetWindow,
+    targetOrigin = '*',
+    handlers = {},
+    hostInfo = { name: 'ai-sdk-react', version: '1.0.0' },
+    hostContext = { displayMode: 'inline' },
+  }: {
+    targetWindow: Window;
+    targetOrigin?: string;
+    handlers?: MCPAppBridgeHandlers;
+    hostInfo?: { name: string; version: string };
+    hostContext?: MCPAppHostContext;
+  }) {
+    this.targetWindow = targetWindow;
+    this.targetOrigin = targetOrigin;
+    this.handlers = handlers;
+    this.hostInfo = hostInfo;
+    this.hostContext = hostContext;
+  }
+
+  private targetWindow: Window;
+  private targetOrigin: string;
+  private handlers: MCPAppBridgeHandlers;
+  private hostInfo: { name: string; version: string };
+  private hostContext: MCPAppHostContext;
+
+  /**
+   * Replaces the callbacks used to serve iframe requests.
+   */
+  setHandlers(handlers: MCPAppBridgeHandlers): void {
+    this.handlers = handlers;
+  }
+
+  /**
+   * Updates host context and notifies the iframe after initialization.
+   *
+   * @example
+   * ```ts
+   * bridge.setHostContext({ theme: 'dark', displayMode: 'inline' });
+   * ```
+   */
+  setHostContext(hostContext: MCPAppHostContext): void {
+    this.hostContext = hostContext;
+    this.sendNotification({
+      method: 'ui/notifications/host-context-changed',
+      params: hostContext,
+    });
+  }
+
+  /**
+   * Processes one `message` event from the sandbox proxy iframe.
+   */
+  handleMessage(event: MessageEvent): void {
+    if (event.source !== this.targetWindow || !isJsonRpcMessage(event.data)) {
+      return;
+    }
+
+    const message = event.data;
+
+    if ('result' in message || 'error' in message) {
+      this.handleResponse(message);
+      return;
+    }
+
+    if (isRequest(message)) {
+      void this.handleRequest(message);
+      return;
+    }
+
+    if (isNotification(message)) {
+      this.handleNotification(message);
+    }
+  }
+
+  /**
+   * Sends app HTML and sandbox settings to the sandbox proxy.
+   */
+  sendSandboxResourceReady(params: unknown): void {
+    this.post({
+      jsonrpc: '2.0',
+      method: 'ui/notifications/sandbox-resource-ready',
+      params,
+    });
+  }
+
+  /**
+   * Sends final tool arguments to the MCP App.
+   */
+  sendToolInput(input: unknown): void {
+    this.sendNotification({
+      method: 'ui/notifications/tool-input',
+      params: { arguments: input },
+    });
+  }
+
+  /**
+   * Sends a completed MCP tool result to the MCP App.
+   */
+  sendToolResult(result: unknown): void {
+    this.sendNotification({
+      method: 'ui/notifications/tool-result',
+      params: result,
+    });
+  }
+
+  /**
+   * Notifies the MCP App that the related tool call was cancelled.
+   */
+  sendToolCancelled(reason?: string): void {
+    this.sendNotification({
+      method: 'ui/notifications/tool-cancelled',
+      params: reason != null ? { reason } : {},
+    });
+  }
+
+  /**
+   * Requests graceful teardown before the host removes the iframe.
+   */
+  teardownResource(): Promise<unknown> {
+    return this.request('ui/resource-teardown', {});
+  }
+
+  /**
+   * Rejects pending bridge requests and clears queued notifications.
+   */
+  close(): void {
+    for (const pending of this.pendingResponses.values()) {
+      pending.reject(new Error('MCP App bridge closed'));
+    }
+    this.pendingResponses.clear();
+    this.pendingNotifications = [];
+  }
+
+  /**
+   * Resolves or rejects a host-initiated request when the iframe responds.
+   */
+  private handleResponse(response: MCPAppJsonRpcResponse): void {
+    const pending = this.pendingResponses.get(response.id);
+    if (pending == null) {
+      return;
+    }
+
+    this.pendingResponses.delete(response.id);
+
+    if (response.error != null) {
+      pending.reject(new Error(response.error.message));
+    } else {
+      pending.resolve(response.result);
+    }
+  }
+
+  /**
+   * Runs a handler for an iframe request and posts the JSON-RPC response.
+   */
+  private async handleRequest(request: MCPAppJsonRpcRequest): Promise<void> {
+    try {
+      const result = await this.getRequestResult(request);
+      this.post({ jsonrpc: '2.0', id: request.id, result });
+    } catch (error) {
+      const normalizedError = toError(error);
+      this.handlers.onError?.(normalizedError);
+      this.post({
+        jsonrpc: '2.0',
+        id: request.id,
+        error: { code: -32603, message: normalizedError.message },
+      });
+    }
+  }
+
+  /**
+   * Maps supported iframe request methods to host callbacks.
+   */
+  private async getRequestResult(
+    request: MCPAppJsonRpcRequest,
+  ): Promise<unknown> {
+    switch (request.method) {
+      case 'ui/initialize':
+        return {
+          protocolVersion: MCP_APP_PROTOCOL_VERSION,
+          hostCapabilities: {
+            ...(this.handlers.callTool != null ? { serverTools: {} } : {}),
+            ...(this.handlers.readResource != null
+              ? { serverResources: {} }
+              : {}),
+            ...(this.handlers.onLog != null ? { logging: {} } : {}),
+          },
+          hostInfo: this.hostInfo,
+          hostContext: this.hostContext,
+        };
+
+      case 'tools/call': {
+        if (this.handlers.callTool == null) {
+          throw new Error('No tools/call handler configured');
+        }
+        const params = assertToolCallParams(request.params);
+        if (
+          this.handlers.allowedTools != null &&
+          !this.handlers.allowedTools.includes(params.name)
+        ) {
+          throw new Error(`Tool is not app-visible: ${params.name}`);
+        }
+        return this.handlers.callTool(params);
+      }
+
+      case 'resources/read':
+        if (this.handlers.readResource == null) {
+          throw new Error('No resources/read handler configured');
+        }
+        return this.handlers.readResource(request.params as { uri: string });
+
+      case 'resources/list':
+        if (this.handlers.listResources == null) {
+          throw new Error('No resources/list handler configured');
+        }
+        return this.handlers.listResources(request.params);
+
+      case 'ui/open-link':
+        if (this.handlers.openLink == null) {
+          throw new Error('No ui/open-link handler configured');
+        }
+        return this.handlers.openLink(request.params as { url: string });
+
+      case 'ui/message':
+        return this.handlers.sendMessage?.(request.params) ?? {};
+
+      case 'ui/update-model-context':
+        return this.handlers.updateModelContext?.(request.params) ?? {};
+
+      case 'ui/request-display-mode':
+        return (
+          this.handlers.requestDisplayMode?.(
+            request.params as { mode: 'inline' | 'fullscreen' | 'pip' },
+          ) ?? { mode: this.hostContext.displayMode ?? 'inline' }
+        );
+
+      default:
+        throw new Error(`Unsupported MCP App method: ${request.method}`);
+    }
+  }
+
+  /**
+   * Handles iframe lifecycle and telemetry notifications.
+   */
+  private handleNotification(notification: MCPAppJsonRpcNotification): void {
+    switch (notification.method) {
+      case 'ui/notifications/initialized':
+        this.initialized = true;
+        this.flushNotifications();
+        this.handlers.onInitialized?.();
+        break;
+      case 'ui/notifications/size-changed':
+        this.handlers.onSizeChange?.(
+          notification.params as { width?: number; height?: number },
+        );
+        break;
+      case 'ui/notifications/request-teardown':
+        this.handlers.onRequestTeardown?.(notification.params);
+        break;
+      case 'notifications/message':
+        this.handlers.onLog?.(notification.params);
+        break;
+    }
+  }
+
+  /**
+   * Sends a host-to-iframe notification, queueing it until app initialization.
+   */
+  private sendNotification(
+    notification: Omit<MCPAppJsonRpcNotification, 'jsonrpc'>,
+  ) {
+    const message = { jsonrpc: '2.0' as const, ...notification };
+    if (!this.initialized && !notification.method.includes('sandbox')) {
+      this.pendingNotifications.push(message);
+      return;
+    }
+    this.post(message);
+  }
+
+  /**
+   * Sends notifications that were queued before `ui/notifications/initialized`.
+   */
+  private flushNotifications(): void {
+    const notifications = this.pendingNotifications;
+    this.pendingNotifications = [];
+    for (const notification of notifications) {
+      this.post(notification);
+    }
+  }
+
+  /**
+   * Sends a host-initiated JSON-RPC request to the iframe.
+   */
+  private request(method: string, params: unknown): Promise<unknown> {
+    const id = this.nextRequestId++;
+    this.post({ jsonrpc: '2.0', id, method, params });
+    return new Promise((resolve, reject) => {
+      this.pendingResponses.set(id, { resolve, reject });
+    });
+  }
+
+  /**
+   * Posts a JSON-RPC message to the sandbox proxy iframe.
+   */
+  private post(message: MCPAppJsonRpcMessage): void {
+    this.targetWindow.postMessage(message, this.targetOrigin);
+  }
+}

package/src/mcp-apps/index.ts

@@ -0,0 +1,8 @@
+export { MCPAppRenderer as experimental_MCPAppRenderer } from './app-renderer';
+export type {
+  MCPAppBridgeHandlers,
+  MCPAppMetadata,
+  MCPAppRendererProps,
+  MCPAppResource,
+  MCPAppSandboxConfig,
+} from './types';

package/src/mcp-apps/sandbox.ts

@@ -0,0 +1,74 @@
+import type { MCPAppResourceCSP } from '@ai-sdk/mcp';
+
+/**
+ * Default sandbox permissions for the outer sandbox proxy iframe.
+ */
+export const MCP_APP_DEFAULT_OUTER_SANDBOX =
+  'allow-scripts allow-same-origin allow-forms';
+
+/**
+ * Default sandbox permissions for the inner iframe that runs app HTML.
+ */
+export const MCP_APP_DEFAULT_INNER_SANDBOX = 'allow-scripts allow-forms';
+
+/**
+ * Converts MCP App CSP metadata into a Content-Security-Policy string.
+ *
+ * The returned value is meant to be passed to a sandbox proxy, which can apply
+ * it to the inner iframe document.
+ *
+ * @example
+ * ```ts
+ * const csp = getMCPAppCSP({
+ *   connectDomains: ['https://api.example.com'],
+ *   resourceDomains: ['https://cdn.example.com'],
+ * });
+ * ```
+ */
+export function getMCPAppCSP(csp?: MCPAppResourceCSP): string | undefined {
+  if (csp == null) {
+    return undefined;
+  }
+
+  const connectSrc = ["'self'", ...(csp.connectDomains ?? [])];
+  const imgSrc = ["'self'", 'data:', ...(csp.resourceDomains ?? [])];
+  const frameSrc = ["'self'", ...(csp.frameDomains ?? [])];
+
+  return [
+    "default-src 'none'",
+    "script-src 'unsafe-inline'",
+    "style-src 'unsafe-inline'",
+    `connect-src ${connectSrc.join(' ')}`,
+    `img-src ${imgSrc.join(' ')}`,
+    `font-src ${imgSrc.join(' ')}`,
+    `frame-src ${frameSrc.join(' ')}`,
+  ].join('; ');
+}
+
+/**
+ * Converts MCP App permission metadata into an iframe `allow` attribute.
+ *
+ * @example
+ * ```ts
+ * const allow = getMCPAppAllowAttribute({
+ *   microphone: {},
+ *   clipboardWrite: {},
+ * });
+ * // "microphone; clipboard-write"
+ * ```
+ */
+export function getMCPAppAllowAttribute(
+  permissions?: Record<string, unknown>,
+): string | undefined {
+  if (permissions == null) {
+    return undefined;
+  }
+
+  const allow = [];
+  if (permissions.camera) allow.push('camera');
+  if (permissions.microphone) allow.push('microphone');
+  if (permissions.geolocation) allow.push('geolocation');
+  if (permissions.clipboardWrite) allow.push('clipboard-write');
+
+  return allow.length > 0 ? allow.join('; ') : undefined;
+}

package/src/mcp-apps/types.ts

@@ -0,0 +1,100 @@
+import type { MCPAppResource } from '@ai-sdk/mcp';
+import type { DynamicToolUIPart, ToolUIPart, UITools } from 'ai';
+import type { CSSProperties, ReactNode } from 'react';
+
+export type { MCPAppResource };
+
+export type MCPAppDisplayMode = 'inline' | 'fullscreen' | 'pip';
+
+export type MCPAppMetadata = {
+  resourceUri: string;
+  mimeType: MCPAppResource['mimeType'];
+  visibility?: Array<'model' | 'app'>;
+};
+
+export type MCPAppHostContext = {
+  theme?: 'light' | 'dark';
+  displayMode?: MCPAppDisplayMode;
+  availableDisplayModes?: MCPAppDisplayMode[];
+  [key: string]: unknown;
+};
+
+export type MCPAppToolCallParams = {
+  name: string;
+  arguments?: Record<string, unknown>;
+};
+
+export type MCPAppBridgeHandlers = {
+  allowedTools?: string[];
+  callTool?: (params: MCPAppToolCallParams) => Promise<unknown> | unknown;
+  readResource?: (params: { uri: string }) => Promise<unknown> | unknown;
+  listResources?: (params?: unknown) => Promise<unknown> | unknown;
+  openLink?: (params: { url: string }) => Promise<unknown> | unknown;
+  sendMessage?: (params: unknown) => Promise<unknown> | unknown;
+  updateModelContext?: (params: unknown) => Promise<unknown> | unknown;
+  requestDisplayMode?: (params: {
+    mode: MCPAppDisplayMode;
+  }) => Promise<{ mode: MCPAppDisplayMode }> | { mode: MCPAppDisplayMode };
+  onSizeChange?: (params: { width?: number; height?: number }) => void;
+  onInitialized?: () => void;
+  onRequestTeardown?: (params: unknown) => void;
+  onLog?: (params: unknown) => void;
+  onError?: (error: Error) => void;
+};
+
+export type MCPAppSandboxConfig = {
+  url: string | URL;
+  title?: string;
+  className?: string;
+  style?: CSSProperties;
+  targetOrigin?: string;
+  outerSandbox?: string;
+  innerSandbox?: string;
+};
+
+export type MCPAppFrameProps = {
+  app: MCPAppMetadata;
+  resource: MCPAppResource;
+  input?: unknown;
+  output?: unknown;
+  sandbox: MCPAppSandboxConfig;
+  handlers?: MCPAppBridgeHandlers;
+  hostInfo?: { name: string; version: string };
+  hostContext?: MCPAppHostContext;
+};
+
+export type MCPAppRendererProps = {
+  part: ToolUIPart<UITools> | DynamicToolUIPart;
+  sandbox: MCPAppSandboxConfig;
+  resource?: MCPAppResource;
+  loadResource?: (app: MCPAppMetadata) => Promise<MCPAppResource>;
+  handlers?: MCPAppBridgeHandlers;
+  hostInfo?: { name: string; version: string };
+  hostContext?: MCPAppHostContext;
+  fallback?: ReactNode;
+};
+
+export type MCPAppJsonRpcRequest = {
+  jsonrpc: '2.0';
+  id: string | number;
+  method: string;
+  params?: unknown;
+};
+
+export type MCPAppJsonRpcNotification = {
+  jsonrpc: '2.0';
+  method: string;
+  params?: unknown;
+};
+
+export type MCPAppJsonRpcResponse = {
+  jsonrpc: '2.0';
+  id: string | number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+};
+
+export type MCPAppJsonRpcMessage =
+  | MCPAppJsonRpcRequest
+  | MCPAppJsonRpcNotification
+  | MCPAppJsonRpcResponse;

package/src/mcp-apps/utils.ts

@@ -0,0 +1,84 @@
+import { isJSONObject } from '@ai-sdk/provider';
+import type { MCPAppMetadata, MCPAppRendererProps } from './types';
+
+/**
+ * Extracts MCP App metadata from an AI SDK tool UI part.
+ *
+ * @example
+ * ```ts
+ * const app = getMCPAppFromToolPart({
+ *   type: 'dynamic-tool',
+ *   toolName: 'showDashboard',
+ *   toolCallId: 'call-1',
+ *   state: 'input-available',
+ *   input: { topic: 'usage' },
+ *   toolMetadata: {
+ *     mcp: {
+ *       app: {
+ *         resourceUri: 'ui://example/dashboard',
+ *         mimeType: 'text/html;profile=mcp-app',
+ *       },
+ *     },
+ *   },
+ * });
+ * // { resourceUri: 'ui://example/dashboard', mimeType: 'text/html;profile=mcp-app' }
+ * ```
+ */
+export function getMCPAppFromToolPart(
+  part: MCPAppRendererProps['part'],
+): MCPAppMetadata | undefined {
+  const mcpMetadata = part.toolMetadata?.mcp;
+  const rawAppMetadata = isJSONObject(mcpMetadata)
+    ? mcpMetadata.app
+    : undefined;
+  const appMetadata = isJSONObject(rawAppMetadata) ? rawAppMetadata : undefined;
+
+  if (
+    appMetadata == null ||
+    appMetadata.mimeType !== 'text/html;profile=mcp-app' ||
+    typeof appMetadata.resourceUri !== 'string' ||
+    !appMetadata.resourceUri.startsWith('ui://') ||
+    (appMetadata.visibility != null &&
+      (!Array.isArray(appMetadata.visibility) ||
+        appMetadata.visibility.some(
+          value => value !== 'model' && value !== 'app',
+        )))
+  ) {
+    return undefined;
+  }
+
+  return appMetadata as MCPAppMetadata;
+}
+
+/**
+ * Converts an AI SDK tool output into the MCP Apps tool-result shape.
+ *
+ * MCP Apps expect tool results to have `content` and optional
+ * `structuredContent`. MCP tools already return that shape, but typed AI SDK
+ * tools may return only structured data. This helper wraps structured-only
+ * outputs so the iframe can receive a valid tool result notification.
+ *
+ * @example
+ * ```ts
+ * normalizeMCPAppToolResult({ cards: [] });
+ * // { content: [], structuredContent: { cards: [] } }
+ * ```
+ */
+export function normalizeMCPAppToolResult(output: unknown): {
+  content: unknown[];
+  structuredContent?: unknown;
+  isError?: boolean;
+} {
+  if (output != null && typeof output === 'object' && 'content' in output) {
+    return output as {
+      content: unknown[];
+      structuredContent?: unknown;
+      isError?: boolean;
+    };
+  }
+
+  return {
+    content: [],
+    structuredContent: output,
+  };
+}