@mastra/mcp-docs-server 0.13.26 → 0.13.27

package/.docs/raw/reference/agents/migration-guide.mdx

@@ -0,0 +1,291 @@
+# Migration Guide: VNext to Standard APIs
+
+## Overview
+
+As of `v 0.20.00`, the `streamVNext()` and `generateVNext()` methods in Mastra agents have been renamed to `stream()` and `generate()` respectively. These are now the standard APIs with full AI SDK v5 compatibility. The original `stream()` and `generate()` methods have been renamed to `streamLegacy()` and `generateLegacy()` to maintain backward compatibility with AI SDK v4.
+
+### Continue using AI SDK v4 models
+- Rename all your `stream()` and `generate()` calls to `streamLegacy()` and `generateLegacy()` respectively. No other change is needed.
+
+### Continue using AI SDK v5 models
+- Rename all your `streamVNext()` and `generateVNext()` calls to `stream()` and `generate()` respectively. No other change is needed.
+
+### Upgrade from AI SDK v4 models to v5 models
+
+First bump all your model provider packages by a major version. This will ensure that they are all v5 models now. Follow the guide below to understand the differences.
+
+## Key Differences
+
+### 1. Model version support
+
+- **Legacy APIs (`generateLegacy`, `streamLegacy`)**: Only support AI SDK v4 models (specificationVersion: 'v1')
+- **Current APIs (`generate`, `stream`)**: Only support AI SDK v5 models (specificationVersion: 'v2')
+- This is enforced at runtime with clear error messages
+
+### 2. Return types
+
+#### Legacy methods return AI SDK v4 types
+
+- **`generateLegacy()`**:
+  - `GenerateTextResult` or `GenerateObjectResult`
+
+- **`streamLegacy()`**:
+  - `StreamTextResult` or `StreamObjectResult`
+
+#### New stream methods return Mastra/AI SDK v5 types
+
+- **`generate()`**:
+  - When `format: 'mastra'` (default): Returns `MastraModelOutput.getFullOutput()` result
+  - When `format: 'aisdk'`: Returns `AISDKV5OutputStream.getFullOutput()` result (AI SDK v5 compatible)
+  - Internally calls `stream()` and awaits `getFullOutput()`
+
+- **`stream()`**:
+  - When `format: 'mastra'` (default): Returns `MastraModelOutput<OUTPUT>`
+  - When `format: 'aisdk'`: Returns `AISDKV5OutputStream<OUTPUT>` (AI SDK v5 compatible)
+
+#### Format Control
+
+- **Legacy**: No format control, always returns AI SDK v4 types
+- **New stream**: Can choose format via `format` option ('mastra' or 'aisdk')
+
+```typescript
+// Mastra native format (default)
+const result = await agent.stream(messages, {
+  format: 'mastra'
+});
+
+// AI SDK v5 compatibility
+const result = await agent.stream(messages, {
+  format: 'aisdk'
+});
+```
+
+### 3. New Options in Non-Legacy APIs
+
+The following options are available in `stream()` and `generate()` but NOT in their legacy counterparts:
+
+1. **`format`** - Choose between 'mastra' or 'aisdk' output format
+
+```typescript
+const result = await agent.stream(messages, {
+  format: 'aisdk' // or 'mastra' (default)
+});
+```
+
+2. **`system`** - Custom system message (separate from instructions)
+
+```typescript
+const result = await agent.stream(messages, {
+  system: 'You are a helpful assistant'
+});
+```
+
+3. **`structuredOutput`** - Enhanced structured output with model override and custom options
+
+- If no model is added it will use the agent's default model.
+- Error strategy when the object does not conform to the schema is `warn` (log a warning), `error` (throw an error), or `fallback` (return a default fallback value of your choice).
+
+```typescript
+const result = await agent.generate(messages, {
+  structuredOutput: {
+    schema: z.object({
+      name: z.string(),
+      age: z.number()
+    }),
+    model: openai('gpt-4o-mini'), // Optional model override for structuring
+    errorStrategy: 'fallback',
+    fallbackValue: { name: 'unknown', age: 0 },
+    instructions: 'Extract user information' // Override default structuring instructions
+  }
+});
+```
+
+4. **`stopWhen`** - Flexible stop conditions (step count, token limit, etc.)
+
+```typescript
+const result = await agent.stream(messages, {
+  stopWhen: ({ steps, totalTokens }) => steps >= 5 || totalTokens >= 10000
+});
+```
+
+5. **`providerOptions`** - Provider-specific options (e.g., OpenAI-specific settings)
+
+```typescript
+const result = await agent.stream(messages, {
+  providerOptions: {
+    openai: {
+      store: true,
+      metadata: { userId: '123' }
+    }
+  }
+});
+```
+
+6. **`onChunk`** - Callback for each streaming chunk
+
+```typescript
+const result = await agent.stream(messages, {
+  onChunk: (chunk) => {
+    console.log('Received chunk:', chunk);
+  }
+});
+```
+
+7. **`onError`** - Error callback
+
+```typescript
+const result = await agent.stream(messages, {
+  onError: (error) => {
+    console.error('Stream error:', error);
+  }
+});
+```
+
+8. **`onAbort`** - Abort callback
+
+```typescript
+const result = await agent.stream(messages, {
+  onAbort: () => {
+    console.log('Stream aborted');
+  }
+});
+```
+
+9. **`activeTools`** - Specify which tools are active for this execution
+
+```typescript
+const result = await agent.stream(messages, {
+  activeTools: ['search', 'calculator'] // Only these tools will be available
+});
+```
+
+10. **`abortSignal`** - AbortSignal for cancellation
+
+```typescript
+const controller = new AbortController();
+const result = await agent.stream(messages, {
+  abortSignal: controller.signal
+});
+
+// Later: controller.abort();
+```
+
+11. **`prepareStep`** - Callback before each step in multi-step execution
+
+```typescript
+const result = await agent.stream(messages, {
+  prepareStep: ({ step, state }) => {
+    console.log('About to execute step:', step);
+    return { /* modified state */ };
+  }
+});
+```
+
+12. **`requireToolApproval`** - Require approval for all tool calls
+
+```typescript
+const result = await agent.stream(messages, {
+  requireToolApproval: true
+});
+```
+
+### 4. Options That Still Exist But Have Been Moved
+
+#### `temperature` and Other Model Settings
+
+Unified in `modelSettings`
+
+```typescript
+const result = await agent.stream(messages, {
+  modelSettings: {
+    temperature: 0.7,
+    maxTokens: 1000,
+    topP: 0.9
+  }
+});
+```
+
+#### `resourceId` and `threadId`
+
+Moved to memory object.
+
+```typescript
+const result = await agent.stream(messages, {
+  memory: {
+    resource: 'user-123',
+    thread: 'thread-456'
+  }
+});
+```
+
+### 5. Options That Are Deprecated or Removed
+
+#### `experimental_output`
+
+Use `structuredOutput` instead to allow for tool calls and an object return.
+
+```typescript
+const result = await agent.generate(messages, {
+  structuredOutput: {
+    schema: z.object({
+      summary: z.string()
+    })
+  }
+});
+```
+
+#### `output`
+
+The `output` property is deprecated in favor of `structuredOutput`, to achieve the same results use maxSteps 1 with `structuredOutput`.
+
+```typescript
+const result = await agent.generate(messages, {
+  structuredOutput: {
+    schema: {
+      z.object({
+        name: z.string()
+      })
+    }
+  },
+  maxSteps: 1
+});
+```
+
+#### `memoryOptions` was removed
+
+Use `memory` instead
+```typescript
+const result = await agent.generate(messages, {
+  memory: {
+    ...
+  }
+});
+```
+
+### 6. Type Changes
+
+#### `context`
+
+- **Legacy**: `CoreMessage[]`
+- **New format**: `ModelMessage[]`
+
+#### `toolChoice` uses the AI SDK v5 `ToolChoice` type
+
+```typescript
+type ToolChoice<TOOLS extends Record<string, unknown>> = 'auto' | 'none' | 'required' | {
+    type: 'tool';
+    toolName: Extract<keyof TOOLS, string>;
+};
+```
+
+
+## Migration Checklist
+
+### If you're already using `streamVNext` and `generateVNext`
+
+Just find/replace the methods to `stream` and `generate` respectively.
+
+### If you're using the old `stream` and `generate`
+
+Decide whether you want to upgrade or not. If you don't, just find/replace to `streamLegacy` and `generateLegacy`.
+

