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

package/.docs/organized/code-examples/server-express-adapter.md

@@ -0,0 +1,87 @@
+### package.json
+```json
+{
+  "name": "examples-server-express-adapter",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "latest",
+    "@mastra/express": "latest",
+    "express": "^5.1.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.5",
+    "@types/node": "22.13.17",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3"
+  }
+}
+```
+
+### mastra/agents/assistant.ts
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+
+export const assistantAgent = new Agent({
+  id: 'assistantAgent',
+  name: 'Assistant',
+  instructions: 'You are a helpful assistant. Answer questions concisely.',
+  model: openai('gpt-4o-mini'),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+
+import { assistantAgent } from './agents/assistant';
+
+export const mastra = new Mastra({
+  agents: { assistantAgent },
+});
+
+```
+
+### server.ts
+```typescript
+/**
+ * Express Server Adapter Example
+ *
+ * This demonstrates how to use @mastra/express to run Mastra with Express.
+ *
+ * Features shown:
+ * - Basic server setup with MastraServer
+ * - Required express.json() middleware
+ * - Custom routes added after init()
+ * - Accessing Mastra context via res.locals
+ */
+
+import express from 'express';
+import { MastraServer } from '@mastra/express';
+
+import { mastra } from './mastra';
+
+const app = express();
+app.use(express.json()); // Required for body parsing
+
+const server = new MastraServer({ app, mastra });
+
+await server.init();
+
+// Custom route with access to Mastra context via res.locals
+app.get('/health', (req, res) => {
+  const mastraInstance = res.locals.mastra;
+  const agents = Object.keys(mastraInstance.listAgents());
+  res.json({ status: 'ok', agents });
+});
+
+const port = 4111;
+
+app.listen(port, () => {
+  console.log(`Server running on http://localhost:${port}`);
+  console.log(`Try: curl http://localhost:${port}/api/agents`);
+});
+
+```

package/.docs/organized/code-examples/server-hono-adapter.md

@@ -0,0 +1,85 @@
+### package.json
+```json
+{
+  "name": "examples-server-hono-adapter",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "latest",
+    "@mastra/hono": "latest",
+    "@hono/node-server": "^1.14.3",
+    "hono": "^4.10.4",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "22.13.17",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3"
+  }
+}
+```
+
+### mastra/agents/assistant.ts
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+
+export const assistantAgent = new Agent({
+  id: 'assistantAgent',
+  name: 'Assistant',
+  instructions: 'You are a helpful assistant. Answer questions concisely.',
+  model: openai('gpt-4o-mini'),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+
+import { assistantAgent } from './agents/assistant';
+
+export const mastra = new Mastra({
+  agents: { assistantAgent },
+});
+
+```
+
+### server.ts
+```typescript
+/**
+ * Hono Server Adapter Example
+ *
+ * This demonstrates how to use @mastra/hono to run Mastra with Hono.
+ *
+ * Features shown:
+ * - Basic server setup with MastraServer
+ * - Custom routes added after init()
+ * - Accessing Mastra context in custom routes
+ */
+
+import { serve } from '@hono/node-server';
+import { Hono } from 'hono';
+import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono';
+
+import { mastra } from './mastra';
+
+const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>();
+const server = new MastraServer({ app: app as any, mastra });
+
+await server.init();
+
+// Custom route with access to Mastra context
+app.get('/health', c => {
+  const mastraInstance = c.get('mastra');
+  const agents = Object.keys(mastraInstance.listAgents());
+  return c.json({ status: 'ok', agents });
+});
+
+const port = 4111;
+
+serve({ fetch: app.fetch, port }, () => {
+  console.log(`Server running on http://localhost:${port}`);
+  console.log(`Try: curl http://localhost:${port}/api/agents`);
+});
+
+```

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

@@ -212,118 +212,9 @@ for await (const chunk of stream.textStream) {
 
 ## Structured output
 
-Agents can return structured, type-safe data by defining the expected output using either [Zod](https://zod.dev/) or [JSON Schema](https://json-schema.org/). We recommend Zod for better TypeScript support and developer experience. The parsed result is available on `response.object`, allowing you to work directly with validated and typed data.
+Agents can return structured, type-safe data using Zod or JSON Schema. The parsed result is available on `response.object`.
 
-### Using Zod
-
-Define the `output` shape using [Zod](https://zod.dev/):
-
-```typescript showLineNumbers copy
-import { z } from "zod";
-
-const response = await testAgent.generate(
-  [
-    {
-      role: "system",
-      content: "Provide a summary and keywords for the following text:",
-    },
-    {
-      role: "user",
-      content: "Monkey, Ice Cream, Boat",
-    },
-  ],
-  {
-    structuredOutput: {
-      schema: z.object({
-        summary: z.string(),
-        keywords: z.array(z.string()),
-      }),
-    },
-  },
-);
-
-console.log(response.object);
-```
-
-### Structuring sub agent
-
-Use the `model` property to have a separate agent generate the structured output for you.
-
-```typescript showLineNumbers copy
-import { z } from "zod";
-
-const response = await testAgentWithTools.generate(
-  [
-    {
-      role: "system",
-      content: "Provide a summary and keywords for the following text:",
-    },
-    {
-      role: "user",
-      content: "Please use your test tool and let me know the results",
-    },
-  ],
-  {
-    structuredOutput: {
-      schema: z.object({
-        summary: z.string(),
-        keywords: z.array(z.string()),
-      }),
-      model: "openai/gpt-5.1",
-    },
-  },
-);
-
-console.log(response.object);
-console.log(response.toolResults);
-```
-
-### Response format
-
-By default `structuredOutput` will use `response_format` to pass the schema to the model provider. If the model provider does not natively support `response_format` it's possible that this will error or not give the desired results. To keep using the same model use `jsonPromptInjection` to bypass response format and inject a system prompt message to coerce the model to return structured output.
-
-```typescript showLineNumbers copy
-import { z } from "zod";
-
-const response = await testAgentThatDoesntSupportStructuredOutput.generate(
-  [
-    {
-      role: "system",
-      content: "Provide a summary and keywords for the following text:",
-    },
-    {
-      role: "user",
-      content: "Monkey, Ice Cream, Boat",
-    },
-  ],
-  {
-    structuredOutput: {
-      schema: z.object({
-        summary: z.string(),
-        keywords: 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
-  },
-});
-```
-
-:::
+> See [Structured Output](/docs/v1/agents/structured-output) for more information.
 
 ## Analyzing images
 

package/.docs/raw/agents/processors.mdx

@@ -276,4 +276,4 @@ const agent = new Agent({
 ## Related documentation
 
 - [Guardrails](/docs/v1/agents/guardrails) - Security and validation processors
-- [Memory Processors](/docs/v1/memory/memory-processors) - Memory-specific processors and automatic integration
+- [Memory Processors](/docs/v1/memory/memory-processors) - Memory-specific processors and automatic integration

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/guides/migrations/upgrade-to-v1/workflows.mdx

@@ -177,8 +177,6 @@ To migrate, update any code that consumes branch outputs to handle optional valu
 
 If your code depends on non-optional types, add runtime checks or provide default values when accessing branch outputs.
 
-See [Run.resumeStream()](/reference/v1/streaming/workflows/resumeStream) for details.
-
 ## Removed
 
 ### `streamVNext`, `resumeStreamVNext`, and `observeStreamVNext` methods
@@ -189,6 +187,16 @@ To migrate, use the standard `stream()`, `resumeStream()`, and `observeStream()`
 
 See [`Run.stream()`](/reference/v1/streaming/workflows/stream), [`Run.resumeStream()`](/reference/v1/streaming/workflows/resumeStream), and [`Run.observeStream()`](/reference/v1/streaming/workflows/observeStream) for details.
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/workflow-stream-vnext .
+```
+
+:::
+
 ### Legacy workflows export
 
 The `./workflows/legacy` export path has been removed from `@mastra/core`. Legacy workflows are no longer supported.

package/.docs/raw/memory/working-memory.mdx

@@ -131,6 +131,7 @@ Resource-scoped working memory requires specific storage adapters that support t
 - **LibSQL** (`@mastra/libsql`)
 - **PostgreSQL** (`@mastra/pg`)
 - **Upstash** (`@mastra/upstash`)
+- **MongoDB** (`@mastra/mongodb`)
 
 ## Custom Templates
 

package/.docs/raw/observability/tracing/bridges/otel.mdx

@@ -129,6 +129,12 @@ Use the `--import` flag to ensure instrumentation loads before your application:
 tsx --import ./instrumentation.ts ./src/index.ts
 ```
 
+## Semantic Conventions
+
+The OtelBridge exports Mastra spans using [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai). This includes standardized span names (`chat {model}`, `execute_tool {tool_name}`, etc.) and attributes (`gen_ai.usage.input_tokens`, `gen_ai.request.model`, etc.).
+
+For details on span naming and attributes, see the [OpenTelemetry Exporter semantic conventions](/docs/v1/observability/tracing/exporters/otel#opentelemetry-semantic-conventions).
+
 ## Trace Hierarchy
 
 With the OtelBridge, your traces maintain proper hierarchy across OTEL and Mastra boundaries:
@@ -160,6 +166,25 @@ Both services must have:
 2. W3C Trace Context propagator enabled
 3. Mastra with OtelBridge configured
 
+## Using Tags
+
+Tags help you categorize and filter traces in your OTEL backend. Add tags when executing agents or workflows:
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+Tags are exported as a JSON string in the `mastra.tags` span attribute for broad backend compatibility. Common use cases include:
+
+- Environment labels: `"production"`, `"staging"`
+- Experiment tracking: `"experiment-v1"`, `"control-group"`
+- Priority levels: `"priority-high"`, `"batch-job"`
+
 ## Troubleshooting
 
 If traces aren't appearing or connecting as expected:
@@ -173,4 +198,3 @@ If traces aren't appearing or connecting as expected:
 - [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [OpenTelemetry Exporter](/docs/v1/observability/tracing/exporters/otel) - For sending traces to OTEL backends
 - [OtelBridge Reference](/reference/v1/observability/tracing/bridges/otel) - API documentation
-- [OpenTelemetry GenAI Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)

package/.docs/raw/observability/tracing/exporters/arize.mdx

@@ -203,6 +203,25 @@ Reserved fields such as `input`, `output`, `sessionId`, thread/user IDs, and Ope
 
 This exporter implements the [OpenInference Semantic Conventions](https://github.com/Arize-ai/openinference/tree/main/spec) for generative AI applications, providing standardized trace structure across different observability platforms.
 
+## Using Tags
+
+Tags help you categorize and filter traces in Phoenix and Arize AX. Add tags when executing agents or workflows:
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+Tags appear as the `tag.tags` attribute following OpenInference conventions and can be used to filter and search traces. Common use cases include:
+
+- Environment labels: `"production"`, `"staging"`
+- Experiment tracking: `"experiment-v1"`, `"control-group"`
+- Priority levels: `"priority-high"`, `"batch-job"`
+
 ## Related
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)