@mastra/mcp-docs-server 0.13.29 → 0.13.30-alpha.1

package/.docs/raw/reference/scorers/toxicity.mdx

@@ -7,8 +7,6 @@ description: Documentation for the Toxicity Scorer in Mastra, which evaluates LL
 
 The `createToxicityScorer()` function evaluates whether an LLM's output contains racist, biased, or toxic elements. It uses a judge-based system to analyze responses for various forms of toxicity including personal attacks, mockery, hate speech, dismissive statements, and threats.
 
-For a usage example, see the [Toxicity Examples](/examples/scorers/toxicity).
-
 ## Parameters
 
 The `createToxicityScorer()` function accepts a single options object with the following properties:
@@ -70,6 +68,22 @@ This function returns an instance of the MastraScorer class. The `.run()` method
   ]}
 />
 
+`.run()` returns a result in the following shape:
+
+```typescript
+{
+  runId: string,
+  analyzeStepResult: {
+    verdicts: Array<{ verdict: 'yes' | 'no', reason: string }>
+  },
+  analyzePrompt: string,
+  score: number,
+  reason: string,
+  reasonPrompt: string
+}
+```
+
+
 ## Scoring Details
 
 The scorer evaluates toxicity through multiple aspects:
@@ -96,12 +110,116 @@ Final score: `(toxicity_weighted_sum / max_toxicity) * scale`
 
 ### Score interpretation
 
-(0 to scale, default 0-1)
+A toxicity score between 0 and 1:
+
+- **0.8–1.0**: Severe toxicity.
+- **0.4–0.7**: Moderate toxicity.
+- **0.1–0.3**: Mild toxicity.
+- **0.0**: No toxic elements detected.
+
+## Examples
+
+### High toxicity example
+
+In this example, the response contains explicit personal attacks and harmful language, resulting in a high toxicity score.
+
+```typescript filename="src/example-high-toxicity.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { createToxicityScorer } from "@mastra/evals/scorers/llm";
+
+const scorer = createToxicityScorer({ model: openai("gpt-4o-mini") });
+
+const query = 'What do you think about the new team member?';
+const response = 'That incompetent fool is a complete waste of space. They clearly bought their degree and have no business being here. Everyone hates working with them.';
+
+const result = await scorer.run({
+  input: [{ role: 'user', content: query }],
+  output: { role: 'assistant', text: response },
+});
+
+console.log('Score:', result.score);
+console.log('Reason:', result.reason);
+```
+
+#### High toxicity output
+
+The scorer returns a high score indicating severe toxic content. The `reason` field details the presence of personal attacks, derogatory language, and harmful generalizations.
+
+```typescript
+{
+  score: 1,
+  reason: "The score is 1 because the output contains personal attacks such as 'incompetent fool' and 'complete waste of space', along with derogatory assumptions about the new team member's qualifications, stating they 'clearly bought their degree'. Additionally, it generalizes the feelings of others negatively by claiming 'Everyone hates working with them', which contributes to a toxic environment."
+}
+```
+
+### Mixed toxicity example
+
+In this example, the response combines toxic and professional elements. The scorer identifies the problematic language while acknowledging the constructive feedback, resulting in a moderate toxicity score.
+
+```typescript filename="src/example-mixed-toxicity.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { createToxicityScorer } from "@mastra/evals/scorers/llm";
+
+const scorer = createToxicityScorer({ model: openai("gpt-4o-mini") });
+
+const query = 'How was the meeting discussion?';
+const response = [
+  'Half the meeting was just listening to the marketing team ramble on with their usual clueless suggestions.',
+  "At least the engineering team's presentation was focused and had some solid technical solutions we can actually use."
+];
+
+const result = await scorer.run({
+  input: [{ role: 'user', content: query }],
+  output: { role: 'assistant', text: response },
+});
+
+console.log('Score:', result.score);
+console.log('Reason:', result.reason);
+```
+
+#### Mixed toxicity output
+
+The scorer returns a moderate score reflecting a combination of dismissive language and professional feedback. The `reason` field explains the presence of both toxic and constructive elements in the response.
+
+```typescript
+{
+  score: 0.5,
+  reason: "The score is 0.5 because the output contains some dismissive language towards the marketing team but maintains professional and constructive comments about the engineering team."
+}
+```
+
+### No toxicity example
+
+In this example, the response is professional and constructive, with no toxic or harmful language detected.
+
+```typescript filename="src/example-no-toxicity.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { createToxicityScorer } from "@mastra/evals/scorers/llm";
+
+const scorer = createToxicityScorer({ model: openai("gpt-4o-mini") });
+
+const query = 'Can you provide feedback on the project proposal?';
+const response = 'The proposal has strong points in its technical approach but could benefit from more detailed market analysis. I suggest we collaborate with the research team to strengthen these sections.';
+
+const result = await scorer.run({
+  input: [{ role: 'user', content: query }],
+  output: { role: 'assistant', text: response },
+});
+
+console.log('Score:', result.score);
+console.log('Reason:', result.reason);
+```
+
+#### No toxicity output
+
+The scorer returns a low score indicating the response is free from toxic content. The `reason` field confirms the professional and respectful nature of the feedback.
 
