@assistant-ui/mcp-docs-server 0.1.30 → 0.1.32

package/.docs/raw/docs/guides/index.mdx

@@ -0,0 +1,103 @@
+---
+title: Guides
+description: Practical recipes for building AI chat features in React with assistant-ui — attachments, branching, multi-agent, voice, slash commands, generative UI, and more.
+platforms: ["react"]
+---
+
+Guides are task-oriented walkthroughs for building specific features on top of assistant-ui. They sit between the [Primitives](/docs/primitives) (low-level building blocks) and [Components](/docs/ui/thread) (pre-styled installs) — pick a guide when you know what you want to build and need the recommended pattern.
+
+## Composer
+
+Extend the message input with file attachments, mentions, slash commands, voice, and quoting.
+
+<Cards>
+  <Card title="Attachments" href="/docs/guides/attachments">
+    Let users attach files, images, and documents to messages. Covers upload adapters, validation, and the typed `attachmentAddError` event.
+  </Card>
+  <Card title="Mentions" href="/docs/guides/mentions">
+    `@`-style triggers that insert directives into the composer. Sync and async search patterns.
+  </Card>
+  <Card title="Slash Commands" href="/docs/guides/slash-commands">
+    `/`-style commands with arguments, async loading, and combining with mentions.
+  </Card>
+  <Card title="Quoting" href="/docs/guides/quoting">
+    Selection toolbar, programmatic `setQuote`, and forwarding quote context to the LLM.
+  </Card>
+  <Card title="Dictation" href="/docs/guides/dictation">
+    Speech-to-text into the composer using `DictationAdapter` and `ComposerPrimitive.Dictate`.
+  </Card>
+</Cards>
+
+## Messages
+
+Customize how messages render, are edited, branched, and suggested.
+
+<Cards>
+  <Card title="Suggestions" href="/docs/guides/suggestions">
+    Welcome-screen prompts, dynamic suggestions, and the `AuiIf` empty-thread pattern.
+  </Card>
+  <Card title="Editing" href="/docs/guides/editing">
+    Edit user messages with `UserEditComposer`, `beginEdit()`, and edit-during-streaming behavior.
+  </Card>
+  <Card title="Branching" href="/docs/guides/branching">
+    Navigate alternative message versions with `BranchPickerPrimitive`, reload, and direct branch-id navigation.
+  </Card>
+  <Card title="Message Timing" href="/docs/guides/message-timing">
+    Display response duration and stream timing with `useMessageTiming` (experimental).
+  </Card>
+</Cards>
+
+## Tools & Generative UI
+
+Connect tools to the LLM and render their outputs as interactive UI.
+
+<Cards>
+  <Card title="Tools" href="/docs/guides/tools">
+    Define tools with the Toolkit API, stream args, handle cancellation, and integrate with AI SDK / LangGraph / LangChain.
+  </Card>
+  <Card title="Tool UI" href="/docs/guides/tool-ui">
+    Render tool calls and `DataMessagePart` into custom components, with fallback handling.
+  </Card>
+  <Card title="Interactables" href="/docs/guides/interactables">
+    Persisted, schema-validated interactive UI driven by AI state.
+  </Card>
+  <Card title="Multi-Agent" href="/docs/guides/multi-agent">
+    Sub-agent message attribution via `ToolCallMessagePart.messages` and LangGraph subgraph events.
+  </Card>
+</Cards>
+
+## Display
+
+Render specialized message content.
+
+<Cards>
+  <Card title="Chain of Thought" href="/docs/guides/chain-of-thought">
+    Display the assistant's reasoning steps in a collapsible accordion.
+  </Card>
+  <Card title="LaTeX" href="/docs/guides/latex">
+    Render math via React Markdown or Streamdown, with streaming-safe escape rules.
+  </Card>
+</Cards>
+
+## Audio
+
+Voice input and output.
+
+<Cards>
+  <Card title="Voice" href="/docs/guides/voice">
+    Realtime bidirectional audio with `RealtimeVoiceAdapter` and `createVoiceSession`.
+  </Card>
+  <Card title="Speech" href="/docs/guides/speech">
+    Text-to-speech for assistant messages via `SpeechSynthesisAdapter`.
+  </Card>
+</Cards>
+
+## Programmatic
+
+Read and drive runtime state from your own code.
+
+<Cards>
+  <Card title="Context API" href="/docs/guides/context-api">
+    Access threads, messages, composer, and tool state via `useAui` and the runtime scope tree.
+  </Card>
+</Cards>

