@assistant-ui/react 0.14.0 → 0.14.3

package/src/mcp-apps/McpAppRenderer.tsx

@@ -0,0 +1,221 @@
+"use client";
+
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type MutableRefObject,
+  type ReactNode,
+} from "react";
+import type { McpAppMetadata } from "@assistant-ui/core";
+import type {
+  ToolCallMessagePartComponent,
+  ToolCallMessagePartProps,
+} from "@assistant-ui/core/react";
+import { useAui } from "@assistant-ui/store";
+import {
+  resource,
+  tapConst,
+  tapRef,
+  tapResource,
+  type ResourceElement,
+} from "@assistant-ui/tap";
+import { McpAppFrame } from "./app-frame";
+import type {
+  McpAppBridgeHandlers,
+  McpAppHostContext,
+  McpAppHostInfo,
+  McpAppResource,
+  McpAppSandboxConfig,
+  McpAppsHost,
+} from "./types";
+import { getMcpAppFromToolPart } from "./utils";
+
+export type McpAppRendererOptions = {
+  /**
+   * Provides the data-plane operations the widget can request
+   * (`loadResource`, `callTool`, `readResource`, `listResources`). Use
+   * `McpAppsRemoteHost({ url })` for the default HTTP-route convention.
+   */
+  host: ResourceElement<McpAppsHost>;
+  /** Sandbox + container styling. Passes through to SafeContentFrame. */
+  sandbox?: McpAppSandboxConfig;
+  /**
+   * Upper bound (in pixels) applied to the widget-driven auto-resize height.
+   * Defaults to 800.
+   */
+  maxHeight?: number;
+  /** Identifies the host to the widget in the `ui/initialize` response. */
+  hostInfo?: McpAppHostInfo;
+  /** Delivered to the widget on initialize and pushed via `notifications/host_context/changed` on change. */
+  hostContext?: McpAppHostContext;
+  /** Rendered when no MCP app is on the part, or while load is in flight / failed (unless overridden). */
+  fallback?: ReactNode;
+  /** Rendered while the resource is loading. Defaults to `fallback`. */
+  loadingFallback?: ReactNode;
+  /** Rendered when the resource load rejects. Defaults to `fallback`. */
+  errorFallback?: ReactNode | ((error: Error) => ReactNode);
+};
+
+type LoadedResourceState = {
+  resourceUri: string;
+  resource?: McpAppResource;
+  error?: Error;
+};
+
+function getInput(part: {
+  status: { type: string };
+  argsText: string;
+  args: unknown;
+}): unknown {
+  if (
+    part.status.type === "running" &&
+    (part.argsText === "" || part.argsText === "{}")
+  ) {
+    return undefined;
+  }
+  return part.args;
+}
+
+const defaultOpenLink = ({ url }: { url: string }) => {
+  window.open(url, "_blank", "noopener,noreferrer");
+};
+
+function extractSendMessageText(params: unknown): string | undefined {
+  if (typeof params === "string") return params;
+  if (!params || typeof params !== "object") return undefined;
+  const obj = params as Record<string, unknown>;
+  if (typeof obj["prompt"] === "string") return obj["prompt"];
+  if (typeof obj["text"] === "string") return obj["text"];
+  if (typeof obj["message"] === "string") return obj["message"];
+  return undefined;
+}
+
+function InlineRenderer({
+  part,
+  internalsRef,
+  optionsRef,
+}: {
+  part: ToolCallMessagePartProps;
+  internalsRef: MutableRefObject<{ host: McpAppsHost }>;
+  optionsRef: MutableRefObject<McpAppRendererOptions>;
+}) {
+  const opts = optionsRef.current;
+  const aui = useAui();
+  const app = getMcpAppFromToolPart(part);
+  const cachedAppRef = useRef<McpAppMetadata | undefined>(undefined);
+  if (app != null && cachedAppRef.current?.resourceUri !== app.resourceUri) {
+    cachedAppRef.current = app;
+  }
+  const appForRender = app ?? cachedAppRef.current;
+
+  const [loadedResource, setLoadedResource] = useState<LoadedResourceState>();
+
+  const resourceUri = appForRender?.resourceUri;
+  // biome-ignore lint/correctness/useExhaustiveDependencies: re-fetches only when URI changes; mcp.app object identity is unstable across renders
+  useEffect(() => {
+    if (appForRender == null || resourceUri == null) return;
+    let cancelled = false;
+    const targetUri = resourceUri;
+
+    internalsRef.current.host
+      .loadResource({ uri: targetUri })
+      .then((res) => {
+        if (!cancelled)
+          setLoadedResource({ resourceUri: targetUri, resource: res });
+      })
+      .catch((error: unknown) => {
+        if (!cancelled) {
+          setLoadedResource({
+            resourceUri: targetUri,
+            error: error instanceof Error ? error : new Error(String(error)),
+          });
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [resourceUri]);
+
+  const bridgeHandlers = useMemo<McpAppBridgeHandlers>(
+    () => ({
+      openLink: defaultOpenLink,
+      sendMessage: (params) => {
+        const text = extractSendMessageText(params);
+        if (!text) return { ok: false, reason: "unrecognised params shape" };
+        aui.thread().append({ content: [{ type: "text", text }] });
+        return { ok: true };
+      },
+      callTool: (params) => internalsRef.current.host.callTool(params),
+      readResource: (params) => internalsRef.current.host.readResource(params),
+      listResources: (params) =>
+        internalsRef.current.host.listResources(params),
+    }),
+    [aui, internalsRef],
+  );
+
+  const loadedResourceForApp =
+    loadedResource?.resourceUri === appForRender?.resourceUri
+      ? loadedResource
+      : undefined;
+  const appResource = loadedResourceForApp?.resource;
+  const error = loadedResourceForApp?.error;
+
+  const fallback = opts.fallback ?? null;
+  if (appForRender == null) {
+    return <>{fallback}</>;
+  }
+  if (error != null) {
+    const errorFallback = opts.errorFallback;
+    if (errorFallback === undefined) return <>{fallback}</>;
+    if (typeof errorFallback === "function") return <>{errorFallback(error)}</>;
+    return <>{errorFallback}</>;
+  }
+  if (appResource == null) {
+    return <>{opts.loadingFallback ?? fallback}</>;
+  }
+
+  return (
+    <McpAppFrame
+      app={appForRender}
+      resource={appResource}
+      input={getInput(part)}
+      output={part.result}
+      sandbox={opts.sandbox}
+      handlers={bridgeHandlers}
+      hostInfo={opts.hostInfo}
+      hostContext={opts.hostContext}
+      maxHeight={opts.maxHeight}
+    />
+  );
+}
+
+export const McpAppRenderer = resource(
+  (
+    options: McpAppRendererOptions,
+  ): { readonly render: ToolCallMessagePartComponent } => {
+    const host = tapResource(options.host);
+
+    const optionsRef = tapRef<McpAppRendererOptions>(options);
+    optionsRef.current = options;
+
+    const internalsRef = tapRef<{ host: McpAppsHost }>({ host });
+    internalsRef.current = { host };
+
+    const render = tapConst((): ToolCallMessagePartComponent => {
+      const Render: ToolCallMessagePartComponent = (props) => (
+        <InlineRenderer
+          part={props}
+          internalsRef={internalsRef}
+          optionsRef={optionsRef}
+        />
+      );
+      Render.displayName = "McpAppRenderer";
+      return Render;
+    }, []);
+
+    return { render };
+  },
+);

package/src/mcp-apps/McpAppsRemoteHost.ts

@@ -0,0 +1,52 @@
+import { resource, tapConst, tapRef } from "@assistant-ui/tap";
+import type {
+  McpAppResource,
+  McpAppsHost,
+  McpAppsRemoteHostOptions,
+} from "./types";
+
+async function postToHost(
+  options: McpAppsRemoteHostOptions,
+  method: string,
+  params: unknown,
+): Promise<unknown> {
+  const doFetch = options.fetch ?? fetch;
+  const extraHeaders =
+    typeof options.headers === "function"
+      ? await options.headers()
+      : (options.headers ?? {});
+  const res = await doFetch(options.url, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...extraHeaders },
+    body: JSON.stringify({ method, params }),
+  });
+  if (!res.ok) {
+    throw new Error(`MCP App host request failed: ${res.status}`);
+  }
+  return res.json();
+}
+
+export const McpAppsRemoteHost = resource(
+  (options: McpAppsRemoteHostOptions): McpAppsHost => {
+    const optionsRef = tapRef(options);
+    optionsRef.current = options;
+
+    return tapConst(
+      (): McpAppsHost => ({
+        loadResource: (params) =>
+          postToHost(
+            optionsRef.current,
+            "mcp-apps/read-resource",
+            params,
+          ) as Promise<McpAppResource>,
+        callTool: (params) =>
+          postToHost(optionsRef.current, "tools/call", params),
+        readResource: (params) =>
+          postToHost(optionsRef.current, "resources/read", params),
+        listResources: (params) =>
+          postToHost(optionsRef.current, "resources/list", params),
+      }),
+      [],
+    );
+  },
+);

package/src/mcp-apps/app-frame.tsx

@@ -0,0 +1,303 @@
+"use client";
+
+import { type MutableRefObject, useEffect, useRef, useState } from "react";
+import { type RenderedFrame, SafeContentFrame } from "safe-content-frame";
+import { type McpAppBridge, createMcpAppBridge } from "./bridge";
+import type {
+  McpAppBridgeHandlers,
+  McpAppFrameProps,
+  McpAppHostContext,
+} from "./types";
+
+const DEFAULT_PRODUCT = "assistant-ui-mcp-app";
+const INIT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_HEIGHT = 800;
+
+function useBridgeNotify<T>(
+  value: T | undefined,
+  bridgeRef: MutableRefObject<McpAppBridge | null>,
+  widgetReadyRef: MutableRefObject<boolean>,
+  pendingRef: MutableRefObject<T | undefined>,
+  lastSentRef: MutableRefObject<T | undefined>,
+  notify: (bridge: McpAppBridge, v: T) => void,
+) {
+  // biome-ignore lint/correctness/useExhaustiveDependencies: refs and notify are stable; we re-run only when value changes.
+  useEffect(() => {
+    if (!bridgeRef.current) return;
+    if (value === undefined) return;
+    if (lastSentRef.current === value) return;
+    if (!widgetReadyRef.current) {
+      pendingRef.current = value;
+      return;
+    }
+    notify(bridgeRef.current, value);
+    lastSentRef.current = value;
+  }, [value]);
+}
+
+type LiveSnapshot = {
+  handlers: McpAppBridgeHandlers | undefined;
+  hostInfo: McpAppFrameProps["hostInfo"];
+  hostContext: McpAppFrameProps["hostContext"];
+  input: unknown;
+  output: unknown;
+};
+
+// Proxy each per-call handler through liveRef so the bridge always dispatches
+// to the latest handler reference (e.g. inline callbacks closing over state).
+// Capability presence is snapshot at mount: a handler added later requires a
+// remount (keyed on resource URI) to expose the capability to the widget.
+function buildLiveHandlers(
+  initial: McpAppBridgeHandlers | undefined,
+  liveRef: { readonly current: LiveSnapshot },
+): McpAppBridgeHandlers {
+  const live = () => liveRef.current.handlers;
+  const has = <K extends keyof McpAppBridgeHandlers>(key: K) =>
+    initial?.[key] !== undefined;
+  const out: McpAppBridgeHandlers = {};
+  if (has("allowedTools")) {
+    Object.defineProperty(out, "allowedTools", {
+      get: () => live()?.allowedTools,
+      enumerable: true,
+      configurable: true,
+    });
+  }
+  const liveCall = <K extends keyof McpAppBridgeHandlers>(
+    key: K,
+  ): NonNullable<McpAppBridgeHandlers[K]> =>
+    ((p: unknown) => {
+      const fn = live()?.[key] as ((p: unknown) => unknown) | undefined;
+      if (!fn) {
+        throw new Error(`${key} handler is no longer available`);
+      }
+      return fn(p);
+    }) as NonNullable<McpAppBridgeHandlers[K]>;
+  if (has("callTool")) out.callTool = liveCall("callTool");
+  if (has("readResource")) out.readResource = liveCall("readResource");
+  if (has("listResources")) out.listResources = liveCall("listResources");
+  if (has("openLink")) out.openLink = liveCall("openLink");
+  if (has("sendMessage")) out.sendMessage = liveCall("sendMessage");
+  if (has("updateModelContext"))
+    out.updateModelContext = liveCall("updateModelContext");
+  if (has("requestDisplayMode"))
+    out.requestDisplayMode = liveCall("requestDisplayMode");
+  out.onSizeChange = (p) => live()?.onSizeChange?.(p);
+  out.onInitialized = () => live()?.onInitialized?.();
+  out.onRequestTeardown = (p) => live()?.onRequestTeardown?.(p);
+  out.onLog = (p) => live()?.onLog?.(p);
+  out.onError = (e) => live()?.onError?.(e);
+  return out;
+}
+
+export function McpAppFrame({
+  app,
+  resource,
+  input,
+  output,
+  sandbox,
+  handlers,
+  hostInfo,
+  hostContext,
+  maxHeight = DEFAULT_MAX_HEIGHT,
+}: McpAppFrameProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [contentHeight, setContentHeight] = useState<number | undefined>(
+    undefined,
+  );
+  const bridgeRef = useRef<McpAppBridge | null>(null);
+  const lastSentInputRef = useRef<unknown>(undefined);
+  const lastSentOutputRef = useRef<unknown>(undefined);
+  const lastSentHostContextRef = useRef<McpAppHostContext | undefined>(
+    undefined,
+  );
+  // Per MCP Apps spec, the host should defer notifications until the widget
+  // signals readiness via `notifications/initialized`. Until then, we record
+  // pending values and flush them on init.
+  const widgetReadyRef = useRef(false);
+  const pendingInputRef = useRef<unknown>(undefined);
+  const pendingOutputRef = useRef<unknown>(undefined);
+  const pendingHostContextRef = useRef<McpAppHostContext | undefined>(
+    undefined,
+  );
+
+  const liveRef = useRef<LiveSnapshot>(null!);
+  liveRef.current = {
+    handlers,
+    hostInfo,
+    hostContext,
+    input,
+    output,
+  };
+
+  const resourceUri = resource.uri;
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: re-mounts only on resource URI; live values flow through liveRef
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    let cancelled = false;
+    let initTimeoutId: ReturnType<typeof setTimeout> | null = null;
+    let frame: RenderedFrame | null = null;
+    const sb = sandbox;
+    const html = resource.html;
+
+    const scf = new SafeContentFrame(sb?.product ?? DEFAULT_PRODUCT, {
+      ...(sb?.sandbox !== undefined && { sandbox: sb.sandbox }),
+      ...(sb?.useShadowDom !== undefined && { useShadowDom: sb.useShadowDom }),
+      ...(sb?.enableBrowserCaching !== undefined && {
+        enableBrowserCaching: sb.enableBrowserCaching,
+      }),
+      ...(sb?.salt !== undefined && { salt: sb.salt }),
+    });
+
+    const renderOpts =
+      sb?.unsafeDocumentWrite !== undefined
+        ? { unsafeDocumentWrite: sb.unsafeDocumentWrite }
+        : undefined;
+
+    scf
+      .renderHtml(html, container, renderOpts)
+      .then((rendered) => {
+        if (cancelled) {
+          rendered.dispose();
+          return;
+        }
+        frame = rendered;
+        const current = liveRef.current;
+        const liveHandlers = buildLiveHandlers(current.handlers, liveRef);
+        const liveOnInitialized = liveHandlers.onInitialized;
+        const flushPending = () => {
+          if (widgetReadyRef.current) return;
+          widgetReadyRef.current = true;
+          const b = bridgeRef.current;
+          if (!b) return;
+          if (pendingInputRef.current !== undefined) {
+            b.notifyToolInput(pendingInputRef.current);
+            lastSentInputRef.current = pendingInputRef.current;
+            pendingInputRef.current = undefined;
+          }
+          if (pendingOutputRef.current !== undefined) {
+            b.notifyToolResult(pendingOutputRef.current);
+            lastSentOutputRef.current = pendingOutputRef.current;
+            pendingOutputRef.current = undefined;
+          }
+          if (pendingHostContextRef.current !== undefined) {
+            b.notifyHostContextChanged(pendingHostContextRef.current);
+            lastSentHostContextRef.current = pendingHostContextRef.current;
+            pendingHostContextRef.current = undefined;
+          }
+        };
+        const wrappedHandlers: McpAppBridgeHandlers = {
+          ...liveHandlers,
+          onInitialized: () => {
+            if (initTimeoutId !== null) {
+              clearTimeout(initTimeoutId);
+              initTimeoutId = null;
+            }
+            flushPending();
+            liveOnInitialized?.();
+          },
+          onSizeChange: (p) => {
+            if (
+              typeof p.height === "number" &&
+              Number.isFinite(p.height) &&
+              p.height > 0
+            ) {
+              setContentHeight(p.height);
+            }
+            liveHandlers.onSizeChange?.(p);
+          },
+        };
+        // Safety net: if the widget never sends notifications/initialized
+        // (broken or non-spec-compliant), flush the queue anyway so the host
+        // doesn't appear hung.
+        initTimeoutId = setTimeout(() => {
+          initTimeoutId = null;
+          flushPending();
+        }, INIT_TIMEOUT_MS);
+        bridgeRef.current = createMcpAppBridge({
+          frame: rendered,
+          handlers: wrappedHandlers,
+          hostInfo: current.hostInfo,
+          hostContext: current.hostContext,
+        });
+
+        if (current.input !== undefined)
+          pendingInputRef.current = current.input;
+        if (current.output !== undefined)
+          pendingOutputRef.current = current.output;
+        // hostContext is delivered inside the ui/initialize response; subsequent
+        // changes flow through useBridgeNotify's pending path.
+      })
+      .catch((err) => {
+        liveRef.current.handlers?.onError?.(
+          err instanceof Error ? err : new Error(String(err)),
+        );
+      });
+
+    return () => {
+      cancelled = true;
+      if (initTimeoutId !== null) {
+        clearTimeout(initTimeoutId);
+        initTimeoutId = null;
+      }
+      bridgeRef.current?.dispose();
+      bridgeRef.current = null;
+      frame?.dispose();
+      frame = null;
+      lastSentInputRef.current = undefined;
+      lastSentOutputRef.current = undefined;
+      lastSentHostContextRef.current = undefined;
+      widgetReadyRef.current = false;
+      pendingInputRef.current = undefined;
+      pendingOutputRef.current = undefined;
+      pendingHostContextRef.current = undefined;
+      setContentHeight(undefined);
+    };
+  }, [resourceUri]);
+
+  useBridgeNotify(
+    input,
+    bridgeRef,
+    widgetReadyRef,
+    pendingInputRef,
+    lastSentInputRef,
+    (b, v) => b.notifyToolInput(v),
+  );
+  useBridgeNotify(
+    output,
+    bridgeRef,
+    widgetReadyRef,
+    pendingOutputRef,
+    lastSentOutputRef,
+    (b, v) => b.notifyToolResult(v),
+  );
+  useBridgeNotify(
+    hostContext,
+    bridgeRef,
+    widgetReadyRef,
+    pendingHostContextRef,
+    lastSentHostContextRef,
+    (b, v) => b.notifyHostContextChanged(v),
+  );
+
+  const resolvedHeight =
+    contentHeight != null ? Math.min(contentHeight, maxHeight) : undefined;
+  const mergedStyle =
+    resolvedHeight != null
+      ? { ...sandbox?.style, height: resolvedHeight }
+      : sandbox?.style;
+
+  return (
+    <div
+      ref={containerRef}
+      className={sandbox?.className}
+      style={mergedStyle}
+      data-mcp-app-resource={app.resourceUri}
+      data-mcp-app-prefers-border={
+        resource.meta?.prefersBorder ? "" : undefined
+      }
+    />
+  );
+}