@mastra/mcp-docs-server 0.13.12 → 0.13.13-alpha.1

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

@@ -3,7 +3,7 @@
 {
   "name": "examples-mcp-registry-registry",
   "dependencies": {
-    "@ai-sdk/openai": "^1.3.22",
+    "@ai-sdk/openai": "^1.3.24",
     "@mastra/core": "latest",
     "@mastra/mcp": "latest",
     "@mastra/mcp-registry-registry": "latest",

package/.docs/organized/code-examples/memory-per-resource-example.md

@@ -3,7 +3,7 @@
 {
   "name": "memory-per-resource-example",
   "dependencies": {
-    "@ai-sdk/openai": "^1.3.22",
+    "@ai-sdk/openai": "^1.3.24",
     "@mastra/core": "latest",
     "@mastra/memory": "latest",
     "@mastra/libsql": "latest",

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

@@ -3,7 +3,7 @@
 {
   "name": "memory-with-context",
   "dependencies": {
-    "@ai-sdk/openai": "^1.3.22",
+    "@ai-sdk/openai": "^1.3.24",
     "@mastra/core": "latest",
     "@mastra/memory": "latest",
     "chalk": "^5.4.1",

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

@@ -6,7 +6,7 @@
     "@ai-sdk/openai": "latest",
     "@mastra/core": "latest",
     "@mastra/memory": "latest",
-    "ai": "^4.3.16",
+    "ai": "^4.3.19",
     "chalk": "^5.4.1",
     "dotenv": "^16.3.1",
     "js-tiktoken": "^1.0.13",

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

@@ -3,7 +3,7 @@
 {
   "name": "examples-openapi-spec-writer",
   "dependencies": {
-    "@ai-sdk/openai": "^1.3.22",
+    "@ai-sdk/openai": "^1.3.24",
     "@mastra/core": "latest",
     "@mastra/firecrawl": "latest",
     "@mastra/github": "latest",

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

@@ -3,7 +3,7 @@
 {
   "name": "examples-weather-agent",
   "dependencies": {
-    "@ai-sdk/openai": "^1.3.22",
+    "@ai-sdk/openai": "^1.3.24",
     "@mastra/core": "latest",
     "@mastra/libsql": "latest",
     "zod": "^3.25.67"

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

@@ -82,42 +82,6 @@ Strategies available:
 - `filter`: Remove messages containing PII
 - `redact`: Replace PII with placeholder values
 
-### `StructuredOutputProcessor`
-
-This processor converts unstructured LLM text responses into structured data using an internal agent. It preserves the original text while adding structured data to the response metadata as well as to result.object.
-
-```typescript copy showLineNumbers {5-15}
-import { StructuredOutputProcessor } from "@mastra/core/processors";
-import { z } from "zod";
-
-const agent = new Agent({
-  outputProcessors: [
-    new StructuredOutputProcessor({
-      schema: z.object({
-        sentiment: z.enum(['positive', 'negative', 'neutral']),
-        confidence: z.number().min(0).max(1),
-        topics: z.array(z.string()),
-      }),
-      model: openai("gpt-4o-mini"),
-      errorStrategy: 'warn', // Log warnings but continue on errors
-      instructions: 'Analyze the sentiment and extract key topics from the response',
-    }),
-  ],
-});
-
-const result = await agent.generate("Some conversational text")
-
-console.log(result.object) // { sentiment: "positive", confidence: 0.6, topics: ["foo", "bar"] }
-```
-
-Available options:
-- `schema`: Zod schema defining the expected structured output (required)
-- `model`: Language model for the internal structuring agent (required)
-- `errorStrategy`: Strategy when parsing or validation fails ('strict' | 'warn' | 'fallback', default: 'strict')
-- `fallbackValue`: Fallback value when errorStrategy is 'fallback'
-- `instructions`: Custom instructions for the structuring agent
-
-The structured data is stored in `result.object` and the original text is preserved in `result.text`.
 
 ### `BatchPartsProcessor`
 
@@ -199,21 +163,15 @@ You can chain multiple output processors. They execute sequentially in the order
 ```typescript copy showLineNumbers {9-18}
 import { Agent } from "@mastra/core/agent";
 import { 
-  UnicodeNormalizer, 
   ModerationProcessor, 
-  PromptInjectionDetector,
   PIIDetector 
 } from "@mastra/core/processors";
 
 const secureAgent = new Agent({
   outputProcessors: [
-    // 1. Normalize text first
-    new UnicodeNormalizer({ stripControlChars: true }),
-    // 2. Check for security threats
-    new PromptInjectionDetector({ model: openai("gpt-4.1-nano") }),
-    // 3. Moderate content
+    // 1. Check for security threats
     new ModerationProcessor({ model: openai("gpt-4.1-nano") }),
-    // 4. Handle PII last
+    // 2. Handle PII
     new PIIDetector({ model: openai("gpt-4.1-nano"), strategy: 'redact' }),
   ],
 });
@@ -226,40 +184,34 @@ You can create custom output processors by implementing the `Processor` interfac
 ### Streaming Output Processor
 
 ```typescript copy showLineNumbers {4-25}
-import type { Processor, MastraMessageV2, TripWire } from "@mastra/core/processors";
-import type { TextStreamPart, ObjectStreamPart } from 'ai';
+import type { Processor, MastraMessageV2 } from "@mastra/core/processors";
+import type { ChunkType } from "@mastra/core/stream";
 
 class ResponseLengthLimiter implements Processor {
-  readonly name = 'response-length-limiter-and-lower-case-results';
+  readonly name = 'response-length-limiter';
   
   constructor(private maxLength: number = 1000) {}
 
-  async processOutputStream({ chunk, streamParts, state, abort }: { // will run on every stream part emitted from the LLM
-    chunk: TextStreamPart<any> | ObjectStreamPart<any>;
-    streamParts: (TextStreamPart<any> | ObjectStreamPart<any>)[];
+  async processOutputStream({ part, streamParts, state, abort }: {
+    part: ChunkType;
+    streamParts: ChunkType[];
     state: Record<string, any>;
     abort: (reason?: string) => never;
-  }): Promise<TextStreamPart<any> | ObjectStreamPart<any> | null> {
+  }): Promise<ChunkType | null | undefined> {
     // Track cumulative length in state, each processor gets its own state
     if (!state.cumulativeLength) {
       state.cumulativeLength = 0;
     }
 
-    const shouldEmitChunk = chunk?.textDelta?.includes('foo');
-    
-    if (chunk.type === 'text-delta') {
-      state.cumulativeLength += chunk.textDelta.length;
+    if (part.type === 'text-delta') {
+      state.cumulativeLength += part.payload.text.length;
       
       if (state.cumulativeLength > this.maxLength) {
         abort(`Response too long: ${state.cumulativeLength} characters (max: ${this.maxLength})`);
       }
     }
 
-    if (shouldEmitChunk) {
-      return chunk; // Emit the chunk
-    } else {
-      return null; // Emit nothing
-    }
+    return part; // Emit the part
   }
 }
 ```
@@ -267,7 +219,7 @@ class ResponseLengthLimiter implements Processor {
 ### Final Result Processor
 
 ```typescript copy showLineNumbers {4-19}
-import type { Processor, MastraMessageV2, TripWire } from "@mastra/core/processors";
+import type { Processor, MastraMessageV2 } from "@mastra/core/processors";
 
 class ResponseValidator implements Processor {
   readonly name = 'response-validator';
@@ -299,9 +251,9 @@ class ResponseValidator implements Processor {
 ```
 
 When creating custom output processors:
-- Always return the processed data (chunks or messages)
+- Always return the processed data (parts or messages)
 - Use `abort(reason)` to terminate processing early. Abort is used to simulate blocking a response. Errors thrown with `abort` will be an instance of TripWire.
-- For streaming processors, return `null` or `undefined` to skip emitting a chunk
+- For streaming processors, return `null` or `undefined` to skip emitting a part
 - Keep processors focused on a single responsibility
 - If using an agent inside your processor, use a fast model, limit the size of the response from it as much as possible, and make the system prompt as concise as possible.
 
@@ -315,10 +267,10 @@ const result = await agent.generate('Hello');
 console.log(result.text); // Processed text
 console.log(result.object); // Structured data if applicable
 
-// Processors also run during streamVNext() for each chunk
+// Processors also run during streamVNext() for each part
 const stream = await agent.streamVNext('Hello');
-for await (const chunk of stream) {
-  console.log(chunk); // Processed chunks
+for await (const part of stream) {
+  console.log(part); // Processed parts
 }
 ```
 
@@ -342,9 +294,9 @@ const stream = await agent.streamVNext('Hello', {
 });
 ```
 
-### Structured Output with Better DX
+### Structured Output Processor
 
-For better developer experience with structured output, you can use the `structuredOutput` option:
+To use the StructuredOutputProcessor, you should use the `structuredOutput` option:
 
 ```typescript copy showLineNumbers
 import { z } from "zod";

package/.docs/raw/agents/streaming.mdx

@@ -5,46 +5,76 @@ description: Documentation on how to stream agents
 
 import { Callout } from "nextra/components";
 
-# Agent Streaming
+# Agent Streaming (VNext)
 
 Agents in Mastra support streaming responses for real-time interaction with clients. This enables progressive rendering of responses and better user experience.
 
 <Callout type="info">
-  **Experimental API**: The `streamVNext` method shown in this guide is an experimental feature that will replace the current `stream()` method after additional testing and refinement. For production use, consider using the stable [`stream()` method](/docs/agents/overview#2-generating-and-streaming-text) until `streamVNext` is finalized.
+  **Experimental API**: The `streamVNext` method shown in this guide is an experimental feature with enhanced streaming format support. It will replace the current `stream()` method after additional testing and refinement. For production use, consider using the stable [`stream()` method](/docs/agents/overview#streaming-responses) until `streamVNext` is finalized.
 </Callout>
 
 ## Usage
 
-The experimental streaming protocol uses the `streamVNext` method on an agent. This method returns a custom MastraAgentStream that extends ReadableStream with additional utilities.
+The experimental streaming protocol uses the `streamVNext` method on an agent. This method now supports multiple output stream formats, for Mastra (default) and AI SDK v5.
+
+
+## Format Parameter
+
+The `format` parameter determines the output stream type:
+
+- **`'mastra'` (default)**: Returns `MastraModelOutput` - Mastra's native streaming format
+- **`'aisdk'`**: Returns `AISDKV5OutputStream` - Compatible with AI SDK v5 interfaces like useChat.
+
+```typescript
+// Mastra format (default)
+const mastraStream = await agent.streamVNext("Hello");
+
+// AI SDK v5 format
+const aiSdkStream = await agent.streamVNext("Hello", { 
+  format: 'aisdk' 
+});
+```
+
+### Default Mastra Format
+
+By default, `streamVNext` returns a `MastraModelOutput` stream:
 
 ```typescript
-const stream = await agent.streamVNext({ role: "user", content: "Tell me a story." });
+const stream = await agent.streamVNext("Tell me a story.");
 
-for await (const chunk of stream) {
+// Access the text stream
+for await (const chunk of stream.textStream) {
   console.log(chunk);
 }
+
+// Or get the full text after streaming
+const fullText = await stream.text;
 ```
 
-Each chunk is a JSON object with the following properties:
+### AI SDK v5 Compatibility
 
-```json
-{
-  type: string;
-  runId: string;
-  from: string;
-  payload: Record<string, any>;
+For integration with AI SDK v5, use the `format: 'aisdk'` parameter to get an `AISDKV5OutputStream`:
+
+```typescript
+const stream = await agent.streamVNext("Tell me a story.", {
+  format: 'aisdk'
+});
+
+// The stream is now compatible with AI SDK v5 interfaces
+for await (const chunk of stream.fullStream) {
+  // Process AI SDK v5 formatted chunks
+  console.log(chunk);
 }
 ```
 
-The stream provides several utility functions for working with streaming responses:
+## Stream Properties
+
+Both stream formats provide access to various response properties:
 
-- `stream.finishReason` - The reason the agent stopped streaming.
-- `stream.toolCalls` - The tool calls made by the agent.
-- `stream.toolResults` - The tool results returned by the agent.
-- `stream.usage` - The total token usage of the agent, including agents/workflows as a tool.
-- `stream.text` - The full text of the agent's response.
-- `stream.object` - The object of the agent's response, if you use output or experimental output.
-- `stream.textStream` - A readable stream that will emit the text of the agent's response.
+- `stream.textStream` - A readable stream that emits text chunks
+- `stream.text` - Promise that resolves to the full text response
+- `stream.finishReason` - The reason the agent stopped streaming
+- `stream.usage` - Token usage information
 
 ### How to use the stream in a tool
 

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

@@ -9,9 +9,9 @@ import { Callout, Tabs } from "nextra/components";
 
 Mastra integrates with [Vercel's AI SDK](https://sdk.vercel.ai) to support model routing, React Hooks, and data streaming methods.
 
-## AI SDK v5 (beta)
+## AI SDK v5
 
-Mastra also supports AI SDK v5 (beta) see the following section for v5 specific methods: [Vercel AI SDK v5](/docs/frameworks/agentic-uis/ai-sdk#vercel-ai-sdk-v5)
+Mastra also supports AI SDK v5 see the following section for v5 specific methods: [Vercel AI SDK v5](/docs/frameworks/agentic-uis/ai-sdk#vercel-ai-sdk-v5)
 
 <Callout type="warning">
   The code examples contained with this page assume you're using the Next.js App Router at the root of your
@@ -380,94 +380,76 @@ export async function POST(req: Request) {
 
 ## Vercel AI SDK v5
 
-This guide covers Mastra-specific considerations when migrating from AI SDK v4 to v5 beta.
+This guide covers Mastra-specific considerations when migrating from AI SDK v4 to v5.
 
 > Please add any feedback or bug reports to the [AI SDK v5 mega issue in Github.](https://github.com/mastra-ai/mastra/issues/5470)
 
+### Experimental streamVNext Support
+
+Mastra's experimental `streamVNext` method now includes native AI SDK v5 support through the `format` parameter. This provides seamless integration with AI SDK v5's streaming interfaces without requiring compatibility wrappers.
+
+```typescript
+// Use streamVNext with AI SDK v5 format
+const stream = await agent.streamVNext(messages, {
+  format: 'aisdk'  // Enable AI SDK v5 compatibility
+});
+
+// The stream is now compatible with AI SDK v5 interfaces
+return stream.toUIMessageStreamResponse();
+```
+
 ### 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.
 
-- **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
+- **Data compatibility**: New data stored in v5 format will no longer work if you downgrade from v5 to v4
+- **Backup recommendation**: Keep DB backups from before you upgrade to v5
 
 ### Memory and Storage
 
 Mastra automatically handles AI SDK v4 data using its internal `MessageList` class, which manages format conversion—including v4 to v5. No database migrations are required; your existing messages are translated on the fly and continue working after 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.
-
-### Upgrade dependencies
+### Message Format Conversion
 
-Install the `@ai-v5` prerelease version of all Mastra packages:
-
-<Tabs items={["npm", "yarn", "pnpm", "bun"]}>
-  <Tabs.Tab>
-    ```bash copy
-    npm install mastra@ai-v5 @mastra/core@ai-v5 @mastra/memory@ai-v5
-    ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-    ```bash copy
-    yarn add mastra@ai-v5 @mastra/core@ai-v5 @mastra/memory@ai-v5
-    ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-    ```bash copy
-    pnpm add mastra@ai-v5 @mastra/core@ai-v5 @mastra/memory@ai-v5
-    ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-    ```bash copy
-    bun add mastra@ai-v5 @mastra/core@ai-v5 @mastra/memory@ai-v5
-    ```
-  </Tabs.Tab>
-</Tabs>
+For cases where you need to manually convert messages between AI SDK and Mastra formats, use the `convertMessages` utility:
 
-Configure your Mastra instance with `v4` compatibility so your frontend, and the Mastra Playground will continue to work:
+```typescript
+import { convertMessages } from '@mastra/core';
 
-```typescript {7} filename="mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+// Convert AI SDK v4 messages to v5
+const aiv5Messages = convertMessages(aiv4Messages).to('AIV5.UI');
 
-import { weatherAgent } from "./agents/weather-agent";
+// Convert Mastra messages to AI SDK v5
+const aiv5Messages = convertMessages(mastraMessages).to('AIV5.Core');
 
-export const mastra = new Mastra({
-  agents: { weatherAgent },
-  aiSdkCompat: 'v4',
-});
+// Supported output formats:
+// 'Mastra.V2', 'AIV4.UI', 'AIV5.UI', 'AIV5.Core', 'AIV5.Model'
 ```
 
-### Enabling stream compatibility
+This utility is helpful when you want to fetch messages directly from your storage DB and convert them for use in AI SDK.
 
-If your frontend calls a Mastra agent using a custom API route, wrap the `toUIMessageStreamResponse()` result with `createV4CompatibleResponse` to maintain AI SDK `v4` compatibility.
+### Enabling stream compatibility
 
+To enable AI SDK v5 compatibility, use the experimental `streamVNext` method with the `format` parameter:
 
 ```typescript filename="app/api/chat/route.ts" showLineNumbers copy
 import { mastra } from "../../../mastra";
-import { createV4CompatibleResponse } from "@mastra/core/agent";
 
 export async function POST(req: Request) {
   const { messages } = await req.json();
   const myAgent = mastra.getAgent("weatherAgent");
-  const stream = await myAgent.stream(messages);
+  
+  // Use streamVNext with AI SDK v5 format (experimental)
+  const stream = await myAgent.streamVNext(messages, {
+    format: 'aisdk'
+  });
 
-  return createV4CompatibleResponse(stream.toUIMessageStreamResponse().body!);
+  return stream.toUIMessageStreamResponse();
 }
 ```
 
-### 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
-
-
+<Callout type="info">
+  **Note**: The `streamVNext` method with format support is experimental and may change as we refine the feature based on feedback. See the [Agent Streaming documentation](/docs/agents/streaming) for more details about streamVNext.
+</Callout>