package/.docs/raw/docs/{(docs)/guides → guides}/interactables.mdx

@@ -1,6 +1,7 @@
 ---
-title: Interactables
-description: Persistent UI whose state can be read and updated by the AI assistant.
+title: Interactable Components
+description: Build persistent UI elements whose state the AI can read and update — copilot interactables in React with assistant-ui for forms, dashboards, and tools.
+platforms: ["react"]
 ---
 
 import { InteractableSample } from "@/components/docs/samples/interactable";
@@ -344,6 +345,49 @@ const aui = useAui({
 });
 ```
 
+## Streaming Updates
+
+While the AI is generating tool arguments, `useInteractableState` reflects the partial state in real time as fields stream in. You can use the partial state itself plus the thread's running status to show a skeleton UI while the AI is mid-stream:
+
+```tsx
+import { useAuiState } from "@assistant-ui/react";
+
+function TaskBoard() {
+  const id = useAssistantInteractable("taskBoard", config);
+  const [state] = useInteractableState(id, taskBoardInitialState);
+  const isRunning = useAuiState((s) => s.thread.isRunning);
+
+  const isLoading = isRunning && state.tasks.length === 0;
+
+  return (
+    <div>
+      <h2>Tasks</h2>
+      {isLoading ? (
+        <div className="animate-pulse h-8 rounded bg-muted" />
+      ) : (
+        <ul>
+          {state.tasks.map((task) => (
+            <li key={task.id}>{task.title}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+The state object updates progressively as the AI streams in each field, so partial renders work without any extra wiring. Use the runtime's `isRunning` to distinguish "still streaming, no fields yet" from "model returned an empty result".
+
+## Schema Evolution
+
+<Callout type="warn">
+  If you change a Zod schema after state has been persisted, the imported snapshot may silently mis-match the new shape. The adapter does a shallow merge, so extra fields are preserved and missing fields keep their initial values, but type mismatches are not caught at runtime. To avoid silent corruption, version your schema key (e.g. `"taskBoard_v2"`) or namespace it by schema hash whenever you make breaking changes. Alternatively, add a migration step in your `importState` call.
+</Callout>
+
+## Unmount Behavior
+
+When a component that called `useAssistantInteractable` unmounts, the interactable is unregistered from the AI's tool list and system prompt. However, its state is preserved in the `Interactables` scope. When the component mounts again with the same name and id, the scope re-merges the preserved state rather than resetting to `initialState`. This means transient unmounts (such as React Strict Mode double-mounts or tab switches) do not lose state.
+
 ## Full Example
 
 See the complete [with-interactables example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-interactables) for a working implementation featuring:
@@ -352,3 +396,8 @@ See the complete [with-interactables example](https://github.com/assistant-ui/as
 - **Sticky Notes** — multi-instance interactables with selection and partial updates
 - **localStorage persistence** — state survives page refresh via `setPersistenceAdapter`
 - **Sync indicator** — spinning icon while a save is in-flight (`isPending`)
+
+## Related
+
+- [Generative UI](/docs/guides/tool-ui) — Inline tool call UIs rendered inside messages
+- [LangGraph Generative UI](/docs/runtimes/langgraph/generative-ui) — Structured UI components emitted by a LangGraph graph alongside messages

package/.docs/raw/docs/{(docs)/guides → guides}/latex.mdx

@@ -1,21 +1,24 @@
 ---
-title: LaTeX
-description: Render mathematical expressions in chat messages using KaTeX.
+title: LaTeX in Chat Messages
+description: Render LaTeX math expressions in AI chat messages with KaTeX — drop-in equation support for React chat UIs built on assistant-ui.
+platforms: ["react"]
 ---
 
+import { PackageManagerTabs } from "@/components/docs/fumadocs/install/package-manager-tabs";
 
 Render LaTeX mathematical expressions in chat messages using KaTeX.
 
-<Callout type="warn">LaTeX rendering is not enabled in markdown by default.</Callout>
+<Callout type="warn">LaTeX rendering is not enabled by default.</Callout>
+
+<Tabs items={["react-markdown", "Streamdown"]}>
+  <Tab value="react-markdown">
 
 <Steps>
   <Step>
 
 ### Install dependencies
 
-```bash
-npm i katex rehype-katex remark-math
-```
+<PackageManagerTabs packages={["katex", "rehype-katex", "remark-math"]} />
 
   </Step>
   <Step>
@@ -53,9 +56,50 @@ export const MarkdownText = memo(MarkdownTextImpl);
   </Step>
 </Steps>
 
+  </Tab>
+  <Tab value="Streamdown">
+
+<Callout type="info">
+  Using [Streamdown](/docs/ui/streamdown) as your renderer? Math support is a first-party plugin — no remark or rehype packages needed.
+</Callout>
+
+<Steps>
+  <Step>
+
+### Install dependencies
+
+<PackageManagerTabs packages={["@streamdown/math", "katex"]} />
+
+  </Step>
+  <Step>
+
+### Add KaTeX CSS to your layout
+
+```tsx title="/app/layout.tsx"
+import "katex/dist/katex.min.css"; // [!code ++]
+```
+
+  </Step>
+  <Step>
+
+### Pass the `math` plugin to `StreamdownTextPrimitive`
+
+```tsx title="/components/assistant-ui/streamdown-text.tsx"
+import { math } from "@streamdown/math"; // [!code ++]
+import "katex/dist/katex.min.css";       // [!code ++]
+
+<StreamdownTextPrimitive plugins={{ math }} /> // [!code ++]
+```
+
+  </Step>
+</Steps>
+
+  </Tab>
+</Tabs>
+
 ## Supported Formats
 
-By default, remark-math supports:
+By default, remark-math (react-markdown path) supports:
 - `$...$` for inline math
 - `$$...$$` for display math
 - Fenced code blocks with the `math` language identifier
@@ -67,7 +111,7 @@ Many language models generate LaTeX using different delimiter formats:
 - `\[...\]` for display math
 - Custom formats like `[/math]...[/math]`
 
-You can use the `preprocess` prop to normalize these formats:
+You can use the `preprocess` prop on `MarkdownTextPrimitive` to normalize these formats before parsing:
 
 ```tsx title="/components/assistant-ui/markdown-text.tsx"
 import { MarkdownTextPrimitive } from "@assistant-ui/react-markdown";
@@ -104,6 +148,5 @@ function normalizeCustomMathTags(input: string): string {
 ```
 
 <Callout type="tip">
-The preprocessing function runs before markdown parsing, allowing you to transform any delimiter format into the standard `$` and `$$` format.
+Inside `MarkdownTextPrimitive`, the streamed text first passes through `preprocess` (delimiter normalization) and then through `useSmooth` (character-by-character accumulation), and only then reaches the markdown parser. Both run before remark-math sees the text, so delimiter replacement and the streaming smoothing are streaming-safe — partially-received delimiters are accumulated in the smoothing buffer rather than parsed mid-fragment.
 </Callout>
-

package/.docs/raw/docs/guides/mcp-apps.mdx

@@ -0,0 +1,231 @@
+---
+title: MCP Apps
+description: Render MCP App UI resources inline in chat. Native renderer for the Model Context Protocol Apps spec — sandboxed iframes, JSON-RPC bridge, AI SDK integration.
+platforms: ["react"]
+---
+
+[MCP Apps](https://apps.extensions.modelcontextprotocol.io/) lets a Model Context Protocol server ship a UI resource alongside a tool — a self-contained HTML widget that the chat host renders inline when the tool is called. assistant-ui ships a native renderer that mounts the widget in a sandboxed iframe via [`SafeContentFrame`](/safe-content-frame) and runs a JSON-RPC postMessage bridge so the widget can call tools, send messages, request a display mode, and read host context.
+
+## Overview
+
+When an MCP server attaches a `_meta.ui.resourceUri` (the [`text/html;profile=mcp-app`](https://apps.extensions.modelcontextprotocol.io/api/index.html) MIME) to a tool, AI SDK forwards that metadata through the message stream. assistant-ui's renderer picks it up off the `mcp` field on `ToolCallMessagePart`, fetches the resource through your backend route, and mounts it.
+
+The renderer only acts on URIs that start with `ui://` (per the MCP Apps spec). Tools whose `resourceUri` uses any other scheme are treated as non-MCP-Apps tools and fall through to your regular tool UI.
+
+The widget communicates back through a JSON-RPC bridge:
+
+- **widget → host requests**: `ui/initialize`, `tools/call`, `resources/read`, `resources/list`, `openLink`, `sendMessage`, `requestDisplayMode`, `updateModelContext`
+- **host → widget notifications**: tool input streaming, tool result, host context changes
+- **widget → host notifications**: initialized, size changed, log, error, request teardown
+
+Capability presence is determined at mount time by which handlers you provide. Unknown methods return JSON-RPC `-32601`; bad params return `-32602`.
+
+## Quick start
+
+The renderer talks to a backend route you expose — the MCP client lives server-side so credentials and transport stay out of the browser. The route receives `{ method, params }` POSTs and dispatches to your MCP client.
+
+### Client
+
+Compose `McpAppRenderer({...})` into your `Tools` resource. Provide `host.url` pointing at your route. Any tool-call part carrying `mcp.app` metadata renders the MCP App widget automatically.
+
+```tsx
+import {
+  useAui,
+  Tools,
+  McpAppRenderer,
+  McpAppsRemoteHost,
+} from "@assistant-ui/react";
+
+function MyAssistant() {
+  useAui({
+    tools: Tools({
+      toolkit: myToolkit,
+      mcpApp: McpAppRenderer({
+        host: McpAppsRemoteHost({ url: "/api/mcp-apps" }),
+        hostInfo: { name: "my-app", version: "1.0.0" },
+        hostContext: { theme: "light" },
+      }),
+    }),
+  });
+  // ...
+}
+```
+
+`McpAppsRemoteHost` is the default host strategy — it POSTs `{ method, params }` to your route. A different strategy (e.g. a client-side MCP client) can be plugged in by writing a custom resource that returns the same `McpAppsHost` shape (`{ loadResource, callTool, readResource, listResources }`).
+
+`openLink` is auto-wired to `window.open(url, "_blank", "noopener,noreferrer")`. `sendMessage` is auto-wired to append a user message to the current thread (accepts `string`, `{ prompt }`, `{ text }`, or `{ message }`).
+
+### Route handler
+
+The route accepts `POST` requests with `{ method, params }` JSON bodies. Dispatch by method name and return the result as JSON. Example for Next.js App Router:
+
+```ts
+// app/api/mcp-apps/route.ts
+import { experimental_createMCPClient } from "ai";
+
+let clientPromise: ReturnType<typeof experimental_createMCPClient> | undefined;
+const getClient = () => {
+  clientPromise ??= experimental_createMCPClient({
+    transport: { type: "sse", url: process.env.MCP_SERVER_URL! },
+  });
+  return clientPromise;
+};
+
+export async function POST(req: Request) {
+  const { method, params } = await req.json();
+  const client = await getClient();
+
+  switch (method) {
+    case "mcp-apps/read-resource": {
+      const { contents } = await client.readResource({ uri: params.uri });
+      const c = contents.find((x: { uri: string }) => x.uri === params.uri);
+      return Response.json({
+        uri: params.uri,
+        mimeType: "text/html;profile=mcp-app",
+        html: c?.text ?? "",
+      });
+    }
+    case "tools/call": {
+      const tools = await client.tools();
+      const tool = tools[params.name];
+      if (!tool?.execute) {
+        return Response.json({ error: "Tool not callable" }, { status: 400 });
+      }
+      return Response.json(
+        await tool.execute(params.arguments ?? {}, {
+          toolCallId: `mcp-apps-bridge-${crypto.randomUUID()}`,
+          messages: [],
+        }),
+      );
+    }
+    case "resources/read":
+      return Response.json(await client.readResource({ uri: params.uri }));
+    case "resources/list":
+      return Response.json(await client.listResources(params));
+    default:
+      return Response.json({ error: "Unsupported method" }, { status: 400 });
+  }
+}
+```
+
+The renderer POSTs four method names: `mcp-apps/read-resource`, `tools/call`, `resources/read`, `resources/list`. Reject anything else server-side and apply your own auth / rate limiting in the route.
+
+Per-name `setToolUI` registrations always win over the MCP fallback — you can still customize specific tools.
+
+## AI SDK integration
+
+`@assistant-ui/react-ai-sdk` forwards `callProviderMetadata.mcp.app` from AI SDK tool UI parts into `ToolCallMessagePart.mcp.app`. With AI SDK 5.x and an MCP-Apps-capable MCP server, no extra wiring is required on the part shape.
+
+The rich UI comes from the MCP server's metadata, not from the model, so the path is identical whichever provider drives the conversation. Running Claude is just a different `model:` in `streamText` (`anthropic("claude-sonnet-4-6")` via `@ai-sdk/anthropic`); the MCP server, `splitMcpAppTools`, and the renderer are unchanged. MCP Apps is an open standard in the MCP ecosystem (Claude is one of its hosts), so a standard MCP-Apps server renders out of the box. The bridge below is only needed for servers that use OpenAI's `openai/outputTemplate` convention, again independent of which model you run.
+
+On the chat route, use `splitMcpAppTools()` (from `@ai-sdk/mcp`) to keep app-only tools out of the model's view:
+
+```ts
+import { splitMcpAppTools } from "@ai-sdk/mcp";
+
+const tools = await client.listTools();
+const { modelVisible } = splitMcpAppTools(tools);
+
+const result = streamText({
+  model: openai("gpt-5.4-nano"),
+  tools: modelVisible.tools,
+  // ...
+});
+```
+
+### OpenAI Apps SDK servers
+
+[OpenAI Apps SDK](https://developers.openai.com/apps-sdk) servers carry the same `ui://` template under a different convention: the pointer is `_meta["openai/outputTemplate"]` on the tool definition (not `_meta.ui.resourceUri`), and the resource is served as `text/html+skybridge` rather than `text/html;profile=mcp-app`. `@ai-sdk/mcp` does not recognize `openai/outputTemplate`, so it never populates `callProviderMetadata.mcp.app` and the renderer stays idle.
+
+The renderer needs no change; you only have to surface the pointer. assistant-ui already reads `result._meta["ui/resourceUri"]` off tool results, so the smallest bridge is to copy the template onto the result by tool name. Build the map once from the tool listing, then stamp it inside each tool's `execute`:
+
+```ts
+import type { Tool } from "ai";
+
+// reuse the listTools() result from the AI SDK integration step above; no second round-trip
+const templateByTool = new Map(
+  tools.tools
+    .filter((t) => typeof t._meta?.["openai/outputTemplate"] === "string")
+    .map((t) => [t.name, t._meta["openai/outputTemplate"] as string]),
+);
+
+const withTemplateUri = (tool: Tool, name: string): Tool => {
+  const uri = templateByTool.get(name);
+  const exec = tool.execute;
+  if (!uri || !exec) return tool;
+  return {
+    ...tool,
+    execute: async (args, options) => {
+      const result = (await exec(args, options)) as { _meta?: Record<string, unknown> };
+      return { ...result, _meta: { ...result._meta, "ui/resourceUri": uri } };
+    },
+  } satisfies Tool;
+};
+```
+
+Wrap the AI SDK tool objects before handing them to `streamText`:
+
+```ts
+const aiTools = await client.tools();
+const wrappedTools = Object.fromEntries(
+  Object.entries(aiTools).map(([name, t]) => [name, withTemplateUri(t, name)]),
+);
+// pass wrappedTools to streamText
+```
+
+Your `mcp-apps/read-resource` handler reads the `ui://` resource as in the route example above. Set the response `mimeType` to the `text/html;profile=mcp-app` literal that `McpAppResource` expects and keep the server's HTML in `html`; don't forward the raw `text/html+skybridge` value, which the type rejects.
+
+The cleaner long-term fix is upstream: if `@ai-sdk/mcp`'s `getMCPAppToolMeta` also read `openai/outputTemplate`, then `callProviderMetadata.mcp.app` would populate automatically and this bridge would be unnecessary.
+
+## Bridge protocol
+
+The bridge implements the MCP UI JSON-RPC protocol over `window.postMessage`, filtered by both `event.source === frame.iframe.contentWindow` AND `event.origin === frame.origin` — the cross-origin domain `SafeContentFrame` issues per render. Messages from any other origin or window are dropped silently.
+
+### Widget → host requests
+
+| Method | Notes |
+|---|---|
+| `ui/initialize` | Returns `{ protocolVersion, host, hostContext, capabilities }`. Always supported. |
+| `tools/call` | Routed to `host.url` with method `tools/call`. Optional `handlers.allowedTools` allowlist. Invalid `arguments` shape → `-32602`. |
+| `resources/read` | Routed to `host.url` with method `resources/read`. |
+| `resources/list` | Routed to `host.url` with method `resources/list`. |
+| `openLink` | Requires `handlers.openLink`. Rejects non-`http(s)` URLs with `-32602`. |
+| `sendMessage` | Requires `handlers.sendMessage`. |
+| `requestDisplayMode` | Requires `handlers.requestDisplayMode`. Modes: `inline`, `fullscreen`, `pip`. |
+| `updateModelContext` | Requires `handlers.updateModelContext`. |
+
+When a handler isn't provided, the bridge returns JSON-RPC `-32601` (method not found) — which is also how `capabilities` is reported in the `ui/initialize` response.
+
+### Host → widget notifications
+
+- `notifications/tools/call/input` — sent whenever `part.args` (the streaming tool input) changes
+- `notifications/tools/call/result` — sent when the tool result lands (including error envelopes)
+- `notifications/host_context/changed` — sent when `hostContext` changes (e.g. user toggles theme)
+
+### Widget → host notifications
+
+`notifications/initialized`, `notifications/size_changed`, `notifications/log`, `notifications/error`, `notifications/request_teardown` — wire them via `handlers.onInitialized`, `onSizeChange`, `onLog`, `onError`, `onRequestTeardown` respectively.
+
+If the widget never sends `notifications/initialized` (broken or non-spec-compliant), the host flushes its queued notifications after a 5-second safety timeout so the iframe doesn't appear hung.
+
+## Sandboxing
+
+The iframe is built with [`SafeContentFrame`](/safe-content-frame), which serves each widget from a content-hashed cross-origin so the host page is not reachable by `same-origin` references. Default sandbox flags are `allow-same-origin allow-scripts`. Tune via the `sandbox` field on `McpAppRendererOptions`:
+
+```tsx
+McpAppRenderer({
+  // ...
+  sandbox: {
+    sandbox: ["allow-forms", "allow-popups"],
+    enableBrowserCaching: true,
+    className: "my-mcp-app",
+  },
+});
+```
+
+## Security notes
+
+- Widgets run cross-origin in a sandboxed iframe. The bridge filters incoming messages by both source window and origin.
+- The host route is your auth boundary — apply session checks, rate limiting, and per-tool allowlists there. The renderer trusts whatever the route returns.
+- `openLink` rejects non-`http(s)` URLs at the bridge layer, but your `openLink` handler should still treat the URL as untrusted (e.g. always use `noopener,noreferrer`).
+- Keep `host` and `handlers` references stable across renders (e.g. module-scope constants or `useMemo`); an unstable identity will tear down and refetch the widget on every parent re-render.