@mastra/mcp-docs-server 0.13.12-alpha.0 → 0.13.12-alpha.2

package/.docs/raw/reference/agents/streamVNext.mdx

@@ -1,11 +1,17 @@
 ---
-title: "Reference: Agent.streamVNext() | Agents | Mastra Docs"
+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."
 ---
 
-# Agent.streamVNext()
+import { Callout } from "nextra/components";
 
-The `.streamVNext()` method enables real-time streaming of responses from an agent with enhanced capabilities. This method accepts messages and optional streaming options, providing a next-generation streaming experience.
+# Agent.streamVNext() (Experimental)
+
+<Callout type="warning">
+  **Experimental Feature**: This is a new streaming implementation that will replace the existing `stream()` method once battle-tested. The API may change as we refine the feature based on feedback.
+</Callout>
+
+The `.streamVNext()` method enables real-time streaming of responses from an agent with enhanced capabilities. This method accepts messages and optional streaming options, providing a next-generation streaming experience that will eventually replace the current `stream()` method.
 
 ## Usage example
 
@@ -48,12 +54,72 @@ await agent.streamVNext("message for agent");
       isOptional: true,
       description: "Additional context messages to provide to the agent.",
     },
+    {
+      name: "structuredOutput",
+      type: "StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>",
+      isOptional: true,
+      description: "Enables structured output generation with better developer experience. Automatically creates and uses a StructuredOutputProcessor internally.",
+      properties: [
+        {
+          parameters: [{
+            name: "schema",
+            type: "z.ZodSchema<S>",
+            isOptional: false,
+            description: "Zod schema to validate the output against."
+          }]
+        },
+        {
+          parameters: [{
+            name: "model",
+            type: "MastraLanguageModel",
+            isOptional: false,
+            description: "Model to use for the internal structuring agent."
+          }]
+        },
+        {
+          parameters: [{
+            name: "errorStrategy",
+            type: "'strict' | 'warn' | 'fallback'",
+            isOptional: true,
+            description: "Strategy when parsing or validation fails. Defaults to 'strict'."
+          }]
+        },
+        {
+          parameters: [{
+            name: "fallbackValue",
+            type: "<S extends ZodTypeAny>",
+            isOptional: true,
+            description: "Fallback value when errorStrategy is 'fallback'."
+          }]
+        },
+        {
+          parameters: [{
+            name: "instructions",
+            type: "string",
+            isOptional: true,
+            description: "Custom instructions for the structuring agent."
+          }]
+        },
+      ]
+    },
+    {
+      name: "outputProcessors",
+      type: "Processor[]",
+      isOptional: true,
+      description: "Overrides the output processors set on the agent. Output processors that can modify or validate messages from the agent before they are returned to the user. Must implement either (or both) of the `processOutputResult` and `processOutputStream` functions.",
+    },
+    {
+      name: "inputProcessors",
+      type: "Processor[]",
+      isOptional: true,
+      description: "Overrides the input processors set on the agent. Input processors that can modify or validate messages before they are processed by the agent. Must implement the `processInput` function.",
+    },
     {
       name: "experimental_output",
       type: "Zod schema | JsonSchema7",
       isOptional: true,
       description:
-        "Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.",
+        "Note, the preferred route is to use the `structuredOutput` property. Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.",
     },
     {
       name: "instructions",
@@ -391,6 +457,9 @@ await agent.streamVNext("message for agent");
 ## Extended usage example
 
 ```typescript showLineNumbers copy
+import { z } from "zod";
+import { ModerationProcessor, BatchPartsProcessor } from "@mastra/core/processors";
+
 await agent.streamVNext("message for agent", {
   temperature: 0.7,
   maxSteps: 3,
@@ -398,6 +467,20 @@ await agent.streamVNext("message for agent", {
     thread: "user-123",
     resource: "test-app"
   },
-  toolChoice: "auto"
+  toolChoice: "auto",
+  // Structured output with better DX
+  structuredOutput: {
+    schema: z.object({
+      sentiment: z.enum(['positive', 'negative', 'neutral']),
+      confidence: z.number(),
+    }),
+    model: openai("gpt-4o-mini"),
+    errorStrategy: 'warn',
+  },
+  // Output processors for streaming response validation
+  outputProcessors: [
+    new ModerationProcessor({ model: openai("gpt-4.1-nano") }),
+    new BatchPartsProcessor({ maxBatchSize: 3, maxWaitTime: 100 }),
+  ],
 });
 ```

package/.docs/raw/reference/rag/chroma.mdx

@@ -3,46 +3,88 @@ title: "Reference: Chroma Vector Store | Vector Databases | RAG | Mastra Docs"
 description: Documentation for the ChromaVector class in Mastra, which provides vector search using ChromaDB.
 ---
 
+import { Callout } from "nextra/components";
+
 # Chroma Vector Store
 
-The ChromaVector class provides vector search using [ChromaDB](https://www.trychroma.com/), an open-source embedding database.
+The ChromaVector class provides vector search using [Chroma](https://docs.trychroma.com/docs/overview/getting-started), an open-source embedding database.
 It offers efficient vector search with metadata filtering and hybrid search capabilities.
 
+<Callout type="info">
+  <b>Chroma Cloud</b>
+  <p>
+    Chroma Cloud powers serverless vector and full-text search. It's extremely fast, cost-effective, scalable and painless. Create a DB and try it out in under 30 seconds with $5 of free credits.
+
+    [Get started with Chroma Cloud](https://trychroma.com/signup)
+  </p>
+</Callout>
+
 ## Constructor Options
 
 <PropertiesTable
   content={[
     {
-      name: "path",
+      name: "host",
       type: "string",
-      description: "URL path to ChromaDB instance",
+      isOptional: true,
+      description: "The host address of the Chroma server. Defaults to 'localhost'",
     },
     {
-      name: "auth",
-      type: "object",
+      name: "port",
+      type: "number",
       isOptional: true,
-      description: "Authentication configuration",
+      description: "The port number of the Chroma server. Defaults to 8000",
+    },
+    {
+      name: "ssl",
+      type: "boolean",
+      isOptional: true,
+      description: "Whether to use SSL/HTTPS for connections. Defaults to false",
     },
-  ]}
-/>
-
-### auth
-
-<PropertiesTable
-  content={[
     {
-      name: "provider",
+      name: "apiKey",
       type: "string",
-      description: "Authentication provider",
+      isOptional: true,
+      description: "A Chroma Cloud API key",
     },
     {
-      name: "credentials",
+      name: "tenant",
       type: "string",
-      description: "Authentication credentials",
+      isOptional: true,
+      description: "The tenant name in the Chroma server to connect to. Defaults to 'default_tenant' for single-node Chroma. Auto-resolved for Chroma Cloud users based on the provided API key",
+    },
+    {
+      name: "database",
+      type: "string",
+      isOptional: true,
+      description: "The database name to connect to. Defaults to 'default_database' for single-node Chroma. Auto-resolved for Chroma Cloud users based on the provided API key",
+    },
+    {
+      name: "headers",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Additional HTTP headers to send with requests",
     },
+    {
+      name: "fetchOptions",
+      type: "RequestInit",
+      isOptional: true,
+      description: "Additional fetch options for HTTP requests",
+    }
   ]}
 />
 
+## Running a Chroma Server
+
+If you are a Chroma Cloud user, simply provide the `ChromaVector` constructor your API key, tenant, and database name.
+
+When you install the `@mastra/chroma` package, you get access to the [Chroma CLI](https://docs.trychroma.com/docs/cli/db), which can set these as environment variables for you: `chroma db connect [DB-NAME] --env-file`.
+
+Otherwise, you have several options for setting up your single-node Chroma server:
+* Run one locally using the Chroma CLI: `chroma run`. You can find more configuration options on the [Chroma docs](https://docs.trychroma.com/docs/cli/run).
+* Run on [Docker](https://docs.trychroma.com/guides/deploy/docker) using the official Chroma image.
+* Deploy your own Chroma server on your provider of choice. Chroma offers example templates for [AWS](https://docs.trychroma.com/guides/deploy/aws), [Azure](https://docs.trychroma.com/guides/deploy/azure), and [GCP](https://docs.trychroma.com/guides/deploy/gcp).
+
 ## Methods
 
 ### createIndex()
@@ -69,6 +111,27 @@ It offers efficient vector search with metadata filtering and hybrid search capa
   ]}
 />
 
+### forkIndex()
+
+Note: Forking is only supported on Chroma Cloud, or if you deploy your own OSS **distributed** Chroma.
+
+`forkIndex` lets you fork an existing Chroma index instantly. Operations on the forked index do not affect the original one. Learn more on the [Chroma docs](https://docs.trychroma.com/cloud/collection-forking).
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to fork",
+    },
+    {
+      name: "newIndexName",
+      type: "string",
+      description: "The name of the forked index",
+    }
+  ]}
+/>
+
 ### upsert()
 
 <PropertiesTable
@@ -107,6 +170,20 @@ It offers efficient vector search with metadata filtering and hybrid search capa
 
 ### query()
 
+Query an index using a `queryVector`. Returns an array of semantically similar records in order of distance from the `queryVector`. Each record has the shape:
+
+```typescript
+{
+  id: string;
+  score: number;
+  document?: string;
+  metadata?: Record<string, string | number | boolean>;
+  embedding?: number[]
+}
+```
+
+You can also provide the shape of your metadata to a `query` call for type inference: `query<T>()`.
+
 <PropertiesTable
   content={[
     {
@@ -148,6 +225,70 @@ It offers efficient vector search with metadata filtering and hybrid search capa
   ]}
 />
 
+### get()
+
+Get records from your Chroma index by IDs, metadata, and document filters. It returns an array of records of the shape:
+
+```typescript
+{
+  id: string;
+  document?: string;
+  metadata?: Record<string, string | number | boolean>;
+  embedding?: number[]
+}
+```
+
+You can also provide the shape of your metadata to a `get` call for type inference: `get<T>()`.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to query",
+    },
+    {
+      name: "ids",
+      type: "string[]",
+      isOptional: true,
+      description: "A list of record IDs to return. If not provided, all records are returned.",
+    },
+    {
+      name: "filter",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Metadata filters.",
+    },
+    {
+      name: "includeVector",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "Whether to include vectors in the results",
+    },
+    {
+      name: "documentFilter",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Chroma-specific: Filter to apply on the document content",
+    },
+    {
+      name: "limit",
+      type: "number",
+      isOptional: true,
+      defaultValue: 100,
+      description: "The maximum number of records to return",
+    },
+    {
+      name: "offset",
+      type: "number",
+      isOptional: true,
+      defaultValue: 0,
+      description: "Offset for returning records. Use with `limit` to paginate results.",
+    },
+  ]}
+/>
+
 ### listIndexes()
 
 Returns an array of index names as strings.

package/.docs/raw/reference/tools/mcp-client.mdx

@@ -342,7 +342,7 @@ The handler function receives a request object with:
 - `requestedSchema`: A JSON schema defining the structure of the expected response
 
 The handler must return an `ElicitResult` with:
-- `action`: One of `'accept'`, `'reject'`, or `'cancel'`
+- `action`: One of `'accept'`, `'decline'`, or `'cancel'`
 - `content`: The user's data (only when action is `'accept'`)
 
 **Example:**
@@ -363,8 +363,8 @@ mcpClient.elicitation.onRequest('serverName', async (request) => {
     };
   }
   
-  // Simulate user rejecting the request
-  return { action: 'reject' };
+  // Simulate user declining the request
+  return { action: 'decline' };
 });
 ```
 
@@ -423,7 +423,7 @@ await mcpClient.elicitation.onRequest('interactiveServer', async (request) => {
     // Validate required fields
     if (answer === '' && isRequired) {
       console.log(`❌ ${fieldName} is required`);
-      return { action: 'reject' };
+      return { action: 'decline' };
     }
     
     if (answer !== '') {
@@ -442,7 +442,7 @@ await mcpClient.elicitation.onRequest('interactiveServer', async (request) => {
   } else if (confirm.toLowerCase() === 'cancel') {
     return { action: 'cancel' };
   } else {
-    return { action: 'reject' };
+    return { action: 'decline' };
   }
 });
 ```
