@mastra/mcp-docs-server 0.13.17-alpha.3 → 0.13.17-alpha.5

package/.docs/organized/code-examples/heads-up-game.md

@@ -126,16 +126,10 @@ export const mastra = new Mastra({
 ```typescript
 import { createWorkflow, createStep } from '@mastra/core/workflows';
 import { z } from 'zod';
-import { Pool } from 'pg';
-
-// PostgreSQL client
-const pool = new Pool({
-  connectionString: process.env.DATABASE_URL!,
-});
 
 const startStep = createStep({
   id: 'start-step',
-  description: "Generate a famous person's name",
+  description: 'Get the name of a famous person',
   inputSchema: z.object({
     start: z.boolean(),
   }),
@@ -169,7 +163,7 @@ const gameStep = createStep({
     userMessage: z.string(),
   }),
   suspendSchema: z.object({
-    agentResponse: z.string(),
+    suspendResponse: z.string(),
   }),
   outputSchema: z.object({
     famousPerson: z.string(),
@@ -181,52 +175,36 @@ const gameStep = createStep({
     let { famousPerson, guessCount } = inputData;
     const { userMessage } = resumeData ?? {};
 
+    // Return suspend with message to inform the user
     if (!userMessage) {
-      // First time - ask for a question
-      const message = "I'm thinking of a famous person. Ask me yes/no questions to figure out who it is!";
-
-      await suspend({
-        agentResponse: message,
+      return await suspend({
+        suspendResponse: "I'm thinking of a famous person. Ask me yes/no questions to figure out who it is!",
       });
-
-      return { famousPerson, gameWon: false, agentResponse: message, guessCount };
-    } else {
-      // Check if the user's message is a guess by using the guess verifier agent
-      const guessVerifier = mastra.getAgent('guessVerifierAgent');
-      const verificationResponse = await guessVerifier.generate(
-        [
-          {
-            role: 'user',
-            content: `Actual famous person: ${famousPerson}
-              User's guess: "${userMessage}"
-              Is this correct?`,
-          },
-        ],
-        {
-          output: z.object({
-            isCorrect: z.boolean(),
-          }),
-        },
-      );
-
-      const gameWon = verificationResponse.object.isCorrect;
-
-      // Let the agent handle the user's message (question or guess)
-      const agent = mastra.getAgent('gameAgent');
-      const response = await agent.generate(`
-      The famous person is: ${famousPerson}
-      The user asked: "${userMessage}"
-      Is this a correct guess: ${gameWon}
-      Please respond appropriately.
-    `);
-
-      const agentResponse = response.text;
-
-      // Increment the guess count
-      guessCount++;
-
-      return { famousPerson, gameWon, agentResponse, guessCount };
     }
+
+    // Let the agent handle the user's message (question or guess)
+    const agent = mastra.getAgent('gameAgent');
+    const response = await agent.generate(
+      `
+        The famous person is: ${famousPerson}
+        The user said: "${userMessage}"
+        Please respond appropriately. If this is a guess, tell me if it's correct.
+      `,
+      {
+        output: z.object({
+          response: z.string(),
+          gameWon: z.boolean(),
+        }),
+      },
+    );
+
+    // Values from structured output object
+    const { response: agentResponse, gameWon } = response.object;
+
+    // Increment the guess count
+    guessCount++;
+
+    return { famousPerson, gameWon, agentResponse, guessCount };
   },
 });
 
@@ -247,11 +225,9 @@ const winStep = createStep({
   execute: async ({ inputData }) => {
     const { famousPerson, gameWon, guessCount } = inputData;
 
-    await pool.query('INSERT INTO heads_up_games (famous_person, game_won, guess_count) VALUES ($1, $2, $3)', [
-      famousPerson,
-      gameWon,
-      guessCount,
-    ]);
+    console.log('famousPerson: ', famousPerson);
+    console.log('gameWon: ', gameWon);
+    console.log('guessCount: ', guessCount);
 
     return { famousPerson, gameWon, guessCount };
   },

package/.docs/organized/code-examples/mcp-configuration.md

@@ -9,8 +9,8 @@
     "@mastra/memory": "latest",
     "@modelcontextprotocol/sdk": "^1.13.0",
     "chalk": "^5.4.1",
-    "zod": "^3.25.67",
-    "zod-to-json-schema": "^3.24.5"
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.24.6"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",

package/.docs/organized/code-examples/mcp-registry-registry.md

@@ -7,7 +7,7 @@
     "@mastra/core": "latest",
     "@mastra/mcp": "latest",
     "@mastra/mcp-registry-registry": "latest",
-    "zod": "^3.25.67"
+    "zod": "^3.25.76"
   }
 }
 ```

package/.docs/organized/code-examples/memory-with-mem0.md

@@ -6,7 +6,7 @@
     "@ai-sdk/openai": "latest",
     "@mastra/core": "latest",
     "@mastra/mem0": "latest",
-    "zod": "^3.25.67"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^22.15.29",

package/.docs/organized/code-examples/memory-with-processors.md

@@ -12,7 +12,7 @@
     "js-tiktoken": "^1.0.13",
     "tiktoken": "^1.0.13",
     "tsx": "^4.6.2",
-    "zod": "^3.25.67"
+    "zod": "^3.25.76"
   }
 }
 ```

package/.docs/organized/code-examples/openapi-spec-writer.md

@@ -16,7 +16,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.454.0",
-    "next": "15.2.4",
+    "next": "15.4.7",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "react-syntax-highlighter": "^15.6.1",
@@ -24,7 +24,7 @@
     "tailwind-merge": "^2.6.0",
     "tailwindcss-animate": "^1.0.7",
     "vaul": "^1.1.2",
-    "zod": "^3.25.67"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@libsql/client": "^0.15.4",

package/.docs/organized/code-examples/quick-start.md

@@ -6,7 +6,7 @@
     "@types/node": "^20.17.57",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",
-    "zod": "^3.25.67"
+    "zod": "^3.25.76"
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^1.2.12",

package/.docs/organized/code-examples/stock-price-tool.md

@@ -5,7 +5,7 @@
   "dependencies": {
     "@ai-sdk/openai": "latest",
     "@mastra/core": "latest",
-    "zod": "^3.25.67"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",

package/.docs/organized/code-examples/weather-agent.md

@@ -6,7 +6,7 @@
     "@ai-sdk/openai": "^1.3.24",
     "@mastra/core": "latest",
     "@mastra/libsql": "latest",
-    "zod": "^3.25.67"
+    "zod": "^3.25.76"
   }
 }
 ```

