@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.1

package/.docs/raw/reference/observability/tracing/exporters/posthog.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: PosthogExporter | Observability"
 description: PostHog exporter for Tracing
+packages:
+  - "@mastra/posthog"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
@@ -19,7 +21,7 @@ new PosthogExporter(config: PosthogExporterConfig)
 
 ```typescript
 interface PosthogExporterConfig extends BaseExporterConfig {
-  apiKey: string;
+  apiKey?: string;
   host?: string;
   flushAt?: number;
   flushInterval?: number;
@@ -38,13 +40,13 @@ Extends `BaseExporterConfig`, which includes:
     {
       name: "apiKey",
       type: "string",
-      description: "PostHog project API key",
-      required: true,
+      description: "PostHog project API key. Falls back to POSTHOG_API_KEY env var.",
+      required: false,
     },
     {
       name: "host",
       type: "string",
-      description: "PostHog host URL (default: 'https://us.i.posthog.com')",
+      description: "PostHog host URL. Falls back to POSTHOG_HOST env var. (default: 'https://us.i.posthog.com')",
       required: false,
     },
     {
@@ -96,6 +98,14 @@ async exportTracingEvent(event: TracingEvent): Promise<void>
 
 Exports a tracing event to PostHog.
 
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered events to PostHog without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
 ### shutdown
 
 ```typescript
@@ -106,6 +116,17 @@ Flushes pending batched events and shuts down the PostHog client.
 
 ## Usage
 
