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

package/.docs/raw/docs/tools/generative-ui.mdx

@@ -0,0 +1,214 @@
+---
+title: Generative UI (JSON spec)
+description: Render agent-described React UI from a JSON spec with a consumer-provided component allowlist.
+---
+
+`MessagePrimitive.GenerativeUI` is a first-class primitive for rendering UI
+described by the agent at runtime as a JSON spec. Instead of hard-coding a
+component per tool, the agent emits a `generative-ui` message part containing
+a tree of components by name. assistant-ui resolves each name against a
+**consumer-provided allowlist** and renders the result.
+
+> The allowlist controls **which** components the agent may render: any name
+> not in it throws a typed `GenerativeUIRenderError` (no implicit fallback). It
+> does not constrain the props passed to those components; see [Security](#security).
+
+> **Opt-in feature:** The default shadcn `Thread` does **not** render
+> `generative-ui` parts. You must wire the primitive explicitly — see
+> [Opt-in wiring](#opt-in-wiring).
+
+## Which generative UI pattern?
+
+assistant-ui uses "generative UI" in three different places. Pick the one that
+matches your integration:
+
+| Pattern | API | Best for | Streaming |
+|---------|-----|----------|-----------|
+| **Generative UI primitive** | `MessagePrimitive.GenerativeUI` + allowlist | Composing dashboards, cards, and layouts from a component vocabulary you ship | Native `generative-ui` parts update progressively when the part spec changes incrementally |
+| **Tool UI** | `Tools({ toolkit })` with `render` | Interactive widgets tied to a known tool (forms, pickers, charts) | Tool **args** stream while the model fills them in |
+| **LangGraph data UI** | `makeAssistantDataUI` + `ui_message` | LangGraph agents emitting UI via the LangGraph stream | UI messages arrive on the LangGraph custom channel |
+
+See also: [Tool UI guide](/docs/tools/tool-ui), [LangGraph generative UI](/docs/runtimes/langgraph/generative-ui).
+
+## When not to use the primitive
+
+- **User input and two-way interaction** → [Tool UI](/docs/tools/tool-ui) or [Interactables](/docs/tools/interactables)
+- **LangGraph `push_ui_message`** → [LangGraph data UI](/docs/runtimes/langgraph/generative-ui)
+- **Untrusted HTML or third-party widgets** → [MCP Apps](/docs/tools/mcp-apps) (sandboxed frames)
+
+## Quick start
+
+### 1. Define your component allowlist
+
+```tsx title="components/gui.tsx"
+const Card = ({ title, children }) => (
+  <div className="rounded-xl border bg-card p-4 shadow-sm">
+    <div className="text-base font-semibold">{title}</div>
+    <div className="mt-2">{children}</div>
+  </div>
+);
+
+const Button = ({ label }) => (
+  <button className="rounded-md bg-primary px-3 py-1.5 text-primary-foreground">
+    {label}
+  </button>
+);
+
+export const componentsAllowlist = { Card, Button };
+```
+
+### 2. Wire the primitive into your message renderer
+
+See [Opt-in wiring](#opt-in-wiring) for all three integration patterns.
+
+### 3. Have the agent emit UI
+
+**ExternalStore / manual messages** attach a native part:
+
+```ts
+{
+  type: "generative-ui",
+  spec: {
+    root: {
+      component: "Card",
+      props: { title: "Welcome" },
+      children: [
+        { component: "Button", props: { label: "Get started" } },
+      ],
+    },
+  },
+}
+```
+
+**AI SDK (`useChatRuntime`)** — the adapter maps tool results to `tool-call`
+parts, not `generative-ui` parts. Use the [AI SDK interim bridge](#pattern-3--ai-sdk-interim-bridge) until a native emission helper ships.
+
+Live examples in [`examples/with-generative-ui`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-generative-ui): Tool UI demo (`/`), static primitive (`/primitive`), GUI chat (`/gui-chat`).
+
+## Opt-in wiring
+
+The stock `@assistant-ui/ui` `Thread` switch returns `null` for unknown part
+types — including `generative-ui`. Add one of these patterns in **your**
+assistant message renderer (~15 lines).
+
+### Pattern 1 — `MessagePrimitive.Parts`
+
+```tsx
+<MessagePrimitive.Parts
+  components={{
+    generativeUI: {
+      components: componentsAllowlist,
+      Fallback: UnknownComponentFallback,
+    },
+  }}
+/>
+```
+
+### Pattern 2 — `GroupedParts` case (shadcn Thread fork)
+
+```tsx
+case "generative-ui":
+  return (
+    <MessagePrimitive.GenerativeUI
+      components={componentsAllowlist}
+      Fallback={UnknownComponentFallback}
+    />
+  );
+```
+
+Also exclude `render_gui` from tool-group chrome in `groupBy` if you use the
+AI SDK bridge (return `null` for that tool name).
+
+### Pattern 3 — AI SDK interim bridge
+
+When using `useChatRuntime`, map a dedicated tool result to the renderer:
+
+```tsx
+case "tool-call":
+  if (part.toolName === "render_gui") {
+    const spec = parseRenderGuiResult(part.result);
+    if (spec) {
+      return (
+        <MessagePrimitive.GenerativeUI
+          spec={spec}
+          components={componentsAllowlist}
+          Fallback={UnknownComponentFallback}
+        />
+      );
+    }
+  }
+  return part.toolUI ?? <ToolFallback {...part} />;
+```
+
+The message store still holds a `tool-call` on this path — not a
+`generative-ui` part. See `examples/with-generative-ui/app/gui-chat` for a
+working reference.
+
+Bare strings act as inline text leaves.
+
+## Spec shape
+
+```ts
+type GenerativeUINode =
+  | string
+  | {
+      component: string;             // resolved against the allowlist
+      props?: Record<string, unknown>;
+      children?: GenerativeUINode[];
+      key?: string;                   // optional stable React key
+    };
+
+type GenerativeUISpec = {
+  root: GenerativeUINode | GenerativeUINode[];
+};
+```
+
+The spec is plain JSON — easy for any agent to emit, and easy to validate
+on the server before delivery.
+
+## Streaming
+
+When a message contains native `generative-ui` parts whose `spec` updates
+incrementally (for example via ExternalStore), the primitive renders
+progressively as nodes and props arrive.
+
+The AI SDK `render_gui` tool path returns the full spec at **tool completion**
+— not incrementally during the tool execute step. For args streaming during
+generation, use [Tool UI](/docs/tools/tool-ui) instead.
+
+## Security
+
+The allowlist is the boundary on **which** components render: a spec can only instantiate components you put in the registry, with no `eval` and no dynamic import (names are looked up in the registry and nothing else). An unknown name throws `GenerativeUIRenderError` or invokes your `Fallback`.
+
+It does **not** constrain the `props` the agent supplies. Spec props are spread directly onto your allowlisted components, so treat every allowlisted component as receiving untrusted input: never forward agent-supplied props into `dangerouslySetInnerHTML`, validate or reject `href` / `src` values (for example block `javascript:` URLs), and avoid passing spec props anywhere they become executable. The safest allowlisted components accept only primitive, display-oriented props.
+
+## Error handling
+
+Unknown component names throw `GenerativeUIRenderError` with a typed
+`componentName` field. Catch it with a React error boundary, or pass a
+`Fallback` component to opt into a soft-fail UX:
+
+```tsx
+<MessagePrimitive.GenerativeUI
+  components={componentsAllowlist}
+  Fallback={({ component }) => (
+    <span className="rounded bg-muted px-1.5 py-0.5 font-mono text-xs">
+      unknown component: {component}
+    </span>
+  )}
+/>
+```
+
+## Composing with other primitives
+
+`generative-ui` is a regular `MessagePart` type, so it composes cleanly with
+`MessagePrimitive.Parts`, `MessagePrimitive.PartByIndex`, and
+`MessagePrimitive.GroupedParts`. Render it alongside text, tool calls, and
+reasoning in the same message.
+
+## Why a primitive (not just a tool)
+
+Tool-call UI is great when the agent already invoked a known tool. Generative
+UI flips it: the agent _composes_ UI from a vocabulary you ship. Useful for
+dashboards, status panels, and structured layouts — not for collecting user
+input (use Tool UI for that).

package/.docs/raw/docs/tools/index.mdx

@@ -0,0 +1,76 @@
+---
+title: Tools
+description: Give the model callable capabilities with assistant-ui toolkits — define frontend, backend, human, and provider tools, render tool calls as interactive UI, and connect MCP servers.
+platforms: ["react"]
+---
+
+Tools are how the model takes action: fetch data, call an API, query a database, drive your UI, or run a workflow. In assistant-ui you declare tools in a **toolkit** — a named map where each key is the tool name the model sees and each value describes the tool's schema, where it runs, and how its call renders in the chat.
+
+## Start here
+
+<Cards>
+  <Card title="Defining Tools" href="/docs/tools/defining-tools">
+    Author a toolkit with the `"use generative"` directive — frontend, backend, human, and provider tools, with the schema, executor, and renderer in one file.
+  </Card>
+  <Card title="Backend Tools" href="/docs/tools/backend">
+    Wire a toolkit into your AI SDK route with `generativeTools` / `frontendTools`, mix client and server tools, and round-trip multi-modal results.
+  </Card>
+  <Card title="Tool UI" href="/docs/tools/tool-ui">
+    Render tool calls as custom components — loading and result states, human-in-the-loop, approvals, and streaming.
+  </Card>
+  <Card title="Dynamic Tools" href="/docs/tools/dynamic-tools">
+    Tools whose executor closes over React state, via `stubTool()` + `useAuiToolOverrides`.
+  </Card>
+</Cards>
+
+## Two ways to define a toolkit
+
+<Callout type="info">
+  **`"use generative"` + `defineToolkit`** — for tools you author yourself
+  (browser or your own backend). The compiler co-locates the schema, executor,
+  and renderer in one file and splits them across the client/server boundary.
+
+  **Plain `satisfies Toolkit`** — for tools that already execute elsewhere (an
+  MCP server, a separate backend route, a LangGraph node) where you only attach a
+  renderer.
+</Callout>
+
+In a `"use generative"` file every tool declares an `execute` and the kind is
+**inferred** from it (you never write `type`). In a plain toolkit you author
+`type` and write render-only `{ type: "backend", render }` entries. See
+[Defining Tools](/docs/tools/defining-tools#two-ways-to-define-a-toolkit).
+
+## Rendering AI output as UI
+
+assistant-ui has a few ways to turn model output into React UI. Pick by **who decides what renders**:
+
+| You want… | Use | The decider |
+| --- | --- | --- |
+| A custom component for a known tool call (form, picker, chart, status) | [Tool UI](/docs/tools/tool-ui) — `render` on a toolkit entry | the **model**, by calling the tool |
+| Persistent, out-of-thread state the AI can read and write | [Interactables](/docs/tools/interactables) | the **model + the user**, bidirectionally |
+| UI composed from a component vocabulary you ship, described as a JSON spec | [Generative UI (JSON spec)](/docs/tools/generative-ui) — `MessagePrimitive.GenerativeUI` | the **model**, composing a tree |
+| UI pushed by a LangGraph node alongside messages | [LangGraph Generative UI](/docs/runtimes/langgraph/generative-ui) — `makeAssistantDataUI` | the **backend / orchestrator** |
+
+## Connect external tools
+
+<Cards>
+  <Card title="MCP (server-side)" href="/docs/tools/mcp">
+    Wire one or more MCP servers into your API route as a tool catalog.
+  </Card>
+  <Card title="User-managed MCP" href="/docs/tools/user-managed-mcp">
+    Let end users add and authenticate MCP servers from the browser.
+  </Card>
+  <Card title="MCP Apps" href="/docs/tools/mcp-apps">
+    Render MCP UI resources (`ui://`) inline in sandboxed frames.
+  </Card>
+  <Card title="Multi-Agent" href="/docs/tools/multi-agent">
+    Render sub-agent conversations inside a tool call.
+  </Card>
+</Cards>
+
+## Reference & components
+
+- [Tools API Reference](/docs/api-reference/tools) — `tool`, `Toolkit`, `Tools`, and the tool-status hooks.
+- [`ToolFallback`](/docs/ui/tool-fallback) — a default tool card for tools with no custom UI.
+- [`ToolGroup`](/docs/ui/tool-group) — collapse consecutive tool calls into one container.
+- [Migrating Tools to Toolkits](/docs/migrations/toolkit-tools) — move off the deprecated `makeAssistantTool` / `useAssistantToolUI` APIs.

package/.docs/raw/docs/{guides → tools}/interactables.mdx

@@ -399,5 +399,5 @@ See the complete [with-interactables example](https://github.com/assistant-ui/as
 
 ## Related
 
-- [Generative UI](/docs/guides/tool-ui) — Inline tool call UIs rendered inside messages
+- [Tool UI](/docs/tools/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/{integrations/tools → tools}/mcp.mdx

@@ -13,7 +13,7 @@ client  ──►  /api/chat  ──►  MCP client  ──►  MCP server (HTTP
                             └─ tools()  ──►  passed to streamText({ tools })
 ```
 
-The MCP client lives on the server inside your AI SDK route handler. It connects to one or more MCP servers, calls `tools()` to get a tool map, and hands that map to `streamText`. assistant-ui's existing tool-call UI (`ToolFallback`, `makeAssistantToolUI`) renders the results.
+The MCP client lives on the server inside your AI SDK route handler. It connects to one or more MCP servers, calls `tools()` to get a tool map, and hands that map to `streamText`. assistant-ui's existing tool-call UI (`ToolFallback`, or toolkit entries with `render`) renders the results.
 
 ## Setup
 
@@ -141,7 +141,7 @@ If two servers expose tools with the same name, the later spread wins. Rename or
 
 ### Render results in the UI
 
-Tool calls flow through the existing assistant-ui tool-call rendering. With no setup, the bundled `<ToolFallback>` component renders the call name, arguments, and result. To customize the appearance for a specific tool, use `makeAssistantToolUI`:
+Tool calls flow through the existing assistant-ui tool-call rendering. With no setup, the bundled `<ToolFallback>` component renders the call name, arguments, and result. To customize the appearance for a specific tool, add a backend entry to your toolkit:
 
 <PlatformTabs>
 <Tab value="React">
@@ -149,86 +149,113 @@ Tool calls flow through the existing assistant-ui tool-call rendering. With no s
 ```tsx title="app/components/GitHubIssueToolUI.tsx"
 "use client";
 
-import { makeAssistantToolUI } from "@assistant-ui/react";
+import type { Toolkit } from "@assistant-ui/react";
 
 type Args = { repo: string; number: number };
 type Result = { title: string; state: string; url: string };
 
-export const GitHubIssueToolUI = makeAssistantToolUI<Args, Result>({
-  toolName: "github_get_issue",
-  render: ({ args, result }) => (
-    <div className="rounded border p-3">
-      <div className="font-mono text-sm">{args.repo}#{args.number}</div>
-      {result && (
-        <a href={result.url} className="underline">
-          {result.title} ({result.state})
-        </a>
-      )}
-    </div>
-  ),
-});
+export const toolkit = {
+  github_get_issue: {
+    type: "backend",
+    render: ({ args, result }: { args: Args; result?: Result }) => (
+      <div className="rounded border p-3">
+        <div className="font-mono text-sm">{args.repo}#{args.number}</div>
+        {result && (
+          <a href={result.url} className="underline">
+            {result.title} ({result.state})
+          </a>
+        )}
+      </div>
+    ),
+  },
+} satisfies Toolkit;
 ```
 
 </Tab>
 <Tab value="React Native">
 
 ```tsx title="components/GitHubIssueToolUI.tsx"
-import { makeAssistantToolUI } from "@assistant-ui/react-native";
+import type { Toolkit } from "@assistant-ui/react-native";
 import { Linking, Pressable, Text, View } from "react-native";
 
 type Args = { repo: string; number: number };
 type Result = { title: string; state: string; url: string };
 
-export const GitHubIssueToolUI = makeAssistantToolUI<Args, Result>({
-  toolName: "github_get_issue",
-  render: ({ args, result }) => (
-    <View style={{ borderWidth: 1, borderRadius: 6, padding: 12 }}>
-      <Text style={{ fontFamily: "Menlo", fontSize: 13 }}>
-        {args.repo}#{args.number}
-      </Text>
-      {result && (
-        <Pressable onPress={() => Linking.openURL(result.url)}>
-          <Text style={{ textDecorationLine: "underline" }}>
-            {result.title} ({result.state})
-          </Text>
-        </Pressable>
-      )}
-    </View>
-  ),
-});
+export const toolkit = {
+  github_get_issue: {
+    type: "backend",
+    render: ({ args, result }: { args: Args; result?: Result }) => (
+      <View style={{ borderWidth: 1, borderRadius: 6, padding: 12 }}>
+        <Text style={{ fontFamily: "Menlo", fontSize: 13 }}>
+          {args.repo}#{args.number}
+        </Text>
+        {result && (
+          <Pressable onPress={() => Linking.openURL(result.url)}>
+            <Text style={{ textDecorationLine: "underline" }}>
+              {result.title} ({result.state})
+            </Text>
+          </Pressable>
+        )}
+      </View>
+    ),
+  },
+} satisfies Toolkit;
 ```
 
 </Tab>
 <Tab value="React Ink">
 
 ```tsx title="components/GitHubIssueToolUI.tsx"
-import { makeAssistantToolUI } from "@assistant-ui/react-ink";
+import type { Toolkit } from "@assistant-ui/react-ink";
 import { Box, Text } from "ink";
 
 type Args = { repo: string; number: number };
 type Result = { title: string; state: string; url: string };
 
-export const GitHubIssueToolUI = makeAssistantToolUI<Args, Result>({
-  toolName: "github_get_issue",
-  render: ({ args, result }) => (
-    <Box borderStyle="round" paddingX={1} flexDirection="column">
-      <Text>
-        {args.repo}#{args.number}
-      </Text>
-      {result && (
+export const toolkit = {
+  github_get_issue: {
+    type: "backend",
+    render: ({ args, result }: { args: Args; result?: Result }) => (
+      <Box borderStyle="round" paddingX={1} flexDirection="column">
         <Text>
-          {result.title} ({result.state}) — {result.url}
+          {args.repo}#{args.number}
         </Text>
-      )}
-    </Box>
-  ),
-});
+        {result && (
+          <Text>
+            {result.title} ({result.state}) — {result.url}
+          </Text>
+        )}
+      </Box>
+    ),
+  },
+} satisfies Toolkit;
 ```
 
 </Tab>
 </PlatformTabs>
 
-Mount it once anywhere inside `<AssistantRuntimeProvider>`. The `toolName` must match the name your MCP server publishes.
+Register the toolkit once with `Tools({ toolkit })`. The toolkit key must match the name your MCP server publishes.
+
+```tsx title="app/components/RuntimeProvider.tsx"
+"use client";
+
+import { AssistantRuntimeProvider, Tools, useAui } from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import type { ReactNode } from "react";
+
+import { toolkit } from "./GitHubIssueToolUI";
+
+export function MyRuntimeProvider({ children }: { children: ReactNode }) {
+  const runtime = useChatRuntime({ api: "/api/chat" });
+  const aui = useAui({ tools: Tools({ toolkit }) });
+
+  return (
+    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
 
 </Step>
 <Step>
@@ -262,6 +289,6 @@ Start the app and trigger a tool call (e.g., ask the assistant to do something t
   <Card
     title="Tools and tool UI"
     description="Build custom renderers for tool calls and approvals."
-    href="/docs/guides/tools"
+    href="/docs/tools/defining-tools"
   />
 </Cards>

package/.docs/raw/docs/{guides → tools}/multi-agent.mdx

@@ -12,7 +12,7 @@ When a tool call includes a `messages` field (`ToolCallMessagePart.messages`), i
 
 Key behaviors:
 
-- **Scope inheritance** — Parent tool UI registrations are available in sub-agent messages. A `makeAssistantToolUI` registered at the top level works inside sub-agent conversations too.
+- **Scope inheritance** — Parent toolkit renderers are available in sub-agent messages. A `Tools({ toolkit })` registration at the top level works inside sub-agent conversations too.
 - **Recursive** — Sub-agent messages can contain tool calls that themselves have nested messages. Just use `MessagePartPrimitive.Messages` again.
 - **Read-only** — Sub-agent messages are rendered in a readonly context. No editing, branching, or composing.
 
@@ -25,13 +25,15 @@ Key behaviors:
 
 ```tsx
 import {
-  makeAssistantToolUI,
+  Tools,
+  type Toolkit,
   MessagePartPrimitive,
 } from "@assistant-ui/react";
 
-const ResearchAgentToolUI = makeAssistantToolUI({
-  toolName: "invoke_researcher",
-  render: ({ args, status }) => (
+const toolkit = {
+  invoke_researcher: {
+    type: "backend",
+    render: ({ args, status }) => (
     <div className="my-2 rounded-lg border p-4">
       <div className="mb-2 text-sm font-medium text-gray-500">
         Researcher Agent {status.type === "running" && "(working...)"}
@@ -44,7 +46,8 @@ const ResearchAgentToolUI = makeAssistantToolUI({
       </MessagePartPrimitive.Messages>
     </div>
   ),
-});
+  },
+} satisfies Toolkit;
 ```
 
   </Step>
@@ -144,23 +147,17 @@ function App() {
 
 ## Subgraph Namespace Events
 
-When using LangGraph, subgraph events carry a `namespace` that identifies which sub-agent emitted them. This lets you attribute messages and state to specific sub-agents without polling or manual coordination.
-
-- `onSubgraphValues(namespace, values)` fires when a subgraph emits a full state snapshot. Use the `values.messages` array to populate `ToolCallMessagePart.messages` for that sub-agent.
-- `onSubgraphUpdates(namespace, updates)` fires for incremental state patches from a subgraph.
-- `onSubgraphError(namespace, error)` fires when a subgraph fails. The parent message is not marked incomplete; only top-level errors trigger that.
-- `onMessageChunk(chunk, metadata)` includes `metadata.namespace` when the chunk originates from a subgraph. Use this to display per-sub-agent streaming indicators.
-
-The `namespace` value mirrors the pipe-separated suffix on the LangGraph event name (e.g. `values|tools:call_abc` gives `"tools:call_abc"`).
+When using LangGraph, subgraph events (`onSubgraphValues` / `onSubgraphUpdates` / `onSubgraphError`, plus the `namespace` on `onMessageChunk`) carry a `namespace` that identifies which sub-agent emitted them, letting you attribute messages and state to specific sub-agents. See [LangGraph Streaming](/docs/runtimes/langgraph/streaming) for the full reference.
 
 ## Recursive Sub-Agents
 
 If a sub-agent's tool calls also have nested messages, the same pattern applies recursively:
 
 ```tsx
-const OuterAgentToolUI = makeAssistantToolUI({
-  toolName: "invoke_planner",
-  render: () => (
+const toolkit = {
+  invoke_planner: {
+    type: "backend",
+    render: () => (
     <div className="rounded border p-3">
       <h4>Planner Agent</h4>
       <MessagePartPrimitive.Messages>
@@ -191,7 +188,8 @@ const OuterAgentToolUI = makeAssistantToolUI({
       </MessagePartPrimitive.Messages>
     </div>
   ),
-});
+  },
+} satisfies Toolkit;
 ```
 
 ## ReadonlyThreadProvider
@@ -227,7 +225,7 @@ function SubConversation({
 
 ## Related
 
-- [Generative UI](/docs/guides/tool-ui) — Creating tool call UIs
+- [Generative UI](/docs/tools/tool-ui) — Creating tool call UIs
 - [MessagePartPrimitive](/docs/api-reference/primitives/message-part) — API reference for message part primitives
 - [Sub-Agent Model Tracking](/docs/cloud/ai-sdk#sub-agent-model-tracking) — Track delegated model usage and costs in the Cloud dashboard
 - [LangGraph Streaming](/docs/runtimes/langgraph/streaming) — Event handlers, subgraph events, and message metadata