package/.docs/organized/code-examples/workflow-ai-recruiter.md

@@ -7,7 +7,7 @@
     "mastra": "latest",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",
-    "zod": "^3.25.67"
+    "zod": "^3.25.76"
   },
   "dependencies": {
     "@ai-sdk/openai": "latest",

package/.docs/organized/code-examples/workflow-with-inline-steps.md

@@ -7,7 +7,7 @@
     "mastra": "latest",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",
-    "zod": "^3.25.67"
+    "zod": "^3.25.76"
   },
   "dependencies": {
     "@mastra/core": "latest"

package/.docs/organized/code-examples/workflow-with-memory.md

@@ -6,7 +6,7 @@
     "@types/node": "^20.17.57",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",
-    "zod": "^3.25.67"
+    "zod": "^3.25.76"
   },
   "dependencies": {
     "@ai-sdk/openai": "latest",

package/.docs/organized/code-examples/workflow-with-separate-steps.md

@@ -7,7 +7,7 @@
     "mastra": "latest",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",
-    "zod": "^3.25.67"
+    "zod": "^3.25.76"
   },
   "dependencies": {
     "@mastra/core": "latest"

package/.docs/organized/code-examples/workflow-with-suspend-resume.md

@@ -7,7 +7,7 @@
     "mastra": "latest",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",
-    "zod": "^3.25.67"
+    "zod": "^3.25.76"
   },
   "dependencies": {
     "@mastra/core": "latest",

package/.docs/raw/agents/overview.mdx

@@ -3,6 +3,8 @@ title: "Agent Overview | Agent Documentation | Mastra"
 description: Overview of agents in Mastra, detailing their capabilities and how they interact with tools, workflows, and external systems.
 ---
 
+import { Steps } from "nextra/components";
+
 # Using Agents
 
 Agents let you build intelligent assistants powered by language models that can make decisions and perform actions. Each agent has required instructions and an LLM, with optional tools and memory.
@@ -261,14 +263,43 @@ const response = await testAgent.generate("Help me organize my day", {
 ```
 
 ## Testing agents locally
+There are two ways to run and test agents.
+
+<Steps>
+
+### Mastra Playground
 
-Use the `mastra dev` CLI command to run your agents behind a local API.
-By default, it loads exported agents from the `src/mastra/agents` directory and creates endpoints for testing (for example, `http://localhost:4111/api/agents/myAgent/generate`).
-It also launches a visual playground where you can chat with your agent and view execution traces.
+With the Mastra Dev Server running you can test an agent from the Mastra Playground by visiting [http://localhost:4111/agents](http://localhost:4111/agents) in your browser.
 
 > For more information, see the [Local Dev Playground](/docs/server-db/local-dev-playground) documentation.
 
-## Next Steps
+### Command line
+
+Create an agent response using `.generate()` or `.stream()`.
+
+```typescript {7} filename="src/test-agent.ts" showLineNumbers copy
+import "dotenv/config";
+
+import { mastra } from "./mastra";
+
+const agent = mastra.getAgent("testAgent");
+
+const response = await agent.generate("Help me organize my day");
+
+console.log(response.text);
+```
+
+> See [.generate()](../../reference/agents/generate.mdx) or [.stream()](../../reference/agents/stream.mdx) for more information.
+
+To test this agent, run the following:
+
+```bash copy
+npx tsx src/test-agent.ts
+```
+
+</Steps>
+
+## Related
 
 - [Agent Memory](./agent-memory.mdx)
 - [Dynamic Agents](./dynamic-agents.mdx)

package/.docs/raw/deployment/monorepo.mdx

@@ -102,6 +102,6 @@ Mastra works with:
 Known limitations:
 
 - Bun workspaces — partial support; known issues
-- Nx — known issues
+- Nx — You can use Nx's [supported dependency strategies](https://nx.dev/concepts/decisions/dependency-management) but you need to have `package.json` files inside your workspace packages
 
 > If you are experiencing issues with monorepos see our: [Monorepos Support mega issue](https://github.com/mastra-ai/mastra/issues/6852).

package/.docs/raw/frameworks/agentic-uis/ai-sdk.mdx

@@ -76,7 +76,7 @@ import { useChat } from "@ai-sdk/react";
 
 export function Chat() {
   const { messages, input, handleInputChange, handleSubmit } = useChat({
-    api: "api/chat"
+    api: "/api/chat"
   });
   return (
     <div>
@@ -432,22 +432,52 @@ This utility is helpful when you want to fetch messages directly from your stora
 
 ### Enabling stream compatibility
 
-To enable AI SDK v5 compatibility, use the experimental `streamVNext` method with the `format` parameter:
+To enable AI SDK v5 compatibility, use the `@mastra/ai-sdk` package:
 
-```typescript filename="app/api/chat/route.ts" showLineNumbers copy
-import { mastra } from "../../../mastra";
+<Tabs items={["npm", "yarn", "pnpm", "bun"]}>
+  <Tabs.Tab>
+    ```bash copy
+    npm install @mastra/ai-sdk
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```bash copy
+    yarn add @mastra/ai-sdk
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```bash copy
+    pnpm add @mastra/ai-sdk
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```bash copy
+    bun add @mastra/ai-sdk
+    ```
+  </Tabs.Tab>
+</Tabs>
 
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-  const myAgent = mastra.getAgent("weatherAgent");
-  
-  // Use streamVNext with AI SDK v5 format (experimental)
-  const stream = await myAgent.streamVNext(messages, {
-    format: 'aisdk'
-  });
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      chatRoute({
+        path: '/chat',
+        agent: 'weatherAgent',
+      }),
+    ],
+  },
+});
+```
 
-  return stream.toUIMessageStreamResponse();
-}
+In your application call the `useChat()` hook.
+```typescript
+const { error, status, sendMessage, messages, regenerate, stop } =
+  useChat({
+    transport: new DefaultChatTransport({
+      api: 'http://localhost:4111/api/chat',
+    }),
+  });
 ```
 
 <Callout type="info">

package/.docs/raw/getting-started/installation.mdx

@@ -22,6 +22,10 @@ Mastra also supports other LLM providers. For a full list of supported models an
 
 Our CLI is the fastest way to get started with Mastra. You can run `create mastra` anywhere on your machine.
 
+<Callout type="warning">
+  The CLI currently generates projects that are only compatible with `ai-sdk v4`. Please refer to [ai-sdk v5 compatibility](#ai-sdk-v5-compatibility) if you wish to use `ai-sdk v5`.
+</Callout>
+
 <Steps>
 
 ## Start the CLI wizard
@@ -171,7 +175,7 @@ This helps users manually set up a Mastra project with their preferred package m
 
     npm install typescript tsx @types/node mastra@latest --save-dev
 
-    npm install @mastra/core@latest zod@^3 @ai-sdk/openai
+    npm install @mastra/core@latest zod@^3 @ai-sdk/openai@^1
     ```
 
   </Tab>
@@ -181,7 +185,7 @@ This helps users manually set up a Mastra project with their preferred package m
 
     pnpm add typescript tsx @types/node mastra@latest --save-dev
 
-    pnpm add @mastra/core@latest zod@^3 @ai-sdk/openai
+    pnpm add @mastra/core@latest zod@^3 @ai-sdk/openai@^1
     ```
 
   </Tab>
@@ -191,7 +195,7 @@ This helps users manually set up a Mastra project with their preferred package m
 
     yarn add typescript tsx @types/node mastra@latest --dev
 
-    yarn add @mastra/core@latest zod@^3 @ai-sdk/openai
+    yarn add @mastra/core@latest zod@^3 @ai-sdk/openai@^1
     ```
 
   </Tab>
@@ -201,7 +205,7 @@ This helps users manually set up a Mastra project with their preferred package m
 
     bun add typescript tsx @types/node mastra@latest --dev
 
-    bun add @mastra/core@latest zod@^3 @ai-sdk/openai
+    bun add @mastra/core@latest zod@^3 @ai-sdk/openai@^1
     ```
 
   </Tab>
@@ -372,6 +376,50 @@ To install Mastra in an existing project, use the `mastra init` command.
 
 > See [mastra init](/reference/cli/init) for more information.
 
+## ai-sdk v5 compatibility
+
+By default, Mastra projects are only compatible with `ai-sdk v4`, if you wish to use `ai-sdk v5`, please make the following changes to the generated project.
+
+Install the latest version to the `@ai-sdk/openai` package:
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+
+  <Tab>
+    ```bash copy
+    npm install @ai-sdk/openai@latest
+    ```
+
+  </Tab>
+  <Tab>
+    ```bash copy
+    pnpm add @ai-sdk/openai@latest
+    ```
+
+  </Tab>
+  <Tab>
+    ```bash copy
+    yarn add @ai-sdk/openai@latest
+    ```
+
+  </Tab>
+  <Tab>
+    ```bash copy
+    bun add @ai-sdk/openai@latest
+    ```
+
+  </Tab>
+</Tabs>
+
+Update the `planActivities` step in `src/mastra/workflows/weather-workflow.ts` as follow:
+```ts filename="src/mastra/workflows/weather-workflow.ts" showLineNumbers{150} copy
+const response = await agent.stream([ // [!code --]
+const response = await agent.streamVNext([ // [!code ++]
+  {
+    role: 'user',
+    content: prompt,
+  },
+]);
+```
+
 ## Next steps
 
 - [Local Development](/docs/server-db/local-dev-playground)

package/.docs/raw/getting-started/templates.mdx

@@ -8,16 +8,7 @@ import { Tabs, Tab } from "@/components/tabs";
 
 # Templates
 
-Templates are pre-built Mastra projects that demonstrate specific use cases and patterns. They provide working examples you can run immediately and customize for your needs.
-
-## What Templates Offer
-
-Templates include:
-
-- **Complete working examples** - Functional code demonstrating specific patterns
-- **Best practices** - Proper project structure and Mastra conventions  
-- **Educational value** - Learn different Mastra features through examples
-- **Quick start** - Bootstrap projects faster than starting from scratch
+Templates are pre-built Mastra projects that demonstrate specific use cases and patterns. Browse available templates in the [templates directory](https://mastra.ai/templates).
 
 ## Using Templates
 
@@ -81,15 +72,4 @@ After installation:
   Each template includes a comprehensive README with specific setup instructions and usage examples.
 </Callout>
 
-## Available Templates
-
-Browse available templates in the [templates directory](https://mastra.ai/templates).
-
-## Next Steps
-
-- **Explore code** - Understand how templates implement functionality
-- **Customize** - Modify agents, tools, and workflows for your use case
-- **Learn patterns** - Study templates to understand Mastra best practices
-- **Contribute** - Create your own templates for the community
-
-For detailed information on creating templates, see the [Templates Reference](/reference/templates).
+For detailed information on creating templates, see the [Templates Reference](/reference/templates).

package/.docs/raw/reference/agents/generate.mdx

@@ -490,5 +490,5 @@ await agent.generate(
 
 ## Related
 
-- [Agent generation](../../docs/agents/overview.mdx#generate)
-- [Streaming responses](../../docs/agents/streaming.mdx)
+- [Generating responses](../../docs/agents/overview.mdx#generating-responses)
+- [Streaming responses](../../docs/agents/overview.mdx#streaming-responses)

package/.docs/raw/reference/agents/getDefaultStreamOptions.mdx

@@ -63,5 +63,6 @@ await agent.getDefaultStreamOptions({
 
 ## Related
 
-- [Agent streaming](../../docs/agents/streaming.mdx)
+- [Generating responses](../../docs/agents/overview.mdx#generating-responses)
+- [Streaming responses](../../docs/agents/overview.mdx#streaming-responses)
 - [Runtime variables](../../docs/agents/runtime-variables.mdx)

package/.docs/raw/reference/agents/getDefaultVNextStreamOptions.mdx

@@ -63,5 +63,5 @@ await agent.getDefaultVNextStreamOptions({
 
 ## Related
 
-- [Agent streaming](../../docs/agents/streaming.mdx)
+- [Streaming with agents](../../docs/streaming/overview.mdx#streaming-with-agents)
 - [Runtime variables](../../docs/agents/runtime-variables.mdx)

package/.docs/raw/reference/agents/stream.mdx

@@ -475,5 +475,5 @@ await agent.stream("message for agent", {
 
 ## Related
 
-- [Agent streaming](../../docs/agents/streaming.mdx)
-- [Agent generation](../../docs/agents/overview.mdx#generate)
+- [Generating responses](../../docs/agents/overview.mdx#generating-responses)
+- [Streaming responses](../../docs/agents/overview.mdx#streaming-responses)

package/.docs/raw/reference/cli/build.mdx

@@ -35,12 +35,6 @@ mastra build [options]
       description: "Comma-separated list of paths to tool files to include",
       isOptional: true,
     },
-    {
-      name: "--env",
-      type: "string", 
-      description: "Path to custom environment file",
-      isOptional: true,
-    },
     {
       name: "--help",
       type: "boolean",

package/.docs/raw/reference/cli/start.mdx

@@ -20,7 +20,8 @@ mastra start [options]
 | Option | Description |
 |--------|-------------|
 | `-d, --dir <path>` | Path to your built Mastra output directory (default: .mastra/output) |
-| `-nt, --no-telemetry` | Enable OpenTelemetry instrumentation for observability |
+| `-e, --env <env>` | Custom env file to include in the start (default: .env.production, .env) |
+| `-nt, --no-telemetry` | Disable telemetry on start |
 
 ## Examples
 
@@ -36,6 +37,12 @@ Start from a custom output directory:
 mastra start --dir ./my-output
 ```
 
+Start with a custom environment file:
+
+```bash
+mastra start --env .env.staging
+```
+
 Start with telemetry disabled:
 
 ```bash