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

package/.docs/raw/docs/(docs)/architecture.mdx

@@ -33,61 +33,113 @@ A React state management context for assistant chat. The runtime handles data co
 A hosted service that enhances your assistant experience with comprehensive thread management and message history. Assistant Cloud stores complete message history, automatically persists threads, supports human-in-the-loop workflows, and integrates with common auth providers to seamlessly allow users to resume conversations at any point. [Cloud Docs](/docs/cloud)
 
 
-### There are three common ways to architect your assistant-ui application:
+## What each layer owns
+
+Before picking a runtime or wiring components, it helps to see which layer owns which responsibility. assistant-ui draws hard lines between rendering, conversation state, and where the model actually runs.
+
+### UI layer
+Primitives and prebuilt components render the assistant experience: thread, messages, composer, message parts, actions, attachments, suggestions. They read and write through the runtime context, not directly against the backend or model.
+
+### Runtime layer
+The state and behavior boundary between UI and backend. The runtime owns or adapts conversation state: messages, thread state, composer state, run lifecycle, branching, editing, regeneration. Different runtimes exist because different backends own this state differently. `LocalRuntime` keeps state internal; `ExternalStoreRuntime` delegates to your store.
+
+### Backend / agent layer
+Produces assistant output and app-specific behavior. Depending on the runtime and protocol, the backend may emit text, message parts, tool calls, metadata, agent state, attachments, or other events that the runtime maps into UI state.
+
+### Integration / protocol layer
+Runtime adapters and protocols bridge assistant-ui to different backend shapes: AI SDK, LangGraph, LangChain, ADK, A2A, AG-UI, OpenCode, or your own. The DataStream and AssistantTransport protocols let a generic backend talk to assistant-ui without a custom adapter per app.
+
+### Persistence layer
+Thread and message history can be stored by Assistant Cloud or by your own database via thread and history adapters. Persistence is separate from rendering and backend generation, though the runtime coordinates with it.
+
+## There are three common ways to architect your assistant-ui application:
 
 #### **1. Direct Integration with External Providers**
 
-```mermaid
-graph TD
+<Flow.Root
+  llm={`graph TD
     A[Frontend Components] --> B[Runtime]
-    B --> D[External Providers or LLM APIs]
-    
-    
-    classDef default color:#f8fafc,text-align:center
-    
-    style A fill:#e879f9,stroke:#2e1065,stroke-width:2px,color:#2e1065,font-weight:bold
-    style B fill:#93c5fd,stroke:#1e3a8a,stroke-width:2px,color:#1e3a8a,font-weight:bold
-    style D fill:#fca5a5,stroke:#7f1d1d,stroke-width:2px,color:#7f1d1d,font-weight:bold
-    
-    class A,B,C,D,E default
-```
+    B --> D[External Providers or LLM APIs]`}
+>
+  <Flow.Column>
+    <Flow.Node tone="pink">Frontend Components</Flow.Node>
+    <Flow.Arrow direction="down" length={36} />
+    <Flow.Node tone="blue">Runtime</Flow.Node>
+    <Flow.Arrow direction="down" length={36} />
+    <Flow.Node tone="red">External Providers or LLM APIs</Flow.Node>
+  </Flow.Column>
+</Flow.Root>
 
 #### **2. Using your own API endpoint**
 
-```mermaid
-graph TD
+<Flow.Root
+  llm={`graph TD
     A[Frontend Components] --> B[Runtime]
     B --> E[Your API Backend]
