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

package/.docs/raw/docs/integrations/frameworks/cloudflare-agents.mdx

@@ -1,283 +0,0 @@
----
-title: Cloudflare Agents
-description: Wire Cloudflare's stateful agent framework into a React chat UI with assistant-ui via the standard AI SDK runtime. WebSocket transport, server-side persistence, tool calling, all preserved.
-platforms: ["react"]
----
-
-import { CloudflareIcon } from "@/components/icons/cloudflare";
-import { VercelIcon } from "@/components/icons/vercel";
-
-[Cloudflare Agents](https://developers.cloudflare.com/agents/) is Cloudflare's framework for stateful AI agents that run on Durable Objects at the edge. Each agent owns its own SQLite-backed message history, exposes a WebSocket channel for low-latency streaming, and can call tools (server-side or client-side).
-
-<Callout type="info">
-This is an integration guide, not a runtime adapter. assistant-ui does not ship a `@assistant-ui/react-cloudflare-agents` package. `@cloudflare/ai-chat`'s `useAgentChat` returns a structural extension of the AI SDK's `useChat`, so the existing [AI SDK runtime](/docs/runtimes/ai-sdk/v7) consumes it directly.
-</Callout>
-
-## Architecture
-
-Cloudflare Agents handles the server half: a Durable Object subclasses `AIChatAgent` from `@cloudflare/ai-chat`, owns the message history, and streams responses back over a WebSocket. `@cloudflare/ai-chat/react`'s `useAgentChat` hook wraps that WebSocket and exposes the same `messages`, `sendMessage`, `regenerate`, `status`, `stop`, `setMessages`, `addToolOutput` surface that the AI SDK's `useChat` does, plus a few Cloudflare-specific extras (`clearHistory`, `isServerStreaming`, `isToolContinuation`).
-
-assistant-ui handles the client half. `useAISDKRuntime` from [`@assistant-ui/ai-sdk`](/docs/runtimes/ai-sdk/v7) reads exactly those AI SDK methods off whatever you pass in, so feeding it `useAgentChat`'s return value yields a fully-featured runtime: streaming, tool calling, edit, reload, history import and export, attachments, suggestions.
-
-Shared adapters (attachments, speech, feedback, history) work the same way as described in [adapters](/docs/runtimes/concepts/adapters). Multi-thread support needs a [custom thread list](/docs/runtimes/concepts/threads) wired around `useAISDKRuntime`; [AssistantCloud](/docs/cloud) integrates via `useChatRuntime` (which constructs its own `useChat` internally) and is not compatible with the `useAgentChat` wiring shown here.
-
-## Requirements
-
-- A Cloudflare account with Workers enabled and `wrangler` installed.
-- A frontend project (Next.js or any other AI-SDK-compatible React app).
-- Model API keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) configured as Worker secrets.
-
-## Setup
-
-The setup has two halves. Steps 1 to 4 happen in the **Worker** project (Cloudflare side); steps 5 to 7 happen in a **separate assistant-ui frontend**. You'll have two dev processes running by the end: `wrangler dev` for the Worker, and your frontend's dev server.
-
-<Steps>
-
-<Step>
-
-### Scaffold the Worker project
-
-```sh
-npm create cloudflare@latest my-agent -- --type=hello-world --ts
-cd my-agent
-```
-
-Add the Cloudflare Agents packages and the AI SDK:
-
-<InstallCommand npm={["agents@0.12.4", "@cloudflare/ai-chat@0.7.0", "ai@latest", "@ai-sdk/openai@latest"]} />
-
-The two Cloudflare packages above are pinned to exact versions because `agents` and `@cloudflare/ai-chat` are pre-1.0 and ship breaking changes between minor releases. See [version stability](#version-stability) below before bumping them.
-
-</Step>
-
-<Step>
-
-### Define the agent
-
-`AIChatAgent` already implements message persistence, streaming protocol, and WebSocket plumbing. Override `onChatMessage` to plug in your model and tools.
-
-```ts title="src/chat.ts"
-import { AIChatAgent } from "@cloudflare/ai-chat";
-import { openai } from "@ai-sdk/openai";
-import { streamText, convertToModelMessages } from "ai";
-
-export type Env = {
-  OPENAI_API_KEY: string;
-  Chat: DurableObjectNamespace<Chat>;
-};
-
-export class Chat extends AIChatAgent<Env> {
-  async onChatMessage(onFinish: Parameters<typeof streamText>[0]["onFinish"]) {
-    return streamText({
-      model: openai("gpt-5.6-luna"),
-      messages: await convertToModelMessages(this.messages),
-      onFinish,
-    });
-  }
-}
-```
-
-`Env` is exported alongside `Chat` so the Worker entry point can reuse the same type. The `Chat: DurableObjectNamespace<Chat>` field mirrors the binding declared in `wrangler.jsonc` (next step) and is what `routeAgentRequest` looks up to resolve the agent. `DurableObjectNamespace` is a global from `@cloudflare/workers-types`, which the `npm create cloudflare` scaffold sets up by default.
-
-`this.messages` is the persisted history for this Durable Object instance. Each unique agent `name` you connect with from the client (step 7) gets its own instance and its own message log.
-
-</Step>
-
-<Step>
-
-### Register the Durable Object and route requests
-
-```ts title="src/index.ts"
-import { routeAgentRequest } from "agents";
-import { Chat, type Env } from "./chat";
-
-export { Chat };
-
-const cors = (request: Request) => ({
-  "Access-Control-Allow-Origin": request.headers.get("Origin") ?? "*",
-  "Access-Control-Allow-Headers": "Content-Type, Upgrade",
-  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-});
-
-export default {
-  async fetch(request: Request, env: Env): Promise<Response> {
-    if (request.method === "OPTIONS") {
-      return new Response(null, { headers: cors(request) });
-    }
-    const upstream =
-      (await routeAgentRequest(request, env)) ??
-      new Response("Not found", { status: 404 });
-    const res = new Response(upstream.body, upstream);
-    for (const [k, v] of Object.entries(cors(request))) res.headers.set(k, v);
-    return res;
-  },
-} satisfies ExportedHandler<Env>;
-```
-
-`routeAgentRequest` handles WebSocket upgrades, agent lookup by URL path, and the `/get-messages` HTTP endpoint that the frontend uses for history rehydration. The `cors` helper reflects the request origin so the frontend can talk to the Worker across ports during local development. WebSocket upgrades bypass CORS in the browser, but the `/get-messages` HTTP fetch and any custom routes need these headers. For production, replace the wildcard fallback with an explicit allowlist.
-
-Wire the Durable Object binding in `wrangler.jsonc`:
-
-```jsonc title="wrangler.jsonc"
-{
-  "name": "my-agent",
-  "main": "src/index.ts",
-  "compatibility_date": "2026-01-01",
-  "compatibility_flags": ["nodejs_compat"],
-  "durable_objects": {
-    "bindings": [{ "name": "Chat", "class_name": "Chat" }]
-  },
-  "migrations": [
-    { "tag": "v1", "new_sqlite_classes": ["Chat"] }
-  ]
-}
-```
-
-The binding `name` and `class_name` must match the exported class. `new_sqlite_classes` is required so the Durable Object can use SQLite for message storage.
-
-</Step>
-
-<Step>
-
-### Run the Worker locally
-
-Local `wrangler dev` reads environment variables from a `.dev.vars` file in the project root (not from the remote secret store):
-
-```sh title=".dev.vars"
-OPENAI_API_KEY=sk-...
-```
-
-```sh
-wrangler dev
-```
-
-For production, upload the same key as a deployed Worker secret before `wrangler deploy`:
-
-```sh
-wrangler secret put OPENAI_API_KEY
-```
-
-The Worker boots on `http://localhost:8787`. Leave it running.
-
-</Step>
-
-<Step>
-
-### Initialize the assistant-ui frontend
-
-In a different directory:
-
-```sh title="New project"
-npx assistant-ui@latest create
-```
-
-```sh title="Existing project"
-npx assistant-ui@latest init
-```
-
-This creates a default chat page and a local API route at `app/api/chat/route.ts`. You won't use the local route, since the agent runs on the Worker; delete it once the next step is wired.
-
-</Step>
-
-<Step>
-
-### Install the Cloudflare client packages
-
-In the frontend project:
-
-<InstallCommand npm={["agents@0.12.4", "@cloudflare/ai-chat@0.7.0"]} />
-
-</Step>
-
-<Step>
-
-### Wire the runtime
-
-```tsx title="app/assistant.tsx"
-"use client";
-
-import { useAgent } from "agents/react";
-import { useAgentChat } from "@cloudflare/ai-chat/react";
-import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useAISDKRuntime } from "@assistant-ui/ai-sdk";
-import { Thread } from "@/components/assistant-ui/thread";
-
-export const Assistant = () => {
-  const agent = useAgent({
-    agent: "Chat",
-    name: "default",
-    host: process.env.NEXT_PUBLIC_AGENT_HOST!,
-  });
-  const chat = useAgentChat({ agent });
-  const runtime = useAISDKRuntime(chat);
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  );
-};
-```
-
-Set the Worker URL in your frontend environment:
-
-```sh title=".env.local"
-NEXT_PUBLIC_AGENT_HOST=http://localhost:8787
-```
-
-`NEXT_PUBLIC_*` exposes the value to the browser. In production, point this at your deployed Worker (e.g. `https://my-agent.example.workers.dev`).
-
-`name: "default"` is the Durable Object instance key. Pass a per-user value (a user ID, session ID, or chat ID) to give each user their own persisted history. Switching `name` from the client opens a new WebSocket connection to a different Durable Object instance.
-
-</Step>
-
-</Steps>
-
-## Notes
-
-### Type compatibility with `useChat`
-
-`useAgentChat`'s return type is `Omit<ReturnType<typeof useChat>, "addToolOutput"> & { ... }`. The `addToolOutput` option shape differs slightly between the two: `useChat` accepts `{ state, tool, toolCallId, ... }`; `useAgentChat` accepts `{ state, toolCallId, toolName?, ... }`. At runtime the call paths converge through `useAISDKRuntime` without issue (verified against `@cloudflare/ai-chat@0.7.0`). If the TypeScript compiler flags the call, cast at the call site: `useAISDKRuntime(chat as Parameters<typeof useAISDKRuntime>[0])`, or `chat as unknown as Parameters<typeof useAISDKRuntime>[0]` if TypeScript still refuses the direct cast. (`satisfies` does not help here; it validates assignability without changing the inferred type, so it surfaces the same error.)
-
-### Cloudflare-specific extras
-
-`useAgentChat` exposes three values that `useChat` does not:
-
-- `clearHistory()` sends a `cf_agent_chat_clear` frame and wipes the Durable Object's SQLite store. Bind it to a "Clear chat" button if you need server-side history reset; `setMessages([])` alone only clears the client view.
-- `isServerStreaming` is `true` while the server is pushing tokens, independent of client-initiated request state. Use it for a universal streaming indicator.
-- `isToolContinuation` distinguishes "server auto-continuing after a tool result" from "user just sent a new message". Useful for typing-indicator gating.
-
-Destructure these alongside `chat` and pass them into your UI directly; they don't need to flow through the runtime.
-
-### `setMessages` round-trips through the Durable Object
-
-`useAgentChat` overrides `setMessages` to broadcast the new list over the WebSocket so the Durable Object's SQLite history stays in sync. This means assistant-ui's `onImport`, `onEdit`, `onReload`, and pending-tool cancellation paths all persist server-side automatically. The tradeoff is one extra WebSocket round-trip per mutation, which can race if the connection is lagging; assume eventual consistency, not transactional.
-
-### Authenticate the Worker before going to production
-
-`routeAgentRequest` accepts any client that knows the agent class and `name`. If you derive `name` from a user ID (as recommended for per-user history), any client that knows or guesses another user's ID can connect to that Durable Object and read its full message log. Before deploying:
-
-- Gate the fetch handler with a header or cookie check (e.g. a JWT issued by your auth backend), and only call `routeAgentRequest` after the request is authenticated.
-- Pass the same credential from the frontend via `useAgent`'s `headers` or `query` options so the WebSocket upgrade carries it.
-- Tighten the CORS `Access-Control-Allow-Origin` to an explicit allowlist; the wildcard in the example above is for local development only.
-
-### Version stability
-
-`agents` and `@cloudflare/ai-chat` are pre-1.0 and ship breaking changes between minor versions. Pin both to exact versions in `package.json` and read the Cloudflare changelog before bumping. The `useAgentChat` return shape has been additive since 0.3.0, so the integration above should keep working across patch releases.
-
-## Related
-
-<Cards>
-  <Card
-    icon={<CloudflareIcon width={20} height={20} />}
-    title="Cloudflare Agents docs"
-    description="Cloudflare's official guide: Durable Object lifecycle, WebSocket protocol, tool patterns, multi-agent routing."
-    href="https://developers.cloudflare.com/agents/"
-  />
-  <Card
-    icon={<VercelIcon width={20} height={20} />}
-    title="AI SDK runtime"
-    description="The runtime that handles the client side of this integration."
-    href="/docs/runtimes/ai-sdk/v7"
-  />
-</Cards>

package/.docs/raw/docs/integrations/frameworks/mastra/full-stack.mdx

@@ -1,188 +0,0 @@
----
-title: Full-stack integration
-description: Run Mastra agents inside your Next.js API routes.
-platforms: ["react"]
----
-
-import { MastraIcon } from "@/components/icons/mastra";
-import { VercelIcon } from "@/components/icons/vercel";
-
-Run Mastra in-process inside your Next.js application. The agent code, the API route, and the assistant-ui frontend all live in one project. This is the lowest-friction path: one deploy target, one set of env vars, no cross-origin plumbing.
-
-For independent scaling, see [separate server](/docs/integrations/frameworks/mastra/separate-server) instead.
-
-## Setup
-
-<Steps>
-<Step>
-
-### Initialize assistant-ui
-
-Set up assistant-ui in your project:
-
-```sh title="New project"
-npx assistant-ui@latest create
-```
-
-```sh title="Existing project"
-npx assistant-ui@latest init
-```
-
-This installs dependencies and creates a default chat API route at `app/api/chat/route.ts`. For manual setup, see the [getting started guide](/docs).
-
-</Step>
-<Step>
-
-### Install Mastra packages
-
-`@mastra/core` provides the agent runtime; `@mastra/ai-sdk` converts Mastra's stream format to AI SDK's UI message stream; `zod` is required for tool schemas.
-
-<InstallCommand npm={["@mastra/core@latest", "@mastra/ai-sdk@latest", "zod@latest"]} />
-
-</Step>
-<Step>
-
-### Configure Next.js
-
-Mastra's runtime depends on Node-only modules. Tell Next.js to bundle Mastra packages externally on the server so they aren't traced into the edge runtime.
-
-```js title="next.config.mjs"
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  serverExternalPackages: ["@mastra/*"],
-};
-
-export default nextConfig;
-```
-
-If you skip this step you'll see opaque bundling errors at request time, not at build time.
-
-</Step>
-<Step>
-
-### Define an agent
-
-Create a `mastra/` folder at the project root with two files:
-
-```txt title="Project layout"
-mastra/
-├── agents/
-│   └── chefAgent.ts
-└── index.ts
-```
-
-Define the agent in `chefAgent.ts`:
-
-```ts title="mastra/agents/chefAgent.ts"
-import { Agent } from "@mastra/core/agent";
-
-export const chefAgent = new Agent({
-  name: "chef-agent",
-  instructions:
-    "You are Michel, a practical and experienced home chef. " +
-    "You help people cook with whatever ingredients they have available.",
-  model: "openai/gpt-5.6-luna",
-});
-```
-
-`model: "openai/gpt-5.6-luna"` uses Mastra's model router. Set the provider key in `.env.local` so Next.js auto-loads it:
-
-```sh title=".env.local"
-OPENAI_API_KEY=sk-...
-```
-
-</Step>
-<Step>
-
-### Register the agent
-
-Initialize Mastra with the agent so it can be looked up by name:
-
-```ts title="mastra/index.ts"
-import { Mastra } from "@mastra/core";
-import { chefAgent } from "./agents/chefAgent";
-
-export const mastra = new Mastra({
-  agents: { chefAgent },
-});
-```
-
-</Step>
-<Step>
-
-### Wire the API route
-
-Replace the default route with one that streams from the Mastra agent:
-
-```ts title="app/api/chat/route.ts"
-import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
-import { toAISdkStream } from "@mastra/ai-sdk";
-import { mastra } from "@/mastra";
-
-export const maxDuration = 30;
-
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-
-  const agent = mastra.getAgent("chefAgent");
-  const stream = await agent.stream(messages);
-
-  const uiMessageStream = createUIMessageStream({
-    originalMessages: messages,
-    execute: async ({ writer }) => {
-      for await (const part of toAISdkStream(stream, { from: "agent" })) {
-        await writer.write(part);
-      }
-    },
-  });
-
-  return createUIMessageStreamResponse({ stream: uiMessageStream });
-}
-```
-
-`agent.stream()` returns a Mastra-native stream. `toAISdkStream` (from `@mastra/ai-sdk`) adapts each part to the AI SDK shape; `createUIMessageStream` wraps the part loop into the UI message stream that `useChatRuntime` consumes; `createUIMessageStreamResponse` returns it as an HTTP response.
-
-The `@/mastra` import assumes the `@/*` path alias is configured in `tsconfig.json` (the assistant-ui starter sets this up). If your project uses a different alias, adjust the import path.
-
-</Step>
-<Step>
-
-### Run and verify
-
-Start the dev server:
-
-```bash npm2yarn
-npm run dev
-```
-
-Open `http://localhost:3000`, send a message like *"What can I make with eggs and rice?"*, and confirm:
-
-- The response streams in token by token.
-- The browser's network tab shows a single `POST /api/chat` returning `text/event-stream`.
-- No console errors about missing modules; if you see `Cannot find module '@mastra/...'`, revisit the `serverExternalPackages` step.
-
-</Step>
-</Steps>
-
-## Notes
-
-- **Errors in the route bubble to the client as a stream error.** Wrap `agent.stream()` in `try/catch` if you need to log structured errors before they reach the client.
-- **Pin compatible versions.** `@mastra/ai-sdk` tracks the AI SDK v6 contract. If you upgrade `ai` to a future major, verify the `toAISdkStream` shape against Mastra's release notes.
-- **Advanced Mastra features** (memory, tools, workflows, evals) live entirely in the agent definition. assistant-ui sees only the resulting stream, so anything Mastra supports works without further frontend changes. See the [Mastra docs](https://mastra.ai/docs).
-
-## Related
-
-<Cards>
-  <Card
-    icon={<MastraIcon width={20} height={20} />}
-    title="Separate server integration"
-    description="Run Mastra as a standalone server, connect via API."
-    href="/docs/integrations/frameworks/mastra/separate-server"
-  />
-  <Card
-    icon={<VercelIcon width={20} height={20} />}
-    title="AI SDK runtime"
-    description="The runtime that handles the client side of this integration."
-    href="/docs/runtimes/ai-sdk/v7"
-  />
-</Cards>

package/.docs/raw/docs/integrations/frameworks/mastra/overview.mdx

@@ -1,57 +0,0 @@
----
-title: Mastra Integration
-description: Wire the Mastra TypeScript agent framework into a React chat UI with assistant-ui — full streaming, tool calling, multi-agent support, and thread management.
----
-
-import { MastraIcon } from "@/components/icons/mastra";
-import { VercelIcon } from "@/components/icons/vercel";
-
-[Mastra](https://mastra.ai/) is an open-source TypeScript agent framework. It provides primitives for AI applications: agents with memory and tool calling, deterministic LLM workflows, RAG, model routing, workflow graphs, and automated evals.
-
-<Callout type="info">
-This is an integration guide, not a runtime adapter. assistant-ui does not ship a `@assistant-ui/react-mastra` package. You wire up Mastra through the standard [AI SDK runtime](/docs/runtimes/ai-sdk/v7) by routing your API endpoint through Mastra's agent stream.
-</Callout>
-
-## Pick a pattern
-
-| Pattern | When to pick |
-| --- | --- |
-| [Full-stack](/docs/integrations/frameworks/mastra/full-stack) | One Next.js app: API routes call Mastra in-process. Simpler deployment, single repo. |
-| [Separate server](/docs/integrations/frameworks/mastra/separate-server) | Mastra runs as its own service; the Next.js frontend hits its API. Independent scaling, clearer separation of concerns. |
-
-Both use the same client-side `useChatRuntime` from [`@assistant-ui/ai-sdk`](/docs/runtimes/ai-sdk/v7). The only difference is where the Mastra agent lives.
-
-## Architecture
-
-Mastra integrates at the LLM-client layer on the server. assistant-ui talks to your API route via the AI SDK runtime; the route calls `agent.stream(messages)` and returns the result wrapped in a UI message stream. The client side is built on [`ExternalStoreRuntime`](/docs/runtimes/custom/external-store) through the AI SDK adapter.
-
-Shared adapters (attachments, speech, feedback, history) work the same way described in [adapters](/docs/runtimes/concepts/adapters). Multi-thread support uses [AssistantCloud](/docs/cloud) or a [custom thread list](/docs/runtimes/concepts/threads).
-
-## Requirements
-
-- A Next.js project, or another framework that can run AI SDK route handlers.
-- Model API keys (OpenAI, Anthropic, etc.) configured in your environment.
-- Node 18 or newer.
-
-## Next
-
-<Cards>
-  <Card
-    icon={<MastraIcon width={20} height={20} />}
-    title="Full-stack integration"
-    description="Run Mastra inside your Next.js API routes."
-    href="/docs/integrations/frameworks/mastra/full-stack"
-  />
-  <Card
-    icon={<MastraIcon width={20} height={20} />}
-    title="Separate server integration"
-    description="Run Mastra as a standalone server, frontend connects via API."
-    href="/docs/integrations/frameworks/mastra/separate-server"
-  />
-  <Card
-    icon={<VercelIcon width={20} height={20} />}
-    title="AI SDK runtime"
-    description="The runtime that handles the client side of this integration."
-    href="/docs/runtimes/ai-sdk/v7"
-  />
-</Cards>