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

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/cli/scorers.mdx

@@ -0,0 +1,160 @@
+---
+title: "mastra scorers | Evaluation Management | Mastra CLI"
+description: "Manage scorers for evaluating AI outputs with the Mastra CLI"
+---
+
+# mastra scorers
+
+The `mastra scorers` command provides management capabilities for evaluation scorers that measure the quality, accuracy, and performance of AI-generated outputs.
+
+## Usage
+
+```bash
+mastra scorers <command> [options]
+```
+
+## Commands
+
+### mastra scorers add
+
+Add a new scorer template to your project.
+
+```bash
+mastra scorers add [scorer-name] [options]
+```
+
+#### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "--dir",
+      type: "string", 
+      description: "Path to your Mastra directory (default: auto-detect)",
+      isOptional: true,
+    },
+    {
+      name: "--help",
+      type: "boolean",
+      description: "Display help for command",
+      isOptional: true,
+    },
+  ]}
+/>
+
+#### Examples
+
+Add a specific scorer by name:
+
+```bash copy
+mastra scorers add answer-relevancy
+```
+
+Interactive scorer selection (when no name provided):
+
+```bash copy
+mastra scorers add
+```
+
+Add scorer to custom directory:
+
+```bash copy  
+mastra scorers add toxicity-detection --dir ./custom/scorers
+```
+
+### mastra scorers list
+
+List all available scorer templates.
+
+```bash
+mastra scorers list
+```
+
+This command displays built-in scorer templates organized by category:
+
+- **Accuracy and Reliability**: answer-relevancy, bias-detection, faithfulness, hallucination, toxicity-detection
+- **Output Quality**: completeness, content-similarity, keyword-coverage, textual-difference, tone-consistency
+
+## Available Scorers
+
+When running `mastra scorers add` without specifying a scorer name, you can select from these built-in templates:
+
+### Accuracy and Reliability
+
+- **answer-relevancy**: Evaluates how relevant an AI response is to the input question
+- **bias-detection**: Identifies potential biases in AI-generated content  
+- **faithfulness**: Measures how faithful the response is to provided context
+- **hallucination**: Detects when AI generates information not grounded in the input
+- **toxicity-detection**: Identifies harmful or inappropriate content
+
+### Output Quality
+
+- **completeness**: Assesses whether the response fully addresses the input
+- **content-similarity**: Measures semantic similarity between expected and actual outputs
+- **keyword-coverage**: Evaluates coverage of expected keywords or topics
+- **textual-difference**: Measures textual differences between responses
+- **tone-consistency**: Evaluates consistency of tone and style
+
+## What It Does
+
+1. **Dependency Management**: Automatically installs `@mastra/evals` package if needed
+2. **Template Selection**: Provides interactive selection when no scorer specified  
+3. **File Generation**: Creates scorer files from built-in templates
+4. **Directory Structure**: Places scorers in `src/mastra/scorers/` or custom directory
+5. **Duplicate Detection**: Prevents overwriting existing scorer files
+
+## Integration
+
+After adding scorers, integrate them with your agents or workflows:
+
+### With Agents
+
+```typescript filename="src/mastra/agents/evaluated-agent.ts"
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { createAnswerRelevancyScorer } from "../scorers/answer-relevancy-scorer";
+
+export const evaluatedAgent = new Agent({
+  // ... other config
+  scorers: {
+    relevancy: {
+      scorer: createAnswerRelevancyScorer({ model: openai("gpt-4o-mini") }),
+      sampling: { type: "ratio", rate: 0.5 }
+    }
+  }
+});
+```
+
+### With Workflow Steps
+
+```typescript filename="src/mastra/workflows/content-generation.ts"
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { customStepScorer } from "../scorers/custom-step-scorer";
+
+const contentStep = createStep({
+  // ... other config
+  scorers: {
+    customStepScorer: {
+      scorer: customStepScorer(),
+      sampling: { type: "ratio", rate: 1 }
+    }
+  },
+});
+```
+
+## Testing Scorers
+
+Use the [Local Dev Playground](/docs/server-db/local-dev-playground) to test your scorers:
+
+```bash copy
+mastra dev
+```
+
+Navigate to [http://localhost:4111/](http://localhost:4111/) and access the scorers section to run individual scorers against test inputs and view detailed results.
+
+## Next Steps
+
+- Learn about scorer implementation in [Creating Custom Scorers](/docs/scorers/custom-scorers)
+- Explore built-in options in [Off-the-shelf Scorers](/docs/scorers/off-the-shelf-scorers)  
+- See [Scorers Overview](/docs/scorers/overview) for evaluation pipeline details
+- Test scorers with the [Local Dev Playground](/docs/server-db/local-dev-playground)

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/templates.mdx

@@ -5,10 +5,10 @@ description: "Complete guide to creating, using, and contributing Mastra templat
 
 import { FileTree, Tabs, Callout } from 'nextra/components'
 
-This reference provides comprehensive information about Mastra templates, including how to use existing templates, create your own, and contribute to the community ecosystem.
-
 ## Overview
 
+This reference provides comprehensive information about Mastra templates, including how to use existing templates, create your own, and contribute to the community ecosystem.
+
 Mastra templates are pre-built project structures that demonstrate specific use cases and patterns. They provide:
 
 - **Working examples** - Complete, functional Mastra applications
@@ -184,7 +184,7 @@ Detailed explanation of the template's functionality and use case.
 ## Setup
 
 1. Copy `.env.example` to `.env` and fill in your API keys
-2. Install dependencies: `npm install`  
+2. Install dependencies: `npm install`
 3. Run the project: `npm run dev`
 
 ## Environment Variables

package/.docs/raw/reference/tools/create-tool.mdx

@@ -13,8 +13,8 @@ The `createTool()` function is used to define custom tools that your Mastra agen
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 
-export const reverseTool = createTool({
-  id: "reverse-tool",
+export const tool = createTool({
+  id: "test-tool",
   description: "Reverse the input string",
   inputSchema: z.object({
     input: z.string()

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/branch.mdx

@@ -44,5 +44,5 @@ workflow.branch([
 
 ## Related
 
-- [Conditional branching](../../docs/workflows/flow-control.mdx#conditional-branching)
+- [Conditional branching](../../docs/workflows/control-flow.mdx)
 - [Conditional branching example](../../examples/workflows/conditional-branching.mdx)

package/.docs/raw/reference/workflows/create-run.mdx

@@ -24,10 +24,9 @@ await workflow.createRunAsync();
 <PropertiesTable
   content={[
     {
-      name: "options",
-      type: "{ runId?: string }",
-      description:
-        "Optional configuration for the run, including a custom run ID",
+      name: "runId",
+      type: "string",
+      description: "Optional custom identifier for the workflow run",
       isOptional: true,
     },
   ]}
@@ -62,4 +61,5 @@ const result = await run.start({
 
 ## Related
 
+- [Run Class](./run.mdx)
 - [Running workflows](../../examples/workflows/running-workflows.mdx)