-    E --> D[External Providers or LLM APIs]
-    
-    
-    classDef default color:#f8fafc,text-align:center
-    
-    style A fill:#e879f9,stroke:#2e1065,stroke-width:2px,color:#2e1065,font-weight:bold
-    style B fill:#93c5fd,stroke:#1e3a8a,stroke-width:2px,color:#1e3a8a,font-weight:bold
-    style D fill:#fca5a5,stroke:#7f1d1d,stroke-width:2px,color:#7f1d1d,font-weight:bold
-    style E fill:#fca5a5,stroke:#7f1d1d,stroke-width:2px,color:#7f1d1d,font-weight:bold
-    
-    class A,B,C,D,E default
-```
+    E --> D[External Providers or LLM APIs]`}
+>
+  <Flow.Column>
+    <Flow.Node tone="pink">Frontend Components</Flow.Node>
+    <Flow.Arrow direction="down" length={36} />
+    <Flow.Node tone="blue">Runtime</Flow.Node>
+    <Flow.Arrow direction="down" length={36} />
+    <Flow.Node tone="red">Your API Backend</Flow.Node>
+    <Flow.Arrow direction="down" length={36} />
+    <Flow.Node tone="red">External Providers or LLM APIs</Flow.Node>
+  </Flow.Column>
+</Flow.Root>
 
 #### **3. With Assistant Cloud**
 
-```mermaid
-graph TD
+<Flow.Root
+  llm={`graph TD
     A[Frontend Components] --> B[Runtime]
     B --> C[Cloud]
     E --> C
     C --> D[External Providers or LLM APIs]
-    B --> E[Your API Backend]
-    
-    classDef default color:#f8fafc,text-align:center
-    
-    style A fill:#e879f9,stroke:#2e1065,stroke-width:2px,color:#2e1065,font-weight:bold
-    style B fill:#93c5fd,stroke:#1e3a8a,stroke-width:2px,color:#1e3a8a,font-weight:bold
-    style C fill:#86efac,stroke:#064e3b,stroke-width:2px,color:#064e3b,font-weight:bold
-    style D fill:#fca5a5,stroke:#7f1d1d,stroke-width:2px,color:#7f1d1d,font-weight:bold
-    style E fill:#fca5a5,stroke:#7f1d1d,stroke-width:2px,color:#7f1d1d,font-weight:bold
-    
-    class A,B,C,D,E default
-```
+    B --> E[Your API Backend]`}
+>
+  <Flow.Canvas
+    edges={[
+      { from: "runtime", to: "backend", route: "down", fromOffset: -20 },
+      { from: "runtime", to: "cloud", route: "down", fromOffset: 20 },
+      { from: "cloud", to: "providers", route: "down" },
+    ]}
+  >
+    <Flow.Column>
+      <Flow.Node tone="pink">Frontend Components</Flow.Node>
+      <Flow.Arrow direction="down" length={36} />
+      <Flow.Node flowId="runtime" tone="blue">Runtime</Flow.Node>
+      <div className="h-10" aria-hidden />
+      <Flow.Row>
+        <Flow.Node flowId="backend" tone="red">Your API Backend</Flow.Node>
+        <Flow.Arrow length={48} />
+        <Flow.Node flowId="cloud" tone="green">Cloud</Flow.Node>
+      </Flow.Row>
+      <div className="h-10" aria-hidden />
+      <Flow.Node flowId="providers" tone="red">External Providers or LLM APIs</Flow.Node>
+    </Flow.Column>
+  </Flow.Canvas>
+</Flow.Root>
+
+## Going deeper
+
+These pages go one level deeper on runtime internals, adapters, and persistence.
+
+<Cards>
+  <Card
+    title="Runtime architecture"
+    description="Core runtimes, protocol layers, and framework adapters — what each layer owns."
+    href="/docs/runtimes/concepts/architecture"
+  />
+  <Card
+    title="Adapters"
+    description="Attachments, speech, feedback, history, suggestions across runtimes."
+    href="/docs/runtimes/concepts/adapters"
+  />
+  <Card
+    title="Threads"
+    description="Multi-thread support: cloud, custom database, ExternalStore."
+    href="/docs/runtimes/concepts/threads"
+  />
+</Cards>

package/.docs/raw/docs/(docs)/cli.mdx

@@ -72,13 +72,12 @@ Use `--example` to create a project from one of the monorepo examples with full
 | `with-ag-ui` | [AG-UI protocol](/docs/runtimes/ag-ui) integration | `npx assistant-ui create my-app -e with-ag-ui` |
 | `with-assistant-transport` | Custom backend via Assistant Transport | `npx assistant-ui create my-app -e with-assistant-transport` |
 | `with-resumable-stream` | Resumable LLM stream that survives reload mid-response | `npx assistant-ui create my-app -e with-resumable-stream` |