@@ -521,7 +521,7 @@ Elicitation is a feature that allows MCP servers to request structured informati
 1. **Server Request**: An MCP server tool calls `server.elicitation.sendRequest()` with a message and schema
 2. **Client Handler**: Your elicitation handler function is called with the request
 3. **User Interaction**: Your handler collects user input (via UI, CLI, etc.)
-4. **Response**: Your handler returns the user's response (accept/reject/cancel)
+4. **Response**: Your handler returns the user's response (accept/decline/cancel)
 5. **Tool Continuation**: The server tool receives the response and continues execution
 
 ### Setting Up Elicitation
@@ -566,9 +566,9 @@ Your elicitation handler must return one of three response types:
   };
   ```
 
-- **Reject**: User explicitly declined to provide the information
+- **Decline**: User explicitly declined to provide the information
   ```typescript
-  return { action: 'reject' };
+  return { action: 'decline' };
   ```
 
 - **Cancel**: User dismissed or cancelled the request
@@ -613,7 +613,7 @@ await mcpClient.elicitation.onRequest('interactiveServer', async (request) => {
 
 - **Always handle elicitation**: Set up your handler before calling tools that might use elicitation
 - **Validate input**: Check that required fields are provided
-- **Respect user choice**: Handle reject and cancel responses gracefully
+- **Respect user choice**: Handle decline and cancel responses gracefully
 - **Clear UI**: Make it obvious what information is being requested and why
 - **Security**: Never auto-accept requests for sensitive information
 

package/.docs/raw/reference/tools/mcp-server.mdx

@@ -872,7 +872,7 @@ A common use case is during tool execution. When a tool needs user input, it can
 1. The tool calls `options.elicitation.sendRequest()` with a message and schema
 2. The request is sent to the connected MCP client
 3. The client presents the request to the user (via UI, command line, etc.)
-4. The user provides input, rejects, or cancels the request
+4. The user provides input, declines, or cancels the request
 5. The client sends the response back to the server
 6. The tool receives the response and continues execution
 
@@ -934,7 +934,7 @@ const server = new MCPServer({
           // Handle the user's response
           if (result.action === 'accept') {
             return `Contact information collected: ${JSON.stringify(result.content, null, 2)}`;
-          } else if (result.action === 'reject') {
+          } else if (result.action === 'decline') {
             return 'Contact information collection was declined by the user.';
           } else {
             return 'Contact information collection was cancelled by the user.';
@@ -990,7 +990,7 @@ Users can respond to elicitation requests in three ways:
 
 1. **Accept** (`action: 'accept'`): User provided data and confirmed submission
    - Contains `content` field with the submitted data
-2. **Reject** (`action: 'reject'`): User explicitly declined to provide information
+2. **Decline** (`action: 'decline'`): User explicitly declined to provide information
    - No content field
 3. **Cancel** (`action: 'cancel'`): User dismissed the request without deciding
    - No content field
@@ -1001,7 +1001,7 @@ Tools should handle all three response types appropriately.
 
 - **Never request sensitive information** like passwords, SSNs, or credit card numbers
 - Validate all user input against the provided schema
-- Handle rejection and cancellation gracefully
+- Handle declining and cancellation gracefully
 - Provide clear reasons for data collection
 - Respect user privacy and preferences
 
@@ -1031,7 +1031,7 @@ The `ElicitResult` type:
 
 ```typescript
 type ElicitResult = {
-  action: 'accept' | 'reject' | 'cancel';
+  action: 'accept' | 'decline' | 'cancel';
   content?: any; // Only present when action is 'accept'
 }
 ```

package/.docs/raw/reference/workflows/run-methods/streamVNext.mdx

@@ -3,9 +3,15 @@ title: "Reference: Run.streamVNext() | Workflows | Mastra Docs"
 description: Documentation for the `Run.streamVNext()` method in workflows, which enables real-time streaming of responses.
 ---
 
+import { Callout } from "nextra/components";
+
 # Run.streamVNext()
 
-The `.streamVNext()` method enables real-time streaming of responses from a workflow.
+<Callout type="warning">
+  **Experimental Feature**: This is a new streaming implementation that will replace the existing `stream()` method once battle-tested. The API may change as we refine the feature based on feedback.
+</Callout>
+
+The `.streamVNext()` method enables real-time streaming of responses from a workflow. This enhanced streaming capability will eventually replace the current `stream()` method.
 
 ## Usage example
 

package/.docs/raw/voice/overview.mdx

@@ -548,7 +548,7 @@ For detailed configuration options and advanced features, check out [Speech to S
   The tab shows how to set up real-time voice communication with event handling for audio responses.
   This enables conversational AI experiences with continuous audio streaming.
 */}
-<Tabs items={["OpenAI"]}>
+<Tabs items={["OpenAI", "Google Gemini Live"]}>
   <Tabs.Tab>
 ```typescript
 import { Agent } from '@mastra/core/agent';