package/.docs/raw/reference/client-js/agents.mdx

@@ -2,7 +2,6 @@
 title: Mastra Client Agents API
 description: Learn how to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools using the client-js SDK.
 ---
-import { StreamVNextCallout } from "@/components/streamVNext-callout.tsx"
 
 # Agents API
 
@@ -161,14 +160,13 @@ const liveEvals = await agent.liveEvals();
 ```
 
 
-### Stream VNext (Experimental)
+### Stream
 
-<StreamVNextCallout />
 
-Stream responses using the enhanced VNext API with improved method signatures.
+Stream responses using the enhanced API with improved method signatures. This method provides enhanced capabilities and format flexibility, with support for both Mastra's native format and AI SDK v5 compatibility:
 
 ```typescript
-const response = await agent.streamVNext(
+const response = await agent.stream(
   "Tell me a story",
   {
     threadId: "thread-1",
@@ -176,6 +174,14 @@ const response = await agent.streamVNext(
   }
 );
 
+// AI SDK v5 compatible format
+const response = await agent.stream(
+  "Tell me a story",
+  {
+    format: 'aisdk', // Enable AI SDK v5 compatibility
+    threadId: "thread-1",
+  }
+);
 
 // Process the stream
 response.processDataStream({
@@ -189,12 +195,12 @@ Currently, AI SDK V5 format is not supported in the client SDK.
 For AI SDK v5 compatible format, leverage the `@mastra/ai-sdk` package
 [AI SDK v5 Stream Compatibility](/docs/frameworks/agentic-uis/ai-sdk#enabling-stream-compatibility)
 
-### Generate VNext (Experimental)
+### Generate
 
-Generate a response using the enhanced VNext API with improved method signatures and AI SDK v5 compatibility:
+Generate a response using the enhanced API with improved method signatures and AI SDK v5 compatibility:
 
 ```typescript
-const response = await agent.generateVNext(
+const response = await agent.generate(
   "Hello, how are you?",
   {
     threadId: "thread-1",

package/.docs/raw/reference/deployer/vercel.mdx

@@ -18,3 +18,29 @@ export const mastra = new Mastra({
   deployer: new VercelDeployer()
 });
 ```
+
+## Constructor options
+
+The deployer supports a small set of high‑value overrides that are written to the Vercel Output API function config (`.vc-config.json`):
+
+- `maxDuration?: number` — Function execution timeout (in seconds)
+- `memory?: number` — Function memory (in MB)
+- `regions?: string[]` — Regions to deploy the function (e.g. `['sfo1','iad1']`)
+
+These options are merged into `.vercel/output/functions/index.func/.vc-config.json` while preserving default fields (`handler`, `launcherType`, `runtime`, `shouldAddHelpers`).
+
+### Example with overrides
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { VercelDeployer } from "@mastra/deployer-vercel";
+
+export const mastra = new Mastra({
+  // ...
+  deployer: new VercelDeployer({
+    maxDuration: 600,
+    memory: 1536,
+    regions: ["sfo1", "iad1"],
+  }),
+});
+```

package/.docs/raw/reference/streaming/ChunkType.mdx

@@ -9,7 +9,7 @@ import { PropertiesTable } from "@/components/properties-table";
 # ChunkType (Experimental)
 
 <Callout type="important">
-  <strong className="block">Experimental API: </strong>This type is part of the experimental `.streamVNext()` method. The API may change as we refine the feature based on feedback.
+  <strong className="block">Experimental API: </strong>This type is part of the experimental `.stream()` method. The API may change as we refine the feature based on feedback.
 </Callout>
 
 The `ChunkType` type defines the mastra format of stream chunks that can be emitted during streaming responses from agents.
@@ -766,7 +766,7 @@ Contains metadata about the LLM provider's response. Emitted by some providers a
 
 ### watch
 
-Contains monitoring and observability data from agent execution. Can include workflow state information, execution progress, or other runtime details depending on the context where `streamVNext()` is used.
+Contains monitoring and observability data from agent execution. Can include workflow state information, execution progress, or other runtime details depending on the context where `stream()` is used.
 
 <PropertiesTable
   content={[
@@ -819,7 +819,7 @@ Emitted when the stream is forcibly terminated due to content being blocked by o
 ## Usage Example
 
 ```typescript
-const stream = await agent.streamVNext("Hello");
+const stream = await agent.stream("Hello");
 
 for await (const chunk of stream.fullStream) {
   switch (chunk.type) {
@@ -853,6 +853,6 @@ for await (const chunk of stream.fullStream) {
 
 ## Related Types
 
+- [.stream()](./stream.mdx) - Method that returns streams emitting these chunks
 - [MastraModelOutput](./agents/MastraModelOutput.mdx) - The stream object that emits these chunks
-- [agent.streamVNext()](./agents/streamVNext.mdx) - Method that returns streams emitting these chunks for agents
 - [workflow.streamVNext()](./workflows/streamVNext.mdx) - Method that returns streams emitting these chunks for workflows

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

@@ -1,6 +1,6 @@
 ---
 title: "Reference: MastraModelOutput (Experimental) | Agents | Mastra Docs"
-description: "Complete reference for MastraModelOutput - the stream object returned by agent.streamVNext() with streaming and promise-based access to model outputs."
+description: "Complete reference for MastraModelOutput - the stream object returned by agent.stream() with streaming and promise-based access to model outputs."
 ---
 
 import { Callout } from "nextra/components";
@@ -9,17 +9,17 @@ import { PropertiesTable } from "@/components/properties-table";
 # MastraModelOutput (Experimental)
 
 <Callout type="important">
-  <strong className="block">Experimental API: </strong>This type is part of the experimental `.streamVNext()` method. The API may change as we refine the feature based on feedback.
+  <strong className="block">Experimental API: </strong>This type is part of the experimental `.stream()` method. The API may change as we refine the feature based on feedback.
 </Callout>
 
-The `MastraModelOutput` class is returned by [.streamVNext()](./streamVNext.mdx) and provides both streaming and promise-based access to model outputs. It supports structured output generation, tool calls, reasoning, and comprehensive usage tracking.
+The `MastraModelOutput` class is returned by [.stream()](./stream.mdx) and provides both streaming and promise-based access to model outputs. It supports structured output generation, tool calls, reasoning, and comprehensive usage tracking.
 
 ```typescript
-// MastraModelOutput is returned by agent.streamVNext()
-const stream = await agent.streamVNext("Hello world");
+// MastraModelOutput is returned by agent.stream()
+const stream = await agent.stream("Hello world");
 ```
 
-For setup and basic usage, see the [.streamVNext()](./streamVNext.mdx) method documentation.
+For setup and basic usage, see the [.stream()](./stream.mdx) method documentation.
 
 ## Streaming Properties
 
@@ -206,7 +206,7 @@ These properties resolve to final values after the stream completes:
 ### Basic Text Streaming
 
 ```typescript
-const stream = await agent.streamVNext("Write a haiku");
+const stream = await agent.stream("Write a haiku");
 
 // Stream text as it's generated
 for await (const text of stream.textStream) {
@@ -221,7 +221,7 @@ console.log(fullText);
 ### Structured Output Streaming
 
 ```typescript
-const stream = await agent.streamVNext("Generate user data", {
+const stream = await agent.stream("Generate user data", {
   output: z.object({
     name: z.string(),
     age: z.number(),
@@ -242,7 +242,7 @@ console.log("Final:", user); // { name: "John", age: 30, email: "john@example.co
 ### Tool Calls and Results
 
 ```typescript
-const stream = await agent.streamVNext("What's the weather in NYC?", {
+const stream = await agent.stream("What's the weather in NYC?", {
   tools: { weather: weatherTool }
 });
 
@@ -257,7 +257,7 @@ console.log("Results:", toolResults);
 ### Complete Output Access
 
 ```typescript
-const stream = await agent.streamVNext("Analyze this data");
+const stream = await agent.stream("Analyze this data");
 
 const output = await stream.getFullOutput();
 console.log({
@@ -271,7 +271,7 @@ console.log({
 ### Full Stream Processing
 
 ```typescript
-const stream = await agent.streamVNext("Complex task");
+const stream = await agent.stream("Complex task");
 
 for await (const chunk of stream.fullStream) {
   switch (chunk.type) {
@@ -294,7 +294,7 @@ for await (const chunk of stream.fullStream) {
 ### Error Handling
 
 ```typescript
-const stream = await agent.streamVNext("Analyze this data");
+const stream = await agent.stream("Analyze this data");
 
 try {
   // Option 1: Handle errors in consumeStream
@@ -318,5 +318,5 @@ if (stream.error) {
 
 ## Related Types
 
+- [.stream()](./stream.mdx) - Method that returns MastraModelOutput
 - [ChunkType](../ChunkType.mdx) - All possible chunk types in the full stream
-- [.streamVNext()](./streamVNext.mdx) - Method that returns MastraModelOutput