-| `with-chain-of-thought` | Chain-of-thought with JS execution | `npx assistant-ui create my-app -e with-chain-of-thought` |
+| `with-chain-of-thought` | Chain-of-thought reasoning, tool calls, and source citations | `npx assistant-ui create my-app -e with-chain-of-thought` |
 | `with-external-store` | External message store | `npx assistant-ui create my-app -e with-external-store` |
 | `with-custom-thread-list` | Custom thread list UI | `npx assistant-ui create my-app -e with-custom-thread-list` |
 | `with-react-hook-form` | React Hook Form integration | `npx assistant-ui create my-app -e with-react-hook-form` |
 | `with-ffmpeg` | FFmpeg video processing tool | `npx assistant-ui create my-app -e with-ffmpeg` |
 | `with-elevenlabs-scribe` | ElevenLabs voice transcription | `npx assistant-ui create my-app -e with-elevenlabs-scribe` |
-| `with-parent-id-grouping` | Message part grouping | `npx assistant-ui create my-app -e with-parent-id-grouping` |
 | `with-expo` | Expo / React Native | `npx assistant-ui create my-app -e with-expo` |
 | `with-react-ink` | Terminal UI chat | `npx assistant-ui create my-app -e with-react-ink` |
 | `with-react-router` | React Router v7 integration | `npx assistant-ui create my-app -e with-react-router` |

package/.docs/raw/docs/(docs)/installation.mdx