@@ -578,6 +578,53 @@ await voiceAgent.voice.send(micStream);
 
 Visit the [OpenAI Voice Reference](/reference/voice/openai-realtime) for more information on the OpenAI voice provider.
 
+  </Tabs.Tab>
+  <Tabs.Tab>
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+import { playAudio, getMicrophoneStream } from '@mastra/node-audio';
+import { GeminiLiveVoice } from "@mastra/voice-google-gemini-live";
+
+const voiceAgent = new Agent({
+  name: "Voice Agent",
+  instructions: "You are a voice assistant that can help users with their tasks.",
+  model: openai("gpt-4o"),
+  voice: new GeminiLiveVoice({
+    // Live API mode
+    apiKey: process.env.GOOGLE_API_KEY,
+    model: 'gemini-2.0-flash-exp',
+    speaker: 'Puck',
+    debug: true,
+    // Vertex AI alternative:
+    // vertexAI: true,
+    // project: 'your-gcp-project',
+    // location: 'us-central1',
+    // serviceAccountKeyFile: '/path/to/service-account.json',
+  }),
+});
+
+// Connect before using speak/send
+await voiceAgent.voice.connect();
+
+// Listen for agent audio responses
+voiceAgent.voice.on('speaker', ({ audio }) => {
+  playAudio(audio);
+});
+
+// Listen for text responses and transcriptions
+voiceAgent.voice.on('writing', ({ text, role }) => {
+  console.log(`${role}: ${text}`);
+});
+
+// Initiate the conversation
+await voiceAgent.voice.speak('How can I help you today?');
+
+// Send continuous audio from the microphone
+const micStream = getMicrophoneStream();
+await voiceAgent.voice.send(micStream);
+```
+
   </Tabs.Tab>
 </Tabs>
 
@@ -592,7 +639,7 @@ The tabs help users understand the full configuration capabilities of each provi
 Each tab shows both speech and listening model configurations where applicable.
 */}
 
-<Tabs items={["OpenAI", "Azure", "ElevenLabs", "PlayAI", "Google", "Cloudflare", "Deepgram", "Speechify", "Sarvam", "Murf", "OpenAI Realtime"]}>
+<Tabs items={["OpenAI", "Azure", "ElevenLabs", "PlayAI", "Google", "Cloudflare", "Deepgram", "Speechify", "Sarvam", "Murf", "OpenAI Realtime", "Google Gemini Live"]}>
   <Tabs.Tab>
 ```typescript
 // OpenAI Voice Configuration
