@assistant-ui/mcp-docs-server 0.1.29 → 0.1.31

package/.docs/raw/docs/runtimes/pick-a-runtime.mdx

@@ -1,237 +1,113 @@
 ---
-title: Picking a Runtime
-description: Which runtime fits your backend? Decision guide for common setups.
+title: Picking a runtime
+description: Decision guide for choosing the right runtime, by framework or by feature.
 ---
 
-Choosing the right runtime is crucial for your assistant-ui implementation. This guide helps you navigate the options based on your specific needs.
+import { AguiIcon } from "@/components/icons/agui";
+import { GeminiIcon } from "@/components/icons/gemini";
+import { LangChainIcon } from "@/components/icons/langchain";
+import { LangGraphIcon } from "@/components/icons/langgraph";
+import { MastraIcon } from "@/components/icons/mastra";
+import { OpenCodeIcon } from "@/components/icons/opencode";
+import { VercelIcon } from "@/components/icons/vercel";
+import { Network } from "lucide-react";
 
-## Quick Decision Tree
+A runtime is the connection between assistant-ui's UI primitives and your AI backend. This page helps you pick one. Two lenses, pick whichever maps to what you already know.
 
-```mermaid
-graph TD
-    A[What's your starting point?] --> B{Existing Framework?}
-    B -->|Vercel AI SDK| C[Use AI SDK Integration]
-    B -->|LangGraph| D[Use LangGraph Runtime]
-    B -->|LangServe| E[Use LangServe Runtime]
-    B -->|Mastra| F[Use Mastra Runtime]
-    B -->|AG-UI Protocol| J[Use AG-UI Runtime]
-    B -->|A2A Protocol| K[Use A2A Runtime]
-    B -->|Custom Backend| G{State Management?}
-    G -->|Let assistant-ui handle it| H[Use LocalRuntime]
-    G -->|I'll manage it myself| I[Use ExternalStoreRuntime]
-```
+## Lens 1: by framework
 
-## Core Runtimes
+If you are already using one of these frameworks, the choice is mechanical.
 
-These are the foundational runtimes that power assistant-ui:
+### First-party adapters
 
-<Cards>
-  <Card
-    title="`LocalRuntime`"
-    description="assistant-ui manages chat state internally. Simple adapter pattern for any backend."
-    href="/docs/runtimes/custom/local"
-  />
-  <Card
-    title="`ExternalStoreRuntime`"
-    description="You control the state. Perfect for Redux, Zustand, or existing state management."
-    href="/docs/runtimes/custom/external-store"
-  />
-</Cards>
-
-## Pre-Built Integrations
-
-For popular frameworks, we provide ready-to-use integrations built on top of our core runtimes:
+assistant-ui ships React adapter packages for these. Pick the matching card and follow its overview.
 
 <Cards>
   <Card
+    icon={<VercelIcon width={20} height={20} />}
     title="Vercel AI SDK"
-    description="For useChat hook - streaming with all major providers"
-    href="/docs/runtimes/ai-sdk/v6"
-  />
-  <Card
-    title="Data Stream Protocol"
-    description="For custom backends using the data stream protocol standard"
-    href="/docs/runtimes/data-stream"
+    description="useChat hook, streaming, tools, attachments, multi-step. v6 current; v5 / v4 legacy."
+    href="/docs/runtimes/ai-sdk"
   />
   <Card
+    icon={<LangGraphIcon width={20} height={20} className="text-[#1C3C3C] dark:text-[#5b9595]" />}
     title="LangGraph"
-    description="For complex agent workflows with LangChain's graph framework"
+    description="Direct integration with @langchain/langgraph-sdk. Subgraph events, UI messages, message metadata."
     href="/docs/runtimes/langgraph"
   />
   <Card
-    title="LangServe"
-    description="For LangChain applications deployed with LangServe"
-    href="/docs/runtimes/langserve"
+    icon={<LangChainIcon width={20} height={20} className="text-[#7FC8FF]" />}
+    title="LangChain useStream"
+    description="Wraps @langchain/react's useStream. Lighter-weight, tracks upstream."
+    href="/docs/runtimes/langchain"
   />
   <Card