@@ -465,7 +465,7 @@ export default function MyApp() {
   <Card
     title="Generative UI"
     description="Create rich UI components for tool executions"
-    href="/docs/guides/tool-ui"
+    href="/docs/tools/tool-ui"
   />
   <Card
     title="Add Persistence"

package/.docs/raw/docs/(reference)/api-reference/adapters/persistence.mdx

@@ -3,7 +3,7 @@ title: Persistence Adapters
 description: Persistence adapters for saving assistant-ui message history, remote thread lists, and long-running chat sessions across browser reloads.
 ---
 
-import { GenericThreadHistoryAdapter, InMemoryThreadListAdapter, MessageFormatAdapter, RemoteThreadListAdapter, ThreadHistoryAdapter } from "@/generated/typeDocs";
+import { ExportedMessageRepository, GenericThreadHistoryAdapter, InMemoryThreadListAdapter, MessageFormatAdapter, RemoteThreadListAdapter, ThreadHistoryAdapter } from "@/generated/typeDocs";
 
 {/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
 {/* Do not edit manually. */}
@@ -14,6 +14,10 @@ import { GenericThreadHistoryAdapter, InMemoryThreadListAdapter, MessageFormatAd
 
 ## API Reference
 
+### ExportedMessageRepository
+
+<ParametersTable {...ExportedMessageRepository} />
+
 ### GenericThreadHistoryAdapter
 
 <ParametersTable {...GenericThreadHistoryAdapter} />

package/.docs/raw/docs/(reference)/api-reference/external-store/message-conversion.mdx

@@ -14,6 +14,20 @@ import { useExternalMessageConverter } from "@/generated/typeDocs";
 
 ## API Reference
 
+### bindExternalStoreMessage
+
+<Callout type="warn">
+<strong>Deprecated.</strong> This API is experimental and may change without notice.
+</Callout>
+
+Attach the original external store message(s) to a ThreadMessage or message part.
+This is a no-op if the target already has a bound message.
+Use `getExternalStoreMessages` to retrieve the bound messages later.
+
+```ts
+const bindExternalStoreMessage: <T>(target: object, message: T | T[]) => void;
+```
+
 ### getExternalStoreMessages
 
 ```ts
@@ -33,20 +47,6 @@ const unstable_convertExternalMessages: <T extends WeakKey>(messages: T[], callb
 ### unstable_createMessageConverter
 
 ```ts
-const unstable_createMessageConverter: <T extends object>(callback: useExternalMessageConverter.Callback<T>) => { useThreadMessages: ({ messages, isRunning, joinStrategy, metadata, }: { messages: T[]; isRunning: boolean; joinStrategy?: "concat-content" | "none" | undefined; metadata?: useExternalMessageConverter.Metadata; }) => ThreadMessage[]; toThreadMessages: (messages: T[], isRunning?: boolean, metadata?: useExternalMessageConverter.Metadata) => ThreadMessage[]; toOriginalMessages: (input: ThreadState | ThreadMessage | ThreadMessage["content"][number]) => unknown[]; toOriginalMessage: (input: ThreadState | ThreadMessage | ThreadMessage["content"][number]) => {}; useOriginalMessage: () => {}; useOriginalMessages: () => unknown[]; };
-```
-
-### bindExternalStoreMessage
-
-<Callout type="warn">
-<strong>Deprecated.</strong> This API is experimental and may change without notice.
-</Callout>
-
-Attach the original external store message(s) to a ThreadMessage or message part.
-This is a no-op if the target already has a bound message.
-Use `getExternalStoreMessages` to retrieve the bound messages later.
-
-```ts
-const bindExternalStoreMessage: <T>(target: object, message: T | T[]) => void;
+const unstable_createMessageConverter: <T extends object>(callback: useExternalMessageConverter.Callback<T>) => { useThreadMessages: ({ messages, isRunning, joinStrategy, metadata, }: { messages: T[]; isRunning: boolean; joinStrategy?: JoinStrategy | undefined; metadata?: useExternalMessageConverter.Metadata; }) => ThreadMessage[]; toThreadMessages: (messages: T[], isRunning?: boolean, metadata?: useExternalMessageConverter.Metadata) => ThreadMessage[]; toOriginalMessages: (input: ThreadState | ThreadMessage | ThreadMessage["content"][number]) => unknown[]; toOriginalMessage: (input: ThreadState | ThreadMessage | ThreadMessage["content"][number]) => {}; useOriginalMessage: () => {}; useOriginalMessages: () => unknown[]; };
 ```
 {/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/external-store/runtime.mdx

@@ -3,7 +3,7 @@ title: External Store Runtime
 description: Runtime components, options, and adapters for using assistant-ui with externally owned chat state.
 ---
 
-import { ExternalStoreAdapter, ExternalThread, ExternalThreadProps, ExternalThreadQueueAdapter, useExternalStoreRuntime } from "@/generated/typeDocs";
+import { ExternalStoreAdapter, ExternalThread, ExternalThreadProps, ExternalThreadQueueAdapter, useExternalStoreRuntime, useExternalStoreSharedOptions } from "@/generated/typeDocs";
 
 {/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
 {/* Do not edit manually. */}
@@ -28,9 +28,22 @@ import { ExternalStoreAdapter, ExternalThread, ExternalThreadProps, ExternalThre
 
 ### ExternalThreadQueueAdapter
 
+The queue surface a runtime exposes so the composer can stay usable during a
+run and render the pending messages.
+
 <ParametersTable {...ExternalThreadQueueAdapter} />
 
+### pickExternalStoreSharedOptions
+
+```ts
+const pickExternalStoreSharedOptions: (options: ExternalStoreSharedOptions) => ExternalStoreSharedOptions;
+```
+
 ### useExternalStoreRuntime
 
 <ParametersTable {...useExternalStoreRuntime} />
+
+### useExternalStoreSharedOptions
+
+<ParametersTable {...useExternalStoreSharedOptions} />
 {/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/generative-ui/index.mdx

@@ -0,0 +1,18 @@
+---
+title: Generative UI API Reference
+description: Spec-driven generative UI for assistant-ui. The data format an assistant streams, the component registry that resolves it, and the renderer that turns it into React elements.
+---
+
+{/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
+{/* The page list is generated from exported APIs; edit only the manual prose slot. */}
+
+## Pages
+
+<Cards>
+  <Card title={"Generative UI Spec"} href={"/docs/api-reference/generative-ui/spec"}>
+    {"The serializable node tree an assistant emits to describe generative UI. Covers the GenerativeUISpec format, its nodes, and the message part that carries the spec."}
+  </Card>
+  <Card title={"Generative UI Rendering"} href={"/docs/api-reference/generative-ui/rendering"}>
+    {"Render a generative UI spec into React. The renderer resolves spec nodes against your component registry, and the error thrown when a component cannot be resolved."}
+  </Card>
+</Cards>

package/.docs/raw/docs/(reference)/api-reference/generative-ui/rendering.mdx

@@ -0,0 +1,33 @@
+---
+title: Generative UI Rendering
+description: Render a generative UI spec into React. The renderer resolves spec nodes against your component registry, and the error thrown when a component cannot be resolved.
+---
+
+import { GenerativeUIRender, GenerativeUIRenderError } from "@/generated/typeDocs";
+
+{/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
+{/* Do not edit manually. */}
+
+{/* api-reference:start */}
+{/* AUTO-GENERATED by scripts/generate-api-reference.mts */}
+{/* Do not edit this block manually. */}
+
+## API Reference
+
+### GenerativeUIRender
+
+Internal renderer. Resolves a [GenerativeUISpec](/docs/api-reference/generative-ui/spec#generativeuispec) against the consumer
+allowlist. Used by `MessagePrimitive.GenerativeUI` and by
+`MessagePrimitive.Parts` when handling a `generative-ui` part.
+
+<ParametersTable {...GenerativeUIRender} />
+
+### GenerativeUIRenderError
+
+Thrown when a generative-ui spec references a component name that is not
+present in the consumer-provided allowlist. The allowlist is the security
+boundary in the same-realm rendering path — there is no fallback by
+default. Pass `Fallback` to opt into a soft-fail UX.
+
+<ParametersTable {...GenerativeUIRenderError} />
+{/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/generative-ui/spec.mdx

@@ -0,0 +1,45 @@
+---
+title: Generative UI Spec
+description: The serializable node tree an assistant emits to describe generative UI. Covers the GenerativeUISpec format, its nodes, and the message part that carries the spec.
+---
+
+import { GenerativeUIMessagePart, GenerativeUINode, GenerativeUISpec } from "@/generated/typeDocs";
+
+{/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
+{/* Do not edit manually. */}
+
+{/* api-reference:start */}
+{/* AUTO-GENERATED by scripts/generate-api-reference.mts */}
+{/* Do not edit this block manually. */}
+
+## API Reference
+
+### GenerativeUIMessagePart
+
+A message part that carries a JSON spec describing UI to render.
+
+Render with `<MessagePrimitive.GenerativeUI components={...} />`. The
+primitive resolves component names against the consumer-provided allowlist
+— any unknown name throws a typed error rather than rendering. Stream-
+friendly: a partially-streamed spec renders progressively.
+
+<ParametersTable {...GenerativeUIMessagePart} />
+
+### GenerativeUINode
+
+A JSON spec describing a tree of UI components to render.
+
+The agent emits a [GenerativeUIMessagePart](/docs/api-reference/generative-ui/spec#generativeuimessagepart) containing this spec, and
+the consumer-provided component allowlist is used to resolve `component`
+names. Any component referenced that is not present in the allowlist is
+rejected with a typed error — the allowlist is the security boundary in the
+default same-realm rendering path.
+
+<ParametersTable {...GenerativeUINode} />
+
+### GenerativeUISpec
+
+The root spec for a generative UI tree.
+
+<ParametersTable {...GenerativeUISpec} />
+{/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/hooks/composer-triggers.mdx

@@ -14,6 +14,47 @@ import { unstable_useMentionAdapter, unstable_useSlashCommandAdapter } from "@/g
 
 ## API Reference
 
+### unstable_useMentionAdapter
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Under active development and might change without notice.
+</Callout>
+
+Creates a spreadable `{ adapter, directive }` bundle for `@` mentions.
+Supports tools registered in model context, explicit items, or both —
+flat or categorized.
+
+```tsx
+const mention = unstable_useMentionAdapter();
+<ComposerTriggerPopover char="@" {...mention} />
+```
+
+<ParametersTable {...unstable_useMentionAdapter} />
+
+### unstable_useSlashCommandAdapter
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Under active development and may change without notice.
+</Callout>
+
+Bundles slash command definitions (with inline `execute` callbacks) into
+`{adapter, action}` that plug directly into `ComposerTriggerPopover`.
+`execute` stays in the hook closure and is never attached to the returned
+`TriggerItem`, keeping items serializable.
+
+```tsx
+const slash = unstable_useSlashCommandAdapter({
+  commands: [
+    { id: "summarize", execute: () => runSummarize(), icon: "FileText" },
+    { id: "translate", execute: () => runTranslate(), icon: "Languages" },
+  ],
+});
+
+<ComposerTriggerPopover char="/" {...slash} />
+```
+
+<ParametersTable {...unstable_useSlashCommandAdapter} />
+
 ### unstable_useTriggerPopoverRootContext
 
 ```ts
@@ -54,45 +95,4 @@ Like `useTriggerPopoverTriggers` but returns an empty map outside a root.
 ```ts
 const unstable_useTriggerPopoverTriggersOptional: () => ReadonlyMap<string, RegisteredTrigger>;
 ```
-
-### unstable_useMentionAdapter
-
-<Callout type="warn">
-<strong>Deprecated.</strong> Under active development and might change without notice.
-</Callout>
-
-Creates a spreadable `{ adapter, directive }` bundle for `@` mentions.
-Supports tools registered via `useAssistantTool`, explicit items, or both —
-flat or categorized.
-
-```tsx
-const mention = unstable_useMentionAdapter();
-<ComposerTriggerPopover char="@" {...mention} />
-```
-
-<ParametersTable {...unstable_useMentionAdapter} />
-
-### unstable_useSlashCommandAdapter
-
-<Callout type="warn">
-<strong>Deprecated.</strong> Under active development and may change without notice.
-</Callout>
-
-Bundles slash command definitions (with inline `execute` callbacks) into
-`{adapter, action}` that plug directly into `ComposerTriggerPopover`.
-`execute` stays in the hook closure and is never attached to the returned
-`TriggerItem`, keeping items serializable.
-
-```tsx
-const slash = unstable_useSlashCommandAdapter({
-  commands: [
-    { id: "summarize", execute: () => runSummarize(), icon: "FileText" },
-    { id: "translate", execute: () => runTranslate(), icon: "Languages" },
-  ],
-});
-
-<ComposerTriggerPopover char="/" {...slash} />
-```
-
-<ParametersTable {...unstable_useSlashCommandAdapter} />
 {/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/hooks/model-context.mdx

@@ -3,7 +3,7 @@ title: Model Context Hooks
 description: React hooks for registering assistant-ui tools, data renderers, instructions, and model context providers.
 ---
 
-import { useAssistantInteractable, useInteractableState } from "@/generated/typeDocs";
+import { useAssistantInteractable, useAuiToolOverrides, useInteractableState } from "@/generated/typeDocs";
 
 {/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
 {/* Do not edit manually. */}
@@ -23,6 +23,24 @@ state, use [useInteractableState](/docs/api-reference/hooks/model-context#useint
 
 <ParametersTable {...useAssistantInteractable} />
 
+### useAuiToolOverrides
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Experimental, API may change.
+</Callout>
+
+Overrides toolkit entries for the current assistant scope.
+
+This is intended for dynamic local-state tools whose model-facing contract is
+declared in a `"use generative"` toolkit file with `execute: stubTool()`, but
+whose actual executor must close over React state in the mounted component.
+Keep the override keys stable after mount; dynamic key addition/removal is not
+currently observed.
+Overrides are registered at priority 1000, above toolkit defaults. Only one
+mounted override provider may define a given tool name at a time.
+
+<ParametersTable {...useAuiToolOverrides} />
+
 ### useInteractableState
 
 Reads and writes the state of a registered interactable.