@mastra/mcp-docs-server 0.13.27 → 0.13.28-alpha.2

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

@@ -1,328 +0,0 @@
----
-title: "Output Processors"
-description: "Learn how to use output processors to intercept and modify AI responses before they are returned to users."
----
-
-# Output Processors
-
-Output Processors allow you to intercept, modify, validate, or filter AI responses _after_ they are generated by the language model but _before_ they are returned to users. This is useful for implementing response validation, content moderation, response transformation, and safety controls on AI-generated content.
-
-Processors operate on the AI's response messages in your conversation thread. They can modify, filter, or validate content, and even abort the response entirely if certain conditions are met.
-
-## Built-in Processors
-
-Mastra provides several built-in output processors for common use cases:
-
-### `ModerationProcessor`
-
-This processor provides content moderation using an LLM to detect inappropriate content across multiple categories.
-
-```typescript copy showLineNumbers {5-13}
-import { ModerationProcessor } from "@mastra/core/processors";
-
-const agent = new Agent({
-  outputProcessors: [
-    new ModerationProcessor({
-      model: openai("gpt-4.1-nano"), // Use a fast, cost-effective model
-      threshold: 0.7, // Confidence threshold for flagging
-      strategy: 'block', // Block flagged content
-      categories: ['hate', 'harassment', 'violence'], // Custom categories
-    }),
-  ],
-});
-```
-
-Available options:
-- `model`: Language model for moderation analysis (required)
-- `categories`: Array of categories to check (default: ['hate','hate/threatening','harassment','harassment/threatening','self-harm','self-harm/intent','self-harm/instructions','sexual','sexual/minors','violence','violence/graphic'])
-- `threshold`: Confidence threshold for flagging (0-1, default: 0.5)
-- `strategy`: Action when content is flagged (default: 'block')
-- `customInstructions`: Custom instructions for the moderation agent
-
-Strategies available:
-- `block`: Reject the response with an error (default)
-- `warn`: Log warning but allow content through
-- `filter`: Remove flagged messages but continue processing
-
-### `PIIDetector`
-
-This processor detects and optionally redacts personally identifiable information (PII) from AI responses.
-
-```typescript copy showLineNumbers {5-14}
-import { PIIDetector } from "@mastra/core/processors";
-
-const agent = new Agent({
-  outputProcessors: [
-    new PIIDetector({
-      model: openai("gpt-4.1-nano"),
-      threshold: 0.6,
-      strategy: 'redact', // Automatically redact detected PII
-      detectionTypes: ['email', 'phone', 'credit-card', 'ssn', 'api-key', 'crypto-wallet', 'iban'],
-      redactionMethod: 'mask', // Preserve format while masking
-      preserveFormat: true, // Keep original structure in redacted values
-      includeDetections: true, // Log details for compliance auditing
-    }),
-  ],
-});
-```
-
-Available options:
-- `model`: Language model for PII detection (required)
-- `detectionTypes`: Array of PII types to detect (default: ['email', 'phone', 'credit-card', 'ssn', 'api-key', 'ip-address', 'name', 'address', 'date-of-birth', 'url', 'uuid', 'crypto-wallet', 'iban'])
-- `threshold`: Confidence threshold for flagging (0-1, default: 0.6)
-- `strategy`: Action when PII is detected (default: 'block')
-- `redactionMethod`: How to redact PII ('mask', 'hash', 'remove', 'placeholder', default: 'mask')
-- `preserveFormat`: Maintain PII structure during redaction (default: true)
-- `includeDetections`: Include detection details in logs for compliance (default: false)
-- `instructions`: Custom detection instructions for the agent
-
-Strategies available:
-- `block`: Reject responses containing PII (default)
-- `warn`: Log warning but allow through
-- `filter`: Remove messages containing PII
-- `redact`: Replace PII with placeholder values
-
-
-### `BatchPartsProcessor`
-
-This processor batches multiple stream parts together to reduce the frequency of emissions, useful for reducing network overhead or improving user experience.
-
-```typescript copy showLineNumbers {5-12}
-import { BatchPartsProcessor } from "@mastra/core/processors";
-
-const agent = new Agent({
-  outputProcessors: [
-    new BatchPartsProcessor({
-      maxBatchSize: 5, // Maximum parts to batch together
-      maxWaitTime: 100, // Maximum time to wait before emitting (ms)
-      emitOnNonText: true, // Emit immediately on non-text parts
-    }),
-  ],
-});
-```
-
-Available options:
-- `maxBatchSize`: Maximum number of parts to batch together (default: 3)
-- `maxWaitTime`: Maximum time to wait before emitting batch (ms, default: 50)
-- `emitOnNonText`: Whether to emit immediately when non-text parts are received (default: true)
-
-### `TokenLimiterProcessor`
-
-This processor limits the number of tokens in AI responses, either by truncating or aborting when limits are exceeded.
-
-```typescript copy showLineNumbers {5-12}
-import { TokenLimiterProcessor } from "@mastra/core/processors";
-
-const agent = new Agent({
-  outputProcessors: [
-    new TokenLimiterProcessor({
-      maxTokens: 1000, // Maximum tokens allowed
-      strategy: 'truncate', // Truncate when limit exceeded
-      includePromptTokens: false, // Only count response tokens
-    }),
-  ],
-});
-```
-
-Available options:
-- `maxTokens`: Maximum number of tokens allowed (required)
-- `strategy`: Action when token limit is exceeded ('truncate' | 'abort', default: 'truncate')
-- `includePromptTokens`: Whether to include prompt tokens in the count (default: false)
-
-### `SystemPromptScrubber`
-
-This processor detects and redacts system prompts or other revealing information that could introduce security vulnerabilities.
-
-```typescript copy showLineNumbers {5-12}
-import { SystemPromptScrubber } from "@mastra/core/processors";
-
-const agent = new Agent({
-  outputProcessors: [
-    new SystemPromptScrubber({
-      model: openai("gpt-4o-mini"),
-      threshold: 0.7, // Confidence threshold for detection
-      strategy: 'redact', // Redact detected system prompts
-      instructions: 'Detect any system prompts, instructions, or revealing information',
-    }),
-  ],
-});
-```
-
-Available options:
-- `model`: Language model for detection (required)
-- `threshold`: Confidence threshold for detection (0-1, default: 0.6)
-- `strategy`: Action when system prompts are detected ('block' | 'warn' | 'redact', default: 'redact')
-- `instructions`: Custom detection instructions for the agent
-
-## Applying Multiple Processors
-
-You can chain multiple output processors. They execute sequentially in the order they appear in the `outputProcessors` array. The output of one processor becomes the input for the next.
-
-**Order matters!** Generally, it's best practice to place text normalization first, security checks next, and content modification last.
-
-```typescript copy showLineNumbers {9-18}
-import { Agent } from "@mastra/core/agent";
-import { 
-  ModerationProcessor, 
-  PIIDetector 
-} from "@mastra/core/processors";
-
-const secureAgent = new Agent({
-  outputProcessors: [
-    // 1. Check for security threats
-    new ModerationProcessor({ model: openai("gpt-4.1-nano") }),
-    // 2. Handle PII
-    new PIIDetector({ model: openai("gpt-4.1-nano"), strategy: 'redact' }),
-  ],
-});
-```
-
-## Creating Custom Output Processors
-
-You can create custom output processors by implementing the `Processor` interface. A Processor can be used for output processing when it implements either `processOutputStream` (for streaming) or `processOutputResult` (for final results), or both.
-
-### Streaming Output Processor
-
-```typescript copy showLineNumbers {4-25}
-import type { Processor, MastraMessageV2 } from "@mastra/core/processors";
-import type { ChunkType } from "@mastra/core/stream";
-
-class ResponseLengthLimiter implements Processor {
-  readonly name = 'response-length-limiter';
-  
-  constructor(private maxLength: number = 1000) {}
-
-  async processOutputStream({ part, streamParts, state, abort }: {
-    part: ChunkType;
-    streamParts: ChunkType[];
-    state: Record<string, any>;
-    abort: (reason?: string) => never;
-  }): Promise<ChunkType | null | undefined> {
-    // Track cumulative length in state, each processor gets its own state
-    if (!state.cumulativeLength) {
-      state.cumulativeLength = 0;
-    }
-
-    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})`);
-      }
-    }
-
-    return part; // Emit the part
-  }
-}
-```
-
-### Final Result Processor
-
-```typescript copy showLineNumbers {4-19}
-import type { Processor, MastraMessageV2 } from "@mastra/core/processors";
-
-class ResponseValidator implements Processor {
-  readonly name = 'response-validator';
-  
-  constructor(private requiredKeywords: string[] = []) {}
-
-  processOutputResult({ messages, abort }: { 
-    messages: MastraMessageV2[]; 
-    abort: (reason?: string) => never 
-  }): MastraMessageV2[] {
-    const responseText = messages
-      .map(msg => msg.content.parts
-        .filter(part => part.type === 'text')
-        .map(part => (part as any).text)
-        .join('')
-      )
-      .join('');
-    
-    // Check for required keywords
-    for (const keyword of this.requiredKeywords) {
-      if (!responseText.toLowerCase().includes(keyword.toLowerCase())) {
-        abort(`Response missing required keyword: ${keyword}`);
-      }
-    }
-    
-    return messages;
-  }
-}
-```
-
-When creating custom output processors:
-- 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 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.
-
-## Integration with Agent Methods
-
-Output processors work with both `generate()` and `stream()` methods. The processor pipeline completes after the agent generates a response but before it's returned to the user.
-
-```typescript copy showLineNumbers
-// Processors run after generate() but before returning result
-const result = await agent.generate('Hello');
-console.log(result.text); // Processed text
-console.log(result.object); // Structured data if applicable
-
-// Processors also run during stream() for each part
-const stream = await agent.stream('Hello');
-for await (const part of stream) {
-  console.log(part); // Processed parts
-}
-```
-
-### Per-Call Overrides
-
-You can override output processors for individual calls:
-
-```typescript copy showLineNumbers
-// Override output processors for this specific call
-const result = await agent.generate('Hello', {
-  outputProcessors: [
-    new ModerationProcessor({ model: openai("gpt-4.1-nano") }),
-  ],
-});
-
-// Same for streaming
-const stream = await agent.stream('Hello', {
-  outputProcessors: [
-    new TokenLimiterProcessor({ maxTokens: 500 }),
-  ],
-});
-```
-
-### Structured Output Processor
-
-To use the StructuredOutputProcessor, you should use the `structuredOutput` option:
-
-```typescript copy showLineNumbers
-import { z } from "zod";
-
-const result = await agent.generate('Analyze this text', {
-  structuredOutput: {
-    schema: z.object({
-      sentiment: z.enum(['positive', 'negative', 'neutral']),
-      confidence: z.number(),
-    }),
-    model: openai("gpt-4o-mini"),
-    errorStrategy: 'warn',
-  },
-});
-
-console.log(result.text); // Original text
-console.log(result.object); // Typed structured data: { sentiment: 'positive', confidence: 0.8 }
-```
-
-If any processor calls `abort()`, the request terminates immediately and subsequent processors are not executed. The agent returns a 200 response with details (`result.tripwireReason`) about why the response was blocked.
-
-## Input vs Output Processors
-
-- **Input Processors**: Handle user messages before they reach the language model
-- **Output Processors**: Handle LLM responses after generation but before they're returned to the user
-
-Use input processors for user input validation and security, and output processors for response validation and safety controls on LLM-generated content.
-
-See the [Input Processors documentation](/docs/agents/input-processors) for details on processing user messages.

package/.docs/raw/networks-vnext/overview.mdx

@@ -1,85 +0,0 @@
----
-title: "Handling Complex LLM Operations | Networks | Mastra"
-description: "Networks in Mastra help you execute individual or multiple Mastra primitives in a non-deterministic way using a single API."
----
-
-# Mastra vNext Agent Network
-
-The vNext Agent Network module introduces a flexible, composable and non-deterministic way to orchestrate multiple specialized agents and workflows, enabling complex, reasoning and task completion.
-
-There are two main problem areas that this system is designed to solve:
-
-- Scenarios where a single agent is insufficient, and tasks require collaboration, routing, or sequential/parallel execution across multiple agents and workflows.
-- Scenarios where the task is not fully defined and is initiated with unstructured input. The AgentNetwork can figure out which primitive to call and turn unstructured input into a structured task.
-
-## Differences from Workflows
-
-- Workflows are linear or branched sequences of steps. This creates a deterministic flow of execution.
-- Agent Networks add a layer of non-deterministic LLM-based orchestration, allowing dynamic, multi-agent collaboration and routing. This creates a non-deterministic flow of execution.
-
-## Differences from current experimental implementation
-
-- The current implementation of AgentNetwork relies on tool calls to call other agents in the network. The vNext implementation is using Mastra workflows under the hood to break down the execution to individual tasks.
-- New methods, `.generate()` for a one-off "playbook"-like execution of a single primitive in the network, more suitable for a chat-based interface where you iterate on a solution. The `.loop()` method is still available for more complex tasks and operates much like the current implementation.
-
-## Important details
-
-- Providing memory to the AgentNetwork is _not_ optional when using the `loop` method, as it is required to store the task history. Memory is the core primitive used for any decisions on which primitives to run, as well as determine task completion.
-- Any available primitives (agents, workflows) are used based on their descriptions. The better the description, the better the routing agent will be able to select the right primitive. For workflows, the input schema is also used to determine which inputs to use when calling the workflow. More descriptive naming yields better results.
-- When primitives with overlapping capabilities are available, the routing agent will use the most specific primitive. For example, if both an agent and a workflow can do research, it will use the input schema of the worklfow to determine
-
-## Registering the network in Mastra
-
-```typescript
-const mastra = new Mastra({
-  vnext_networks: {
-    'test-network': network,
-  },
-});
-
-// using the network
-const network = mastra.vnext_getNetwork('test-network');
-
-if (!network) {
-  throw new Error('Network not found');
-}
-
-console.log(await network.generate('What are the biggest cities in France?', { runtimeContext }));
-```
-
-## Using @mastra/client-js
-
-You can use the `@mastra/client-js` package to run the network from the client side.
-
-```typescript
-import { MastraClient } from '@mastra/client-js';
-
-const client = new MastraClient();
-
-const network = client.getVNextNetwork('test-network');
-
-console.log(await network.generate('What are the biggest cities in France?', { runtimeContext }));
-```
-
-You can also stream the response
-
-```typescript
-const stream = await network.stream('What are the biggest cities in France?', { runtimeContext });
-
-for await (const chunk of stream) {
-  console.log(chunk);
-}
-```
-
-And for loops
-
-```typescript
-console.log(
-  // specifying the task, note that there is a mention here about using an agent for synthesis. This is because the routing agent can actually do some synthesis on results on its own, so this will force it to use agent2 instead
-  await network.loop(
-    'What are the biggest cities in France? Give me 3. How are they like? Find cities, then do thorough research on each city, and give me a final full report synthesizing all that information. Make sure to use an agent for synthesis.',
-    { runtimeContext },
-  ),
-);
-```
-

package/.docs/raw/networks-vnext/single-task-execution.mdx

@@ -1,135 +0,0 @@
----
-title: "Single Task Execution with AgentNetwork Generate Method"
-description: "Learn how to use the AgentNetwork's generate method in Mastra vNext to convert unstructured input into structured tasks and route them to the most appropriate agent or workflow."
----
-## Unstructured input to structured task
-
-As an example, we have an AgentNetwork with 3 primitives at its disposal:
-
-- `agent1`: A general research agent that can do research on a given topic.
-- `agent2`: A general writing agent that can write a full report based on the researched material.
-- `workflow1`: A workflow that can research a given city and write a full report based on the researched material (using both agent1 and agent2).
-
-The AgentNetwork is able to route the task to the most appropriate primitive based on the task and the context.
-To ask the AgentNetwork to act on unstructured (text) input, we can use the `generate` method.
-
-```typescript
-import { NewAgentNetwork } from '@mastra/core/network/vNext';
-import { Agent } from '@mastra/core/agent';
-import { createStep, createWorkflow } from '@mastra/core/workflows';
-import { Memory } from '@mastra/memory';
-import { openai } from '@ai-sdk/openai';
-import { LibSQLStore } from '@mastra/libsql';
-import { z } from 'zod';
-import { RuntimeContext } from '@mastra/core/runtime-context';
-
-const memory = new Memory({
-  storage: new LibSQLStore({
-    url: 'file:../mastra.db', // Or your database URL
-  }),
-});
-
-const agent1 = new Agent({
-  name: 'agent1',
-  instructions:
-    'This agent is used to do research, but not create full responses. Answer in bullet points only and be concise.',
-  description:
-    'This agent is used to do research, but not create full responses. Answer in bullet points only and be concise.',
-  model: openai('gpt-4o'),
-});
-
-const agent2 = new Agent({
-  name: 'agent2',
-  description: 'This agent is used to do text synthesis on researched material. It writes articles in full paragraphs.',
-  instructions:
-    'This agent is used to do text synthesis on researched material. Write a full report based on the researched material. Do not use bullet points. Write full paragraphs. There should not be a single bullet point in the final report. You write articles.',
-  model: openai('gpt-4o'),
-});
-
-const agentStep1 = createStep({
-  id: 'agent-step',
-  description: 'This step is used to do research and text synthesis.',
-  inputSchema: z.object({
-    city: z.string().describe('The city to research'),
-  }),
-  outputSchema: z.object({
-    text: z.string(),
-  }),
-  execute: async ({ inputData }) => {
-    const resp = await agent1.generate(inputData.city, {
-      output: z.object({
-        text: z.string(),
-      }),
-    });
-
-    return { text: resp.object.text };
-  },
-});
-
-const agentStep2 = createStep({
-  id: 'agent-step-two',
-  description: 'This step is used to do research and text synthesis.',
-  inputSchema: z.object({
-    text: z.string().describe('The city to research'),
-  }),
-  outputSchema: z.object({
-    text: z.string(),
-  }),
-  execute: async ({ inputData }) => {
-    const resp = await agent2.generate(inputData.text, {
-      output: z.object({
-        text: z.string(),
-      }),
-    });
-
-    return { text: resp.object.text };
-  },
-});
-
-const workflow1 = createWorkflow({
-  id: 'workflow1',
-  description: 'This workflow is perfect for researching a specific city.',
-  steps: [],
-  inputSchema: z.object({
-    city: z.string(),
-  }),
-  outputSchema: z.object({
-    text: z.string(),
-  }),
-})
-  .then(agentStep1)
-  .then(agentStep2)
-  .commit();
-
-const network = new NewAgentNetwork({
-  id: 'test-network',
-  name: 'Test Network',
-  instructions:
-    'You can research cities. You can also synthesize research material. You can also write a full report based on the researched material.',
-  model: openai('gpt-4o'),
-  agents: {
-    agent1,
-    agent2,
-  },
-  workflows: {
-    workflow1,
-  },
-  memory: memory,
-});
-
-const runtimeContext = new RuntimeContext();
-
-// This will call agent1, as the workflow is meant to be used with individual cities. The best primitive according to the routing agent is thus agent1 which is a general research primitive.
-console.log(await network.generate('What are the biggest cities in France? How are they like?', { runtimeContext }));
-// This will call workflow1, as it is the most suitable primitive according to the routing agent when researching individual cities.
-console.log(await network.generate('Tell me more about Paris', { runtimeContext }));
-```
-
-The AgentNetwork will call the most appropriate primitive based on the task and the context. In the case of researching specific cities, it can figure out how to turn unstructured input into structured workflow inputs based on the workflow's input schema and description. It also knows, that for any other research topic, `agent1` is likely the most appropriate primitive.
-
-### How It Works
-
-- The underlying engine is a Mastra workflow.
-- As a first step, the network uses a **routing agent** to decide which agent or workflow should handle each step.
-- The routing agent will generate a prompt and or structured input for the selected primitive.
-- The next step in the workflow is a `.branch()` that will select the right primitive, calling either an agent step or a workflow step with the input generated by the routing agent.

package/.docs/raw/reference/cli/build.mdx

@@ -1,115 +0,0 @@
----
-title: "mastra build | Production Bundle | Mastra CLI"
-description: "Build your Mastra project for production deployment"
----
-
-# mastra build
-
-The `mastra build` command bundles your Mastra project into a production-ready Hono server. Hono is a lightweight, type-safe web framework that makes it easy to deploy Mastra agents as HTTP endpoints with middleware support.
-
-## Usage
-
-```bash
-mastra build [options]
-```
-
-## Options
-
-<PropertiesTable
-  content={[
-    {
-      name: "--dir",
-      type: "string",
-      description: "Path to your Mastra Folder",
-      isOptional: true,
-    },
-    {
-      name: "--root",
-      type: "string",
-      description: "Path to your root folder",
-      isOptional: true,
-    },
-    {
-      name: "--tools",
-      type: "string",
-      description: "Comma-separated list of paths to tool files to include",
-      isOptional: true,
-    },
-    {
-      name: "--help",
-      type: "boolean",
-      description: "display help for command",
-      isOptional: true,
-    },
-  ]}
-/>
-
-## Advanced usage
-
-### Limit parallelism
-
-For CI or when running in resource constrained environments you can cap
-how many expensive tasks run at once by setting `MASTRA_CONCURRENCY`.
-
-```bash copy
-MASTRA_CONCURRENCY=2 mastra build
-```
-
-Unset it to allow the CLI to base concurrency on the host capabilities.
-
-### Disable telemetry
-
-To opt out of anonymous build analytics set:
-
-```bash copy
-MASTRA_TELEMETRY_DISABLED=1 mastra build
-```
-
-### Custom provider endpoints
-
-Build time respects the same `OPENAI_BASE_URL` and `ANTHROPIC_BASE_URL`
-variables that `mastra dev` does. They are forwarded by the AI SDK to
-any workflows or tools that call the providers.
-
-## What It Does
-
-1. Locates your Mastra entry file (either `src/mastra/index.ts` or `src/mastra/index.js`)
-2. Creates a `.mastra` output directory
-3. Bundles your code using Rollup with:
-   - Tree shaking for optimal bundle size
-   - Node.js environment targeting
-   - Source map generation for debugging
-   - Excluding test files (named `.test.`, `.spec.` or inside `__tests__` directory)
-
-## Example
-
-```bash copy
-# Build from current directory
-mastra build
-
-# Build from specific directory
-mastra build --dir ./my-mastra-project
-```
-
-## Output
-
-The command generates a production bundle in the `.mastra` directory, which includes:
-
-- A Hono-based HTTP server with your Mastra agents exposed as endpoints
-- Bundled JavaScript files optimized for production
-- Source maps for debugging
-- Required dependencies
-
-This output is suitable for:
-
-- Deploying to cloud servers (EC2, Digital Ocean)
-- Running in containerized environments
-- Using with container orchestration systems
-
-## Deployers
-
-When a Deployer is used, the build output is automatically prepared for the target platform e.g
-
-- [Vercel Deployer](/reference/deployer/vercel)
-- [Netlify Deployer](/reference/deployer/netlify)
-- [Cloudflare Deployer](/reference/deployer/cloudflare)