@mastra/mcp-docs-server 1.0.0-beta.5 → 1.0.0-beta.7

package/.docs/raw/agents/structured-output.mdx

@@ -0,0 +1,224 @@
+---
+title: "Structured Output | Agents"
+description: "Learn how to generate structured data from agents using schemas and validation."
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Structured Output
+
+Structured output lets an agent return an object that matches the shape defined by a schema instead of returning text. The schema tells the model what fields to produce, and the model ensures the final result fits that shape.
+
+## When to use structured output
+
+Use structured output when you need an agent to return a data object rather than text. Having well defined fields can make it simpler to pull out the values you need for API calls, UI rendering, or application logic.
+
+## Defining schemas
+
+Agents can return structured data by defining the expected output with either [Zod](https://zod.dev/) or [JSON Schema](https://json-schema.org/). Zod is recommended because it provides TypeScript type inference and runtime validation, while JSON Schema is useful when you need a language agnostic format.
+
+<Tabs>
+  <TabItem value="zod" label="Zod">
+
+Define the `output` shape using [Zod](https://zod.dev/):
+
+```typescript showLineNumbers copy
+import { z } from "zod";
+
+const response = await testAgent.generate("Help me plan my day.", {
+  structuredOutput: {
+    schema: z.array(
+      z.object({
+        name: z.string(),
+        activities: z.array(z.string()),
+      }),
+    ),
+  },
+});
+
+console.log(response.object);
+```
+
+  </TabItem>
+  <TabItem value="json-schema" label="JSON Schema">
+
+You can also use JSON Schema to define your output structure:
+
+```typescript showLineNumbers copy
+const response = await testAgent.generate("Help me plan my day.", {
+  structuredOutput: {
+    schema: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          activities: {
+            type: "array",
+            items: { type: "string" },
+          },
+        },
+        required: ["name", "activities"],
+      },
+    },
+  },
+});
+
+console.log(response.object);
+```
+
+  </TabItem>
+</Tabs>
+
+
+> See [.generate()](/reference/v1/agents/generate#structuredoutput) for a full list of configuration options.
+
+### Example output
+
+The `response.object` will contain the structured data as defined by the schema.
+
+```json
+[
+  {
+    "name": "Morning Routine",
+    "activities": ["Wake up at 7am", "Exercise", "Shower", "Breakfast"]
+  },
+  {
+    "name": "Work",
+    "activities": ["Check emails", "Team meeting", "Lunch break"]
+  },
+  {
+    "name": "Evening",
+    "activities": ["Dinner", "Relax", "Read a book", "Sleep by 10pm"]
+  }
+]
+```
+
+## Streaming
+
+Streaming also supports structured output. The final structured object is available on `stream.fullStream` and after the stream completes on `stream.object`. Text stream chunks are still emitted, but they contain natural language text rather than structured data.
+
+```typescript showLineNumbers copy
+import { z } from "zod";
+
+const stream = await testAgent.stream("Help me plan my day.", {
+  structuredOutput: {
+    schema: z.array(
+      z.object({
+        name: z.string(),
+        activities: z.array(z.string())
+      })
+    ),
+  },
+});
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === "object-result") {
+    console.log("\n", JSON.stringify(chunk, null, 2));
+  }
+  process.stdout.write(JSON.stringify(chunk));
+}
+
+console.log(await stream.object)
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+## Structuring agent
+
+When your main agent isn't proficient at creating structured output you can provide a `model` to `structuredOutput`. In this case, Mastra uses a second agent under the hood to extract structured data from the main agent's natural language response. This makes two LLM calls, one to generate the response and another to turn that response into the structured object, which adds some latency and cost but can improve accuracy for complex structuring tasks.
+
+```typescript showLineNumbers copy
+import { z } from "zod";
+
+const response = await testAgent.generate("Analyze the TypeScript programming language.", {
+  structuredOutput: {
+    schema: z.object({
+      overview: z.string(),
+      strengths: z.array(z.string()),
+      weaknesses: z.array(z.string()),
+      useCases: z.array(z.object({
+        scenario: z.string(),
+        reasoning: z.string(),
+      })),
+      comparison: z.object({
+        similarTo: z.array(z.string()),
+        differentiators: z.array(z.string()),
+      }),
+    }),
+    model: "openai/gpt-4o",
+  },
+});
+
+console.log(response.object);
+```
+
+## Response format
+
+By default, Mastra passes the schema to the model provider using the `response_format` API parameter. Most model providers have built-in support for this, which reliably enforces the schema.
+
+If your model provider doesn't support `response_format`, you'll get an error from the API. When this happens, set `jsonPromptInjection: true`. This adds the schema to the system prompt instead, instructing the model to output JSON. This is less reliable than the API parameter approach.
+
+```typescript showLineNumbers copy
+import { z } from "zod";
+
+const response = await testAgent.generate("Help me plan my day.", {
+  structuredOutput: {
+    schema: z.array(
+      z.object({
+        name: z.string(),
+        activities: z.array(z.string()),
+      }),
+    ),
+    jsonPromptInjection: true,
+  },
+});
+
+console.log(response.object);
+```
+
+:::info[Gemini 2.5 with tools]
+
+Gemini 2.5 models do not support combining `response_format` (structured output) with function calling (tools) in the same API call. If your agent has tools and you're using `structuredOutput` with a Gemini 2.5 model, you must set `jsonPromptInjection: true` to avoid the error `Function calling with a response mime type: 'application/json' is unsupported`.
+
+```typescript
+const response = await agentWithTools.generate("Your prompt", {
+  structuredOutput: {
+    schema: yourSchema,
+    jsonPromptInjection: true,  // Required for Gemini 2.5 when tools are present
+  },
+});
+```
+:::
+
+## Error handling
+
+When schema validation fails, you can control how errors are handled using `errorStrategy`. The default `strict` strategy throws an error, while `warn` logs a warning and continues. The `fallback` strategy returns the values provided using `fallbackValue`.
+
+```typescript showLineNumbers copy
+import { z } from "zod";
+
+const response = await testAgent.generate("Tell me about TypeScript.", {
+  structuredOutput: {
+    schema: z.object({
+      summary: z.string(),
+      keyFeatures: z.array(z.string())
+    }),
+    errorStrategy: "fallback",
+    fallbackValue: {
+      summary: "TypeScript is a typed superset of JavaScript",
+      keyFeatures: ["Static typing", "Compiles to JavaScript", "Better tooling"]
+    }
+  }
+});
+
+console.log(response.object);
+```
+
+## Related
+
+- [Using Tools](/docs/v1/agents/using-tools)
+- [Agent Memory](/docs/v1/agents/agent-memory)

package/.docs/raw/deployment/cloud-providers/index.mdx

@@ -15,7 +15,6 @@ Standalone Mastra applications can be deployed to popular cloud providers, see o
 - [Netlify](/docs/v1/deployment/cloud-providers/netlify-deployer)
 - [Vercel](/docs/v1/deployment/cloud-providers/vercel-deployer)
 
-
 For self-hosted Node.js server deployment, see the [Creating A Mastra Server](/docs/v1/deployment/building-mastra) guide.
 
 ## Prerequisites
@@ -30,33 +29,27 @@ Before deploying to a cloud provider, ensure you have:
 
 ## LibSQLStore
 
-`LibSQLStore` writes to the local filesystem, which is not supported in cloud environments that use ephemeral file systems. If you're deploying to platforms like **AWS Lambda**, **Azure App Services**, or **Digital Ocean App Platform**, you **must remove** all usage of `LibSQLStore`.
+`LibSQLStore` writes to the local filesystem, which is not supported in cloud environments that use ephemeral file systems. If you're deploying to platforms like AWS Lambda, Netlify, Azure App Services, or Digital Ocean App Platform, you must remove all usage of `LibSQLStore`.
 
-Specifically, ensure you've removed it from both `src/mastra/index.ts` and `src/mastra/agents/weather-agent.ts`:
+Specifically, ensure you've removed it from all Mastra files, including configuration on the main Mastra instance and any agents using it, e.g. for memory storage.
 
-```typescript title="src/mastra/index.ts" showLineNumbers
-export const mastra = new Mastra({
-  // ...
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    // [!code --]
-    // stores telemetry, scorer results, ... into memory storage, if it needs to persist, change to file:../mastra.db // [!code --]
-    url: ":memory:", // [!code --]
-  }), //[!code --]
-});
+```diff title="src/mastra/index.ts"
+ export const mastra = new Mastra({
+-  storage: new LibSQLStore({
+-    id: 'mastra-storage',
+-    url: ":memory:",
+-  }),
+ });
 ```
 
-```typescript title="src/mastra/agents/weather-agent.ts" showLineNumbers
-export const weatherAgent = new Agent({
-  id: "weather-agent",
-  // ..
-  memory: new Memory({
-    // [!code --]
-    storage: new LibSQLStore({
-      id: 'mastra-storage',
-      // [!code --]
-      url: "file:../mastra.db", // path is relative to the .mastra/output directory // [!code --]
-    }), // [!code --]
-  }), //  [!code --]
-});
+```diff
+ export const weatherAgent = new Agent({
+   id: "weather-agent",
+   memory: new Memory({
+-    storage: new LibSQLStore({
+-      id: 'mastra-storage',
+-      url: "file:../mastra.db",
+-    }),
+   }),
+ });
 ```

package/.docs/raw/deployment/cloud-providers/netlify-deployer.mdx

@@ -15,12 +15,11 @@ npm install @mastra/deployer-netlify@beta
 
 ## Usage example
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core";
 import { NetlifyDeployer } from "@mastra/deployer-netlify";
 
 export const mastra = new Mastra({
-  // ...
   deployer: new NetlifyDeployer(),
 });
 ```
@@ -43,32 +42,64 @@ Your project is now configured with automatic deployments which occur whenever y
 
 ## 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.
+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. You can also run `netlify dev` from your project root to test your Mastra application locally.
 
 ```bash copy
 netlify deploy --prod
 ```
 
-> You can also run `netlify dev` from your project root to test your Mastra application locally.
+:::warning
 
-## Build output
+When using `netlify deploy` instead of continuous deployment, you need to create a `netlify.toml` file with these contents:
+
+```toml
+[build]
+  command = "npm run build"
+  publish = ".netlify/v1/functions"
 
-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.
+[functions]
+  directory = ".netlify/v1/functions"
+  node_bundler = "none"
+  included_files = [".netlify/v1/functions/**"]
 
+[[redirects]]
+  from = "/*"
+  to = "/.netlify/functions/api/:splat"
+  status = 200
+
+[build.environment]
+  NODE_VERSION = "22.13.0"
 ```
-.netlify/
-└── v1/
-    ├── functions/
-    │   └── api/
-    │       └── index.mjs
-    └── config.json
-package.json
+
+Adjust the `build.command` to your project.
+
+:::
+
+## 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.
+
+```bash
+your-project/
+└── .netlify/
+    └── v1/
+        ├── config.json
+        └── functions/
+            └── api/
+                ├── index.js
+                ├── package.json
+                └── node_modules/
 ```
 
 The `NetlifyDeployer` automatically generates a `config.json` configuration file in `.netlify/v1` with the following settings:
 
 ```json
 {
+  "functions": {
+    "directory": ".netlify/v1/functions",
+    "node_bundler": "none",
+    "included_files": [".netlify/v1/functions/**"]
+  },
   "redirects": [
     {
       "force": true,

package/.docs/raw/evals/running-in-ci.mdx

@@ -49,8 +49,6 @@ describe('Weather Agent Tests', () => {
 });
 ```
 
-View the full example [here](/examples/v1/evals/running-in-ci)
-
 ## Understanding Results
 
 The `runEvals` function returns an object with:

package/.docs/raw/{guides/getting-started → getting-started}/manual-install.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Manual Install | Guides"
+title: "Manual Install | Getting Started"
 description: Set up a Mastra project manually without using the create mastra CLI.
 ---
 
@@ -11,7 +11,7 @@ import StepItem from "@site/src/components/StepItem";
 # Manual Install
 
 :::info
-Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the [Standalone Server Quickstart](/guides/v1/getting-started/quickstart), which achieves the same result using the [`mastra create`](/reference/v1/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init).
+Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow a [getting-started guide](/docs/v1/getting-started/start), which achieves the same result using the [`mastra create`](/reference/v1/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init).
 :::
 
 If you prefer not to use our automatic CLI tool, you can set up your project yourself by following the guide below.

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

@@ -6,7 +6,7 @@ description: Choose how to get started with Mastra - quickstart, framework integ
 import { CardGrid, CardGridItem } from "@site/src/components/cards/card-grid";
  
 # Start
-Start a new Mastra project, or integrate Mastra with your preferred framework.
+Create a new Mastra project, or integrate Mastra with your preferred framework to start building.
 
 ## New project
 

package/.docs/raw/guides/build-your-ui/ai-sdk-ui.mdx

@@ -142,6 +142,12 @@ const { error, status, sendMessage, messages, regenerate, stop } = useChat({
 });
 ```
 
+:::tip Agent streaming in workflows
+When a workflow step pipes an agent's stream to the workflow writer (e.g., `await response.fullStream.pipeTo(writer)`), the agent's text chunks and tool calls are automatically streamed to the UI in real-time. This provides a seamless streaming experience even when agents are running inside workflow steps.
+
+Learn more in [Workflow Streaming](/docs/v1/streaming/workflow-streaming#streaming-agent-text-chunks-to-ui).
+:::
+
 ### `networkRoute()`
 
 Use the `networkRoute()` utility to create a route handler that automatically formats the agent network stream into an AI SDK-compatible format.
@@ -292,6 +298,7 @@ export async function POST(req: Request) {
 
   // Transform stream into AI SDK format and create UI messages stream
   const uiMessageStream = createUIMessageStream({
+    originalMessages: messages,
     execute: async ({ writer }) => {
       for await (const part of toAISdkStream(stream, { from: "agent" })!) {
         writer.write(part);
@@ -384,6 +391,7 @@ export async function POST(req: Request) {
   });
 
   const uiMessageStream = createUIMessageStream({
+    initialMessages: messages,
     execute: async ({ writer }) => {
       for await (const part of toAISdkStream(stream, {
         from: "agent",

package/.docs/raw/guides/getting-started/quickstart.mdx

@@ -13,7 +13,7 @@ import { VideoPlayer } from "@site/src/components/video-player";
 
 The `create mastra` CLI command is the quickest way to get started. It walks you through setup and creates example agents, workflows, and tools for you to run locally or adapt
 
-If you need more control over the setup, see the [manual installation guide](/guides/v1/getting-started/manual-install). You can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init) for existing projects.
+If you need more control over the setup, see the [manual installation guide](/docs/v1/getting-started/manual-install). You can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init) for existing projects.
 
 ## Before you begin