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

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

@@ -0,0 +1,188 @@
+---
+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.4-mini",
+});
+```
+
+`model: "openai/gpt-5.4-mini"` 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/v6"
+  />
+</Cards>

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

@@ -0,0 +1,57 @@
+---
+title: Overview
+description: Wire up the Mastra TypeScript agent framework with assistant-ui.
+---
+
+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/v6) 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/react-ai-sdk`](/docs/runtimes/ai-sdk/v6). 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/v6"
+  />
+</Cards>

package/.docs/raw/docs/integrations/frameworks/mastra/separate-server.mdx

@@ -0,0 +1,201 @@
+---
+title: Separate server integration
+description: Run Mastra as a standalone server with assistant-ui as a separate frontend.
+---
+
+import { MastraIcon } from "@/components/icons/mastra";
+import { VercelIcon } from "@/components/icons/vercel";
+
+Run Mastra as its own service and have the assistant-ui frontend hit it over HTTP. The two halves can deploy, scale, and version independently. The tradeoff is one extra hop and CORS to configure.
+
+For the simpler in-process variant, see [full-stack](/docs/integrations/frameworks/mastra/full-stack) instead.
+
+## Setup
+
+The setup has two halves. Steps 1 to 4 happen in the **Mastra server** project; steps 5 to 7 happen in a **separate assistant-ui frontend** project. You'll have two terminals open by the end: one for each dev server.
+
+<Steps>
+
+<Step>
+
+### Create the Mastra server project
+
+In a directory separate from your frontend, scaffold a Mastra project:
+
+```sh
+npx create-mastra@latest
+```
+
+Follow the wizard's prompts. When it finishes, change into the new directory and add the AI SDK adapter:
+
+```sh
+cd your-mastra-server
+```
+
+<InstallCommand npm={["@mastra/ai-sdk@latest"]} />
+
+Set the model provider keys (`OPENAI_API_KEY`, etc.) in `.env.development`. The `create-mastra` wizard prompts for some keys, but verify all the providers you plan to call are present.
+
+</Step>
+
+<Step>
+
+### Define an agent
+
+```ts title="src/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-4o-mini",
+});
+```
+
+</Step>
+
+<Step>
+
+### Register the agent, chat route, and CORS
+
+Open the Mastra entry point. You will set three things in the same `Mastra` constructor: the agent, a chat route, and CORS for the frontend's origin.
+
+```ts title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { chefAgent } from "./agents/chefAgent";
+import { chatRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  agents: { chefAgent },
+  server: {
+    cors: {
+      origin: process.env.FRONTEND_ORIGIN ?? "http://localhost:3000",
+      credentials: true,
+    },
+    apiRoutes: [
+      chatRoute({ path: "/chat/:agentId" }),
+    ],
+  },
+});
+```
+
+A few things to note:
+
+- `:agentId` matches the **JavaScript key** in the `agents` object, not the agent's `name` field. So `chefAgent` is reachable at `/chat/chefAgent` (camelCase), not `/chat/chef-agent`.
+- Add more agents to the `agents` object and they all become callable through this single route.
+- `FRONTEND_ORIGIN` should be set to your deployed frontend's URL in production. Without CORS configured, the browser blocks the request and the chat silently fails.
+
+</Step>
+
+<Step>
+
+### Run the Mastra server
+
+```bash npm2yarn
+npm run dev
+```
+
+The server starts on `http://localhost:4111` by default. Leave it running for the rest of the steps.
+
+</Step>
+
+<Step>
+
+### Initialize the assistant-ui frontend
+
+In a **different directory** from the Mastra server, scaffold the frontend:
+
+```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 separate Mastra server; delete it once the next step is wired.
+
+</Step>
+
+<Step>
+
+### Point the runtime at the Mastra server
+
+Open the file containing `useChatRuntime` (typically `app/assistant.tsx`) and pass an explicit `api` URL:
+
+```tsx title="app/assistant.tsx" {8}
+"use client";
+
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { AssistantChatTransport, useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { Thread } from "@/components/assistant-ui/thread";
+
+export const Assistant = () => {
+  const runtime = useChatRuntime({
+    transport: new AssistantChatTransport({
+      api: process.env.NEXT_PUBLIC_MASTRA_URL!,
+    }),
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+};
+```
+
+Set the URL in your frontend's environment:
+
+```sh title=".env.local"
+NEXT_PUBLIC_MASTRA_URL=http://localhost:4111/chat/chefAgent
+```
+
+`NEXT_PUBLIC_*` makes the URL available in the browser. In production, point this at your deployed Mastra server. Mastra itself uses `.env.development` for its server keys; the two projects keep separate environment files.
+
+</Step>
+
+<Step>
+
+### Run and verify
+
+Make sure the Mastra server (step 4) is still running in its own terminal, then start the frontend in a new terminal:
+
+```bash npm2yarn
+npm run dev
+```
+
+Open `http://localhost:3000`, send a message, and confirm:
+
+- The response streams in token by token.
+- The network tab shows the `POST` going to `http://localhost:4111/chat/chefAgent`, not the local `/api/chat`.
+- No CORS errors in the console; if you see `blocked by CORS policy`, revisit step 3.
+
+</Step>
+
+</Steps>
+
+## Notes
+
+- **Auth between frontend and Mastra**: the example above is open. In production, gate the Mastra route with a header or cookie check and forward credentials from the frontend (`AssistantChatTransport` accepts `headers` and `credentials` options).
+- **Single agent vs router**: `chatRoute({ path: "/chat/:agentId" })` works for any agent registered on the `Mastra` instance. Switching agents from the frontend is a matter of pointing `NEXT_PUBLIC_MASTRA_URL` at a different agent ID.
+- **Advanced Mastra features** (memory, tools, workflows, evals) live in the agent definition. The frontend sees only the resulting stream. See the [Mastra docs](https://mastra.ai/docs).
+
+## Related
+
+<Cards>
+  <Card
+    icon={<MastraIcon width={20} height={20} />}
+    title="Full-stack integration"
+    description="Run Mastra inside your Next.js API routes for a single deploy target."
+    href="/docs/integrations/frameworks/mastra/full-stack"
+  />
+  <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/v6"
+  />
+</Cards>

package/.docs/raw/docs/integrations/gateways/index.mdx

@@ -0,0 +1,157 @@
+---
+title: LLM gateways
+description: Route assistant-ui traffic through OpenAI-compatible gateways for cost, fallback, and BYOK.
+---
+
+LLM gateways sit between your route handler and the upstream provider. They give you a single endpoint that fronts many providers, plus features like multi-provider fallback, prompt caching, and BYOK (bring-your-own-key) flows. Most are OpenAI API-compatible, so the integration is a `baseURL` swap on `createOpenAI` from `@ai-sdk/openai`.
+
+For pure observability (proxy that logs every call) see [Helicone](/docs/integrations/observability/helicone). The gateways here overlap in spirit but are positioned around routing rather than logging.
+
+## Compare
+
+| Gateway | Base URL | Auth header | Distinguishing feature |
+| --- | --- | --- | --- |
+| [OpenRouter](#openrouter) | `https://openrouter.ai/api/v1` | `Authorization: Bearer <key>` | Catalog of 100+ models with `vendor/model` IDs |
+| [Portkey](#portkey) | `https://api.portkey.ai/v1` | `x-portkey-api-key` | Config-driven multi-provider fallback |
+| [LiteLLM Proxy](#litellm-proxy) | Self-hosted | `Authorization: Bearer <virtual key>` | OSS, self-host, virtual keys per tenant |
+
+If your need is only request logging, Helicone fits the same shape and is documented separately.
+
+## Common pattern
+
+All three gateways below speak OpenAI's API. Wire them with `createOpenAI`:
+
+```ts title="app/api/chat/route.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages } from "ai";
+import type { UIMessage } from "ai";
+
+const openai = createOpenAI({
+  baseURL: "<gateway base url>",
+  headers: { /* gateway-specific auth */ },
+});
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+  const result = streamText({
+    model: openai("<model id>"),
+    messages: await convertToModelMessages(messages),
+  });
+  return result.toUIMessageStreamResponse();
+}
+```
+
+The rest of this page is what to put in `baseURL`, `headers`, and `model(...)` for each gateway.
+
+## OpenRouter
+
+[OpenRouter](https://openrouter.ai/) aggregates 100+ models behind one OpenAI-compatible endpoint. The model ID is `provider/model` (e.g., `anthropic/claude-sonnet-4`, `openai/gpt-5.4-mini`, `meta-llama/llama-3.3-70b-instruct`).
+
+```sh title=".env.local"
+OPENROUTER_API_KEY=sk-or-...
+SITE_URL=https://your-app.example
+```
+
+```ts title="app/api/chat/route.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages } from "ai";
+import type { UIMessage } from "ai";
+
+const openrouter = createOpenAI({
+  baseURL: "https://openrouter.ai/api/v1",
+  apiKey: process.env.OPENROUTER_API_KEY,
+  headers: {
+    "HTTP-Referer": process.env.SITE_URL ?? "http://localhost:3000",
+    "X-Title": "My App",
+  },
+});
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+  const result = streamText({
+    model: openrouter("anthropic/claude-sonnet-4"),
+    messages: await convertToModelMessages(messages),
+  });
+  return result.toUIMessageStreamResponse();
+}
+```
+
+`HTTP-Referer` and `X-Title` are optional attribution headers; OpenRouter shows them in your usage dashboard.
+
+When to pick: you want a single bill across many models, or you let users pick the model from a long list, or you need to run open-weights models without managing the inference yourself.
+
+## Portkey
+
+[Portkey](https://portkey.ai/) is a gateway plus observability with a config-driven router. The differentiating feature is the *config*: a server-defined object that describes routing rules (try Anthropic first, fall back to OpenAI, fall back to a local model), retries, and caching.
+
+```sh title=".env.local"
+PORTKEY_API_KEY=...
+PORTKEY_VIRTUAL_KEY=...
+```
+
+```ts title="app/api/chat/route.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+
+const portkey = createOpenAI({
+  baseURL: "https://api.portkey.ai/v1",
+  apiKey: "no-auth-here",
+  headers: {
+    "x-portkey-api-key": process.env.PORTKEY_API_KEY!,
+    "x-portkey-virtual-key": process.env.PORTKEY_VIRTUAL_KEY!,
+  },
+});
+```
+
+Configs live in the Portkey dashboard; reference them with `x-portkey-config: <config-id>` in the headers when you want a specific routing strategy.
+
+When to pick: you need cross-provider fallback or prompt-cache hit rates that the AI SDK doesn't give you out of the box.
+
+## LiteLLM Proxy
+
+[LiteLLM Proxy](https://docs.litellm.ai/docs/simple_proxy) is OSS and self-hostable. You run it, you configure provider keys server-side, and you hand virtual keys (per-tenant, per-user) to clients. It's the only viable path for BYOK SaaS or air-gapped deployments.
+
+Run the proxy first (Docker, k8s, or a single Node process). Then point the AI SDK at your instance:
+
+```sh title=".env.local"
+LITELLM_BASE_URL=https://litellm.example.com
+LITELLM_VIRTUAL_KEY=sk-...
+```
+
+```ts title="app/api/chat/route.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+
+const litellm = createOpenAI({
+  baseURL: process.env.LITELLM_BASE_URL!,
+  apiKey: process.env.LITELLM_VIRTUAL_KEY!,
+});
+
+const result = streamText({
+  model: litellm("gpt-5.4-mini"),
+  messages: await convertToModelMessages(messages),
+});
+```
+
+Model IDs depend on how you configured the proxy. LiteLLM rewrites them to upstream providers based on your config.
+
+When to pick: self-host requirement, BYOK metering for end-users, or unified billing across providers managed by your platform team.
+
+## Notes
+
+- **Server-side only.** A gateway key is a write capability against your billing account. Never set it in client code; the route handler is the right boundary.
+- **Streaming, tools, attachments.** All three gateways are transparent to the AI SDK; everything that works against OpenAI directly works through them.
+- **Combining with observability.** A gateway and an observability tool are not mutually exclusive. Helicone in front of OpenRouter is a common stack: OpenRouter does the routing, Helicone logs the calls.
+
+## Related
+
+<Cards>
+  <Card
+    title="Helicone"
+    description="The observability-first proxy. Same shape, different goal."
+    href="/docs/integrations/observability/helicone"
+  />
+  <Card
+    title="AI SDK runtime"
+    description="The runtime that ferries gateway responses to the chat UI."
+    href="/docs/runtimes/ai-sdk/v6"
+  />
+</Cards>