@@ -618,6 +665,38 @@ Visit the [OpenAI Voice Reference](/reference/voice/openai) for more information
   </Tabs.Tab>
   <Tabs.Tab>
 ```typescript
+// Google Gemini Live Voice Configuration
+import { GeminiLiveVoice } from '@mastra/voice-google-gemini-live';
+
+const voice = new GeminiLiveVoice({
+  // Live API
+  apiKey: process.env.GOOGLE_API_KEY,
+  model: 'gemini-2.0-flash-exp',
+  speaker: 'Puck',
+  debug: true,
+  // Vertex AI alternative:
+  // vertexAI: true,
+  // project: 'your-gcp-project',
+  // location: 'us-central1',
+  // serviceAccountKeyFile: '/path/to/service-account.json',
+  // sessionConfig: {
+  //   vad: { enabled: true, sensitivity: 0.5, silenceDurationMs: 1000 },
+  //   interrupts: { enabled: true, allowUserInterruption: true },
+  //   contextCompression: false,
+  // }
+});
+
+// Per-turn overrides
+await voice.speak('Hello', {
+  languageCode: 'en-US',
+  responseModalities: ['AUDIO'] as any,
+  speaker: 'Puck',
+});
+```
+
+  </Tabs.Tab>
+  <Tabs.Tab>
+```typescript
 // Azure Voice Configuration
 const voice = new AzureVoice({
   speechModel: {

package/.docs/raw/voice/speech-to-speech.mdx

@@ -58,3 +58,48 @@ await agent.voice.send(micStream);
 ```
 
 For integrating Speech-to-Speech capabilities with agents, refer to the [Adding Voice to Agents](../agents/adding-voice.mdx) documentation.
