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

package/.docs/raw/docs/runtimes/custom/overview.mdx

@@ -1,71 +0,0 @@
----
-title: Custom Runtime
-description: Build a React chat UI for any AI backend with assistant-ui — four runtime patterns covering local state, REST, custom protocols, and external runtimes.
----
-
-If no [framework adapter](/docs/runtimes/pick-a-runtime) fits your backend, this section gives you four building blocks. All four are built on one of the two core runtimes; understanding the layering (see [architecture](/docs/runtimes/concepts/architecture)) makes the choice clear.
-
-## The four paths
-
-| Path | Layered on | Wire shape | Choose when |
-| --- | --- | --- | --- |
-| [`LocalRuntime`](/docs/runtimes/custom/local-runtime) | Core | You write a `ChatModelAdapter.run` function | The simplest case: you have a `fetch` call to make, want assistant-ui to handle state |
-| [`ExternalStoreRuntime`](/docs/runtimes/custom/external-store) | Core | You provide messages + callbacks | You already have state in redux, zustand, tanstack-query, or anywhere |
-| [`DataStream`](/docs/runtimes/custom/data-stream) | LocalRuntime + protocol | Your backend emits the data stream protocol | You want a thin message-stream contract, or you are migrating from AI SDK v4 |
-| [`AssistantTransport`](/docs/runtimes/custom/assistant-transport) | ExternalStoreRuntime + protocol | Your backend streams agent state snapshots | Your agent has rich internal state and you want it surfaced in the UI; or you need bidirectional commands |
-
-## Decision tree
-
-```text
-do you have an AI SDK / LangGraph / Google ADK / A2A backend?
-└── yes → use that framework adapter; you do not need this section
-└── no → continue
-    │
-    do you already have message state in redux / zustand / tanstack-query?
-    └── yes → ExternalStoreRuntime
-    └── no → continue
-        │
-        do you control the backend wire format?
-        └── yes, and i want simple fetch calls → LocalRuntime
-        └── yes, and i want to stream a structured agent state → AssistantTransport
-        └── no, the backend already speaks data stream protocol → DataStream
-```
-
-## What each path gives you
-
-**`LocalRuntime`** is the lowest-friction path. You implement one method (`run` or `async *run`). Branching, editing, regeneration, multi-thread, and adapter slots all work without extra code.
-
-**`ExternalStoreRuntime`** is the inverse: you own the message array and provide callbacks for each interaction. UI features turn on based on which callbacks you provide. Ideal when chat state is a first-class entity in your existing store.
-
-**`DataStream`** is `LocalRuntime` plus a wire protocol. You do not write a `ChatModelAdapter`; your backend emits a standardized stream of message parts and the runtime consumes it directly.
-
-**`AssistantTransport`** is `ExternalStoreRuntime` plus a state-streaming protocol. Instead of sending message parts, your backend sends snapshots of its full agent state. The UI is a stateless view on top of that state. Supports custom commands beyond the built-in `add-message` and `add-tool-result`.
-
-## Common building blocks
-
-Regardless of which path you pick, the [adapter](/docs/runtimes/concepts/adapters) and [thread](/docs/runtimes/concepts/threads) interfaces work the same way. Wire attachments, history, speech, feedback, suggestions, and multi-thread support through those shared contracts.
-
-## Next
-
-<Cards>
-  <Card
-    title="LocalRuntime"
-    description="Write a single ChatModelAdapter.run function."
-    href="/docs/runtimes/custom/local-runtime"
-  />
-  <Card
-    title="ExternalStoreRuntime"
-    description="Bring redux, zustand, tanstack-query, or your own state."
-    href="/docs/runtimes/custom/external-store"
-  />
-  <Card
-    title="Data Stream"
-    description="Standard message-stream protocol on top of LocalRuntime."
-    href="/docs/runtimes/custom/data-stream"
-  />
-  <Card
-    title="Assistant Transport"
-    description="Stream full agent state snapshots and bidirectional commands."
-    href="/docs/runtimes/custom/assistant-transport"
-  />
-</Cards>

