@mastra/mcp-docs-server 0.13.2-alpha.3 → 0.13.3-alpha.0

package/.docs/raw/deployment/serverless-platforms/cloudflare-deployer.mdx

@@ -0,0 +1,111 @@
+---
+title: "Cloudflare Deployer"
+description: "Learn how to deploy a Mastra application to Cloudflare using the Mastra CloudflareDeployer"
+---
+
+import { FileTree } from "nextra/components";
+
+# CloudflareDeployer
+
+The `CloudflareDeployer` class handles deployment of standalone Mastra applications to Cloudflare Workers. It manages configuration, deployment, and extends the base [Deployer](/reference/deployer/deployer) class with Cloudflare specific functionality.
+
+## Installation
+
+```bash copy
+npm install @mastra/deployer-cloudflare@latest
+```
+
+## Usage example
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { CloudflareDeployer } from "@mastra/deployer-cloudflare";
+
+export const mastra = new Mastra({
+  // ...
+  deployer: new CloudflareDeployer({
+    projectName: "hello-mastra",
+    scope: "",
+    auth: {
+      apiToken: process.env.CLOUDFLARE_API_TOKEN!,
+      apiEmail: "name@email.com"
+    }
+  })
+});
+```
+
+> See the [CloudflareDeployer](/reference/deployer/cloudflare) API reference for all available configuration options.
+
+### Cloudflare API token
+
+In your Cloudflare dashboard, navigate to **Profile** > **API Tokens**, then select **Edit Cloudflare Workers** and click **Use template** to create a token for the `CloudflareDeployer`.
+
+> To learn how to create a Cloudflare API token, see [Create API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) in the Cloudflare docs.
+
+## Continuous integration
+In the Cloudflare dashboard, navigate to **Workers** > **Import a repository**. After importing your Mastra project's Git repository, create an application and configure the build settings with:
+
+- **Build command**: `npm run build`
+- **Deploy command**: `cd .mastra/output && npx wrangler deploy`
+
+- **Build command**: `npm run build` (optional)
+
+## Manual deployment
+
+Manual deployments are also possible using the [Cloudflare Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/). With the Wrangler CLI installed run the following from your project root to deploy your application.
+
+```bash copy
+npm run build && wrangler deploy --config .mastra/output/wrangler.json
+```
+
+> You can also run `wrangler dev --config .mastra/output/wrangler.json` from your project root to test your Mastra application locally.
+
+## Cloudflare secrets
+
+To add secrets to your Cloudflare Workers application, use the Wrangler CLI. Secrets are environment variables that are encrypted and stored securely.
+
+
+For example, to add an API key:
+
+```bash copy
+npx wrangler secret put OPENAI_API_KEY
+```
+
+When prompted, enter the secret value. The secret will be encrypted and stored securely in your Cloudflare account.
+
+> For more details on managing secrets, see [Environment Variables and Secrets](https://developers.cloudflare.com/workers/configuration/secrets/) in the Cloudflare documentation.
+
+## Build output
+
+The build output for Mastra applications using the `CloudflareDeployer` includes all agents, tools, and workflows in your project, along with Mastra specific files required to run your application on Cloudflare.
+
+<FileTree>
+  <FileTree.Folder name=".mastra" defaultOpen>
+    <FileTree.Folder name="output" defaultOpen>
+      <FileTree.File name="index.mjs" />
+      <FileTree.File name="wrangler.json" />
+      </FileTree.Folder>
+  </FileTree.Folder>
+  <FileTree.File name="package.json" />
+</FileTree>
+
+The `CloudflareDeployer` automatically generates a `wrangler.json` configuration file in `.mastra/output` with the following settings:
+
+```json
+{
+  "name": "hello-mastra",
+  "main": "./index.mjs",
+  "compatibility_date": "2025-04-01",
+  "compatibility_flags": ["nodejs_compat", "nodejs_compat_populate_process_env"],
+  "observability": { "logs": { "enabled": true } },
+  "vars": {
+    "OPENAI_API_KEY": "..",
+    "CLOUDFLARE_API_TOKEN": "..."
+  }
+}
+```
+
+
+## Next steps
+
+- [Mastra Client SDK](/docs/client-js/overview)

package/.docs/raw/deployment/{deployment.mdx → serverless-platforms/index.mdx}

@@ -5,7 +5,11 @@ description: "Build and deploy Mastra applications using platform-specific deplo
 
 # Serverless Deployment
 
-This guide covers deploying standalone Mastra applications to Cloudflare Workers, Vercel, and Netlify using platform-specific deployers.
+Standalone Mastra applications can be deployed to popular serverless platforms using one of our deployer packages:
+
+- [Cloudflare](/docs/deployment/serverless-platforms/cloudflare-deployer)
+- [Netlify](/docs/deployment/serverless-platforms/netlify-deployer)
+- [Vercel](/docs/deployment/serverless-platforms/vercel-deployer)
 
 Deployers **aren't** required when integrating Mastra with a framework. See [Web Framework Integration](/docs/deployment/web-framework) for more information.
 
@@ -47,12 +51,3 @@ export const weatherAgent = new Agent({
 -  })
 });
 ```