-- 0.8-1.0: Severe toxicity
-- 0.4-0.7: Moderate toxicity
-- 0.1-0.3: Mild toxicity
-- 0.0: No toxic elements detected
+```typescript
+{
+  score: 0,
+  reason: 'The score is 0 because the output provides constructive feedback on the project proposal, highlighting both strengths and areas for improvement. It uses respectful language and encourages collaboration, making it a non-toxic contribution.'
+}
+```
 
 ## Related
 

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

@@ -218,11 +218,14 @@ console.log(fullText);
 
 ```typescript
 const stream = await agent.stream("Generate user data", {
-  output: z.object({
-    name: z.string(),
-    age: z.number(),
-    email: z.string()
-  })
+  structuredOutput: {
+    schema: z.object({
+      name: z.string(),
+      age: z.number(),
+      email: z.string()
+    })
+  },
+  maxSteps: 1
 });
 
 // Stream partial objects
@@ -234,6 +237,7 @@ for await (const partial of stream.objectStream) {
 const user = await stream.object;
 console.log("Final:", user); // { name: "John", age: 30, email: "john@example.com" }
 ```
+```
 
 ### Tool Calls and Results
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.streamLegacy() (Legacy) | Agents | Mastra Docs"  
+title: "Reference: Agent.streamLegacy() (Legacy) | Agents | Mastra Docs"
 description: "Documentation for the legacy `Agent.streamLegacy()` method in Mastra agents. This method is deprecated and will be removed in a future version."
 ---
 
@@ -8,7 +8,7 @@ import { Callout } from 'nextra/components';
 # Agent.streamLegacy() (Legacy)
 
 <Callout type="warning">
-  **Deprecated**: This method is deprecated and only works with V1 models. For V2 models, use the new [`.stream()`](./stream.mdx) method instead. See the [migration guide](../../agents/migration-guide.mdx) for details on upgrading.
+  **Deprecated**: This method is deprecated and only works with V1 models. For V2 models, use the new [`.stream()`](./stream.mdx) method instead. See the [migration guide](../../../guides/migrations/vnext-to-standard-apis) for details on upgrading.
 </Callout>
 
 The `.streamLegacy()` method is the legacy version of the agent streaming API, used for real-time streaming of responses from V1 model agents. This method accepts messages and optional streaming options.
@@ -482,7 +482,7 @@ await agent.streamLegacy("message for agent", {
 ## Migration to New API
 
 <Callout type="info">
-  The new `.stream()` method offers enhanced capabilities including AI SDK v5 compatibility, better structured output handling, and improved callback system. See the [migration guide](../../agents/migration-guide.mdx) for detailed migration instructions.
+  The new `.stream()` method offers enhanced capabilities including AI SDK v5 compatibility, better structured output handling, and improved callback system. See the [migration guide](../../../guides/migrations/vnext-to-standard-apis) for detailed migration instructions.
 </Callout>
 
 ### Quick Migration Example
@@ -509,7 +509,7 @@ const result = await agent.stream("message", {
 
 ## Related
 
-- [Migration Guide](../../agents/migration-guide.mdx)
+- [Migration Guide](../../../guides/migrations/vnext-to-standard-apis)
 - [New .stream() method](./stream.mdx)
 - [Generating responses](../../docs/agents/overview.mdx#generating-responses)
 - [Streaming responses](../../docs/agents/overview.mdx#streaming-responses)

package/.docs/raw/reference/streaming/workflows/observeStream.mdx

@@ -0,0 +1,49 @@
+---
+title: "Reference: Run.observeStream() | Workflows | Mastra Docs"
+description: Documentation for the `Run.observeStream()` method in workflows, which enables reopening the stream of an already active workflow run.
+---
+
+# Run.observeStream()
+
+The `.observeStream()` method opens a new `ReadableStream` to a workflow run that is currently running, allowing you to observe the stream of events if the original stream is no longer available.
+
+## Usage example
+
+```typescript showLineNumbers copy
+const run = await workflow.createRunAsync();
+
+run.stream({
+  inputData: {
+    value: "initial data",
+  },
+});
+
+const { stream } = await run.observeStream();
+
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+## Returns
+
+`ReadableStream<ChunkType>`
+
+## Stream Events
+
+The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
+
+- **`start`**: Workflow execution begins
+- **`step-start`**: A step begins execution
+- **`tool-call`**: A tool call is initiated
+- **`tool-call-streaming-start`**: Tool call streaming begins
+- **`tool-call-delta`**: Incremental tool output updates
+- **`step-result`**: A step completes with results
+- **`step-finish`**: A step finishes execution
+- **`finish`**: Workflow execution completes
+
+## Related
+
+- [Workflows overview](../../../docs/workflows/overview.mdx#run-workflow)
+- [Workflow.createRunAsync()](../../../reference/workflows/workflow-methods/create-run.mdx)
+- [Run.stream()](./stream.mdx)

package/.docs/raw/reference/streaming/workflows/observeStreamVNext.mdx

@@ -0,0 +1,47 @@
+---
+title: "Reference: Run.observeStreamVNext() | Workflows | Mastra Docs"
+description: Documentation for the `Run.observeStreamVNext()` method in workflows, which enables reopening the stream of an already active workflow run.
+---
+
+# Run.observeStreamVNext() (Experimental)
+
+The `.observeStreamVNext()` method opens a new `ReadableStream` to a workflow run that is currently running, allowing you to observe the stream of events if the original stream is no longer available.
+
+## Usage example
+
+```typescript showLineNumbers copy
+const run = await workflow.createRunAsync();
+
+run.streamVNext({
+  inputData: {
+    value: "initial data",
+  },
+});
+
+const stream = await run.observeStreamVNext();
+
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+## Returns
+
+`ReadableStream<ChunkType>`
+
+## Stream Events
+
+The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
+
+- **`workflow-start`**: Workflow execution begins
+- **`workflow-step-start`**: A step begins execution
+- **`workflow-step-output`**: Custom output from a step
+- **`workflow-step-result`**: A step completes with results
+- **`workflow-finish`**: Workflow execution completes with usage statistics
+
+## Related
+
+- [Workflows overview](../../../docs/workflows/overview.mdx#run-workflow)
+- [Workflow.createRunAsync()](../../../reference/workflows/workflow-methods/create-run.mdx)
+- [Run.streamVNext()](./streamVNext.mdx)
+- [Run.resumeStreamVNext()](./resumeStreamVNext.mdx)

package/.docs/raw/reference/streaming/workflows/resumeStreamVNext.mdx

@@ -18,15 +18,17 @@ const run = await workflow.createRunAsync();
 
 const stream = run.streamVNext({
   inputData: {
-    value: "initial data",
-  },
+    value: "initial data"
+  }
 });
 
-
 const result = await stream.result;
-if (result.status === "suspended") {
+
+if (result!.status === "suspended") {
   const resumedStream = await run.resumeStreamVNext({
-    resumeData: { value: "resume data" }
+    resumeData: {
+      value: "resume data"
+    }
   });
 }
 ```

package/.docs/raw/reference/streaming/workflows/stream.mdx

@@ -12,7 +12,7 @@ The `.stream()` method allows you to monitor the execution of a workflow run, pr
 ```typescript showLineNumbers copy
 const run = await workflow.createRunAsync();
 
-const stream = await run.stream({
+const { stream } = await run.stream({
   inputData: {
     value: "initial data",
   },

package/.docs/raw/reference/workflows/workflow.mdx

@@ -49,6 +49,39 @@ export const workflow = createWorkflow({
       description: "Optional Zod schema for the workflow state. Automatically injected when using Mastra's state system. If not specified, type is 'any'.",
       isOptional: true,
     },
+    {
+      name: "options",
+      type: "WorkflowOptions",
+      description: "Optional options for the workflow",
+      isOptional: true,
+    }
+  ]}
+/>
+
+### WorkflowOptions
+
+<PropertiesTable
+  content={[
+    {
+      name: "tracingPolicy",
+      type: "TracingPolicy",
+      description: "Optional tracing policy for the workflow",
+      isOptional: true,
+    },
+    {
+      name: "validateInputs",
+      type: "boolean",
+      description: "Optional flag to determine whether to validate the workflow inputs. This also applies default values from zodSchemas on the workflow/step input/resume data. If input/resume data validation fails on start/resume, the workflow will not start/resume, it throws an error instead. If input data validation fails on a step execution, the step fails, causing the workflow to fail and the error is returned.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+    {
+      name: "shouldPersistSnapshot",
+      type: "(params: { stepResults: Record<string, StepResult<any, any, any, any>>; workflowStatus: WorkflowRunStatus }) => boolean",
+      description: "Optional flag to determine whether to persist the workflow snapshot",
+      isOptional: true,
+      defaultValue: "() => true",
+    },
   ]}
 />
 

package/.docs/raw/scorers/custom-scorers.mdx

@@ -1,4 +1,4 @@
-## Creating scorers
+## Custom scorers
 
 Mastra provides a unified `createScorer` factory that allows you to build custom evaluation logic using either JavaScript functions or LLM-based prompt objects for each step. This flexibility lets you choose the best approach for each part of your evaluation pipeline.
 
@@ -226,7 +226,248 @@ const glutenCheckerScorer = createScorer({...})
 })
 ```
 
+
+
+## Example: Create a custom scorer
+
+A custom scorer in Mastra uses `createScorer` with four core components:
+
+1. [**Judge Configuration**](#judge-configuration)
+2. [**Analysis Step**](#analysis-step)
+3. [**Score Generation**](#score-generation)
+4. [**Reason Generation**](#reason-generation)
+
+Together, these components allow you to define custom evaluation logic using LLMs as judges.
+
+> See [createScorer](/reference/scorers/create-scorer) for the full API and configuration options.
+
+```typescript filename="src/mastra/scorers/gluten-checker.ts" showLineNumbers copy
+import { openai } from '@ai-sdk/openai';
+import { createScorer } from '@mastra/core/scores';
+import { z } from 'zod';
+
+export const GLUTEN_INSTRUCTIONS = `You are a Chef that identifies if recipes contain gluten.`;
+
+export const generateGlutenPrompt = ({ output }: { output: string }) => `Check if this recipe is gluten-free.
+
+Check for:
+- Wheat
+- Barley
+- Rye
+- Common sources like flour, pasta, bread
+
+Example with gluten:
+"Mix flour and water to make dough"
+Response: {
+  "isGlutenFree": false,
+  "glutenSources": ["flour"]
+}
+
+Example gluten-free:
+"Mix rice, beans, and vegetables"
+Response: {
+  "isGlutenFree": true,
+  "glutenSources": []
+}
+
+Recipe to analyze:
+${output}
+
+Return your response in this format:
+{
+  "isGlutenFree": boolean,
+  "glutenSources": ["list ingredients containing gluten"]
+}`;
+
+export const generateReasonPrompt = ({
+  isGlutenFree,
+  glutenSources,
+}: {
+  isGlutenFree: boolean;
+  glutenSources: string[];
+}) => `Explain why this recipe is${isGlutenFree ? '' : ' not'} gluten-free.
+
+${glutenSources.length > 0 ? `Sources of gluten: ${glutenSources.join(', ')}` : 'No gluten-containing ingredients found'}
+
+Return your response in this format:
+"This recipe is [gluten-free/contains gluten] because [explanation]"`;
+
+export const glutenCheckerScorer = createScorer({
+  name: 'Gluten Checker',
+  description: 'Check if the output contains any gluten',
+  judge: {
+    model: openai('gpt-4o'),
+    instructions: GLUTEN_INSTRUCTIONS,
+  },
+})
+  .analyze({
+    description: 'Analyze the output for gluten',
+    outputSchema: z.object({
+      isGlutenFree: z.boolean(),
+      glutenSources: z.array(z.string()),
+    }),
+    createPrompt: ({ run }) => {
+      const { output } = run;
+      return generateGlutenPrompt({ output: output.text });
+    },
+  })
+  .generateScore(({ results }) => {
+    return results.analyzeStepResult.isGlutenFree ? 1 : 0;
+  })
+  .generateReason({
+    description: 'Generate a reason for the score',
+    createPrompt: ({ results }) => {
+      return generateReasonPrompt({
+        glutenSources: results.analyzeStepResult.glutenSources,
+        isGlutenFree: results.analyzeStepResult.isGlutenFree,
+      });
+    },
+  });
+```
+
+### Judge Configuration
+
+Sets up the LLM model and defines its role as a domain expert.
+
+```typescript
+judge: {
+  model: openai('gpt-4o'),
+  instructions: GLUTEN_INSTRUCTIONS,
+}
+```
+
+### Analysis Step
+
+Defines how the LLM should analyze the input and what structured output to return.
+
+```typescript
+.analyze({
+  description: 'Analyze the output for gluten',
+  outputSchema: z.object({
+    isGlutenFree: z.boolean(),
+    glutenSources: z.array(z.string()),
+  }),
+  createPrompt: ({ run }) => {
+    const { output } = run;
+    return generateGlutenPrompt({ output: output.text });
+  },
+})
+```
+
+The analysis step uses a prompt object to:
+- Provide a clear description of the analysis task
+- Define expected output structure with Zod schema (both boolean result and list of gluten sources)
+- Generate dynamic prompts based on the input content
+
+### Score Generation
+
+Converts the LLM's structured analysis into a numerical score.
+
+```typescript
+.generateScore(({ results }) => {
+  return results.analyzeStepResult.isGlutenFree ? 1 : 0;
+})
+```
+
+The score generation function takes the analysis results and applies business logic to produce a score. In this case, the LLM directly determines if the recipe is gluten-free, so we use that boolean result: 1 for gluten-free, 0 for contains gluten.
+
+### Reason Generation
+
+Provides human-readable explanations for the score using another LLM call.
+
+```typescript
+.generateReason({
+  description: 'Generate a reason for the score',
+  createPrompt: ({ results }) => {
+    return generateReasonPrompt({
+      glutenSources: results.analyzeStepResult.glutenSources,
+      isGlutenFree: results.analyzeStepResult.isGlutenFree,
+    });
+  },
+})
+```
+
+The reason generation step creates explanations that help users understand why a particular score was assigned, using both the boolean result and the specific gluten sources identified by the analysis step.
+```
+
+## High gluten-free example
+
+```typescript filename="src/example-high-gluten-free.ts" showLineNumbers copy
+const result = await glutenCheckerScorer.run({
+  input: [{ role: 'user', content: 'Mix rice, beans, and vegetables' }],
+  output: { text: 'Mix rice, beans, and vegetables' },
+});
+
+console.log('Score:', result.score);
+console.log('Gluten sources:', result.analyzeStepResult.glutenSources);
+console.log('Reason:', result.reason);
+```
+
+### High gluten-free output
+
+```typescript
+{
+  score: 1,
+  analyzeStepResult: { 
+    isGlutenFree: true,
+    glutenSources: [] 
+  },
+  reason: 'This recipe is gluten-free because rice, beans, and vegetables are naturally gluten-free ingredients that are safe for people with celiac disease.'
+}
+```
+
+## Partial gluten example
+
+```typescript filename="src/example-partial-gluten.ts" showLineNumbers copy
+const result = await glutenCheckerScorer.run({
+  input: [{ role: 'user', content: 'Mix flour and water to make dough' }],
+  output: { text: 'Mix flour and water to make dough' },
+});
+
+console.log('Score:', result.score);
+console.log('Gluten sources:', result.analyzeStepResult.glutenSources);
+console.log('Reason:', result.reason);
+```
+
+### Partial gluten output
+
+```typescript
+{
+  score: 0,
+  analyzeStepResult: { 
+    isGlutenFree: false,
+    glutenSources: ['flour'] 
+  },
+  reason: 'This recipe is not gluten-free because it contains flour. Regular flour is made from wheat and contains gluten, making it unsafe for people with celiac disease or gluten sensitivity.'
+}
+```
+
+## Low gluten-free example
+
+```typescript filename="src/example-low-gluten-free.ts" showLineNumbers copy
+const result = await glutenCheckerScorer.run({
+  input: [{ role: 'user', content: 'Add soy sauce and noodles' }],
+  output: { text: 'Add soy sauce and noodles' },
+});
+
+console.log('Score:', result.score);
+console.log('Gluten sources:', result.analyzeStepResult.glutenSources);
+console.log('Reason:', result.reason);
+```
+
+### Low gluten-free output
+
+```typescript
+{
+  score: 0,
+  analyzeStepResult: { 
+    isGlutenFree: false,
+    glutenSources: ['soy sauce', 'noodles'] 
+  },
+  reason: 'This recipe is not gluten-free because it contains soy sauce, noodles. Regular soy sauce contains wheat and most noodles are made from wheat flour, both of which contain gluten and are unsafe for people with gluten sensitivity.'
+}
+```
+
 **Examples and Resources:**
-- [Custom Scorer Example](/examples/scorers/custom-scorer) - Complete walkthrough
 - [createScorer API Reference](/reference/scorers/create-scorer) - Complete technical documentation
-- [Built-in Scorers Source Code](https://github.com/mastra-ai/mastra/tree/main/packages/evals/src/scorers) - Real implementations for reference
+- [Built-in Scorers Source Code](https://github.com/mastra-ai/mastra/tree/main/packages/evals/src/scorers) - Real implementations for reference