@assistant-ui/mcp-docs-server 0.1.1

package/.docs/raw/docs/runtimes/mastra/full-stack-integration.mdx

@@ -0,0 +1,218 @@
+---
+title: Full-Stack Integration
+---
+
+import { Step, Steps } from "fumadocs-ui/components/steps";
+import { Callout } from "fumadocs-ui/components/callout";
+
+Integrate Mastra directly into your Next.js application's API routes. This approach keeps your backend and frontend code within the same project.
+
+<Steps>
+<Step>
+
+### Initialize Assistant UI
+
+Start by setting up Assistant UI in your project. Run one of the following commands:
+
+```sh title="New Project"
+npx assistant-ui@latest create
+```
+
+```sh title="Existing Project"
+npx assistant-ui@latest init
+```
+
+This command installs necessary dependencies and creates basic configuration files, including a default chat API route.
+
+<Callout title="Need Help?">
+  For detailed setup instructions, including adding API keys, basic
+  configuration, and manual setup steps, please refer to the main [Getting
+  Started guide](/docs/getting-started).
+</Callout>
+
+</Step>
+<Step>
+
+### Review Initial API Route
+
+The initialization command creates a basic API route at `app/api/chat/route.ts` (or `src/app/api/chat/route.ts`). It typically looks like this:
+
+```typescript title="app/api/chat/route.ts"
+import { openai } from "@ai-sdk/openai";
+import { streamText } from "ai";
+
+// Allow streaming responses up to 30 seconds
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-4o-mini"),
+    messages,
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+This default route uses the Vercel AI SDK directly with OpenAI. In the following steps, we will modify this route to integrate Mastra.
+
+</Step>
+<Step>
+
+### Install Mastra Packages
+
+Add the Mastra core, memory, the AI SDK OpenAI provider packages to your project:
+
+```bash npm2yarn
+npm install @mastra/core@latest @mastra/memory@latest @ai-sdk/openai
+```
+
+</Step>
+<Step>
+
+### Configure Next.js
+
+To ensure Next.js correctly bundles your application when using Mastra directly in API routes, you need to configure `serverExternalPackages`.
+
+Update your `next.config.mjs` (or `next.config.js`) file to include `@mastra/*`:
+
+```js title="next.config.mjs"
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  serverExternalPackages: ["@mastra/*"],
+  // ... other configurations
+};
+
+export default nextConfig;
+```
+
+This tells Next.js to treat Mastra packages as external dependencies on the server-side.
+
+</Step>
+<Step>
+
+### Create Mastra Files
+
+Set up the basic folder structure for your Mastra configuration. Create a `mastra` folder (e.g., in your `src` or root directory) with the following structure:
+
+```txt title="Project Structure"
+/
+├── mastra/
+│   ├── agents/
+│   │   └── chefAgent.ts
+│   └── index.ts
+└── ... (rest of your project)
+```
+
+You can create these files and folders manually or use the following commands in your terminal:
+
+```bash
+mkdir -p mastra/agents
+touch mastra/index.ts mastra/agents/chefAgent.ts
+```
+
+These files will be used in the next steps to define your Mastra agent and configuration.
+
+</Step>
+<Step>
+
+### Define the Agent
+
+Now, let's define the behavior of our AI agent. Open the `mastra/agents/chefAgent.ts` file and add the following code:
+
+```typescript title="mastra/agents/chefAgent.ts"
+import { openai } from "@ai-sdk/openai";
+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"),
+});
+```
+
+This code creates a new Mastra `Agent` named `chef-agent`.
+
+- `instructions`: Defines the agent's persona and primary goal.
+- `model`: Specifies the language model the agent will use (in this case, OpenAI's GPT-4o Mini via the AI SDK).
+
+Make sure you have set up your OpenAI API key as described in the [Getting Started guide](/docs/getting-started).
+
+</Step>
+<Step>
+
+### Register the Agent
+
+Next, register the agent with your Mastra instance. Open the `mastra/index.ts` file and add the following code:
+
+```typescript title="mastra/index.ts"
+import { Mastra } from "@mastra/core";
+
+import { chefAgent } from "./agents/chefAgent";
+
+export const mastra = new Mastra({
+  agents: { chefAgent },
+});
+```
+
+This code initializes Mastra and makes the `chefAgent` available for use in your application's API routes.
+
+</Step>
+<Step>
+
+### Modify the API Route
+
+Now, update your API route (`app/api/chat/route.ts`) to use the Mastra agent you just configured. Replace the existing content with the following:
+
+```typescript title="app/api/chat/route.ts"
+import { mastra } from "@/mastra"; // Adjust the import path if necessary
+
+// Allow streaming responses up to 30 seconds
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  // Extract the messages from the request body
+  const { messages } = await req.json();
+
+  // Get the chefAgent instance from Mastra
+  const agent = mastra.getAgent("chefAgent");
+
+  // Stream the response using the agent
+  const result = await agent.stream(messages);
+
+  // Return the result as a data stream response
+  return result.toDataStreamResponse();
+}
+```
+
+Key changes:
+- We import the `mastra` instance created in `mastra/index.ts`. Make sure the import path (`@/mastra`) is correct for your project setup (you might need `~/mastra`, `../../../mastra`, etc., depending on your path aliases and project structure).
+- We retrieve the `chefAgent` using `mastra.getAgent("chefAgent")`.
+- Instead of calling the AI SDK's `streamText` directly, we call `agent.stream(messages)` to process the chat messages using the agent's configuration and model.
+- The result is still returned in a format compatible with Assistant UI using `toDataStreamResponse()`.
+
+Your API route is now powered by Mastra!
+
+</Step>
+<Step>
+
+### Run the Application
+
+You're all set! Start your Next.js development server:
+
+```bash npm2yarn
+npm run dev
+```
+
+Open your browser to `http://localhost:3000` (or the port specified in your terminal). You should now be able to interact with your `chefAgent` through the Assistant UI chat interface. Ask it for cooking advice based on ingredients you have!
+
+</Step>
+</Steps>
+
+Congratulations! You have successfully integrated Mastra into your Next.js application using the full-stack approach. Your Assistant UI frontend now communicates with a Mastra agent running in your Next.js backend API route.
+
+To explore more advanced Mastra features like memory, tools, workflows, and more, please refer to the [official Mastra documentation](https://mastra.ai/docs).

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

@@ -0,0 +1,17 @@
+---
+title: Overview
+---
+
+Mastra is an open-source TypeScript agent framework designed to provide the essential primitives for building AI applications. It enables developers to create AI agents with memory and tool-calling capabilities, implement deterministic LLM workflows, and leverage RAG for knowledge integration. With features like model routing, workflow graphs, and automated evals, Mastra provides a complete toolkit for developing, testing, and deploying AI applications.
+
+## Integrating with Next.js and Assistant UI
+
+There are two primary ways to integrate Mastra into your Next.js project when using Assistant UI:
+
+1.  **Full-Stack Integration**: Integrate Mastra directly into your Next.js application's API routes. This approach keeps your backend and frontend code within the same project.
+    [Learn how to set up Full-Stack Integration](./full-stack-integration)
+
+2.  **Separate Server Integration**: Run Mastra as a standalone server and connect your Next.js frontend to its API endpoints. This approach separates concerns and allows for independent scaling.
+    [Learn how to set up Separate Server Integration](./separate-server-integration)
+
+Choose the guide that best fits your project architecture. Both methods allow seamless integration with the Assistant UI components.

package/.docs/raw/docs/runtimes/mastra/separate-server-integration.mdx

@@ -0,0 +1,196 @@
+---
+title: Separate Server Integration
+---
+
+import { Step, Steps } from "fumadocs-ui/components/steps";
+import { Callout } from "fumadocs-ui/components/callout";
+
+Run Mastra as a standalone server and connect your Next.js frontend (using Assistant UI) to its API endpoints. This approach separates your AI backend from your frontend application, allowing for independent development and scaling.
+
+<Steps>
+
+<Step>
+
+### Create Mastra Server Project
+
+First, create a dedicated project for your Mastra server. Choose a directory separate from your Next.js/Assistant UI frontend project.
+
+Navigate to your chosen parent directory in the terminal and run the Mastra create command:
+
+```bash
+npx create-mastra@latest
+```
+
+This command will launch an interactive wizard to help you scaffold a new Mastra project, including prompting you for a project name and setting up basic configurations. Follow the prompts to create your server project. For more detailed setup instructions, refer to the [official Mastra installation guide](https://mastra.ai/docs/getting-started/installation).
+
+Once the setup is complete, navigate into your new Mastra project directory (the name you provided during the setup):
+
+```bash
+cd your-mastra-server-directory # Replace with the actual directory name
+```
+
+You now have a basic Mastra server project ready.
+
+<Callout title="API Keys">
+  Ensure you have configured your environment variables (e.g., `OPENAI_API_KEY`)
+  within this Mastra server project, typically in a `.env.development` file, as
+  required by the models you use. The `create-mastra` wizard might prompt you
+  for some keys, but ensure all necessary keys for your chosen models are
+  present.
+</Callout>
+
+</Step>
+
+<Step>
+
+### Define the Agent
+
+Next, let's define an agent within your Mastra server project. We'll create a `chefAgent` similar to the one used in the full-stack guide.
+
+Open or create the agent file (e.g., `src/agents/chefAgent.ts` within your Mastra project) and add the following code:
+
+```typescript title="src/agents/chefAgent.ts"
+import { openai } from "@ai-sdk/openai";
+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"),
+});
+```
+
+This defines the agent's behavior, but it's not yet active in the Mastra server.
+
+</Step>
+
+<Step>
+
+### Register the Agent
+
+Now, you need to register the `chefAgent` with your Mastra instance so the server knows about it. Open your main Mastra configuration file (this is often `src/index.ts` in projects created with `create-mastra`).
+
+Import the `chefAgent` and add it to the `agents` object when initializing Mastra:
+
+```typescript title="src/index.ts"
+import { Mastra } from "@mastra/core";
+import { chefAgent } from "./agents/chefAgent"; // Adjust path if necessary
+
+export const mastra = new Mastra({
+  agents: { chefAgent },
+});
+```
+
+Make sure you adapt this code to fit the existing structure of your `src/index.ts` file generated by `create-mastra`. The key is to import your agent and include it in the `agents` configuration object.
+
+</Step>
+
+<Step>
+
+### Run the Mastra Server
+
+With the agent defined and registered, start the Mastra development server:
+
+```bash npm2yarn
+npm run dev
+```
+
+By default, the Mastra server will run on `http://localhost:4111`. Your `chefAgent` should now be accessible via a POST request endpoint, typically `http://localhost:4111/api/agents/chefAgent/stream`. Keep this server running for the next steps where we'll set up the Assistant UI frontend to connect to it.
+
+</Step>
+
+<Step>
+
+### Initialize Assistant UI Frontend
+
+Now, set up your frontend application using Assistant UI. Navigate to a **different directory** from your Mastra server project. You can either create a new Next.js project or use an existing one.
+
+Inside your frontend project directory, run one of the following commands:
+
+```sh title="New Project"
+npx assistant-ui@latest create
+```
+
+```sh title="Existing Project"
+npx assistant-ui@latest init
+```
+
+This command installs the necessary Assistant UI dependencies and sets up basic configuration files, including a default chat page and an API route (`app/api/chat/route.ts`).
+
+<Callout title="Need Help?">
+  For detailed setup instructions for Assistant UI, including manual setup
+  steps, please refer to the main [Getting Started
+  guide](/docs/getting-started).
+</Callout>
+
+In the next step, we will configure this frontend to communicate with the separate Mastra server instead of using the default API route.
+
+</Step>
+
+<Step>
+
+### Configure Frontend API Endpoint
+
+The default Assistant UI setup configures the chat runtime to use a local API route (`/api/chat`) within the Next.js project. Since our Mastra agent is running on a separate server, we need to update the frontend to point to that server's endpoint.
+
+Open the main page file in your Assistant UI frontend project (usually `app/page.tsx` or `src/app/page.tsx`). Find the `useChatRuntime` hook and change the `api` property to the full URL of your Mastra agent's stream endpoint:
+
+```tsx {10} title="app/page.tsx"
+"use client";
+import { Thread } from "@/components/assistant-ui/thread";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { ThreadList } from "@/components/assistant-ui/thread-list";
+
+export default function Home() {
+  // Point the runtime to the Mastra server endpoint
+  const runtime = useChatRuntime({
+    api: "http://localhost:4111/api/agents/chefAgent/stream",
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <main className="grid h-dvh grid-cols-[200px_1fr] gap-x-2 px-4 py-4">
+        <ThreadList />
+        <Thread />
+      </main>
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+Replace `"http://localhost:4111/api/agents/chefAgent/stream"` with the actual URL if your Mastra server runs on a different port or host, or if your agent has a different name.
+
+Now, the Assistant UI frontend will send chat requests directly to your running Mastra server.
+
+<Callout title="Delete Default API Route">
+  Since the frontend no longer uses the local `/api/chat` route created by the
+  `init` command, you can safely delete the `app/api/chat/route.ts` (or
+  `src/app/api/chat/route.ts`) file from your frontend project.
+</Callout>
+
+</Step>
+
+<Step>
+
+### Run the Frontend Application
+
+You're ready to connect the pieces! Make sure your separate Mastra server is still running (from Step 4).
+
+In your Assistant UI frontend project directory, start the Next.js development server:
+
+```bash npm2yarn
+npm run dev
+```
+
+Open your browser to `http://localhost:3000` (or the port specified in your terminal for the frontend app). You should now be able to interact with your `chefAgent` through the Assistant UI chat interface. The frontend will make requests to your Mastra server running on `http://localhost:4111`.
+
+</Step>
+
+</Steps>
+
+Congratulations! You have successfully integrated Mastra with Assistant UI using a separate server approach. Your Assistant UI frontend now communicates with a standalone Mastra agent server.
+
+This setup provides a clear separation between your frontend and AI backend. To explore more advanced Mastra features like memory, tools, workflows, and deployment options, please refer to the [official Mastra documentation](https://mastra.ai/docs).

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

@@ -0,0 +1,222 @@
+---
+title: Picking a Runtime
+---
+
+import { Card, Cards } from "fumadocs-ui/components/card";
+import { Callout } from "fumadocs-ui/components/callout";
+
+Choosing the right runtime is crucial for your assistant-ui implementation. This guide helps you navigate the options based on your specific needs.
+
+## Quick Decision Tree
+
+```mermaid
+graph TD
+    A[What's your starting point?] --> B{Existing Framework?}
+    B -->|Vercel AI SDK| C[Use AI SDK Integration]
+    B -->|LangGraph| D[Use LangGraph Runtime]
+    B -->|LangServe| E[Use LangServe Runtime]
+    B -->|Mastra| F[Use Mastra 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]
+```
+
+## Core Runtimes
+
+These are the foundational runtimes that power assistant-ui:
+
+<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:
+
+<Cards>
+  <Card
+    title="Vercel AI SDK"
+    description="For useChat and useAssistant hooks - streaming with all major providers"
+    href="/docs/runtimes/ai-sdk/use-chat"
+  />
+  <Card
+    title="LangGraph"
+    description="For complex agent workflows with LangChain's graph framework"
+    href="/docs/runtimes/langgraph"
+  />
+  <Card
+    title="LangServe"
+    description="For LangChain applications deployed with LangServe"
+    href="/docs/runtimes/langserve"
+  />
+  <Card
+    title="Mastra"
+    description="For workflow orchestration with Mastra's ecosystem"
+    href="/docs/runtimes/mastra/overview"
+  />
+</Cards>
+
+## Understanding Runtime Architecture
+
+### How Pre-Built Integrations Work
+
+The pre-built integrations (AI SDK, LangGraph, etc.) are **not separate runtime types**. They're convenient wrappers built on top of our core runtimes:
+
+- **AI SDK Integration** → Built on `LocalRuntime` with streaming adapter
+- **LangGraph Runtime** → Built on `LocalRuntime` with graph execution adapter
+- **LangServe Runtime** → Built on `LocalRuntime` with LangServe client adapter
+- **Mastra Runtime** → Built on `LocalRuntime` with workflow adapter
+
+This means you get all the benefits of `LocalRuntime` (automatic state management, built-in features) with zero configuration for your specific framework.
+
+### When to Use Pre-Built vs Core Runtimes
+
+**Use a pre-built integration when:**
+- You're already using that framework
+- You want the fastest possible setup
+- The integration covers your needs
+
+**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
+
+<Callout>
+Pre-built integrations can always be replaced with a custom `LocalRuntime` or `ExternalStoreRuntime` implementation if you need more control later.
+</Callout>
+
+## 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 { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+
+export function MyAssistant() {
+  const runtime = useChatRuntime({
+    api: "/api/chat",
+  });
+
+  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 Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ai-sdk)** - 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
+- **[OpenAI Assistants Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-openai-assistants)** - OpenAI Assistants API
+
+## 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/use-chat)
+   - [`LocalRuntime` Guide](/docs/runtimes/custom/local)
+   - [`ExternalStoreRuntime` Guide](/docs/runtimes/custom/external-store)
+   - [LangGraph Integration](/docs/runtimes/langgraph)
+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
+
+<Callout type="info">
+Need help? Join our [Discord community](https://discord.gg/assistant-ui) or check the [GitHub](https://github.com/assistant-ui/assistant-ui).
+</Callout>