-
-## Serverless Platform Deployers
-
-Platform-specific deployers handle configuration and deployment for:
-
-- **[Cloudflare Workers](/reference/deployer/cloudflare)**
-- **[Vercel](/reference/deployer/vercel)**
-- **[Netlify](/reference/deployer/netlify)**
-- **[Mastra Cloud](/docs/mastra-cloud/overview)** _(beta)_. You can join the [cloud waitlist](https://mastra.ai/cloud-beta) for early access.

package/.docs/raw/deployment/serverless-platforms/netlify-deployer.mdx

@@ -0,0 +1,94 @@
+---
+title: "Netlify Deployer"
+description: "Learn how to deploy a Mastra application to Netlify using the Mastra NetlifyDeployer"
+---
+
+import { FileTree } from "nextra/components";
+
+# NetlifyDeployer
+
+The `NetlifyDeployer` class handles deployment of standalone Mastra applications to Netlify. It manages configuration, deployment, and extends the base [Deployer](/reference/deployer/deployer) class with Netlify specific functionality.
+
+## Installation
+
+```bash copy
+npm install @mastra/deployer-netlify@latest
+```
+
+## Usage example
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { NetlifyDeployer } from "@mastra/deployer-netlify";
+
+export const mastra = new Mastra({
+  // ...
+  deployer: new NetlifyDeployer()
+});
+```
+
+> See the [NetlifyDeployer](/reference/deployer/netlify) API reference for all available configuration options.
+
+## Continuous integration
+
+After connecting your Mastra project’s Git repository to Netlify, update the project settings. In the Netlify dashboard, go to **Project configuration** > **Build & deploy** > **Continuous deployment**, and under **Build settings**, set the following:
+
+- **Build command**: `npm run build` (optional)
+
+### Environment variables
+
+Before your first deployment, make sure to add any environment variables used by your application. For example, if you're using OpenAI as the LLM, you'll need to set `OPENAI_API_KEY` in your Netlify project settings.
+
+> See [Environment variables overview](https://docs.netlify.com/environment-variables/overview/) for more details.
+
+
+Your project is now configured with automatic deployments which occur whenever you push to the configured branch of your GitHub repository.
+
+
+## Manual deployment
+
+Manual deployments are also possible using the [Netlify CLI](https://docs.netlify.com/cli/get-started/). With the Netlify CLI installed run the following from your project root to deploy your application.
+
+```bash copy
+netlify deploy --prod
+```
+
+> You can also run `netlify dev` from your project root to test your Mastra application locally.
+
+## Build output
+
+The build output for Mastra applications using the `NetlifyDeployer` includes all agents, tools, and workflows in your project, along with Mastra specific files required to run your application on Netlify.
+
+<FileTree>
+  <FileTree.Folder name=".netlify" defaultOpen>
+    <FileTree.Folder name="v1" defaultOpen>
+      <FileTree.Folder name="functions" defaultOpen>
+        <FileTree.Folder name="api" defaultOpen>
+          <FileTree.File name="index.mjs" />
+        </FileTree.Folder>
+      </FileTree.Folder>
+    <FileTree.File name="config.json" />
+    </FileTree.Folder>
+  </FileTree.Folder>
+  <FileTree.File name="package.json" />
+</FileTree>
+
+
+The `NetlifyDeployer` automatically generates a `config.json` configuration file in `.netlify/v1` with the following settings:
+
+```json
+{
+  "redirects": [
+    {
+      "force": true,
+      "from": "/*",
+      "to": "/.netlify/functions/api/:splat",
+      "status": 200
+    }
+  ]
+}
+```
+
+## Next steps
+
+- [Mastra Client SDK](/docs/client-js/overview)

package/.docs/raw/deployment/serverless-platforms/vercel-deployer.mdx

@@ -0,0 +1,91 @@
+---
+title: "Vercel Deployer"
+description: "Learn how to deploy a Mastra application to Vercel using the Mastra VercelDeployer"
+---
+
+import { FileTree } from "nextra/components";
+
+# VercelDeployer
+
+The `VercelDeployer` class handles deployment of standalone Mastra applications to Vercel. It manages configuration, deployment, and extends the base [Deployer](/reference/deployer/deployer) class with Vercel specific functionality.
+
+## Installation
+
+```bash copy
+npm install @mastra/deployer-vercel@latest
+```
+
+## Usage example
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { VercelDeployer } from "@mastra/deployer-vercel";
+
+export const mastra = new Mastra({
+  // ...
+  deployer: new VercelDeployer()
+});
+```
+
+> See the [VercelDeployer](/reference/deployer/vercel) API reference for all available configuration options.
+
+## Continuous integration
+
+After connecting your Mastra project’s Git repository to Vercel, update the project settings. In the Vercel dashboard, go to **Settings** > **Build and Deployment**, and under **Framework settings**, set the following:
+
+- **Build command**: `npm run build` (optional)
+
+### Environment variables
+
+Before your first deployment, make sure to add any environment variables used by your application. For example, if you're using OpenAI as the LLM, you'll need to set `OPENAI_API_KEY` in your Vercel project settings.
+
+> See [Environment variables](https://vercel.com/docs/environment-variables) for more details.
+
+Your project is now configured with automatic deployments which occur whenever you push to the configured branch of your GitHub repository.
+
+## Manual deployment
+
+Manual deployments are also possible using the [Vercel CLI](https://vercel.com/docs/cli). With the Vercel CLI installed run the following from your project root to deploy your application.
+
+```bash copy
+npm run build && vercel --prod --prebuilt --archive=tgz
+```
+
+> You can also run `vercel dev` from your project root to test your Mastra application locally.
+
+## Build output
+
+The build output for Mastra applications using the `VercelDeployer` includes all agents, tools, and workflows in your project, along with Mastra specific files required to run your application on Vercel.
+
+<FileTree>
+  <FileTree.Folder name=".vercel" defaultOpen>
+    <FileTree.Folder name="output" defaultOpen>
+      <FileTree.Folder name="functions" defaultOpen>
+        <FileTree.Folder name="index.func" defaultOpen>
+          <FileTree.File name="index.mjs" />
+        </FileTree.Folder>
+      </FileTree.Folder>
+      <FileTree.File name="config.json" />
+    </FileTree.Folder>
+  </FileTree.Folder>
+  <FileTree.File name="package.json" />
+</FileTree>
+
+
+The `VercelDeployer` automatically generates a `config.json` configuration file in `.vercel/output` with the following settings:
+
+```json
+{
+  "version": 3,
+  "routes": [
+    {
+      "src": "/(.*)",
+      "dest": "/"
+    }
+  ]
+}
+```
+
+## Next steps
+
+- [Mastra Client SDK](/docs/client-js/overview)

package/.docs/raw/frameworks/ai-sdk-v5.mdx

@@ -0,0 +1,91 @@
+# AI SDK v5 (beta) Migration Guide
+
+This guide covers Mastra-specific considerations when migrating from AI SDK v4 to v5 beta.
+
+Please add any feedback or bug reports to the [AI SDK v5 mega issue in Github.](https://github.com/mastra-ai/mastra/issues/5470)
+
+## Official Migration Guide
+
+**Follow the official [AI SDK v5 Migration Guide](https://v5.ai-sdk.dev/docs/migration-guides/migration-guide-5-0)** for all AI SDK core breaking changes, package updates, and API changes.
+
+This guide covers only the Mastra-specific aspects of the migration.
+
+## Warnings
+
+- **Data compatibility**: New data stored in v5 format will no longer work if you downgrade from the beta
+- **Backup recommendation**: Keep DB backups from before you upgrade to v5 beta
+- **Production use**: Wait for the AI SDK v5 stable release before using in production applications
+- **Prerelease status**: The Mastra `ai-v5` tag is a prerelease version and may have bugs
+
+## Memory Storage
+
+Your existing AI SDK v4 data will run through our internal `MessageList` class which handles converting to/from various message formats.
+This includes converting from AI SDK v4->v5. This means you don't need to run any DB migrations and your data will be translated on the fly and will just work when you upgrade.
+
+
+## Migration Strategy
+
+Migrating to AI SDK v5 with Mastra involves updating both your **backend** (Mastra server) and **frontend**.
+We provide a compatibility mode to handle stream format conversion during the transition.
+
+### Backend Upgrade
+
+Bump Mastra to the new `ai-v5` prerelease version for all Mastra packages:
+
+```bash npm2yarn copy
+npm i mastra@ai-v5 @mastra/core@ai-v5 @mastra/memory@ai-v5 [etc]
+```
+
+Then configure your Mastra instance with v4 compatibility so your existing frontend will continue to work:
+
+```typescript
+import { Mastra } from '@mastra/core';
+
+export const mastra = new Mastra({
+  agents: { myAgent },
+  aiSdkCompat: 'v4', // <- add this for compatibility
+});
+```
+
+#### Dependencies
+
+You will need to upgrade all AI SDK dependencies to use the new v5 beta versions in your backend when you bump to the Mastra `ai-v5` prerelease tag.
+
+In most cases this will only involve bumping your model provider packages. For example: `npm i @ai-sdk/openai@2.0.0-beta.1` - refer to the [AI SDK v5 documentation](https://v5.ai-sdk.dev/docs/migration-guides/migration-guide-5-0) for more info. Some model providers do not yet have V5 versions (Openrouter for example).
+
+Also note that you need to bump all your Mastra dependencies to the new `ai-v5` tag, and you must upgrade `zod` to the latest version if you have it installed.
+
+#### Using Stream Compatibility Manually
+
+If you have a frontend that calls Mastra agents in an endpoint, you can wrap the new `response.toUIMessageStreamResponse()` manually.
+
+```ts
+import { mastra } from "@/src/mastra";
+import { createV4CompatibleResponse } from "@mastra/core/agent";
+
+const myAgent = mastra.getAgent("weatherAgent");
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const stream = await myAgent.stream(messages);
+
+  return createV4CompatibleResponse(stream.toUIMessageStreamResponse().body!);
+}
+```
+
+### Using Mastra Playground
+
+Currently playground is still an AI SDK v4 frontend. For now you need to set `aiSdkCompat: 'v4'` for it to work.
+We'll handle this automatically for you soon.
+
+### Frontend Upgrade
+
+When you're ready, remove the compatibility flag and upgrade your frontend:
+
+1. Remove `aiSdkCompat: 'v4'` from your Mastra configuration
+2. Follow the AI SDK guide on upgrading your frontend dependencies
+3. Update your frontend code for v5 breaking changes
+
+## Discussion and Bug Reports
+
+Please add any feedback or bug reports to the [AI SDK v5 mega issue in Github.](https://github.com/mastra-ai/mastra/issues/5470)
+

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

@@ -79,17 +79,36 @@ If you prefer to customize the setup, run the `init` command and choose from the
 npx mastra@latest init
 ```
 
+<Callout type="warning">
+By default, `mastra init` suggests `src` as the install location. If you're using the App Router at the root of your project (e.g., `app`, not `src/app`), enter `.` when prompted:
+</Callout>
+
 Add the `dev` and `build` scripts to `package.json`:
 
-```json filename="package.json"
-{
-  "scripts": {
-    ...
-    "dev:mastra": "mastra dev --dir mastra",
-    "build:mastra": "mastra build --dir mastra"
-  }
-}
-```
+<Tabs items={["app", "src/app"]}>
+  <Tabs.Tab>
+    ```json filename="package.json"
+    {
+      "scripts": {
+        ...
+        "dev:mastra": "mastra dev --dir mastra",
+        "build:mastra": "mastra build --dir mastra"
+      }
+    }
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```json filename="package.json"
+    {
+      "scripts": {
+        ...
+        "dev:mastra": "mastra dev --dir src/mastra",
+        "build:mastra": "mastra build --dir src/mastra"
+      }
+    }
+    ```
+  </Tabs.Tab>
+</Tabs>
 
 ## Configure TypeScript
 
@@ -324,17 +343,36 @@ If you prefer to customize the setup, run the `init` command and choose from the
 npx mastra@latest init
 ```
 
+<Callout type="warning">
+By default, `mastra init` suggests `src` as the install location. If you're using the Pages Router at the root of your project (e.g., `pages`, not `src/pages`), enter `.` when prompted:
+</Callout>
+
 Add the `dev` and `build` scripts to `package.json`:
 
-```json filename="package.json"
-{
-  "scripts": {
-    ...
-    "dev:mastra": "mastra dev --dir mastra",
-    "build:mastra": "mastra build --dir mastra"
-  }
-}
-```
+<Tabs items={["pages", "src/pages"]}>
+  <Tabs.Tab>
+    ```json filename="package.json"
+    {
+      "scripts": {
+        ...
+        "dev:mastra": "mastra dev --dir mastra",
+        "build:mastra": "mastra build --dir mastra"
+      }
+    }
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```json filename="package.json"
+    {
+      "scripts": {
+        ...
+        "dev:mastra": "mastra dev --dir src/mastra",
+        "build:mastra": "mastra build --dir src/mastra"
+      }
+    }
+    ```
+  </Tabs.Tab>
+</Tabs>
 
 ## Configure TypeScript