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

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

@@ -0,0 +1,252 @@
+---
+title: "Reference: CLI Commands"
+description: Documentation for the Mastra CLI to develop, build, and start your project.
+---
+
+import { Callout } from "nextra/components";
+
+# CLI Commands
+
+You can use the Command-Line Interface (CLI) provided by Mastra to develop, build, and start your Mastra project.
+
+## `mastra dev`
+
+Starts a server which exposes a [local dev playground](/docs/server-db/local-dev-playground) and REST endpoints for your agents, tools, and workflows. You can visit [http://localhost:4111/swagger-ui](http://localhost:4111/swagger-ui) for an overview of all available endpoints once `mastra dev` is running.
+
+You can also [configure the server](/docs/server-db/local-dev-playground#configuration).
+
+### Flags
+
+The command accepts [common flags][common-flags] and the following additional flags:
+
+#### `--https`
+
+Enable local HTTPS support. [Learn more](/docs/server-db/local-dev-playground#local-https).
+
+#### `--inspect`
+
+Start the development server in inspect mode, helpful for debugging. This can't be used together with `--inspect-brk`.
+
+#### `--inspect-brk`
+
+Start the development server in inspect mode and break at the beginning of the script. This can't be used together with `--inspect`.
+
+#### `--custom-args`
+
+Comma-separated list of custom arguments to pass to the development server. You can pass arguments to the Node.js process, e.g. `--experimental-transform-types`.
+
+### Configs
+
+You can set certain environment variables to modify the behavior of `mastra dev`.
+
+#### Disable build caching
+
+Set `MASTRA_DEV_NO_CACHE=1` to force a full rebuild rather than using the cached assets under `.mastra/`:
+
+```bash copy
+MASTRA_DEV_NO_CACHE=1 mastra dev
+```
+
+This helps when you are debugging bundler plugins or suspect stale output.
+
+#### Limit parallelism
+
+`MASTRA_CONCURRENCY` caps how many expensive operations run in parallel (primarily build and evaluation steps). For example:
+
+```bash copy
+MASTRA_CONCURRENCY=4 mastra dev
+```
+
+Leave it unset to let the CLI pick a sensible default for the machine.
+
+#### Custom provider endpoints
+
+When using providers supported by the Vercel AI SDK you can redirect requests through proxies or internal gateways by setting a base URL. For OpenAI:
+
+```bash copy
+OPENAI_API_KEY=<your-api-key> \
+OPENAI_BASE_URL=https://openrouter.example/v1 \
+mastra dev
+```
+
+For Anthropic:
+
+```bash copy
+ANTHROPIC_API_KEY=<your-api-key> \
+ANTHROPIC_BASE_URL=https://anthropic.internal \
+mastra dev
+```
+
+These are forwarded by the AI SDK and work with any `openai()` or `anthropic()` calls.
+
+## `mastra build`
+
+The `mastra build` command bundles your Mastra project into a production-ready Hono server. [Hono](https://hono.dev/) is a lightweight, type-safe web framework that makes it easy to deploy Mastra agents as HTTP endpoints with middleware support.
+
+Under the hood Mastra's Rollup server locates your Mastra entry file and bundles it to a production-ready Hono server. During that bundling it tree-shakes your code and generates source maps for debugging.
+
+The output in `.mastra` can be deployed to any cloud server using [`mastra start`](#mastra-start).
+
+If you're deploying to a [serverless platform](/docs/deployment/serverless-platforms) you need to install the correct deployer in order to receive the correct output in `.mastra`.
+
+It accepts [common flags][common-flags].
+
+### Configs
+
+You can set certain environment variables to modify the behavior of `mastra build`.
+
+#### 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
+```
+
+## `mastra start`
+
+<Callout type="info">
+You need to run `mastra build` before using `mastra start`.
+</Callout>
+
+Starts a local server to serve your built Mastra application in production mode. By default, [OTEL Tracing](/docs/observability/otel-tracing) is enabled.
+
+### Flags
+
+The command accepts [common flags][common-flags] and the following additional flags:
+
+#### `--dir`
+
+The path to your built Mastra output directory. Defaults to `.mastra/output`.
+
+#### `--no-telemetry`
+
+Disable the [OTEL Tracing](/docs/observability/otel-tracing).
+
+## `mastra lint`
+
+The `mastra lint` command validates the structure and code of your Mastra project to ensure it follows best practices and is error-free.
+
+It accepts [common flags][common-flags].
+
+## `mastra scorers`
+
+The `mastra scorers` command provides management capabilities for evaluation scorers that measure the quality, accuracy, and performance of AI-generated outputs.
+
+Read the [Scorers overview](/docs/scorers/overview) to learn more.
+
+### `add`
+
+Add a new scorer to your project. You can use an interactive prompt:
+
+```bash copy
+mastra scorers add
+```
+
+Or provide a scorer name directly:
+
+```bash copy
+mastra scorers add answer-relevancy
+```
+
+Use the [`list`](#list) command to get the correct ID.
+
+### `list`
+
+List all available scorer templates. Use the ID for the `add` command.
+
+## `mastra init`
+
+The `mastra init` command initializes Mastra in an existing project. Use this command to scaffold the necessary folders and configuration without generating a new project from scratch.
+
+### Flags
+
+The command accepts the following additional flags:
+
+#### `--default`
+
+Creates files inside `src` using OpenAI. It also populates the `src/mastra` folders with example code.
+
+#### `--dir`
+
+The directory where Mastra files should be saved to. Defaults to `src`.
+
+#### `--components`
+
+Comma-separated list of components to add. For each component a new folder will be created. Defaults to `['agents', 'tools', 'workflows']`.
+
+#### `--llm`
+
+Default model provider. Choose from: `"openai" | "anthropic" | "groq" | "google" | "cerebras" | "mistral"`.
+
+#### `--llm-api-key`
+
+The API key for your chosen model provider. Will be written to an environment variables file (`.env`).
+
+#### `--example`
+
+If enabled, example code is written to the list of components (e.g. example agent code).
+
+#### `--no-example`
+
+Do not include example code. Useful when using the `--default` flag.
+
+#### `--mcp`
+
+Configure your code editor with Mastra's MCP server. Choose from: `"cursor" | "cursor-global" | "windsurf" | "vscode"`.
+
+## Common flags
+
+### `--dir`
+
+**Available in:** `dev`, `build`, `lint`
+
+The path to your Mastra folder. Defaults to `src/mastra`.
+
+### `--env`
+
+**Available in:** `dev`, `build`, `start`
+
+Custom environment variables file to include. By default, includes `.env.development`, `.env.local`, and `.env`.
+
+### `--root`
+
+**Available in:** `dev`, `build`, `lint`
+
+Path to your root folder. Defaults to `process.cwd()`.
+
+### `--tools`
+
+**Available in:** `dev`, `build`, `lint`
+
+Comma-separated list of tool paths to include. Defaults to `src/mastra/tools`.
+
+## Global flags
+
+Use these flags to get information about the `mastra` CLI.
+
+### `--version`
+
+Prints the Mastra CLI version and exits.
+
+### `--help`
+
+Prints help message and exits.
+
+## Telemetry
+
+By default, Mastra collects anonymous information about your project like your OS, Mastra version or Node.js version. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts) to check what's collected.
+
+You can opt out of the CLI analytics by setting an environment variable:
+
+```bash copy
+MASTRA_TELEMETRY_DISABLED=1
+```
+
+You can also set this while using other `mastra` commands:
+
+```bash copy
+MASTRA_TELEMETRY_DISABLED=1 mastra dev
+```
+
+[common-flags]: #common-flags

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

@@ -163,7 +163,7 @@ const liveEvals = await agent.liveEvals();
 ### Stream
 
 
-Stream responses using the enhanced API with improved method signatures. This method provides enhanced capabilities and format flexibility, with support for both Mastra's native format and AI SDK v5 compatibility:
+Stream responses using the enhanced API with improved method signatures. This method provides enhanced capabilities and format flexibility, with support for Mastra's native format.
 
 ```typescript
 const response = await agent.stream(
@@ -174,15 +174,6 @@ const response = await agent.stream(
   }
 );
 
-// AI SDK v5 compatible format
-const response = await agent.stream(
-  "Tell me a story",
-  {
-    format: 'aisdk', // Enable AI SDK v5 compatibility
-    threadId: "thread-1",
-  }
-);
-
 // Process the stream
 response.processDataStream({
   onChunk: (chunk) => {

package/.docs/raw/reference/processors/batch-parts-processor.mdx

@@ -0,0 +1,111 @@
+---
+title: "Reference: Batch Parts Processor | Processors | Mastra Docs"
+description: "Documentation for the BatchPartsProcessor in Mastra, which batches multiple stream parts together to reduce frequency of emissions."
+---
+
+# BatchPartsProcessor
+
+The `BatchPartsProcessor` is an **output processor** that batches multiple stream parts together to reduce the frequency of emissions during streaming. This processor is useful for reducing network overhead, improving user experience by consolidating small text chunks, and optimizing streaming performance by controlling when parts are emitted to the client.
+
+## Usage example
+
+```typescript copy
+import { BatchPartsProcessor } from "@mastra/core/processors";
+
+const processor = new BatchPartsProcessor({
+  batchSize: 5,
+  maxWaitTime: 100,
+  emitOnNonText: true
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "Options",
+      description: "Configuration options for batching stream parts",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "batchSize",
+      type: "number",
+      description: "Number of parts to batch together before emitting",
+      isOptional: true,
+      default: "5",
+    },
+    {
+      name: "maxWaitTime",
+      type: "number",
+      description: "Maximum time to wait before emitting a batch (in milliseconds). If set, will emit the current batch even if it hasn't reached batchSize",
+      isOptional: true,
+      default: "undefined (no timeout)",
+    },
+    {
+      name: "emitOnNonText",
+      type: "boolean",
+      description: "Whether to emit immediately when a non-text part is encountered",
+      isOptional: true,
+      default: "true",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "name",
+      type: "string",
+      description: "Processor name set to 'batch-parts'",
+      isOptional: false,
+    },
+    {
+      name: "processOutputStream",
+      type: "(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never }) => Promise<ChunkType | null>",
+      description: "Processes streaming output parts to batch them together",
+      isOptional: false,
+    },
+    {
+      name: "flush",
+      type: "(state?: BatchPartsState) => ChunkType | null",
+      description: "Force flush any remaining batched parts when the stream ends",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Extended usage example
+
+```typescript filename="src/mastra/agents/batched-agent.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+import { BatchPartsProcessor } from "@mastra/core/processors";
+
+export const agent = new Agent({
+  name: "batched-agent",
+  instructions: "You are a helpful assistant",
+  model: openai("gpt-4o-mini"),
+  outputProcessors: [
+    new BatchPartsProcessor({
+      batchSize: 5,
+      maxWaitTime: 100,
+      emitOnNonText: true
+    })
+  ]
+});
+```
+
+## Related
+
+- [Output Processors documentation](/docs/agents/output-processors)

package/.docs/raw/reference/processors/language-detector.mdx

@@ -0,0 +1,154 @@
+---
+title: "Reference: Language Detector | Processors | Mastra Docs"
+description: "Documentation for the LanguageDetector in Mastra, which detects language and can translate content in AI responses."
+---
+
+# LanguageDetector
+
+The `LanguageDetector` is an **input processor** that identifies the language of input text and optionally translates it to a target language for consistent processing. This processor helps maintain language consistency by detecting the language of incoming messages and providing flexible strategies for handling multilingual content, including automatic translation to ensure all content is processed in the target language.
+
+## Usage example
+
+```typescript copy
+import { openai } from "@ai-sdk/openai";
+import { LanguageDetector } from "@mastra/core/processors";
+
+const processor = new LanguageDetector({
+  model: openai("gpt-4.1-nano"),
+  targetLanguages: ["English", "en"],
+  threshold: 0.8,
+  strategy: "translate"
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "Options",
+      description: "Configuration options for language detection and translation",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "model",
+      type: "MastraLanguageModel",
+      description: "Model configuration for the detection/translation agent",
+      isOptional: false,
+    },
+    {
+      name: "targetLanguages",
+      type: "string[]",
+      description: "Target language(s) for the project. If content is detected in a different language, it may be translated. Can be language name ('English') or ISO code ('en')",
+      isOptional: true,
+      default: "['English', 'en']",
+    },
+    {
+      name: "threshold",
+      type: "number",
+      description: "Confidence threshold for language detection (0-1). Only process when detection confidence exceeds this threshold",
+      isOptional: true,
+      default: "0.7",
+    },
+    {
+      name: "strategy",
+      type: "'detect' | 'translate' | 'block' | 'warn'",
+      description: "Strategy when non-target language is detected: 'detect' only detects language, 'translate' automatically translates to target language, 'block' rejects content not in target language, 'warn' logs warning but allows through",
+      isOptional: true,
+      default: "'detect'",
+    },
+    {
+      name: "preserveOriginal",
+      type: "boolean",
+      description: "Whether to preserve original content in message metadata. Useful for audit trails and debugging",
+      isOptional: true,
+      default: "true",
+    },
+    {
+      name: "instructions",
+      type: "string",
+      description: "Custom detection instructions for the agent. If not provided, uses default instructions",
+      isOptional: true,
+      default: "undefined",
+    },
+    {
+      name: "minTextLength",
+      type: "number",
+      description: "Minimum text length to perform detection. Short text is often unreliable for language detection",
+      isOptional: true,
+      default: "10",
+    },
+    {
+      name: "includeDetectionDetails",
+      type: "boolean",
+      description: "Whether to include detailed detection info in logs",
+      isOptional: true,
+      default: "false",
+    },
+    {
+      name: "translationQuality",
+      type: "'speed' | 'quality' | 'balanced'",
+      description: "Translation quality preference: 'speed' prioritizes fast translation, 'quality' prioritizes accuracy, 'balanced' balances between speed and quality",
+      isOptional: true,
+      default: "'quality'",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "name",
+      type: "string",
+      description: "Processor name set to 'language-detector'",
+      isOptional: false,
+    },
+    {
+      name: "processInput",
+      type: "(args: { messages: MastraMessageV2[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraMessageV2[]>",
+      description: "Processes input messages to detect language and optionally translate content before sending to LLM",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Extended usage example
+
+```typescript filename="src/mastra/agents/multilingual-agent.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+import { LanguageDetector } from "@mastra/core/processors";
+
+export const agent = new Agent({
+  name: "multilingual-agent",
+  instructions: "You are a helpful assistant",
+  model: openai("gpt-4o-mini"),
+  inputProcessors: [
+    new LanguageDetector({
+      model: openai("gpt-4.1-nano"),
+      targetLanguages: ["English", "en"],
+      threshold: 0.8,
+      strategy: "translate",
+      preserveOriginal: true,
+      instructions: "Detect language and translate non-English content to English while preserving original intent",
+      minTextLength: 10,
+      includeDetectionDetails: true,
+      translationQuality: "quality"
+    })
+  ]
+});
+```
+
+## Related
+
+- [Input Processors](/docs/agents/input-processors)

package/.docs/raw/reference/processors/moderation-processor.mdx

@@ -0,0 +1,145 @@
+---
+title: "Reference: Moderation Processor | Processors | Mastra Docs"
+description: "Documentation for the ModerationProcessor in Mastra, which provides content moderation using LLM to detect inappropriate content across multiple categories."
+---
+
+# ModerationProcessor
+
+The `ModerationProcessor` is a **hybrid processor** that can be used for both input and output processing to provide content moderation using an LLM to detect inappropriate content across multiple categories. This processor helps maintain content safety by evaluating messages against configurable moderation categories with flexible strategies for handling flagged content.
+
+## Usage example
+
+```typescript copy
+import { openai } from "@ai-sdk/openai";
+import { ModerationProcessor } from "@mastra/core/processors";
+
+const processor = new ModerationProcessor({
+  model: openai("gpt-4.1-nano"),
+  threshold: 0.7,
+  strategy: "block",
+  categories: ["hate", "harassment", "violence"]
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "Options",
+      description: "Configuration options for content moderation",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "model",
+      type: "MastraLanguageModel",
+      description: "Model configuration for the moderation agent",
+      isOptional: false,
+    },
+    {
+      name: "categories",
+      type: "string[]",
+      description: "Categories to check for moderation. If not specified, uses default OpenAI categories",
+      isOptional: true,
+      default: "['hate', 'hate/threatening', 'harassment', 'harassment/threatening', 'self-harm', 'self-harm/intent', 'self-harm/instructions', 'sexual', 'sexual/minors', 'violence', 'violence/graphic']",
+    },
+    {
+      name: "threshold",
+      type: "number",
+      description: "Confidence threshold for flagging (0-1). Content is flagged if any category score exceeds this threshold",
+      isOptional: true,
+      default: "0.5",
+    },
+    {
+      name: "strategy",
+      type: "'block' | 'warn' | 'filter'",
+      description: "Strategy when content is flagged: 'block' rejects with error, 'warn' logs warning but allows through, 'filter' removes flagged messages",
+      isOptional: true,
+      default: "'block'",
+    },
+    {
+      name: "instructions",
+      type: "string",
+      description: "Custom moderation instructions for the agent. If not provided, uses default instructions based on categories",
+      isOptional: true,
+      default: "undefined",
+    },
+    {
+      name: "includeScores",
+      type: "boolean",
+      description: "Whether to include confidence scores in logs. Useful for tuning thresholds and debugging",
+      isOptional: true,
+      default: "false",
+    },
+    {
+      name: "chunkWindow",
+      type: "number",
+      description: "Number of previous chunks to include for context when moderating stream chunks. If set to 1, includes the previous part, etc.",
+      isOptional: true,
+      default: "0 (no context window)",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "name",
+      type: "string",
+      description: "Processor name set to 'moderation'",
+      isOptional: false,
+    },
+    {
+      name: "processInput",
+      type: "(args: { messages: MastraMessageV2[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraMessageV2[]>",
+      description: "Processes input messages to moderate content before sending to LLM",
+      isOptional: false,
+    },
+    {
+      name: "processOutputStream",
+      type: "(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<ChunkType | null | undefined>",
+      description: "Processes streaming output parts to moderate content during streaming",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Extended usage example
+
+```typescript filename="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+import { ModerationProcessor } from "@mastra/core/processors";
+
+export const agent = new Agent({
+  name: "moderated-agent",
+  instructions: "You are a helpful assistant",
+  model: openai("gpt-4o-mini"),
+  inputProcessors: [
+    new ModerationProcessor({
+      model: openai("gpt-4.1-nano"),
+      categories: ["hate", "harassment", "violence"],
+      threshold: 0.7,
+      strategy: "block",
+      instructions: "Detect and flag inappropriate content in user messages",
+      includeScores: true,
+      chunkWindow: 1
+    })
+  ]
+});
+```
+
+## Related
+
+- [Input Processors](/docs/agents/input-processors)
+- [Output Processors](/docs/agents/output-processors)