+
+## Google Gemini Live (Realtime)
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { GeminiLiveVoice } from "@mastra/voice-google-gemini-live";
+import { playAudio, getMicrophoneStream } from "@mastra/node-audio";
+
+const agent = new Agent({
+  name: 'Agent',
+  instructions: 'You are a helpful assistant with real-time voice capabilities.',
+  // Model used for text generation; voice provider handles realtime audio
+  model: openai("gpt-4o"),
+  voice: new GeminiLiveVoice({
+    apiKey: process.env.GOOGLE_API_KEY,
+    model: 'gemini-2.0-flash-exp',
+    speaker: 'Puck',
+    debug: true,
+    // Vertex AI option:
+    // vertexAI: true, 
+    // project: 'your-gcp-project', 
+    // location: 'us-central1',
+    // serviceAccountKeyFile: '/path/to/service-account.json',
+  }),
+});
+
+await agent.voice.connect();
+
+agent.voice.on('speaker', ({ audio }) => {
+  playAudio(audio);
+});
+
+agent.voice.on('writing', ({ role, text }) => {
+  console.log(`${role}: ${text}`);
+});
+
+await agent.voice.speak('How can I help you today?');
+
+const micStream = getMicrophoneStream();
+await agent.voice.send(micStream);
+```
+
+Note:
+- Live API requires `GOOGLE_API_KEY`. Vertex AI requires project/location and service account credentials.
+- Events: `speaker` (audio stream), `writing` (text), `turnComplete`, `usage`, and `error`.

package/.docs/raw/workflows/overview.mdx

@@ -21,10 +21,17 @@ You create workflows by:
 
 This structure provides full type safety and runtime validation, ensuring data integrity across the entire workflow.
 
+> **📹 Watch**:  → An introduction to workflows, and how they compare to agents [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
 
 ## Getting started
 
-To use workflows, first import the necessary functions from the workflows module:
+To use workflows, install the required dependencies:
+
+```bash
+npm install @mastra/core
+```
+
+Import the necessary functions from the `workflows` subpath:
 
 ```typescript filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";