@mastra/mcp-docs-server 1.0.0-beta.2 → 1.0.0-beta.4

package/.docs/raw/frameworks/agentic-uis/cedar-os.mdx

@@ -1,6 +1,6 @@
 ---
-title: "Integrate Cedar-OS with Mastra | Frameworks | Mastra Docs"
-description: "Build AI-native frontends for your Mastra agents with Cedar-OS"
+title: "Using Cedar-OS | Frameworks"
+description: "Learn how to integrate Cedar-OS with Mastra"
 ---
 
 import Tabs from "@theme/Tabs";
@@ -8,29 +8,17 @@ import TabItem from "@theme/TabItem";
 import Steps from "@site/src/components/Steps";
 import StepItem from "@site/src/components/StepItem";
 
-# Integrate Cedar-OS with Mastra
+# Using Cedar-OS
 
-Cedar-OS is an open-source agentic UI framework designed specifically for building the most ambitious AI-native applications. Cedar was built with Mastra in mind.
+[Cedar-OS](https://docs.cedarcopilot.com/introduction/overview) is an open-source agentic UI framework designed specifically for building the most ambitious AI-native applications. Cedar was built with Mastra in mind.
 
-## Should you use Cedar?
+:::info
 
-There are a few pillars Cedar cares about strongly that you can read more about [here](https://docs.cedarcopilot.com/introduction/philosophy):
+Also see the [Extending Mastra](https://docs.cedarcopilot.com/agent-backend-connection/mastra) and [Custom Backend Implementation](https://docs.cedarcopilot.com/agent-backend-connection/custom) guides on Cedar's documentation site for more advanced integration patterns.
 
-#### 1. Developer experience
+:::
 
-- **Every single component is downloaded shadcn-style** – You own all the code and can style it however you want
-- **Works out of the box** – Just drop in the chat component, and it'll work
-- **Fully extensible** - Built on a [Zustand store architecture](https://docs.cedarcopilot.com/introduction/architecture) that you can customize completely. Every single internal function can be overridden in one line.
-
-#### 2. Enabling truly AI-native applications
-
-For the first time in history, products can come to life. Cedar is aimed at helping you build something with life.
-
-- **[Spells](https://docs.cedarcopilot.com/spells/spells#what-are-spells)** - Users can trigger AI from keyboard shortcuts, mouse events, text selection, and other components
-- **[State Diff Management](https://docs.cedarcopilot.com/state-diff/using-state-diff)** - Give users control over accepting/rejecting agent outputs
-- **[Voice Integration](https://docs.cedarcopilot.com/voice/voice-integration)** - Let users control your app with their voice
-
-## Quick Start
+## Integration Guide
 
 <Steps>
 
@@ -112,12 +100,3 @@ Your backend and frontend are now linked! You're ready to start building AI-nati
 </StepItem>
 
 </Steps>
-
-## More information
-
-- Check out the [detailed Mastra integration guide](https://docs.cedarcopilot.com/agent-backend-connection/mastra#extending-mastra) for more configuration options (or for manual installation instructions if something goes wrong)
-- Explore Mastra-specific optimizations and features Cedar has built
-  - **Seamless event streaming** - Automatic rendering of [Mastra streamed events](https://docs.cedarcopilot.com/chat/custom-message-rendering#mastra-event-renderer)
-  - **Voice endpoint support** - Built-in [voice backend integration](https://docs.cedarcopilot.com/voice/agentic-backend#endpoint-configuration)
-  - **End-to-End type safety** - [Types](https://docs.cedarcopilot.com/type-safety/typing-agent-requests) for communicating between your app and Mastra backend
-- [Join the Discord!](https://discord.gg/4AWawRjNdZ) The Cedar team is excited to have you :)

package/.docs/raw/frameworks/agentic-uis/copilotkit.mdx

@@ -1,6 +1,6 @@
 ---
-title: "Integrate CopilotKit with Mastra | Frameworks | Mastra Docs"
-description: "Learn how Mastra leverages the CopilotKit's AGUI library and how you can leverage it to build user experiences"
+title: "Using CopilotKit | Frameworks"
+description: "Learn how to integrate CopilotKit with Mastra"
 ---
 
 import Tabs from "@theme/Tabs";
@@ -8,125 +8,99 @@ import TabItem from "@theme/TabItem";
 import Steps from "@site/src/components/Steps";
 import StepItem from "@site/src/components/StepItem";
 
-# Integrate CopilotKit with Mastra
+# Using CopilotKit
 
-CopilotKit provides React components to quickly integrate customizable AI copilots into your application. Combined with Mastra, you can build sophisticated AI apps featuring bidirectional state synchronization and interactive UIs.
+[CopilotKit](https://www.copilotkit.ai/) provides React components to quickly integrate customizable AI copilots into your application. Combined with Mastra, you can build sophisticated AI apps featuring bidirectional state synchronization and interactive UIs.
 
 Visit the [CopilotKit documentation](https://docs.copilotkit.ai/) to learn more about CopilotKit concepts, components, and advanced usage patterns.
 
-This guide shows two distinct integration approaches:
+:::info
 
-1. Integrate CopilotKit in your Mastra server with a separate React frontend.
-2. Integrate CopilotKit in your Next.js app
+For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [CopilotKit Quickstart](https://docs.copilotkit.ai/mastra/quickstart) guide.
 
-<Tabs>
-<TabItem value="mastra-server" label="Mastra Server">
+:::
 
-  <Steps>
+:::tip
 
-  <StepItem>
+Visit Mastra's [**"UI Dojo"**](https://ui-dojo.mastra.ai/) to see real-world examples of CopilotKit integrated with Mastra.
 
-In your React frontend, install the required CopilotKit packages:
+:::
 
-<Tabs>
-<TabItem value="npm" label="npm">
+## Integration Guide
 
-```bash copy
-npm install @copilotkit/react-core @copilotkit/react-ui
-```
-
-</TabItem>
-<TabItem value="yarn" label="yarn">
-
-```bash copy
-yarn add @copilotkit/react-core @copilotkit/react-ui
-```
+Run Mastra as a standalone server and connect your Next.js frontend (with CopilotKit) to its API endpoints.
 
-</TabItem>
-<TabItem value="pnpm" label="pnpm">
-
-```bash copy
-pnpm add @copilotkit/react-core @copilotkit/react-ui
-```
-
-</TabItem>
-</Tabs>
-
-</StepItem>
+<Steps>
 
 <StepItem>
 
-Create a CopilotKit component in your React frontend:
+Set up your directory structure. A possible directory structure could look like this:
 
-```tsx title="components/copilotkit-component.tsx" copy
-import { CopilotChat } from "@copilotkit/react-ui";
-import { CopilotKit } from "@copilotkit/react-core";
-import "@copilotkit/react-ui/styles.css";
-
-export function CopilotKitComponent({ runtimeUrl }: { runtimeUrl: string }) {
-  return (
-    <CopilotKit runtimeUrl={runtimeUrl} agent="weatherAgent">
-      <CopilotChat
-        labels={{
-          title: "Your Assistant",
-          initial: "Hi! 👋 How can I assist you today?",
-        }}
-      />
-    </CopilotKit>
-  );
-}
+```shell
+project-root
+├── mastra-server
+│   ├── src
+│   │   └── mastra
+│   └── package.json
+└── my-copilot-app
+    └── package.json
 ```
 
-</StepItem>
-
-<StepItem>
+Bootstrap your Mastra server:
 
-If you have not yet set up your Mastra server, follow the [getting started guide](/docs/v1/getting-started/installation) to set up a new Mastra project.
+```bash copy
+npx create-mastra@latest
+```
 
-In your Mastra server, install additional packages for CopilotKit integration:
+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.
 
-<Tabs>
-<TabItem value="npm" label="npm">
+Navigate to your newly created Mastra server directory:
 
 ```bash copy
-npm install @copilotkit/runtime @ag-ui/mastra@beta
+cd mastra-server # Replace with the actual directory name you provided
 ```
 
-</TabItem>
-<TabItem value="yarn" label="yarn">
+You now have a basic Mastra server project ready. You should have the following files and folders:
 
-```bash copy
-yarn add @copilotkit/runtime @ag-ui/mastra@beta
+```shell
+src
+└── mastra
+    ├── agents
+    │   └── weather-agent.ts
+    ├── scorers
+    │   └── weather-scorer.ts
+    ├── tools
+    │   └── weather-tool.ts
+    ├── workflows
+    │   └── weather-workflow.ts
+    └── index.ts
 ```
 
-</TabItem>
-<TabItem value="pnpm" label="pnpm">
+:::note
 
-```bash copy
-pnpm add @copilotkit/runtime @ag-ui/mastra@beta
-```
+Ensure that you have set the appropriate environment variables for your LLM provider in the `.env` file.
 
-</TabItem>
-</Tabs>
+:::
 
 </StepItem>
 
 <StepItem>
 
-Configure your Mastra instance to include CopilotKit's runtime endpoint:
+Create a chat route for the CopilotKit frontend by using the `registerCopilotKit()` helper from `@ag-ui/mastra`. Add it to your Mastra project (and its peer dependencies):
+
+```bash copy
+npm install --legacy-peer-deps @ag-ui/mastra @copilotkit/runtime @ag-ui/core @ag-ui/client @ag-ui/encoder @ag-ui/langgraph @ag-ui/proto
+```
 
-```typescript title="src/mastra/index.ts" copy {2,5-8,12-28}
-import { Mastra } from "@mastra/core";
-import { registerCopilotKit } from "@ag-ui/mastra/copilotkit";
-import { weatherAgent } from "./agents/weather-agent";
+In your `src/mastra/index.ts` file, register the chat route:
 
-type WeatherRequestContext = {
-  "user-id": string;
-  "temperature-scale": "celsius" | "fahrenheit";
-};
+```typescript copy title="src/mastra/index.ts" {2,7-19}
+import { Mastra } from '@mastra/core/mastra';
+import { registerCopilotKit } from '@ag-ui/mastra/copilotkit';
+// Rest of the imports...
 
 export const mastra = new Mastra({
-  agents: { weatherAgent },
+  // Rest of the configuration...
   server: {
     cors: {
       origin: "*",
@@ -134,99 +108,78 @@ export const mastra = new Mastra({
       allowHeaders: ["*"],
     },
     apiRoutes: [
-      registerCopilotKit<WeatherRequestContext>({
-        path: "/copilotkit",
-        resourceId: "weatherAgent",
-        setContext: (c, requestContext) => {
-          requestContext.set(
-            "user-id",
-            c.req.header("X-User-ID") || "anonymous",
-          );
-          requestContext.set("temperature-scale", "celsius");
-        },
-      }),
-    ],
-  },
+      registerCopilotKit({
+        path: '/chat',
+        resourceId: 'weatherAgent'
+      })
+    ]
+  }
 });
 ```
 
+This will make the `weatherAgent` available at `/chat` in a CopilotKit-compatible format. You have to add the CORS configuration to allow the CopilotKit frontend to access the Mastra server. For production deployments, make sure to restrict the CORS origins to only your frontend domain.
+
 </StepItem>
 
 <StepItem>
 
-Use the component in your React app with your Mastra server URL:
-
-```tsx title="App.tsx" copy {5}
-import { CopilotKitComponent } from "./components/copilotkit-component";
-
-function App() {
-  return <CopilotKitComponent runtimeUrl="http://localhost:4111/copilotkit" />;
-}
+Run the Mastra server using the following command:
 
-export default App;
+```bash copy
+npm run dev
 ```
 
-Now start both the Mastra server and your frontend.
+By default, the Mastra server will run on `http://localhost:4111`. Keep this server running for the next steps where we'll set up the CopilotKit frontend to connect to it.
 
 </StepItem>
 
-  </Steps>
- </TabItem>
-
-  <TabItem value="nextjs" label="Next.js">
-
-  <Steps>
-
 <StepItem>
 
-In your Next.js app, install the required packages:
-
-<Tabs>
-<TabItem value="npm" label="npm">
+Go up one directory to your project root.
 
 ```bash copy
-npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/mastra@beta
+cd ..
 ```
 
-</TabItem>
-<TabItem value="yarn" label="yarn">
+Create a new Next.js project with the name `my-copilot-app`:
 
 ```bash copy
-yarn add @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/mastra@beta
+npx create-next-app@latest my-copilot-app
 ```
 
-</TabItem>
-<TabItem value="pnpm" label="pnpm">
+Navigate to your newly created Next.js project directory:
 
 ```bash copy
-pnpm add @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/mastra@beta
+cd my-copilot-app
 ```
 
-</TabItem>
-</Tabs>
-
 </StepItem>
 
 <StepItem>
 
-Create a CopilotKit component:
+Install the CopilotKit UI packages which you'll use to display a chat interface:
+
+```bash copy
+npm install @copilotkit/react-ui @copilotkit/react-core
+```
+
+Open the home route of the Next.js app (usually `app/page.tsx` or `src/app/page.tsx`) and replace the existing contents with the following code to set up a basic CopilotKit chat interface:
 
-```tsx title="components/copilotkit-component.tsx" copy
-'use client';
+```typescript copy title="app/page.tsx"
 import { CopilotChat } from "@copilotkit/react-ui";
 import { CopilotKit } from "@copilotkit/react-core";
 import "@copilotkit/react-ui/styles.css";
 
-export function CopilotKitComponent({ runtimeUrl }: { runtimeUrl: string}) {
+export default function Home() {
   return (
     <CopilotKit
-      runtimeUrl={runtimeUrl}
+      runtimeUrl="http://localhost:4111/chat"
       agent="weatherAgent"
     >
       <CopilotChat
         labels={{
-          title: "Your Assistant",
-          initial: "Hi! 👋 How can I assist you today?",
+          title: "Weather Agent",
+          initial: "Hi! 👋 Ask me about the weather, forecasts, and climate.",
         }}
       />
     </CopilotKit>
@@ -238,145 +191,16 @@ export function CopilotKitComponent({ runtimeUrl }: { runtimeUrl: string}) {
 
 <StepItem>
 
-There are two approaches for the API route determined by how you're integrating Mastra in your Next.js application.
-
-1. For a full-stack Next.js app with an instance of Mastra integrated into the app.
-2. For a Next.js app with a separate Mastra server and the Mastra Client SDK.
-
-<Tabs>
-  <TabItem value="mastra-instance" label="With a Mastra instance">
-
-Create an API route that connects to local Mastra agents.
-
-```typescript title="app/api/copilotkit/route.ts" copy {1-7,11-26}
-import { mastra } from "../../mastra";
-import {
-  CopilotRuntime,
-  ExperimentalEmptyAdapter,
-  copilotRuntimeNextJSAppRouterEndpoint,
-} from "@copilotkit/runtime";
-import { MastraAgent } from "@ag-ui/mastra";
-import { NextRequest } from "next/server";
-
-export const POST = async (req: NextRequest) => {
-  const mastraAgents = MastraAgent.getLocalAgents({
-    mastra,
-    agentId: "weatherAgent",
-  });
-
-  const runtime = new CopilotRuntime({
-    agents: mastraAgents,
-  });
-
-  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
-    runtime,
-    serviceAdapter: new ExperimentalEmptyAdapter(),
-    endpoint: "/api/copilotkit",
-  });
-
-  return handleRequest(req);
-};
-```
-
-  </TabItem>
-  <TabItem value="mastra-client" label="With the Mastra Client SDK">
-
-Install the Mastra Client SDK.
-
-<Tabs>
-<TabItem value="npm" label="npm">
-
-```bash copy
-npm install @mastra/client-js@beta
-```
-
-</TabItem>
-<TabItem value="yarn" label="yarn">
-
-```bash copy
-yarn add @mastra/client-js@beta
-```
-
-</TabItem>
-<TabItem value="pnpm" label="pnpm">
+You're ready to connect the pieces! Make sure both the Mastra server and the CopilotKit frontend are running. Start the Next.js development server:
 
 ```bash copy
-pnpm add @mastra/client-js@beta
+npm run dev
 ```
 
-</TabItem>
-</Tabs>
-
-Create an API route that connects to remote Mastra agents:
-
-```typescript title="app/api/copilotkit/route.ts" copy {1-7,12-26}
-import { MastraClient } from "@mastra/client-js";
-import {
-  CopilotRuntime,
-  ExperimentalEmptyAdapter,
-  copilotRuntimeNextJSAppRouterEndpoint,
-} from "@copilotkit/runtime";
-import { MastraAgent } from "@ag-ui/mastra";
-import { NextRequest } from "next/server";
-
-export const POST = async (req: NextRequest) => {
-  const baseUrl = process.env.MASTRA_BASE_URL || "http://localhost:4111";
-  const mastraClient = new MastraClient({ baseUrl });
-
-  const mastraAgents = await MastraAgent.getRemoteAgents({ mastraClient });
-
-  const runtime = new CopilotRuntime({
-    agents: mastraAgents,
-  });
-
-  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
-    runtime,
-    serviceAdapter: new ExperimentalEmptyAdapter(),
-    endpoint: "/api/copilotkit",
-  });
-
-  return handleRequest(req);
-};
-```
-
-  </TabItem>
-</Tabs>
+You should now be able to chat with your agent in the browser.
 
 </StepItem>
 
-<StepItem>
-
-Use the component with the local API endpoint:
-
-```tsx title="App.tsx" copy {5}
-import { CopilotKitComponent } from "./components/copilotkit-component";
-
-function App() {
-  return <CopilotKitComponent runtimeUrl="/api/copilotkit" />;
-}
-
-export default App;
-```
-
-</StepItem>
-
-  </Steps>
-  </TabItem>
-</Tabs>
-
-Start building the future!
-
-<br />
-
-<img
-  className="rounded-lg"
-  src="/img/copilotkit/cpkoutput.jpg"
-  alt="CopilotKit output"
-  style={{ maxWidth: "700px", width: "100%" }}
-/>
-
-## Next Steps
+</Steps>
 
-- [CopilotKit Documentation](https://docs.copilotkit.ai) - Complete CopilotKit reference
-- [React Hooks with CopilotKit](https://docs.copilotkit.ai/reference/hooks/useCoAgent) - Advanced React integration patterns
-- [Next.js Integration with Mastra](/docs/v1/frameworks/web-frameworks/next-js) - Full-stack Next.js setup guide
+Congratulations! You have successfully integrated Mastra with CopilotKit using a separate server approach. Your CopilotKit frontend now communicates with a standalone Mastra agent server.

package/.docs/raw/frameworks/agentic-uis/openrouter.mdx

@@ -1,14 +1,14 @@
 ---
-title: "Use OpenRouter with Mastra | Frameworks | Mastra Docs"
+title: "Using OpenRouter | Frameworks"
 description: "Learn how to integrate OpenRouter with Mastra"
 ---
 
 import Steps from "@site/src/components/Steps";
 import StepItem from "@site/src/components/StepItem";
 
-# Use OpenRouter with Mastra
+# Using OpenRouter
 
-Integrate OpenRouter with Mastra to leverage the numerous models available on OpenRouter.
+Integrate [OpenRouter](https://openrouter.ai/) with Mastra to leverage the numerous models available on OpenRouter.
 
 <Steps>
 

package/.docs/raw/frameworks/servers/express.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Integrate Mastra in your Express project | Frameworks | Mastra Docs"
+title: "Integrate Mastra in your Express project | Frameworks"
 description: A step-by-step guide to integrating Mastra with an Express backend.
 ---
 

package/.docs/raw/frameworks/web-frameworks/astro.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Integrate Mastra in your Astro project | Frameworks | Mastra Docs"
+title: "Integrate Mastra in your Astro project | Frameworks"
 description: A step-by-step guide to integrating Mastra with Astro.
 ---
 

package/.docs/raw/frameworks/web-frameworks/next-js.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Integrate Mastra in your Next.js project | Frameworks | Mastra Docs"
+title: "Integrate Mastra in your Next.js project | Frameworks"
 description: A step-by-step guide to integrating Mastra with Next.js.
 ---
 

package/.docs/raw/frameworks/web-frameworks/sveltekit.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Integrate Mastra in your SvelteKit project | Frameworks | Mastra Docs"
+title: "Integrate Mastra in your SvelteKit project | Frameworks"
 description: A step-by-step guide to integrating Mastra with SvelteKit.
 ---
 

package/.docs/raw/frameworks/web-frameworks/vite-react.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Integrate Mastra in your Vite/React project | Frameworks | Mastra Docs"
+title: "Integrate Mastra in your Vite/React project | Frameworks"
 description: A step-by-step guide to integrating Mastra with Vite and React.
 ---
 

package/.docs/raw/getting-started/mcp-docs-server.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Mastra Docs Server | Getting Started | Mastra Docs"
+title: "Mastra Docs Server | Getting Started"
 description: "Learn how to use the Mastra MCP documentation server in your IDE to turn it into an agentic Mastra expert."
 ---
 
@@ -31,7 +31,7 @@ If there are no specific instructions for your tool below, you may be able to ad
     "mastra": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@mastra/mcp-docs-server"]
+      "args": ["-y", "@mastra/mcp-docs-server@beta"]
     }
   }
 }
@@ -42,7 +42,7 @@ If there are no specific instructions for your tool below, you may be able to ad
 Install using the terminal command:
 
 ```bash copy
-claude mcp add mastra -- npx -y @mastra/mcp-docs-server
+claude mcp add mastra -- npx -y @mastra/mcp-docs-server@beta
 ```
 
 [More info on using MCP servers with Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)
@@ -52,7 +52,7 @@ claude mcp add mastra -- npx -y @mastra/mcp-docs-server
 1. Register it from the terminal:
 
    ```bash copy
-   codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server
+   codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@beta
    ```
 
 2. Run `codex mcp list` to confirm the server shows as `enabled`.
@@ -86,7 +86,7 @@ If you followed the automatic installation, you'll see a popup when you open cur
        "mastra": {
          "type": "stdio",
          "command": "npx",
-         "args": ["-y", "@mastra/mcp-docs-server"]
+         "args": ["-y", "@mastra/mcp-docs-server@beta"]
        }
      }
    }
@@ -135,7 +135,7 @@ After starting the MCP server, click the tools button in the Copilot pane to see
      "mcpServers": {
        "mastra": {
          "command": "npx",
-         "args": ["-y", "@mastra/mcp-docs-server"]
+         "args": ["-y", "@mastra/mcp-docs-server@beta"]
        }
      }
    }

package/.docs/raw/getting-started/project-structure.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Project Structure | Getting Started | Mastra Docs"
+title: "Project Structure | Getting Started"
 description: Guide on organizing folders and files in Mastra, including best practices and recommended structures.
 ---