@mastra/mcp-docs-server 1.1.5 → 1.1.6

package/.docs/guides/build-your-ui/assistant-ui.md

@@ -0,0 +1,156 @@
+# Using Assistant UI
+
+[Assistant UI](https://assistant-ui.com) is the TypeScript/React library for AI Chat. Built on shadcn/ui and Tailwind CSS, it enables developers to create beautiful, enterprise-grade chat experiences in minutes.
+
+> **Info:** For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [Full-Stack Integration Guide](https://www.assistant-ui.com/docs/runtimes/mastra/full-stack-integration) on Assistant UI's documentation site.
+
+> **Tip:** Visit Mastra's [**"UI Dojo"**](https://ui-dojo.mastra.ai/) to see real-world examples of Assistant UI integrated with Mastra.
+
+## Integration Guide
+
+Run Mastra as a standalone server and connect your Next.js frontend (with Assistant UI) to its API endpoints.
+
+1. Set up your directory structure. A possible directory structure could look like this:
+
+   ```bash
+   project-root
+   ├── mastra-server
+   │   ├── src
+   │   │   └── mastra
+   │   └── package.json
+   └── my-app
+       └── package.json
+   ```
+
+   Bootstrap your Mastra server:
+
+   ```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.
+
+   Navigate to your newly created Mastra server directory:
+
+   ```bash
+   cd mastra-server # Replace with the actual directory name you provided
+   ```
+
+   You now have a basic Mastra server project ready. You should have the following files and folders:
+
+   ```bash
+   src
+   └── mastra
+       ├── agents
+       │   └── weather-agent.ts
+       ├── scorers
+       │   └── weather-scorer.ts
+       ├── tools
+       │   └── weather-tool.ts
+       ├── workflows
+       │   └── weather-workflow.ts
+       └── index.ts
+   ```
+
+   > **Note:** Ensure that you have set the appropriate environment variables for your LLM provider in the `.env` file.
+
+2. Create a chat route for the Assistant UI frontend by using the `chatRoute()` helper from `@mastra/ai-sdk`. Add it to your Mastra project:
+
+   **npm**:
+
+   ```bash
+   npm install @mastra/ai-sdk@latest
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add @mastra/ai-sdk@latest
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add @mastra/ai-sdk@latest
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add @mastra/ai-sdk@latest
+   ```
+
+   In your `src/mastra/index.ts` file, register the chat route:
+
+   ```typescript
+   import { Mastra } from '@mastra/core/mastra'
+   import { chatRoute } from '@mastra/ai-sdk'
+   // Rest of the imports...
+
+   export const mastra = new Mastra({
+     // Rest of the configuration...
+     server: {
+       apiRoutes: [
+         chatRoute({
+           path: '/chat/:agentId',
+         }),
+       ],
+     },
+   })
+   ```
+
+   This will make all agents available in AI SDK-compatible formats, including the `weatherAgent` at the endpoint `/chat/weatherAgent`.
+
+3. Run the Mastra server using the following command:
+
+   ```bash
+   npm run dev
+   ```
+
+   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 Assistant UI frontend to connect to it.
+
+4. Go up one directory to your project root.
+
+   ```bash
+   cd ..
+   ```
+
+   Create a new `assistant-ui` project with the following command.
+
+   ```bash
+   npx assistant-ui@latest create
+   ```
+
+   > **Note:** For detailed setup instructions, including adding API keys, basic configuration, and manual setup steps, please refer to [assistant-ui's official documentation](https://assistant-ui.com/docs).
+
+5. 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 file in your assistant-ui frontend project that contains the `useChatRuntime` hook (usually `app/assistant.tsx` or `src/app/assistant.tsx`). Find the `useChatRuntime` hook and change the `api` property to the full URL of your Mastra agent's stream endpoint:
+
+   ```tsx
+   'use client'
+
+   // Rest of the imports...
+
+   export const Assistant = () => {
+     const runtime = useChatRuntime({
+       transport: new AssistantChatTransport({
+         api: 'http://localhost:4111/chat/weatherAgent',
+       }),
+     })
+
+     // Rest of the component...
+   }
+   ```
+
+   Now, the Assistant UI frontend will send chat requests directly to your running Mastra server.
+
+6. You're ready to connect the pieces! Make sure both the Mastra server and the Assistant UI frontend are running. Start the Next.js development server:
+
+   ```bash
+   npm run dev
+   ```
+
+   You should now be able to chat with your agent in the browser.
+
+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.

package/.docs/guides/build-your-ui/copilotkit.md

@@ -0,0 +1,289 @@
+# Using CopilotKit
+
+[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.
+
+> **Info:** 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.
+
+> **Tip:** Visit Mastra's [**"UI Dojo"**](https://ui-dojo.mastra.ai/) to see real-world examples of CopilotKit integrated with Mastra.
+
+## Integration Guide
+
+Run Mastra as a standalone server and connect your Next.js frontend (with CopilotKit) to its API endpoints.
+
+1. Set up your directory structure. A possible directory structure could look like this:
+
+   ```bash
+   project-root
+   ├── mastra-server
+   │   ├── src
+   │   │   └── mastra
+   │   └── package.json
+   └── my-copilot-app
+       └── package.json
+   ```
+
+   Bootstrap your Mastra server:
+
+   **npm**:
+
+   ```bash
+   npx create-mastra@latest
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm dlx create-mastra@latest
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn dlx create-mastra@latest
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun x 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.
+
+   Navigate to your newly created Mastra server directory:
+
+   ```bash
+   cd mastra-server # Replace with the actual directory name you provided
+   ```
+
+   You now have a basic Mastra server project ready. You should have the following files and folders:
+
+   ```bash
+   src
+   └── mastra
+       ├── agents
+       │   └── weather-agent.ts
+       ├── scorers
+       │   └── weather-scorer.ts
+       ├── tools
+       │   └── weather-tool.ts
+       ├── workflows
+       │   └── weather-workflow.ts
+       └── index.ts
+   ```
+
+   > **Note:** Ensure that you have set the appropriate environment variables for your LLM provider in the `.env` file.
+
+2. 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):
+
+   **npm**:
+
+   ```bash
+   npm install @ag-ui/mastra @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client @copilotkit/runtime
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add @ag-ui/mastra @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client @copilotkit/runtime
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add @ag-ui/mastra @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client @copilotkit/runtime
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add @ag-ui/mastra @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client @copilotkit/runtime
+   ```
+
+   In your `src/mastra/index.ts` file, register the chat route:
+
+   ```typescript
+   import { Mastra } from '@mastra/core/mastra'
+   import { registerCopilotKit } from '@ag-ui/mastra/copilotkit'
+   // Rest of the imports...
+
+   export const mastra = new Mastra({
+     // Rest of the configuration...
+     server: {
+       cors: {
+         origin: '*',
+         allowMethods: ['*'],
+         allowHeaders: ['*'],
+       },
+       apiRoutes: [
+         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.
+
+3. Run the Mastra server using the following command:
+
+   **npm**:
+
+   ```bash
+   npm run dev
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm run dev
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn dev
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun run dev
+   ```
+
+   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.
+
+4. Go up one directory to your project root.
+
+   ```bash
+   cd ..
+   ```
+
+   Create a new Next.js project with the name `my-copilot-app`:
+
+   **npm**:
+
+   ```bash
+   npx create-next-app@latest my-copilot-app
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm dlx create-next-app@latest my-copilot-app
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn dlx create-next-app@latest my-copilot-app
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun x create-next-app@latest my-copilot-app
+   ```
+
+   Navigate to your newly created Next.js project directory:
+
+   ```bash
+   cd my-copilot-app
+   ```
+
+5. Install the CopilotKit UI packages which you'll use to display a chat interface:
+
+   **npm**:
+
+   ```bash
+   npm install @copilotkit/react-ui @copilotkit/react-core
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add @copilotkit/react-ui @copilotkit/react-core
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add @copilotkit/react-ui @copilotkit/react-core
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add @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:
+
+   ```typescript
+   import { CopilotChat } from '@copilotkit/react-ui'
+   import { CopilotKit } from '@copilotkit/react-core'
+   import '@copilotkit/react-ui/styles.css'
+
+   export default function Home() {
+     return (
+       <CopilotKit runtimeUrl="http://localhost:4111/chat" agent="weatherAgent">
+         <CopilotChat
+           labels={{
+             title: 'Weather Agent',
+             initial: 'Hi! 👋 Ask me about the weather, forecasts, and climate.',
+           }}
+         />
+       </CopilotKit>
+     )
+   }
+   ```
+
+6. 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:
+
+   **npm**:
+
+   ```bash
+   npm run dev
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm run dev
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn dev
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun run dev
+   ```
+
+   You should now be able to chat with your agent in the browser.
+
+Congratulations! You have successfully integrated Mastra with CopilotKit using a separate server approach. Your CopilotKit frontend now communicates with a standalone Mastra agent server.
+
+## Deployment
+
+When deploying your Mastra server with CopilotKit, you must exclude `@copilotkit/runtime` from the bundle. This package contains dependencies that are not compatible with bundling and will cause 500 errors if included.
+
+> **Note:** This issue doesn't occur during development with `mastra dev` since it doesn't require bundling. However, anyone running `mastra build` for deployment will encounter this issue.
+
+Add the `@copilotkit/runtime` package to your bundler externals configuration:
+
+```typescript
+export const mastra = new Mastra({
+  bundler: {
+    externals: ['@copilotkit/runtime'],
+  },
+})
+```

package/.docs/guides/deployment/amazon-ec2.md

@@ -0,0 +1,130 @@
+# Deploy Mastra to Amazon EC2
+
+Deploy your Mastra server to Amazon EC2. This gives you full control over your server environment and supports long-running agents and workflows.
+
+> **Info:** This guide covers deploying the [Mastra server](https://mastra.ai/docs/server/mastra-server). If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.
+
+## Before you begin
+
+You'll need:
+
+- A [Mastra application](https://mastra.ai/guides/getting-started/quickstart)
+- An [EC2](https://aws.amazon.com/ec2/) instance (Ubuntu or Amazon Linux) with Git and Node.js 22.13.0+ installed
+
+For production, you'll also need:
+
+- A domain name pointing to your instance (required for SSL certificates)
+- An SSL certificate for your domain (e.g., using [Certbot](https://certbot.eff.org/) with Let's Encrypt)
+- A reverse proxy (e.g., [nginx](https://nginx.org/)) to forward traffic to your application
+
+## Deploy
+
+1. Connect to your EC2 instance and clone your repository:
+
+   **Public Repository**:
+
+   ```bash
+   git clone https://github.com/<your-username>/<your-repository>.git
+   ```
+
+   **Private Repository**:
+
+   ```bash
+   git clone git@github.com:<your-username>/<your-repository>.git
+   ```
+
+   Navigate to the repository directory:
+
+   ```bash
+   cd "<your-repository>"
+   ```
+
+2. Install dependencies:
+
+   **npm**:
+
+   ```bash
+   npm install
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm install
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn install
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun install
+   ```
+
+3. Create a `.env` file and add your environment variables:
+
+   ```bash
+   touch .env
+   ```
+
+   Remember to set your environment variables needed to run your application (e.g. your model provider API key):
+
+   ```bash
+   OPENAI_API_KEY=<your-openai-api-key>
+   # Add other required environment variables
+   ```
+
+4. Build the application:
+
+   **npm**:
+
+   ```bash
+   npm run build
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm run build
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn build
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun run build
+   ```
+
+5. Run the application:
+
+   ```bash
+   node --env-file=".env" .mastra/output/index.mjs
+   ```
+
+   This is a basic example. In production, use a process manager like [PM2](https://pm2.keymetrics.io/) or [systemd](https://systemd.io/) to keep your application running and handle restarts.
+
+   > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.
+
+6. Your Mastra server is now running on port 4111, but it's only accessible locally.
+
+   You can open port 4111 in your EC2 security group for direct access, or configure a reverse proxy (such as nginx) to listen on ports 80 and 443 and forward requests to `http://localhost:4111`.
+
+   In production, you should use a reverse proxy so you can configure HTTPS. HTTPS encrypts traffic and is required for most webhook integrations and external services your agents interact with.
+
+7. Verify your deployment at `https://<your-ec2-address>/api/agents`, which should return a JSON list of your agents.
+
+8. You can now call your Mastra endpoints over HTTP.
+
+## Next steps
+
+- [Connect from a Mastra Client](https://mastra.ai/docs/server/mastra-client)
+- [Deployment overview](https://mastra.ai/docs/deployment/overview)