-    title="Mastra"
-    description="For workflow orchestration with Mastra's ecosystem"
-    href="/docs/runtimes/mastra/overview"
-  />
-  <Card
-    title="AG-UI Protocol"
-    description="For backends implementing the AG-UI (Agent-User Interaction) protocol"
-    href="https://www.npmjs.com/package/@assistant-ui/react-ag-ui"
+    icon={<GeminiIcon width={20} height={20} />}
+    title="Google ADK"
+    description="ADK JS or Python agents. Tool confirmations, auth flows, multi-agent, code execution."
+    href="/docs/runtimes/google-adk"
   />
   <Card
+    icon={<Network width={20} height={20} />}
     title="A2A Protocol"
-    description="For Agent-to-Agent protocol communication between AI agents"
+    description="Any A2A v1.0-compliant agent server. Streaming task state, artifacts, multi-tenancy."
     href="/docs/runtimes/a2a"
   />
+  <Card
+    icon={<AguiIcon width={20} height={20} />}
+    title="AG-UI Protocol"
+    description="AG-UI agents (CopilotKit, custom servers). Streaming text, thinking, tool calls, state snapshots."
+    href="/docs/runtimes/ag-ui"
+  />
+  <PlatformOnly platforms={["react"]}>
+    <Card
+      icon={<OpenCodeIcon width={20} height={20} />}
+      title="OpenCode"
+      description="OpenCode coding-agent server. Permission flows, questions, fork / revert. Experimental."
+      href="/docs/runtimes/opencode"
+    />
+  </PlatformOnly>
 </Cards>
 
-## Understanding Runtime Architecture
+<PlatformOnly platforms={["react"]}>
 
-### How Pre-Built Integrations Work
+### Integration guides
 
-The pre-built integrations (AI SDK, LangGraph, etc.) are **not separate runtime types**. They're convenient wrappers built on top of our core runtimes:
+For frameworks without a dedicated adapter, these wiring guides route through one of the adapters above.
 
-- **AI SDK Integration** → Built on `LocalRuntime` with streaming adapter
-- **LangGraph Runtime** → Built on `LocalRuntime` with graph execution adapter
-- **LangServe Runtime** → Built on `LocalRuntime` with LangServe client adapter
-- **Mastra Runtime** → Built on `LocalRuntime` with workflow adapter
-- **AG-UI Runtime** → Built on `LocalRuntime` with AG-UI protocol adapter
-- **A2A Runtime** → Built on `LocalRuntime` with Agent-to-Agent protocol adapter
+  <Cards>
+    <Card
+      icon={<MastraIcon width={20} height={20} />}
+      title="Mastra"
+      description="TypeScript agent framework. Wired through the Vercel AI SDK runtime."
+      href="/docs/integrations/frameworks/mastra/overview"
+    />
+  </Cards>
 
-This means you get all the benefits of `LocalRuntime` (automatic state management, built-in features) with zero configuration for your specific framework.
+</PlatformOnly>
 
-### When to Use Pre-Built vs Core Runtimes
+## Lens 2: by needs
 
-**Use a pre-built integration when:**
-- You're already using that framework
-- You want the fastest possible setup
-- The integration covers your needs
+If you do not know your framework yet, or your backend is custom, pick by what you need:
 
-**Use a core runtime when:**
-- You have a custom backend
-- You need features not exposed by the integration
-- You want full control over the implementation
+| You need | Use |
+| --- | --- |
+| Simple `fetch` call to your API, runtime owns state | [LocalRuntime](/docs/runtimes/custom/local-runtime) |
+| Keep messages in redux, zustand, tanstack-query, etc. | [ExternalStoreRuntime](/docs/runtimes/custom/external-store) |
+| Backend that already speaks the data stream protocol | [DataStream](/docs/runtimes/custom/data-stream) |
+| Stream full agent state snapshots (not just messages) | [AssistantTransport](/docs/runtimes/custom/assistant-transport) |
 
