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

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

@@ -1,245 +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 via langgraph-sdk| D1[Use react-langgraph]
-    B -->|LangChain via @langchain/react useStream| D2[Use react-langchain]
-    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="Integrates with `@langchain/langgraph-sdk` directly. Broader feature set: subgraph events, UI messages, message metadata, cancellation."
+    description="Direct integration with @langchain/langgraph-sdk. Subgraph events, UI messages, message metadata."
     href="/docs/runtimes/langgraph"
   />
   <Card
+    icon={<LangChainIcon width={20} height={20} className="text-[#7FC8FF]" />}
     title="LangChain useStream"
-    description="Wraps `useStream` from `@langchain/react`. Lighter-weight, stays aligned with upstream. Fewer features today."
+    description="Wraps @langchain/react's useStream. Lighter-weight, tracks upstream."
     href="/docs/runtimes/langchain"
   />
   <Card
-    title="LangServe"
-    description="For LangChain applications deployed with LangServe"
-    href="/docs/runtimes/langserve"
+    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
-    title="Mastra"
-    description="For workflow orchestration with Mastra's ecosystem"
-    href="/docs/runtimes/mastra/overview"
+    icon={<Network width={20} height={20} />}
+    title="A2A Protocol"
+    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="For backends implementing the AG-UI (Agent-User Interaction) protocol"
-    href="https://www.npmjs.com/package/@assistant-ui/react-ag-ui"
-  />
-  <Card
-    title="A2A Protocol"
-    description="For Agent-to-Agent protocol communication between AI agents"
-    href="/docs/runtimes/a2a"
+    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 `ExternalStoreRuntime`, integrates with `@langchain/langgraph-sdk`
-- **LangChain useStream Runtime** → Built on `ExternalStoreRuntime`, wraps `useStream` from `@langchain/react`
-- **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 pre-built integrations give you assistant-ui's features — state management, streaming, UI primitives — with zero configuration for your specific framework, regardless of whether the adapter happens to build on `LocalRuntime` or `ExternalStoreRuntime` internally. The list above tells you which core runtime each adapter uses.
+</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)
-   - [LangChain useStream Integration](/docs/runtimes/langchain)
-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

@@ -1,6 +1,7 @@
 ---
 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";

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";

package/.docs/raw/docs/ui/directive-text.mdx

@@ -1,6 +1,7 @@
 ---
 title: Directive Text
 description: Render mention directives as inline chips in user messages.
+platforms: ["react"]
 ---
 
 import { DirectiveTextSample } from "@/components/docs/samples/directive-text";

package/.docs/raw/docs/ui/file.mdx

@@ -1,6 +1,7 @@
 ---
 title: File
 description: Display file message parts with icon, name, size, and download button.
+platforms: ["react"]
 ---
 
 import { FileSample } from "@/components/docs/samples/file";

package/.docs/raw/docs/ui/image.mdx

@@ -1,6 +1,7 @@
 ---
 title: Image
 description: Display image message parts with preview, loading states, and fullscreen dialog.
+platforms: ["react"]
 ---
 
 import { ImageSample } from "@/components/docs/samples/image";

package/.docs/raw/docs/ui/markdown.mdx

@@ -1,6 +1,7 @@
 ---
 title: Markdown
 description: Display rich text with headings, lists, links, and code blocks.
+platforms: ["react"]
 ---
 
 import { MarkdownSample } from "@/components/docs/samples/markdown";
@@ -30,20 +31,7 @@ This adds a `/components/assistant-ui/markdown-text.tsx` file to your project, w
 
 Pass the `MarkdownText` component to the `MessagePrimitive.Parts` component
 
-```tsx twoslash title="/components/assistant-ui/thread.tsx" {1,7}
-// @filename: /components/assistant-ui/markdown-text.tsx
-import { FC } from "react";
-export const MarkdownText: FC = () => null;
-
-// @filename: ./thread.tsx
-import { FC } from "react";
-import { MessagePrimitive } from "@assistant-ui/react";
-import { Avatar, AvatarFallback } from "@/components/ui/avatar";
-
-const AssistantActionBar: FC = () => null;
-const BranchPicker: FC<{ className?: string }> = () => null;
-
-// ---cut---
+```tsx title="/components/assistant-ui/thread.tsx" {1,7}
 import { MarkdownText } from "@/components/assistant-ui/markdown-text";
 
 const AssistantMessage: FC = () => {

package/.docs/raw/docs/ui/mermaid.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Mermaid Diagrams"
 description: Render Mermaid diagrams in chat messages with streaming support.
+platforms: ["react"]
 ---
 
 import { MermaidSample } from "@/components/docs/samples/mermaid";

package/.docs/raw/docs/ui/message-timing.mdx

@@ -1,6 +1,7 @@
 ---
 title: Message Timing
 description: Display streaming performance stats — TTFT, total time, tok/s, and chunk count — as a badge with hover popover.
+platforms: ["react"]
 ---
 
 import { MessageTimingSample } from "@/components/docs/samples/message-timing";
@@ -65,9 +66,9 @@ The badge displays `totalStreamTime` inline and reveals a popover on hover with
 
 Timing accuracy depends on how your backend is connected.
 
-### assistant-stream (accurate)
+### Data Stream (accurate)
 
-When using `assistant-stream` on the backend, token counts come directly from the model's usage data sent in `step-finish` chunks. The `tokensPerSecond` metric is exact whenever your backend reports `outputTokens`.
+When using the [Data Stream](/docs/runtimes/custom/data-stream) protocol on the backend (via `assistant-stream`), token counts come directly from the model's usage data sent in `step-finish` chunks. The `tokensPerSecond` metric is exact whenever your backend reports `outputTokens`.
 
 ### Vercel AI SDK (estimated)
 

package/.docs/raw/docs/ui/model-selector.mdx

@@ -1,6 +1,7 @@
 ---
 title: ModelSelector
 description: Model picker with unified overlay positioning and runtime integration.
+platforms: ["react"]
 ---
 
 import { ModelSelectorSample } from "@/components/docs/samples/model-selector";