+### Zero-Config (using environment variables)
+
+```typescript
+import { PosthogExporter } from "@mastra/posthog";
+
+// Reads from POSTHOG_API_KEY, POSTHOG_HOST
+const exporter = new PosthogExporter();
+```
+
+### Explicit Configuration
+
 ```typescript
 import { PosthogExporter } from "@mastra/posthog";
 

package/.docs/raw/reference/observability/tracing/exporters/sentry.mdx

@@ -0,0 +1,224 @@
+---
+title: "Reference: SentryExporter | Observability"
+description: Sentry AI monitoring exporter for Tracing
+packages:
+  - "@mastra/sentry"
+  - "@mastra/observability"
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# SentryExporter
+
+Sends Tracing data to Sentry for AI tracing and monitoring using OpenTelemetry semantic conventions.
+
+## Constructor
+
+```typescript
+new SentryExporter(config: SentryExporterConfig)
+```
+
+## SentryExporterConfig
+
+```typescript
+interface SentryExporterConfig extends BaseExporterConfig {
+  dsn?: string;
+  environment?: string;
+  tracesSampleRate?: number;
+  release?: string;
+  options?: Partial<Sentry.NodeOptions>;
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+<PropertiesTable
+  props={[
+    {
+      name: "dsn",
+      type: "string",
+      description: "Data Source Name - tells the SDK where to send events. Either this parameter or the SENTRY_DSN env var must be set. Falls back to SENTRY_DSN env var.",
+      required: false,
+    },
+    {
+      name: "environment",
+      type: "string",
+      description: "Deployment environment (enables filtering issues and alerts by environment). Falls back to SENTRY_ENVIRONMENT env var. Default: 'production'.",
+      required: false,
+    },
+    {
+      name: "tracesSampleRate",
+      type: "number",
+      description: "Percentage of transactions sent to Sentry (0.0 = 0%, 1.0 = 100%). Default: 1.0.",
+      required: false,
+    },
+    {
+      name: "release",
+      type: "string",
+      description: "Version of your code deployed (helps identify regressions and track deployments). Falls back to SENTRY_RELEASE env var.",
+      required: false,
+    },
+    {
+      name: "options",
+      type: "Partial<Sentry.NodeOptions>",
+      description: "Additional Sentry SDK options (integrations, beforeSend, etc.). See Sentry SDK documentation for available options.",
+      required: false,
+    },
+  ]}
+/>
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to Sentry. Handles SPAN_STARTED, SPAN_UPDATED, and SPAN_ENDED events.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any pending spans to Sentry without shutting down the exporter. Waits up to 2 seconds for pending data to be sent. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Ends all active spans, clears internal state, and closes the Sentry connection. Waits up to 2 seconds for pending data to be sent.
+
+## Usage
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { SentryExporter } from "@mastra/sentry";
+
+// Reads from SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE
+const exporter = new SentryExporter();
+```
+
+### Explicit Configuration
+
+```typescript
+import { SentryExporter } from "@mastra/sentry";
+
+const exporter = new SentryExporter({
+  dsn: process.env.SENTRY_DSN,
+  environment: "production",
+  tracesSampleRate: 1.0,
+  release: "1.0.0",
+});
+```
+
+### With Sampling
+
+```typescript
+const exporter = new SentryExporter({
+  dsn: process.env.SENTRY_DSN,
+  environment: "production",
+  tracesSampleRate: 0.1, // Send 10% of transactions to Sentry (recommended for high-load backends)
+});
+```
+
+### With Custom Sentry Options
+
+```typescript
+const exporter = new SentryExporter({
+  dsn: process.env.SENTRY_DSN,
+  environment: "production",
+  options: {
+    integrations: [
+      // Custom Sentry integrations
+    ],
+    beforeSend: (event) => {
+      // Custom event processing
+      return event;
+    },
+  },
+});
+```
+
+## Span Mapping
+
+Mastra span types are mapped to Sentry operations:
+
+| Mastra SpanType             | Sentry Operation       |
+| --------------------------- | ---------------------- |
+| `AGENT_RUN`                 | `gen_ai.invoke_agent`  |
+| `MODEL_GENERATION`          | `gen_ai.chat`          |
+| `MODEL_STEP`                | _(skipped)_            |
+| `MODEL_CHUNK`               | _(skipped)_            |
+| `TOOL_CALL`                 | `gen_ai.execute_tool`  |
+| `MCP_TOOL_CALL`             | `gen_ai.execute_tool`  |
+| `WORKFLOW_RUN`              | `workflow.run`         |
+| `WORKFLOW_STEP`             | `workflow.step`        |
+| `WORKFLOW_CONDITIONAL`      | `workflow.conditional` |
+| `WORKFLOW_CONDITIONAL_EVAL` | `workflow.conditional` |
+| `WORKFLOW_PARALLEL`         | `workflow.parallel`    |
+| `WORKFLOW_LOOP`             | `workflow.loop`        |
+| `WORKFLOW_SLEEP`            | `workflow.sleep`       |
+| `WORKFLOW_WAIT_EVENT`       | `workflow.wait`        |
+| `PROCESSOR_RUN`             | `ai.processor`         |
+| `GENERIC`                   | `ai.span`              |
+
+MODEL_STEP and MODEL_CHUNK spans are skipped to simplify trace hierarchy. Their data is aggregated into MODEL_GENERATION spans.
+
+## Environment Variables
+
+The exporter reads configuration from these environment variables:
+
+| Variable              | Description                                          |
+| --------------------- | ---------------------------------------------------- |
+| `SENTRY_DSN`          | Data Source Name - tells the SDK where to send events |
+| `SENTRY_ENVIRONMENT`  | Deployment environment name                          |
+| `SENTRY_RELEASE`      | Version of your code deployed                        |
+
+## OpenTelemetry Attributes
+
+The exporter sets these standard OpenTelemetry attributes:
+
+**Common attributes (all spans):**
+- `sentry.origin`: `auto.ai.mastra` (identifies spans from Mastra)
+- `ai.span.type`: Mastra span type
+
+**MODEL_GENERATION spans:**
+- `gen_ai.operation.name`: `chat`
+- `gen_ai.system`: Model provider
+- `gen_ai.request.model`: Model identifier
+- `gen_ai.request.messages`: Input messages/prompts (JSON)
+- `gen_ai.response.model`: Response model
+- `gen_ai.response.text`: Output text
+- `gen_ai.response.tool_calls`: Tool calls made during generation (JSON array)
+- `gen_ai.usage.input_tokens`: Input token count
+- `gen_ai.usage.output_tokens`: Output token count
+- `gen_ai.usage.total_tokens`: Total tokens
+- `gen_ai.request.stream`: Streaming flag
+- `gen_ai.request.temperature`: Temperature parameter
+- `gen_ai.completion_start_time`: First token time
+
+**TOOL_CALL spans:**
+- `gen_ai.operation.name`: `execute_tool`
+- `gen_ai.tool.name`: Tool identifier
+- `gen_ai.tool.type`: `function`
+- `gen_ai.tool.call.id`: Tool call ID
+- `gen_ai.tool.input`: Tool input
+- `gen_ai.tool.output`: Tool output
+- `tool.success`: Success flag
+
+**AGENT_RUN spans:**
+- `gen_ai.operation.name`: `invoke_agent`
+- `gen_ai.agent.name`: Agent identifier
+- `gen_ai.pipeline.name`: Agent name
+- `gen_ai.agent.instructions`: Agent instructions
+- `gen_ai.response.model`: Model from child generation
+- `gen_ai.response.text`: Output from child generation
+- `gen_ai.usage.*`: Token usage from child generation

package/.docs/raw/reference/observability/tracing/instances.mdx

@@ -2,6 +2,8 @@
 title: "Reference: Tracing | Observability"
 description: Core Tracing classes and methods
 asIndexPage: true
+packages:
+  - "@mastra/core"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";

package/.docs/raw/reference/observability/tracing/interfaces.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Interfaces | Observability"
 description: Tracing type definitions and interfaces
+packages:
+  - "@mastra/core"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
@@ -32,6 +34,9 @@ interface ObservabilityInstance {
     options: StartSpanOptions<TType>,
   ): Span<TType>;
 
+  /** Force flush any buffered spans without shutting down */
+  flush(): Promise<void>;
+
   /** Shutdown observability and clean up resources */
   shutdown(): Promise<void>;
 }
@@ -152,6 +157,9 @@ interface ObservabilityExporter {
     metadata?: Record<string, any>;
   }): Promise<void>;
 
+  /** Force flush any buffered spans without shutting down */
+  flush(): Promise<void>;
+
   /** Shutdown exporter */
   shutdown(): Promise<void>;
 }
@@ -578,6 +586,18 @@ interface TracingOptions {
    * Note: Tags are only applied to the root span of a trace.
    */
   tags?: string[];
+
+  /**
+   * When true, input data will be hidden from all spans in this trace.
+   * Useful for protecting sensitive data from being logged.
+   */
+  hideInput?: boolean;
+
+  /**
+   * When true, output data will be hidden from all spans in this trace.
+   * Useful for protecting sensitive data from being logged.
+   */
+  hideOutput?: boolean;
 }
 ```
 

package/.docs/raw/reference/observability/tracing/processors/sensitive-data-filter.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: SensitiveDataFilter | Observability"
 description: API reference for the SensitiveDataFilter processor
+packages:
+  - "@mastra/core"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";

package/.docs/raw/reference/observability/tracing/spans.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Spans | Observability"
 description: Span interfaces, methods, and lifecycle events
+packages:
+  - "@mastra/core"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Batch Parts Processor | Processors"
 description: "Documentation for the BatchPartsProcessor in Mastra, which batches multiple stream parts together to reduce frequency of emissions."
+packages:
+  - "@mastra/core"
 ---
 
 # BatchPartsProcessor
@@ -9,7 +11,7 @@ The `BatchPartsProcessor` is an **output processor** that batches multiple strea
 
 ## Usage example
 
-```typescript copy
+```typescript
 import { BatchPartsProcessor } from "@mastra/core/processors";
 
 const processor = new BatchPartsProcessor({
@@ -93,7 +95,7 @@ const processor = new BatchPartsProcessor({
 
 ## Extended usage example
 
-```typescript title="src/mastra/agents/batched-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/batched-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { BatchPartsProcessor } from "@mastra/core/processors";
 

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Language Detector | Processors"
 description: "Documentation for the LanguageDetector in Mastra, which detects language and can translate content in AI responses."
+packages:
+  - "@mastra/core"
 ---
 
 # LanguageDetector
@@ -9,7 +11,7 @@ The `LanguageDetector` is an **input processor** that identifies the language of
 
 ## Usage example
 
-```typescript copy
+```typescript
 import { LanguageDetector } from "@mastra/core/processors";
 
 const processor = new LanguageDetector({
@@ -127,7 +129,7 @@ const processor = new LanguageDetector({
     },
     {
       name: "processInput",
-      type: "(args: { messages: MastraMessageV2[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraMessageV2[]>",
+      type: "(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>",
       description: "Processes input messages to detect language and optionally translate content before sending to LLM",
       isOptional: false,
     },
@@ -136,11 +138,12 @@ const processor = new LanguageDetector({
 
 ## Extended usage example
 
-```typescript title="src/mastra/agents/multilingual-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/multilingual-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { LanguageDetector } from "@mastra/core/processors";
 
 export const agent = new Agent({
+  id: "multilingual-agent",
   name: "multilingual-agent",
   instructions: "You are a helpful assistant",
   model: "openai/gpt-5.1",

package/.docs/raw/reference/processors/message-history-processor.mdx

@@ -1,6 +1,9 @@
 ---
 title: "Reference: Message History Processor | Processors"
 description: "Documentation for the MessageHistory processor in Mastra, which handles retrieval and persistence of conversation history."
+packages:
+  - "@mastra/core"
+  - "@mastra/pg"
 ---
 
 # MessageHistory
@@ -9,7 +12,7 @@ The `MessageHistory` is a **hybrid processor** that handles both retrieval and p
 
 ## Usage example
 
-```typescript copy
+```typescript
 import { MessageHistory } from "@mastra/core/processors";
 
 const processor = new MessageHistory({
@@ -83,7 +86,7 @@ const processor = new MessageHistory({
 
 ## Extended usage example
 
-```typescript title="src/mastra/agents/memory-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/memory-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { MessageHistory } from "@mastra/core/processors";
 import { PostgresStorage } from "@mastra/pg";

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Moderation Processor | Processors"
 description: "Documentation for the ModerationProcessor in Mastra, which provides content moderation using LLM to detect inappropriate content across multiple categories."
+packages:
+  - "@mastra/core"
 ---
 
 # ModerationProcessor
@@ -9,7 +11,7 @@ The `ModerationProcessor` is a **hybrid processor** that can be used for both in
 
 ## Usage example
 
-```typescript copy
+```typescript
 import { ModerationProcessor } from "@mastra/core/processors";
 
 const processor = new ModerationProcessor({
@@ -113,7 +115,7 @@ const processor = new ModerationProcessor({
     },
     {
       name: "processInput",
-      type: "(args: { messages: MastraMessageV2[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraMessageV2[]>",
+      type: "(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>",
       description: "Processes input messages to moderate content before sending to LLM",
       isOptional: false,
     },
@@ -130,7 +132,7 @@ const processor = new ModerationProcessor({
 
 ### Input processing
 
-```typescript title="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/moderated-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { ModerationProcessor } from "@mastra/core/processors";
 
@@ -155,7 +157,7 @@ export const agent = new Agent({
 
 When using `ModerationProcessor` as an output processor, it's recommended to combine it with `BatchPartsProcessor` to optimize performance. The `BatchPartsProcessor` batches stream chunks together before passing them to the moderator, reducing the number of LLM calls required for moderation.
 
-```typescript title="src/mastra/agents/output-moderated-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/output-moderated-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { BatchPartsProcessor, ModerationProcessor } from "@mastra/core/processors";
 

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

@@ -1,6 +1,8 @@
 ---
 title: "Reference: PII Detector | Processors"
 description: "Documentation for the PIIDetector in Mastra, which detects and redacts personally identifiable information (PII) from AI responses."
+packages:
+  - "@mastra/core"
 ---
 
 # PIIDetector
@@ -9,7 +11,7 @@ The `PIIDetector` is a **hybrid processor** that can be used for both input and
 
 ## Usage example
 
-```typescript copy
+```typescript
 import { PIIDetector } from "@mastra/core/processors";
 
 const processor = new PIIDetector({
@@ -120,7 +122,7 @@ const processor = new PIIDetector({
     },
     {
       name: "processInput",
-      type: "(args: { messages: MastraMessageV2[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraMessageV2[]>",
+      type: "(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>",
       description: "Processes input messages to detect and redact PII before sending to LLM",
       isOptional: false,
     },
@@ -137,7 +139,7 @@ const processor = new PIIDetector({
 
 ### Input processing
 
-```typescript title="src/mastra/agents/private-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/private-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { PIIDetector } from "@mastra/core/processors";
 
@@ -164,7 +166,7 @@ export const agent = new Agent({
 
 When using `PIIDetector` as an output processor, it's recommended to combine it with `BatchPartsProcessor` to optimize performance. The `BatchPartsProcessor` batches stream chunks together before passing them to the PII detector, reducing the number of LLM calls required for detection.
 
-```typescript title="src/mastra/agents/output-pii-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/output-pii-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { BatchPartsProcessor, PIIDetector } from "@mastra/core/processors";