-<Callout>
-Pre-built integrations can always be replaced with a custom `LocalRuntime` or `ExternalStoreRuntime` implementation if you need more control later.
-</Callout>
+If none of the framework adapters fits, start at [custom backend](/docs/runtimes/custom).
+
+## Shared concepts
+
+Regardless of which runtime you pick, four ideas apply across the board.
 
-## Feature Comparison
-
-### Core Runtime Capabilities
-
-| Feature | `LocalRuntime` | `ExternalStoreRuntime` |
-| ------- | -------------- | ---------------------- |
-| **State Management** | Automatic | You control |
-| **Setup Complexity** | Simple | Moderate |
-| **Message Editing** | Built-in | Implement `onEdit` |
-| **Branch Switching** | Built-in | Implement `setMessages` |
-| **Regeneration** | Built-in | Implement `onReload` |
-| **Cancellation** | Built-in | Implement `onCancel` |
-| **Multi-thread** | Via adapters | Via adapters |
-
-### Available Adapters
-
-| Adapter | `LocalRuntime` | `ExternalStoreRuntime` |
-| ------- | -------------- | ---------------------- |
-| ChatModel | ✅ Required | ❌ N/A |
-| Attachments | ✅ | ✅ |
-| Speech | ✅ | ✅ |
-| Feedback | ✅ | ✅ |
-| History | ✅ | ❌ Use your state |
-| Suggestions | ✅ | ❌ Use your state |
-
-## Common Implementation Patterns
-
-### Vercel AI SDK with Streaming
-
-```tsx
-import { AssistantRuntimeProvider, Thread } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
-
-export function MyAssistant() {
-  const runtime = useChatRuntime();
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-### Custom Backend with `LocalRuntime`
-
-```tsx
-import { useLocalRuntime } from "@assistant-ui/react";
-
-const runtime = useLocalRuntime({
-  async run({ messages, abortSignal }) {
-    const response = await fetch("/api/chat", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ messages }),
-      signal: abortSignal,
-    });
-    return response.json();
-  },
-});
-```
-
-### Redux Integration with `ExternalStoreRuntime`
-
-```tsx
-import { useExternalStoreRuntime } from "@assistant-ui/react";
-
-const messages = useSelector(selectMessages);
-const dispatch = useDispatch();
-
-const runtime = useExternalStoreRuntime({
-  messages,
-  onNew: async (message) => {
-    dispatch(addUserMessage(message));
-    const response = await api.chat(message);
-    dispatch(addAssistantMessage(response));
-  },
-  setMessages: (messages) => dispatch(setMessages(messages)),
-  onEdit: async (message) => dispatch(editMessage(message)),
-  onReload: async (parentId) => dispatch(reloadMessage(parentId)),
-});
-```
-
-## Examples
-
-Explore our implementation examples:
-
-- **[AI SDK v6 Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ai-sdk-v6)** - Vercel AI SDK with `useChatRuntime`
-- **[External Store Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-external-store)** - `ExternalStoreRuntime` with custom state
-- **[Assistant Cloud Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud)** - Multi-thread with cloud persistence
-- **[LangGraph Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph)** - Agent workflows
-
-## Common Pitfalls to Avoid
-
-### LocalRuntime Pitfalls
-- **Forgetting the adapter**: `LocalRuntime` requires a `ChatModelAdapter` - it won't work without one
-- **Not handling errors**: Always handle API errors in your adapter's `run` function
-- **Missing abort signal**: Pass `abortSignal` to your fetch calls for proper cancellation
-
-### ExternalStoreRuntime Pitfalls
-- **Mutating state**: Always create new arrays/objects when updating messages
-- **Missing handlers**: Each UI feature requires its corresponding handler (e.g., no edit button without `onEdit`)
-- **Forgetting optimistic updates**: Set `isRunning` to `true` for loading states
-
-### General Pitfalls
-- **Wrong integration level**: Don't use `LocalRuntime` if you already have Vercel AI SDK - use the AI SDK integration instead
-- **Over-engineering**: Start with pre-built integrations before building custom solutions
-- **Ignoring TypeScript**: The types will guide you to the correct implementation
-
-## Next Steps
-
-1. **Choose your runtime** based on the decision tree above
-2. **Follow the specific guide**:
-   - [AI SDK Integration](/docs/runtimes/ai-sdk/v6)
-   - [`LocalRuntime` Guide](/docs/runtimes/custom/local)
-   - [`ExternalStoreRuntime` Guide](/docs/runtimes/custom/external-store)
-   - [LangGraph Integration](/docs/runtimes/langgraph)
-3. **Start with an example** from our [examples repository](https://github.com/assistant-ui/assistant-ui/tree/main/examples)
-4. **Add features progressively** using adapters
-5. **Consider Assistant Cloud** for production persistence
+- **Architecture** — Framework adapters wrap one of two **core runtimes** (`LocalRuntime`, `ExternalStoreRuntime`). See [architecture](/docs/runtimes/concepts/architecture) for the full layering.
+- **Adapters** (attachments, speech, feedback, history, suggestions) work the same way across runtimes. See [adapters](/docs/runtimes/concepts/adapters).
+- **Threads** (single, cloud, custom database) follow the same model. See [threads](/docs/runtimes/concepts/threads).
+- **Stability** policy: APIs prefixed with `unstable_` may change in any release. See [stability](/docs/runtimes/concepts/stability).
 
 <Callout type="info">
-Need help? Join our [Discord community](https://discord.gg/S9dwgCNEFs) or check the [GitHub](https://github.com/assistant-ui/assistant-ui).
+Need help? Join our [Discord community](https://discord.gg/S9dwgCNEFs) or check the [GitHub repo](https://github.com/assistant-ui/assistant-ui).
 </Callout>

package/.docs/raw/docs/ui/accordion.mdx

@@ -4,6 +4,7 @@ description: A vertically stacked set of interactive headings that reveal or hid
 links:
   - label: Radix UI Accordion
     url: https://www.radix-ui.com/primitives/docs/components/accordion
+platforms: ["react"]
 ---
 
 import { PreviewCode } from "@/components/docs/preview-code.server";

package/.docs/raw/docs/ui/assistant-modal.mdx

@@ -1,6 +1,7 @@
 ---
 title: AssistantModal
 description: Floating chat bubble for support widgets and help desks.
+platforms: ["react"]
 ---
 
 import { AssistantModalSample } from "@/components/docs/samples/assistant-modal";

package/.docs/raw/docs/ui/assistant-sidebar.mdx

@@ -1,6 +1,7 @@
 ---
 title: AssistantSidebar
 description: Side panel chat for co-pilot experiences and inline assistance.
+platforms: ["react"]
 ---
 
 import { AssistantSidebarSample } from "@/components/docs/samples/assistant-sidebar";

package/.docs/raw/docs/ui/attachment.mdx

@@ -1,6 +1,7 @@
 ---
 title: Attachment
 description: UI components for attaching and viewing files in messages.
+platforms: ["react"]
 ---
 
 import { AttachmentSample } from "@/components/docs/samples/attachment";

package/.docs/raw/docs/ui/badge.mdx

@@ -4,6 +4,7 @@ description: A small label component for displaying status, categories, or metad
 links:
   - label: Radix UI Slot
     url: https://www.radix-ui.com/primitives/docs/utilities/slot
+platforms: ["react"]
 ---
 
 import { PreviewCode } from "@/components/docs/preview-code.server";

package/.docs/raw/docs/ui/composer-trigger-popover.mdx

@@ -0,0 +1,200 @@
+---
+title: Composer Trigger Popover
+description: Reusable picker UI for @ mentions, / slash commands, and any other character-triggered popover.
+platforms: ["react"]
+---
+
+import { ComposerTriggerPopoverSample } from "@/components/docs/samples/composer-trigger-popover";
+
+<ComposerTriggerPopoverSample />
+
+## Getting Started
+
+<Steps>
+  <Step>
+
+### Add `composer-trigger-popover`
+
+<InstallCommand shadcn={["composer-trigger-popover"]} />
+
+This adds `/components/assistant-ui/composer-trigger-popover.tsx` — a generic picker UI (Categories + Items + Back) driven by an adapter and one of two behavior props: `directive` (insert a chip) or `action` (run a callback).
+
+  </Step>
+  <Step>
+
+### Wrap the composer
+
+Place `ComposerPrimitive.Unstable_TriggerPopoverRoot` around your composer. Any number of `ComposerTriggerPopover` declarations can live inside — each with its own trigger character, adapter, and behavior prop.
+
+```tsx title="components/assistant-ui/thread.tsx"
+import { ComposerPrimitive } from "@assistant-ui/react";
+import { ComposerTriggerPopover } from "@/components/assistant-ui/composer-trigger-popover";
+
+const Composer = () => (
+  <ComposerPrimitive.Unstable_TriggerPopoverRoot>
+    <ComposerPrimitive.Root>
+      <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
+      <ComposerPrimitive.Send />
+
+      {/* triggers declared here */}
+    </ComposerPrimitive.Root>
+  </ComposerPrimitive.Unstable_TriggerPopoverRoot>
+);
+```
+
+  </Step>
+</Steps>
+
+## @ Mention
+
+Pair the popover with `unstable_useMentionAdapter` — the hook returns a spreadable `{ adapter, directive }` bundle so selecting an item writes a `:tool[Label]{name=id}` directive into the composer text.
+
+```tsx
+import { unstable_useMentionAdapter } from "@assistant-ui/react";
+import { WrenchIcon } from "lucide-react";
+
+const mention = unstable_useMentionAdapter();
+
+<ComposerTriggerPopover
+  char="@"
+  {...mention}
+  fallbackIcon={WrenchIcon}
+/>;
+```
+
+Override formatter or add an `onInserted` callback via hook options: `unstable_useMentionAdapter({ formatter, onInserted })`.
+
+`unstable_useMentionAdapter` also accepts `items` (flat custom list), `categories` (multi-category drill-down), and `includeModelContextTools` for fine-grained control. See the [Mentions guide](/docs/guides/mentions#built-in-mention-adapter).
+
+Render selected mentions as chips in user messages with [`DirectiveText`](/docs/ui/directive-text). For inline chips **inside** the composer, use [`LexicalComposerInput`](/docs/guides/mentions#textarea-vs-lexical).
+
+## / Slash Command
+
+Use [`unstable_useSlashCommandAdapter`](/docs/guides/slash-commands) to bundle commands (data + `execute`) into `{ adapter, action }` — then plug both into `ComposerTriggerPopover`. By default a directive chip is left in the composer as an audit trail; pass `removeOnExecute` to strip the `/command` text entirely. `iconMap` maps `metadata.icon` strings on items and categories to Lucide icons.
+
+```tsx
+import {
+  unstable_useSlashCommandAdapter,
+  type Unstable_SlashCommand,
+} from "@assistant-ui/react";
+import { FileTextIcon, GlobeIcon, LanguagesIcon, SlashIcon } from "lucide-react";
+
+const SLASH_COMMANDS: readonly Unstable_SlashCommand[] = [
+  {
+    id: "summarize",
+    description: "Summarize the conversation",
+    icon: "FileText",
+    execute: () => {/* ... */},
+  },
+  {
+    id: "translate",
+    description: "Translate to another language",
+    icon: "Languages",
+    execute: () => {/* ... */},
+  },
+  {
+    id: "search",
+    description: "Search the web",
+    icon: "Globe",
+    execute: () => {/* ... */},
+  },
+];
+
+function SlashComposer() {
+  const slash = unstable_useSlashCommandAdapter({ commands: SLASH_COMMANDS });
+
+  return (
+    <ComposerTriggerPopover
+      char="/"
+      {...slash}
+      iconMap={{
+        FileText: FileTextIcon,
+        Languages: LanguagesIcon,
+        Globe: GlobeIcon,
+      }}
+      fallbackIcon={SlashIcon}
+    />
+  );
+}
+```
+
+## Combining Triggers
+
+Multiple popovers coexist under one `TriggerPopoverRoot`. Each reads state from its own declaration, so `@` and `/` never collide.
+
+```tsx
+const commandHandlers: Record<string, () => void> = {
+  summarize: () => {/* ... */},
+  translate: () => {/* ... */},
+};
+
+<ComposerPrimitive.Unstable_TriggerPopoverRoot>
+  <ComposerPrimitive.Root>
+    <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
+
+    <ComposerTriggerPopover
+      char="@"
+      adapter={mentionAdapter}
+      directive={{ formatter: unstable_defaultDirectiveFormatter }}
+      fallbackIcon={WrenchIcon}
+    />
+    <ComposerTriggerPopover
+      char="/"
+      adapter={slashAdapter}
+      action={{
+        formatter: unstable_defaultDirectiveFormatter,
+        onExecute: (item) => commandHandlers[item.id]?.(),
+      }}
+      iconMap={slashIcons}
+      fallbackIcon={SlashIcon}
+    />
+  </ComposerPrimitive.Root>
+</ComposerPrimitive.Unstable_TriggerPopoverRoot>
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+| --- | --- |
+| <Kbd>ArrowDown</Kbd> | Highlight next item |
+| <Kbd>ArrowUp</Kbd> | Highlight previous item |
+| <Kbd>Enter</Kbd> | Select highlighted item / drill into category |
+| <Kbd>Escape</Kbd> | Close popover |
+| <Kbd>Backspace</Kbd> | Go back to categories (when query is empty) |
+
+## API Reference
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `char` | `string` | — | Trigger character, e.g. `"@"` or `"/"` (required; unique within the root) |
+| `adapter` | `Unstable_TriggerAdapter` | — | Provides categories, items, and search (required) |
+| `directive` | `{ formatter, onInserted?, chip? }` | — | Enables directive-insert behavior. Mutually exclusive with `action`. |
+| `action` | `{ formatter, onExecute, removeOnExecute?, chip? }` | — | Enables action behavior. Mutually exclusive with `directive`. |
+| `iconMap` | `Record<string, IconComponent>` | — | Maps `item.metadata.icon` / `category.metadata.icon` strings to icons |
+| `fallbackIcon` | `IconComponent` | `SparklesIcon` | Icon used when no `iconMap` entry matches |
+| `backLabel` | `string` | `"Back"` | Back button label |
+| `emptyCategoriesLabel` | `string` | `"No items available"` | Shown when no categories are available |
+| `emptyItemsLabel` | `string` | `"No matching items"` | Shown when no items match |
+
+All other props (`className`, etc.) forward to the underlying popover `div`.
+
+### `directive` object
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `formatter` | `Unstable_DirectiveFormatter` | Serializes the selected item into the directive text written to the composer |
+| `onInserted` | `(item) => void` | Optional callback fired after the directive has been inserted |
+
+### `action` object
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `formatter` | `Unstable_DirectiveFormatter` | Serializes the selected item into the chip left behind (unused when `removeOnExecute`) |
+| `onExecute` | `(item) => void` | Callback fired when an item is selected |
+| `removeOnExecute` | `boolean` | When `true`, strips the trigger text instead of leaving a chip. Default `false`. |
+
+## Related
+
+- [Directive Text](/docs/ui/directive-text) — renderer for mention chips in user messages
+- [Mentions guide](/docs/guides/mentions) — `@`-mention architecture and formatter details
+- [Slash Commands guide](/docs/guides/slash-commands) — `/`-command architecture

package/.docs/raw/docs/ui/context-display.mdx

@@ -1,6 +1,7 @@
 ---
 title: Context Display
 description: Visualize token usage relative to a model's context window — ring, bar, or text — with a detailed hover popover.
+platforms: ["react"]
 ---
 
 import { ContextDisplaySample } from "@/components/docs/samples/context-display";

package/.docs/raw/docs/ui/diff-viewer.mdx

@@ -6,6 +6,7 @@ links:
     url: https://github.com/sergeyt/parse-diff
   - label: diff
     url: https://github.com/kpdecker/jsdiff
+platforms: ["react"]
 ---
 
 import { PreviewCode } from "@/components/docs/preview-code.server";