package/.docs/raw/docs/runtimes/eve/overview.mdx

@@ -1,151 +0,0 @@
----
-title: Eve Runtime
-description: Connect an Eve agent to assistant-ui with useEveAgentRuntime, eve/next, durable sessions, streaming messages, and human-in-the-loop approvals.
----
-
-import { VercelIcon } from "@/components/icons/vercel";
-
-`@assistant-ui/eve` integrates assistant-ui with [Eve](https://eve.dev/), Vercel's filesystem-first framework for durable agents. It wraps Eve's `useEveAgent` hook and exposes it as an assistant-ui `ExternalStoreRuntime`, so Eve owns the session stream while assistant-ui renders messages, reasoning, dynamic tool calls, and approval requests.
-
-## When to use it
-
-Pick the Eve runtime when:
-
-- You want your agent implementation to live under `agent/` and be served by `eve/next`.
-- You want Eve sessions, continuation tokens, NDJSON streaming, and local development tooling.
-- You want assistant-ui to render Eve messages and human-in-the-loop tool approvals without writing a custom runtime adapter.
-
-## Architecture
-
-The Next.js app mounts Eve with `withEve()` and assistant-ui's registry transform with `withAui()`:
-
-```ts title="next.config.ts"
-import { withAui } from "@assistant-ui/next";
-import type { NextConfig } from "next";
-import { withEve } from "eve/next";
-
-const nextConfig: NextConfig = {};
-
-export default withEve(withAui(nextConfig));
-```
-
-On the client, `useEveAgentRuntime()` calls Eve's React hook and converts Eve message parts into assistant-ui thread messages:
-
-```tsx title="app/page.tsx"
-"use client";
-
-import { Thread } from "@/components/assistant-ui/thread";
-import { useEveAgentRuntime } from "@assistant-ui/eve";
-import { AssistantRuntimeProvider } from "@assistant-ui/react";
-
-export default function Home() {
-  const runtime = useEveAgentRuntime();
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-The `custom` bag of a per-turn `runConfig` is forwarded to Eve as
-`clientContext`, so `runConfig: { custom: { page: "/pricing" } }` arrives as
-`clientContext: { page: "/pricing" }`. An empty or absent bag is omitted, and
-every value must be JSON-serializable.
-
-Eve turns that object into a model context message, which is why the
-assistant-ui `custom` envelope is unwrapped: the envelope would put a literal
-`custom` key in the prompt. It is page or client context rather than run
-configuration, and it cannot select a model or change how the turn executes.
-Keep secrets, credentials, and personal data out of it, since the model reads
-it as message text.
-
-## Connector authorization
-
-When Eve pauses for connector authorization, the runtime emits an assistant
-data part named `authorization`. Its data includes `state`, `name`, and the
-available display fields such as `displayName`, `description`, `url`,
-`userCode`, `instructions`, and `expiresAt`. Completed parts may also include
-`outcome` and `reason`. `url` is present only when the connector supplied an
-`http(s)` address; the adapter drops other schemes so a renderer can link to it
-directly.
-
-The Eve template ships this renderer as `components/eve-authorization.tsx` and
-mounts it next to `<Thread />`. To add it to an existing app, register a data UI
-for the part and type it with the exported `EveAuthorizationData`:
-
-```tsx title="authorization-ui.tsx"
-import type { EveAuthorizationData } from "@assistant-ui/eve";
-import { makeAssistantDataUI } from "@assistant-ui/react";
-
-export const AuthorizationUI = makeAssistantDataUI<EveAuthorizationData>({
-  name: "authorization",
-  render: ({ data }) => (
-    <div>
-      {data.state === "required" ? (
-        <>
-          <p>{data.instructions ?? `Sign in to ${data.displayName ?? data.name}`}</p>
-          {data.userCode && <code>{data.userCode}</code>}
-          {data.url && <a href={data.url}>Continue to sign in</a>}
-        </>
-      ) : (
-        <p>{data.outcome ?? "Authorization completed"}</p>
-      )}
-    </div>
-  ),
-});
-```
-
-Mount `<AuthorizationUI />` inside the `AssistantRuntimeProvider` tree. The
-standard thread intentionally leaves unmatched data parts unrendered.
-
-## Requirements
-
-- Node.js 24 or higher.
-- React 18 or 19.
-- An Eve app mounted with `eve/next`.
-- A model credential for the model configured in `agent/agent.ts`.
-
-Eve's default gateway model ids route through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). Use `AI_GATEWAY_API_KEY` or Vercel OIDC, or configure a direct provider `LanguageModel`. For local development, a direct `LanguageModel` can also run on a ChatGPT Plus or Pro plan without any API key; see [ChatGPT Subscription](/docs/guides/chatgpt-subscription).
-
-## Install
-
-<PlatformTabs>
-<Tab value="React">
-
-<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/eve", "eve"]} />
-
-</Tab>
-<Tab value="React Native">
-
-Eve's browser hook talks to the Eve HTTP channel. There is not a React Native Eve runtime package yet.
-
-</Tab>
-<Tab value="React Ink">
-
-Use Eve's terminal UI directly for command-line agent sessions. There is not an Ink Eve runtime package yet.
-
-</Tab>
-</PlatformTabs>
-
-## Auth note
-
-Eve's built-in `eve` channel accepts localhost during development and trusted Vercel OIDC callers. It does not automatically admit browser users in production. Before deploying a public app, add `agent/channels/eve.ts` and wire the channel to your application auth.
-
-## Next
-
-<Cards>
-  <Card
-    icon={<VercelIcon width={20} height={20} />}
-    title="Quickstart"
-    description="Scaffold the Eve template or add Eve to an existing assistant-ui app."
-    href="/docs/runtimes/eve/quickstart"
-  />
-  <Card
-    icon={<VercelIcon width={20} height={20} />}
-    title="Eve channel"
-    description="Routes, auth, session creation, and stream events in the default Eve HTTP channel."
-    href="https://eve.dev/docs/channels/eve"
-  />
-</Cards>

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

@@ -1,192 +0,0 @@
----
-title: Quickstart
-description: Template, Eve CLI, and manual setup paths to a working Eve agent chat in assistant-ui.
----
-
-Three paths to a running Eve-powered assistant-ui app. The template is fastest, `eve add` drops assistant-ui into an Eve app you already have, and the manual path is what you adapt when integrating into an existing Next.js project.
-
-## From the template
-
-<PlatformTabs>
-<Tab value="React">
-
-```sh
-npx create-assistant-ui@latest -t eve my-app
-cd my-app
-```
-
-Set a model credential:
-
-```sh title=".env.local"
-AI_GATEWAY_API_KEY=your-api-key
-```
-
-```sh
-npm run dev
-```
-
-Open http://localhost:3000 and send a message. The template includes:
-
-- `agent/agent.ts` for Eve runtime config.
-- `agent/instructions.md` for the always-on system prompt.
-- `next.config.ts` with `withEve(withAui(nextConfig))`.
-- `app/page.tsx` with `useEveAgentRuntime()`.
-
-</Tab>
-<Tab value="React Native">
-
-There is not a React Native Eve template yet.
-
-</Tab>
-<Tab value="React Ink">
-
-Use Eve's terminal UI directly for command-line agent sessions.
-
-</Tab>
-</PlatformTabs>
-
-## With the Eve CLI
-
-For an Eve app that already exists, register the assistant-ui registry once and install the chat page from it:
-
-```sh
-eve registry add @assistant-ui=https://r.assistant-ui.com/{name}.json
-eve add @assistant-ui/eve-chat --overwrite
-```
-
-`eve registry add` records the namespace in your `package.json`. `eve add` then installs `@assistant-ui/react` and `@assistant-ui/eve`, writes `app/page.tsx`, and writes the thread component together with everything it imports into `components/assistant-ui` and `components/ui`. It expects an Eve app that carries the Next.js Web Chat scaffold, because the installed files import `@/lib/utils` through the `@/*` alias that `eve init --channel-web-nextjs` sets up.
-
-`--overwrite` is global rather than per file. It is what lets the item replace the scaffold's own `app/page.tsx`, and it also replaces any `components/assistant-ui` or `components/ui` file already in the project, including `avatar`, `button`, `collapsible`, `dialog`, and `tooltip`, so install on a clean tree and read the diff before keeping it. A plain `eve add` skips every pre-existing file instead, which leaves `app/page.tsx` untouched. Inspect an item before installing it with `eve registry view @assistant-ui/eve-chat`, and browse the rest of the registry with `eve registry list --registry @assistant-ui`.
-
-That namespace serves the Radix flavor, which matches the shadcn components in Eve's Next.js scaffold. Point it at `https://r.assistant-ui.com/base/{name}.json` instead for a Base UI project.
-
-The Eve CLI writes registry files without editing CSS, so add the styles the reasoning and tool components animate with to `app/globals.css` yourself:
-
-```css title="app/globals.css"
-@import "tw-shimmer";
-
-@custom-variant data-open (&:where([data-state="open"], [data-open]:not([data-open="false"])));
-@custom-variant data-closed (&:where([data-state="closed"], [data-closed]:not([data-closed="false"])));
-
-@theme inline {
-  @keyframes collapsible-down {
-    from {
-      height: 0;
-    }
-    to {
-      height: var(
-        --radix-collapsible-content-height,
-        var(--collapsible-panel-height, auto)
-      );
-    }
-  }
-  @keyframes collapsible-up {
-    from {
-      height: var(
-        --radix-collapsible-content-height,
-        var(--collapsible-panel-height, auto)
-      );
-    }
-    to {
-      height: 0;
-    }
-  }
-}
-```
-
-## Manual setup in an existing app
-
-<Steps>
-<Step>
-
-### Install dependencies
-
-<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/eve", "eve"]} />
-
-</Step>
-<Step>
-
-### Mount Eve in Next.js
-
-```ts title="next.config.ts"
-import { withAui } from "@assistant-ui/next";
-import type { NextConfig } from "next";
-import { withEve } from "eve/next";
-
-const nextConfig: NextConfig = {};
-
-export default withEve(withAui(nextConfig));
-```
-
-</Step>
-<Step>
-
-### Add an Eve agent
-
-```ts title="agent/agent.ts"
-import { defineAgent } from "eve";
-
-export default defineAgent({
-  model: "anthropic/claude-sonnet-4.6",
-});
-```
-
-```md title="agent/instructions.md"
-You are a concise assistant. Use tools when they are available.
-```
-
-</Step>
-<Step>
-
-### Create the runtime
-
-```tsx title="app/page.tsx"
-"use client";
-
-import { Thread } from "@/components/assistant-ui/thread";
-import { useEveAgentRuntime } from "@assistant-ui/eve";
-import { AssistantRuntimeProvider } from "@assistant-ui/react";
-
-export default function Home() {
-  const runtime = useEveAgentRuntime();
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Step>
-</Steps>
-
-## Production auth
-
-The default Eve channel is convenient for local development. For production browser users, define `agent/channels/eve.ts` and replace the default auth policy with your app's auth.
-
-```ts title="agent/channels/eve.ts"
-import { localDev, vercelOidc } from "eve/channels/auth";
-import { eveChannel } from "eve/channels/eve";
-
-export default eveChannel({
-  auth: [localDev(), vercelOidc()],
-});
-```
-
-That example keeps the development defaults. Swap in your Clerk, Auth.js, OIDC, or JWT verification before going live.
-
-## Next
-
-<Cards>
-  <Card
-    title="Eve overview"
-    description="Architecture, requirements, and runtime behavior."
-    href="/docs/runtimes/eve/overview"
-  />
-  <Card
-    title="API reference"
-    description="useEveAgentRuntime and message conversion helpers."
-    href="/docs/api-reference/integrations/eve"
-  />
-</Cards>

package/.docs/raw/docs/runtimes/google-adk/api.mdx

@@ -1,256 +0,0 @@
----
-title: API reference
-description: createAdkStream, server helpers, session adapter, threads, message editing.
----
-
-Reference for the runtime's wire-up surface. Start with [quickstart](/docs/runtimes/google-adk/quickstart) if you have not already.
-
-## createAdkStream
-
-Creates an `AdkStreamCallback` that connects to an ADK endpoint via SSE. Supports two modes.
-
-**proxy mode** — POST to your own API route:
-
-```ts
-import { createAdkStream } from "@assistant-ui/react-google-adk";
-
-const stream = createAdkStream({ api: "/api/chat" });
-```
-
-**direct mode** — connect directly to an ADK server:
-
-```ts
-const stream = createAdkStream({
-  api: "http://localhost:8000",
-  appName: "my-app",
-  userId: "user-1",
-});
-```
-
-| Option | Type | Description |
-| --- | --- | --- |
-| `api` | `string` | URL to POST to (proxy route or ADK server base URL). |
-| `appName` | `string?` | ADK app name (enables direct mode when set). |
-| `userId` | `string?` | ADK user ID (required with `appName`). |
-| `headers` | `Record<string, string>` or `() => ...` | Static or dynamic request headers. |
-
-## Direct ADK server connection
-
-When connecting directly to an ADK server (without a proxy API route), use `createAdkSessionAdapter` to back your thread list with ADK sessions:
-
-```tsx
-import {
-  useAdkRuntime,
-  createAdkStream,
-  createAdkSessionAdapter,
-} from "@assistant-ui/react-google-adk";
-
-const ADK_URL = "http://localhost:8000";
-
-const { adapter, load, artifacts } = createAdkSessionAdapter({
-  apiUrl: ADK_URL,
-  appName: "my-app",
-  userId: "user-1",
-});
-
-const runtime = useAdkRuntime({
-  stream: createAdkStream({
-    api: ADK_URL,
-    appName: "my-app",
-    userId: "user-1",
-  }),
-  sessionAdapter: adapter,
-  load,
-});
-```
-
-The session adapter maps ADK sessions to assistant-ui threads:
-
-- **`adapter`** is a `RemoteThreadListAdapter` that uses ADK's session REST API for thread CRUD.
-- **`load`** reconstructs messages from session events via `AdkEventAccumulator`.
-- **`artifacts`** are functions to fetch, list, and delete session artifacts (see [hooks → artifacts](/docs/runtimes/google-adk/hooks#artifacts)).
-
-| Option | Type | Description |
-| --- | --- | --- |
-| `apiUrl` | `string` | ADK server base URL. |
-| `appName` | `string` | ADK app name. |
-| `userId` | `string` | ADK user ID. |
-| `headers` | `Record<string, string>` or `() => ...` | Static or dynamic request headers. |
-
-## Server helpers
-
-Server helpers live under the `/server` subpath:
-
-```ts
-import {
-  createAdkApiRoute,
-  adkEventStream,
-  parseAdkRequest,
-  toAdkContent,
-} from "@assistant-ui/react-google-adk/server";
-```
-
-### createAdkApiRoute
-
-One-liner API route handler that combines request parsing and SSE streaming:
-
-```ts
-export const POST = createAdkApiRoute({
-  runner,
-  userId: "default-user",
-  sessionId: (req) =>
-    new URL(req.url).searchParams.get("sessionId") ?? "default",
-});
-```
-
-Both `userId` and `sessionId` accept a static string or a function `(req: Request) => string` for dynamic resolution.
-
-### adkEventStream
-
-Converts an `AsyncGenerator<Event>` from ADK's `Runner.runAsync()` into an SSE `Response`. Sends an initial `:ok` comment to keep connections alive through proxies.
-
-```ts
-const events = runner.runAsync({ userId, sessionId, newMessage });
-return adkEventStream(events);
-```
-
-### parseAdkRequest and toAdkContent
-
-Lower-level helpers for custom API routes. `parseAdkRequest` parses incoming requests; `toAdkContent` converts to ADK's `Content` format. Supports user messages, tool results, `stateDelta`, `checkpointId`, and multimodal content:
-
-```ts
-const parsed = await parseAdkRequest(req);
-// parsed.type is "message" or "tool-result"
-// parsed.config contains runConfig, checkpointId
-// parsed.stateDelta contains session state changes
-
-const newMessage = toAdkContent(parsed);
-const events = runner.runAsync({
-  userId,
-  sessionId,
-  newMessage,
-  stateDelta: parsed.stateDelta,
-});
-return adkEventStream(events);
-```
-
-## Thread management
-
-Three options, picked by what you want to own. See [threads](/docs/runtimes/concepts/threads) for the general model.
-
-### ADK session adapter
-
-Use `createAdkSessionAdapter` to persist threads via ADK's session API; see [Direct ADK server connection](#direct-adk-server-connection) above.
-
-### Custom thread management
-
-```ts
-const runtime = useAdkRuntime({
-  stream: createAdkStream({ api: "/api/chat" }),
-  create: async () => {
-    const sessionId = await createSession();
-    return { externalId: sessionId };
-  },
-  load: async (externalId) => {
-    const history = await loadSession(externalId);
-    return { messages: history };
-  },
-  delete: async (externalId) => {
-    await deleteSession(externalId);
-  },
-});
-```
-
-### Cloud persistence
-
-For persistent thread history via assistant-cloud, pass a `cloud` instance:
-
-```ts
-const runtime = useAdkRuntime({
-  cloud, // see "AssistantCloud" in /docs/runtimes/concepts/threads
-  stream: createAdkStream({ api: "/api/chat" }),
-});
-```
-
-## Message editing and regeneration
-
-Provide a `getCheckpointId` callback to enable edit and regenerate buttons:
-
-```ts
-const runtime = useAdkRuntime({
-  stream: createAdkStream({ api: "/api/chat" }),
-  getCheckpointId: async (threadId, parentMessages) => {
-    // Resolve checkpoint ID for server-side forking
-    return checkpointId;
-  },
-});
-```
-
-When `getCheckpointId` is provided:
-
-- **Edit buttons** appear on user messages.
-- **Regenerate buttons** appear on assistant messages.
-
-The resolved `checkpointId` is passed to your `stream` callback via `config.checkpointId`.
-
-<Callout type="info">
-Without `getCheckpointId`, edit and regenerate buttons will not appear. This is intentional; truncating client-side messages without forking from the correct server-side checkpoint would produce incorrect state.
-</Callout>
-
-## Event handlers
-
-Listen to streaming events:
-
-```ts
-const runtime = useAdkRuntime({
-  stream: createAdkStream({ api: "/api/chat" }),
-  eventHandlers: {
-    onError: (error) => {
-      console.error("Stream error:", error);
-    },
-    onAgentTransfer: (toAgent) => {
-      console.log("Agent transferred to:", toAgent);
-    },
-    onCustomEvent: (key, value) => {
-      // Fired for each entry in event.customMetadata
-      console.log("Custom metadata:", key, value);
-    },
-  },
-});
-```
-
-## RunConfig and stateDelta
-
-Pass `AdkRunConfig` to control agent behavior, and `stateDelta` to mutate session state along with messages:
-
-```ts
-import { useAdkSend } from "@assistant-ui/react-google-adk";
-
-const send = useAdkSend();
-
-send(messages, {
-  runConfig: {
-    streamingMode: "sse",
-    maxLlmCalls: 10,
-    pauseOnToolCalls: true,
-  },
-  stateDelta: { taskId: "abc", mode: "verbose" },
-});
-```
-
-`stateDelta` maps to ADK's `stateDelta` parameter on `/run_sse`.
-
-## Next
-
-<Cards>
-  <Card
-    title="Hooks"
-    description="Tool confirmations, auth, input requests, artifacts, escalation, metadata."
-    href="/docs/runtimes/google-adk/hooks"
-  />
-  <Card
-    title="Threads"
-    description="General model for multi-thread support across runtimes."
-    href="/docs/runtimes/concepts/threads"
-  />
-</Cards>