@mastra/mcp-docs-server 0.13.17-alpha.2 → 0.13.17-alpha.4

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/agents/streamVNext.mdx

@@ -3,13 +3,11 @@ title: "Reference: Agent.streamVNext() (Experimental) | Agents | Mastra Docs"
 description: "Documentation for the `Agent.streamVNext()` method in Mastra agents, which enables real-time streaming of responses with enhanced capabilities."
 ---
 
-import { Callout } from "nextra/components";
+import { StreamVNextCallout } from "@/components/streamVNext-callout.tsx"
 
 # Agent.streamVNext() (Experimental)
 
-<Callout type="warning">
-  **Experimental Feature**: This is a new streaming implementation with support for multiple output formats, including AI SDK v5 compatibility. It will replace the existing `stream()` method once battle-tested. The API may change as we refine the feature based on feedback.
-</Callout>
+<StreamVNextCallout />
 
 The `.streamVNext()` method enables real-time streaming of responses from an agent with enhanced capabilities and format flexibility. This method accepts messages and optional streaming options, providing a next-generation streaming experience with support for both Mastra's native format and AI SDK v5 compatibility.
 

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