@assistant-ui/mcp-docs-server 0.2.2 → 0.3.0

package/.docs/raw/docs/runtimes/opencode/quickstart.mdx

@@ -1,119 +0,0 @@
----
-title: Quickstart
-description: Minimal useOpenCodeRuntime setup against a local OpenCode server.
----
-
-Three steps to a working chat against a local OpenCode server. Assumes you have OpenCode running; if not, follow [opencode.ai](https://opencode.ai/) to install and start the server first.
-
-<Steps>
-<Step>
-
-### Wire up the runtime provider
-
-```tsx title="app/MyRuntimeProvider.tsx"
-"use client";
-
-import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useOpenCodeRuntime } from "@assistant-ui/react-opencode";
-
-export function MyRuntimeProvider({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const runtime = useOpenCodeRuntime({
-    baseUrl: "http://localhost:4096",
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-`baseUrl` defaults to `http://localhost:4096` if omitted.
-
-</Step>
-<Step>
-
-### Render the Thread
-
-```tsx title="app/page.tsx"
-import { Thread } from "@assistant-ui/react";
-import { MyRuntimeProvider } from "./MyRuntimeProvider";
-
-export default function Page() {
-  return (
-    <MyRuntimeProvider>
-      <Thread />
-    </MyRuntimeProvider>
-  );
-}
-```
-
-</Step>
-<Step>
-
-### Set up UI components
-
-Follow the [UI Components guide](/docs/ui/thread) to wire up the Thread, composer, and supporting primitives.
-
-</Step>
-</Steps>
-
-The runtime opens an SSE event stream against the OpenCode server, listens for session and message events, and projects them into the thread. Each OpenCode session corresponds to one thread; the thread list reflects sessions on the server.
-
-## Default model and agent
-
-Pin a default model or agent when starting new sessions:
-
-```tsx
-const runtime = useOpenCodeRuntime({
-  baseUrl: "http://localhost:4096",
-  defaultModel: { providerID: "anthropic", modelID: "claude-sonnet-4-6" },
-  defaultAgent: "coder",
-});
-```
-
-## Bring your own client
-
-If you need a pre-configured `OpencodeClient` (e.g. for auth headers), pass it directly:
-
-```tsx
-import { createOpencodeClient } from "@assistant-ui/react-opencode";
-
-const client = createOpencodeClient({
-  baseUrl: "http://localhost:4096",
-  // additional client config...
-});
-
-const runtime = useOpenCodeRuntime({ client });
-```
-
-## Resuming a session
-
-Pass `initialSessionId` to open the runtime against an existing session on first load:
-
-```tsx
-const runtime = useOpenCodeRuntime({
-  baseUrl: "http://localhost:4096",
-  initialSessionId: "ses_abc123",
-});
-```
-
-## Next
-
-<Cards>
-  <Card
-    title="Hooks"
-    description="Permissions, questions, session state, runtime extras."
-    href="/docs/runtimes/opencode/hooks"
-  />
-  <Card
-    title="Pick a runtime"
-    description="Compare OpenCode to other runtime options."
-    href="/docs/runtimes/pick-a-runtime"
-  />
-</Cards>

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

@@ -1,133 +0,0 @@
----
-title: Picking a runtime
-description: Decision guide for choosing the right runtime, by framework or by feature.
----
-
-import { A2AIcon } from "@/components/icons/a2a";
-import { AdkIcon } from "@/components/icons/adk";
-import { AguiIcon } from "@/components/icons/agui";
-import { ClaudeIcon } from "@/components/icons/claude";
-import { CloudflareIcon } from "@/components/icons/cloudflare";
-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";
-
-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.
-
-## Lens 1: by framework
-
-If you are already using one of these frameworks, the choice is mechanical.
-
-### First-party adapters
-
-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="useChat hook, streaming, tools, attachments, multi-step. v6 current; v5 / v4 legacy."
-    href="/docs/runtimes/ai-sdk/overview"
-  />
-  <Card
-    icon={<VercelIcon width={20} height={20} />}
-    title="Eve"
-    description="Filesystem-first durable agents with eve/next, sessions, NDJSON streaming, and HITL."
-    href="/docs/runtimes/eve/overview"
-  />
-  <Card
-    icon={<LangGraphIcon width={20} height={20} className="text-[#1C3C3C] dark:text-[#5b9595]" />}
-    title="LangGraph"
-    description="Direct integration with @langchain/langgraph-sdk. Subgraph events, UI messages, message metadata."
-    href="/docs/runtimes/langgraph/overview"
-  />
-  <Card
-    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
-    icon={<AdkIcon 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/overview"
-  />
-  <Card
-    icon={<A2AIcon 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/overview"
-  />
-  <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/overview"
-  />
-  <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/overview"
-    />
-  </PlatformOnly>
-</Cards>
-
-<PlatformOnly platforms={["react"]}>
-
-### Integration guides
-
-For frameworks without a dedicated adapter, these wiring guides route through an existing runtime: an adapter above, or one of the core runtimes.
-
-  <Cards>
-    <Card
-      icon={<CloudflareIcon width={20} height={20} />}
-      title="Cloudflare Agents"
-      description="Stateful agents on Durable Objects with WebSocket streaming. Wired through the Vercel AI SDK runtime."
-      href="/docs/integrations/frameworks/cloudflare-agents/overview"
-    />
-    <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"
-    />
-    <Card
-      icon={<ClaudeIcon width={20} height={20} className="text-[#D97757]" />}
-      title="Claude Managed Agents"
-      description="Anthropic-hosted agent sessions. Wired through the external store runtime: event-log replay, approval gates, sessions as threads."
-      href="/docs/runtimes/claude-managed-agents"
-    />
-  </Cards>
-
-</PlatformOnly>
-
-## Lens 2: by needs
-
-If you do not know your framework yet, or your backend is custom, pick by what you need:
-
-| 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) |
-
-If none of the framework adapters fits, start at [custom backend](/docs/runtimes/custom/overview).
-
-## Shared concepts
-
-Regardless of which runtime you pick, four ideas apply across the board.
-
-- **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 repo](https://github.com/assistant-ui/assistant-ui).
-</Callout>

package/.docs/raw/docs/tools/a2ui.mdx

@@ -1,107 +0,0 @@
----
-title: A2UI over AG-UI
-description: Render A2UI surfaces from AG-UI activity snapshots as generative UI, using the community a2ui-surface convention.
-platforms: ["react"]
----
-
-[A2UI](https://a2ui.org/) is a declarative generative UI protocol: the agent streams surface operations (create a surface, upsert components, update a data model) and the host renders them from a pre-approved component catalog, with no code over the wire. The AG-UI ecosystem carries A2UI as `ACTIVITY_SNAPSHOT` events with `activityType: "a2ui-surface"` and the operations under `content.a2ui_operations`; this is the convention emitted by [`@ag-ui/a2ui-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2ui-middleware).
-
-`useAgUiRuntime` consumes these snapshots natively. Each surface becomes one tool-call part with `toolCallId` `a2ui:<surfaceId>` and `toolName` `"present"`, whose args are the converted generative UI spec, so surfaces render through the same path as the [`present` frontend tool](/docs/tools/generative-ui). Snapshots with any other `activityType` are ignored, and the MCP Apps activity path is unaffected.
-
-## Wire contract
-
-A backend paints or updates a surface by emitting an activity snapshot on the AG-UI stream:
-
-```json
-{
-  "type": "ACTIVITY_SNAPSHOT",
-  "messageId": "a2ui-surface-call_1",
-  "activityType": "a2ui-surface",
-  "replace": true,
-  "content": {
-    "a2ui_operations": [
-      { "version": "v0.9", "createSurface": { "surfaceId": "s1" } },
-      {
-        "version": "v0.9",
-        "updateComponents": {
-          "surfaceId": "s1",
-          "components": [
-            { "id": "root", "component": "Card", "title": "Order", "children": ["total"] },
-            { "id": "total", "component": "Text", "text": { "path": "/total" } }
-          ]
-        }
-      },
-      {
-        "version": "v0.9",
-        "updateDataModel": { "surfaceId": "s1", "path": "/", "contents": { "total": "$42" } }
-      }
-    ]
-  }
-}
-```
-
-- A snapshot with `replace: true` (the schema default) rebuilds that `messageId`'s surface state from the operations it carries. `replace: false` means the snapshot is ignored when that `messageId` has already been seen, matching the AG-UI event spec. The middleware always emits `replace: true`.
-- Surfaces are keyed by the `surfaceId` inside the operations, not by `messageId`. Multiple snapshots that share a `messageId` update their surfaces in place, and the synthesized part keeps its `toolCallId`, so the rendered surface updates without duplicating parts.
-- Component trees use the A2UI adjacency-list model: nodes reference children by id, the root node has id `root`, and props of shape `{ "path": "/x/y" }` are JSON Pointer bindings resolved against the surface data model. Both v0.9 and v1.0 operation payloads are accepted, including the v1.0 inline `components` and `dataModel` on `createSurface`.
-- Lifecycle snapshots that carry a `status` (such as `"building"`) but no `a2ui_operations` are tolerated and produce no part until operations arrive. A `deleteSurface` operation removes the surface's part.
-- The `a2ui:` tool-call id prefix is reserved for synthesized surface parts: they are client-side render artifacts and are excluded from the history sent back to the agent, so genuine agent tool calls must not use ids starting with `a2ui:`.
-
-## Quick start
-
-Register the `present` frontend tool from `@assistant-ui/react-generative-ui`; incoming surfaces then render with the default vocabulary:
-
-```tsx
-import {
-  JSONGenerativeUI,
-  defaultGenerativeUILibrary,
-} from "@assistant-ui/react-generative-ui";
-
-const generative = new JSONGenerativeUI({
-  library: defaultGenerativeUILibrary,
-});
-
-const toolkit = {
-  present: generative.present({ display: "standalone" }),
-};
-```
-
-Pass the toolkit to your assistant as on the [Generative UI](/docs/tools/generative-ui) page; no other configuration is needed on `useAgUiRuntime`.
-
-## Actions
-
-`Button` nodes dispatch `$action` objects with type `"a2ui:action"` through the action registry. Wire the registry to `useAgUiSendA2uiAction` inside a component; the hook returns a stable function, so the toolkit can be memoized on it:
-
-```tsx
-import { useMemo } from "react";
-import { useAgUiSendA2uiAction } from "@assistant-ui/react-ag-ui";
-import {
-  JSONGenerativeUI,
-  createActionRegistry,
-  defaultGenerativeUILibrary,
-} from "@assistant-ui/react-generative-ui";
-
-function useA2uiToolkit() {
-  const sendA2uiAction = useAgUiSendA2uiAction();
-  return useMemo(() => {
-    const generative = new JSONGenerativeUI({
-      library: defaultGenerativeUILibrary,
-      actions: createActionRegistry({
-        "a2ui:action": ({ payload }) => sendA2uiAction(payload),
-      }),
-    });
-    return { present: generative.present({ display: "standalone" }) };
-  }, [sendA2uiAction]);
-}
-```
-
-Sending an action triggers a run with no new user message, and the agent receives it as `forwardedProps.a2uiAction.userAction`, the convention `@ag-ui/a2ui-middleware` consumes. The action rides exactly one run; the `type` field is stripped and a `timestamp` is added when absent.
-
-The middleware turns the action into a synthetic `log_a2ui_event` tool-call pair that is never declared in `input.tools`; a backend that validates tool calls against the declared tool list will reject it.
-
-## Component mapping
-
-The converter maps the A2UI basic catalog onto the default generative UI vocabulary: `Text` becomes `Markdown` (`h1` to `h6` variants become `Header`, `caption` becomes `Caption`), `Column` becomes `Col`, `TextField` becomes `Input` (the control name is derived from the last segment of its binding path), `CheckBox` becomes `Checkbox`, and `Image`, `Row`, `Card`, `Divider`, `Button` map one to one. A node with template children expands into a `ListView` over the bound list. `Button` actions become `$action` objects with type `"a2ui:action"` carrying the action name, `surfaceId`, and `sourceComponentId`, which is how your action registry receives them. Unknown components and operations are skipped with a debug warning, and conversion is bounded (depth 32, 100 template items, 5000 nodes) so a malformed stream cannot hang the client.
-
-## Limitations
-
-- The upstream middleware currently emits v0.9 operation payloads; the renderer accepts v0.9 and v1.0 shapes.

package/.docs/raw/docs/tools/backend.mdx

@@ -1,147 +0,0 @@
----
-title: Backend Tools
-description: Wire assistant-ui toolkits into your server with the AI SDK — AISDKToolkit, frontendTools, mixing client and server tools, and multi-modal results.
-platforms: ["react"]
----
-
-A tool is only callable if the **model** knows about it, and the model is configured on your server. This page covers wiring a toolkit into an AI SDK route handler: exposing your generative toolkit, receiving client-defined tools, mixing the two, and round-tripping multi-modal results.
-
-For authoring tools, see [Defining Tools](/docs/tools/defining-tools). For MCP servers, see [MCP](/docs/tools/mcp).
-
-## The request body
-
-`@assistant-ui/react-ai-sdk` posts `{ messages, system, tools }` to your route. `tools` is the map of **frontend** tools the client serialized for this request (the model needs their schemas to call them, even though they run in the browser):
-
-```ts
-import type { FrontendTools } from "@assistant-ui/react-ai-sdk";
-
-const {
-  messages,
-  system,
-  tools,
-}: {
-  messages: UIMessage[];
-  system?: string;
-  tools?: FrontendTools;
-} = await req.json();
-```
-
-## Generative toolkits: `AISDKToolkit`
-
-When you author tools in a [`"use generative"` file](/docs/tools/defining-tools#quick-start-use-generative), the same import resolves to the **server build** inside a route handler — schema plus any backend `execute`, with renderers stripped. Wrap it in an `AISDKToolkit` and call `.tools()` with the uploaded `tools`:
-
-```ts title="app/api/chat/route.ts"
-import { AISDKToolkit } from "@assistant-ui/react-ai-sdk";
-import { streamText, convertToModelMessages, type UIMessage } from "ai";
-import { openai } from "@ai-sdk/openai";
-import toolkit from "../../toolkit";
-
-const aiToolkit = new AISDKToolkit({ toolkit });
-
-export async function POST(req: Request) {
-  const { messages, system, tools } = await req.json();
-
-  const result = streamText({
-    model: openai("gpt-5.6-luna"),
-    system,
-    messages: await convertToModelMessages(messages),
-    tools: await aiToolkit.tools({ frontend: tools }),
-  });
-
-  return result.toUIMessageStreamResponse();
-}
-```
-
-`AISDKToolkit.tools()` registers every toolkit tool with the model using its schema, wires the backend `execute` where the server build carries one, and merges in the uploaded frontend tools. A server `execute` wins over an uploaded entry of the same name. Frontend and human tools (no server `execute`) are exposed schema-only and left for the client and the user to fulfill.
-
-<Callout type="info">
-  If your toolkit spreads in MCP server tools (`defineMcpToolkit`), `.tools()`
-  also opens those connections. A module-scope `aiToolkit` pools them across
-  requests; see [MCP](/docs/tools/mcp) for the connection lifecycle and when to
-  call `aiToolkit.close()`. The older
-  `generativeTools({ toolkit, frontendTools })` is deprecated, MCP-less, and
-  superseded by `AISDKToolkit`.
-</Callout>
-
-## Client-defined tools: `frontendTools`
-
-If a toolkit cannot go through the generative compiler, the AI SDK adapter still
-serializes browser-executed tools into the request `tools`. Convert them to the
-AI SDK shape with `frontendTools` and spread your own server tools alongside:
-
-```ts title="app/api/chat/route.ts"
-import { frontendTools } from "@assistant-ui/react-ai-sdk";
-import { streamText, convertToModelMessages, tool, zodSchema } from "ai";
-import { openai } from "@ai-sdk/openai";
-import { z } from "zod";
-
-export async function POST(req: Request) {
-  const { messages, tools } = await req.json();
-
-  const result = streamText({
-    model: openai("gpt-5.6-luna"),
-    messages: await convertToModelMessages(messages),
-    tools: {
-      ...frontendTools(tools ?? {}),
-      query_database: tool({
-        description: "Query the application database.",
-        inputSchema: zodSchema(z.object({ query: z.string() })),
-        execute: async ({ query }) => db.query(query),
-      }),
-    },
-  });
-
-  return result.toUIMessageStreamResponse();
-}
-```
-
-`AISDKToolkit.tools()` calls `frontendTools` for you under the hood; reach for
-`frontendTools` directly when you're not on the generative build.
-
-<Callout type="tip">
-  `toToolsJSONSchema` emits the uploaded tools in alphabetical order, so two
-  renders that register the same set produce byte-identical request bodies —
-  which keeps provider prompt caches stable across renders.
-</Callout>
-
-## Multi-modal results
-
-When a tool declares [`toModelOutput`](/docs/tools/defining-tools#multi-modal-tool-results), frontend tool results round-trip through the AI SDK chat protocol back to your route on the next turn. For `toModelOutput` to fire on those round-tripped results, pass the tool registry to `convertToModelMessages` as well — the [same pattern the AI SDK documents](https://ai-sdk.dev/docs/reference/ai-sdk-ui/convert-to-model-messages#multi-modal-tool-responses) for any multi-modal tool response:
-
-```ts
-const aiSDKTools = { ...frontendTools(tools ?? {}) };
-
-const result = streamText({
-  model,
-  // Pass tools to BOTH calls so prior results are projected via toModelOutput.
-  messages: await convertToModelMessages(messages, { tools: aiSDKTools }),
-  tools: aiSDKTools,
-});
-```
-
-Skip the `{ tools }` argument and prior results are sent as a plain JSON blob — `toModelOutput` is silently ignored. Tools without `toModelOutput` are unaffected either way.
-
-<Callout type="warn">
-  **Read/write compatibility for persisted threads.** When `toModelOutput` is
-  set, the runtime persists the AI SDK output as
-  `{ __aui_modelContent, value }`. Upgrade every reader before any writer starts
-  producing `toModelOutput`; older readers treat the whole envelope as the
-  `result` and break that tool's `render`. Don't return objects whose top-level
-  key is literally `__aui_modelContent` from any `execute`.
-</Callout>
-
-## Multi-step tool calls
-
-To let the model see a frontend tool's result and continue, configure the runtime to send back automatically when the last assistant message is complete with tool calls:
-
-```tsx
-import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
-
-const runtime = useChatRuntime({
-  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
-});
-```
-
-`useChatRuntime()` targets `/api/chat` by default. To point at a different endpoint or customize requests, see [Custom transport](/docs/runtimes/ai-sdk/v7#custom-transport).
-
-For the full AI SDK v7 backend setup — history persistence, reasoning, server-side approvals — see the [AI SDK v7 guide](/docs/runtimes/ai-sdk/v7).