@mastra/mcp-docs-server 1.0.0-beta.5 → 1.0.0-beta.6

package/.docs/raw/reference/observability/tracing/bridges/otel.mdx

@@ -0,0 +1,150 @@
+---
+title: "Reference: OtelBridge | Observability"
+description: OpenTelemetry bridge for Tracing
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# OtelBridge
+
+:::warning
+
+The OpenTelemetry Bridge is currently **experimental**. APIs and configuration options may change in future releases.
+
+:::
+
+Enables bidirectional integration between Mastra tracing and OpenTelemetry infrastructure. Creates native OTEL spans for Mastra operations and inherits context from active OTEL spans.
+
+## Constructor
+
+```typescript
+new OtelBridge()
+```
+
+## Methods
+
+### executeInContext
+
+```typescript
+executeInContext<T>(spanId: string, fn: () => Promise<T>): Promise<T>
+```
+
+Executes an async function within the OTEL context of a Mastra span. OTEL-instrumented code running inside the function will have correct parent relationships.
+
+<PropertiesTable
+  props={[
+    {
+      name: "spanId",
+      type: "string",
+      description: "The ID of the Mastra span to use as context",
+      required: true,
+    },
+    {
+      name: "fn",
+      type: "() => Promise<T>",
+      description: "The async function to execute within the span context",
+      required: true,
+    },
+  ]}
+/>
+
+**Returns:** `Promise<T>` - The result of the function execution.
+
+### executeInContextSync
+
+```typescript
+executeInContextSync<T>(spanId: string, fn: () => T): T
+```
+
+Executes a synchronous function within the OTEL context of a Mastra span.
+
+<PropertiesTable
+  props={[
+    {
+      name: "spanId",
+      type: "string",
+      description: "The ID of the Mastra span to use as context",
+      required: true,
+    },
+    {
+      name: "fn",
+      type: "() => T",
+      description: "The synchronous function to execute within the span context",
+      required: true,
+    },
+  ]}
+/>
+
+**Returns:** `T` - The result of the function execution.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Shuts down the bridge and cleans up resources. Ends any spans that were not properly closed.
+
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { OtelBridge } from "@mastra/otel-bridge";
+
+const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: "my-service",
+        bridge: new OtelBridge(),
+      },
+    },
+  }),
+  agents: { myAgent },
+});
+```
+
+### Combined with Exporters
+
+The bridge can be used alongside exporters. The bridge handles OTEL context, while exporters send data to additional destinations:
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { Observability, DefaultExporter } from "@mastra/observability";
+import { OtelBridge } from "@mastra/otel-bridge";
+import { LangfuseExporter } from "@mastra/langfuse";
+
+const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: "my-service",
+        bridge: new OtelBridge(), // Handles OTEL context
+        exporters: [
+          new DefaultExporter(), // Studio access
+          new LangfuseExporter({
+            // Additional destination
+            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
+            secretKey: process.env.LANGFUSE_SECRET_KEY,
+          }),
+        ],
+      },
+    },
+  }),
+});
+```
+
+## OpenTelemetry Setup Requirements
+
+The OtelBridge requires an active OpenTelemetry SDK to function. The bridge reads from OTEL's ambient context.
+
+See the [OtelBridge Guide](/docs/v1/observability/tracing/bridges/otel#configuration) for complete setup instructions, including how to configure OTEL instrumentation and run your application.
+
+## Related
+
+- [OtelBridge Guide](/docs/v1/observability/tracing/bridges/otel) - Setup guide with examples
+- [Tracing Overview](/docs/v1/observability/tracing/overview) - General tracing concepts
+- [OtelExporter Reference](/reference/v1/observability/tracing/exporters/otel) - OTEL exporter for sending traces

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

@@ -232,10 +232,6 @@ Shuts down all observability instances and clears the registry.
 - [Interfaces](/reference/v1/observability/tracing/interfaces) - Type definitions
 - [Spans Reference](/reference/v1/observability/tracing/spans) - Span lifecycle
 
-### Examples
-
-- [Basic Tracing](/examples/v1/observability/basic-ai-tracing) - Getting started
-
 ### Exporters
 
 - [DefaultExporter](/reference/v1/observability/tracing/exporters/default-exporter) - Storage configuration

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

@@ -38,6 +38,10 @@ Inherits from `OtelExporterConfig` (excluding `provider`), which includes:
 - `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: WARN)
 - `resourceAttributes?: Record<string, any>` - Custom resource attributes
 
+### Metadata passthrough
+
+Non-reserved span attributes are serialized into the OpenInference `metadata` payload. Add them via `tracingOptions.metadata` (e.g., `companyId`, `tier`). Reserved fields such as `input`, `output`, `sessionId`, thread/user IDs, and OpenInference IDs are excluded automatically.
+
 <PropertiesTable
   props={[
     {

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

@@ -20,6 +20,7 @@ new LangSmithExporter(config: LangSmithExporterConfig)
 ```typescript
 interface LangSmithExporterConfig extends ClientConfig, BaseExporterConfig {
   client?: Client;
+  projectName?: string;
 }
 ```
 
@@ -32,7 +33,13 @@ Extends both `ClientConfig` (from LangSmith SDK) and `BaseExporterConfig`:
     {
       name: "apiKey",
       type: "string",
-      description: "LangSmith API key",
+      description: "LangSmith API key. Defaults to LANGSMITH_API_KEY env var.",
+      required: false,
+    },
+    {
+      name: "projectName",
+      type: "string",
+      description: "The LangSmith project to send traces to. Overrides LANGCHAIN_PROJECT env var. Defaults to 'default'.",
       required: false,
     },
     {
@@ -99,11 +106,20 @@ import { LangSmithExporter } from "@mastra/langsmith";
 
 const exporter = new LangSmithExporter({
   apiKey: process.env.LANGSMITH_API_KEY,
+  projectName: "my-project", // Optional: specify which project to send traces to
   apiUrl: "https://api.smith.langchain.com",
   logLevel: "info",
 });
 ```
 
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LANGSMITH_API_KEY` | Your LangSmith API key |
+| `LANGCHAIN_PROJECT` | Default project name for traces (used if `projectName` not specified) |
+| `LANGSMITH_BASE_URL` | API URL for self-hosted instances |
+
 ## Span Type Mapping
 
 | Span Type       | LangSmith Type |

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

@@ -367,3 +367,9 @@ The exporter preserves span hierarchy from Mastra's Tracing:
 - Uses `parentSpanId` directly from Mastra spans
 - Maintains correct nesting for agents, workflows, LLM calls, and tools
 - Exports complete traces with all relationships intact
+
+## Related
+
+- [OtelExporter Guide](/docs/v1/observability/tracing/exporters/otel) - Setup guide with provider configurations
+- [OtelBridge](/docs/v1/observability/tracing/bridges/otel) - For bidirectional OTEL context integration
+- [Tracing Overview](/docs/v1/observability/tracing/overview) - General tracing concepts

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

@@ -157,10 +157,6 @@ class CustomObservabilityInstance extends BaseObservabilityInstance {
 - [Interfaces Reference](/reference/v1/observability/tracing/interfaces) - Type definitions
 - [Spans Reference](/reference/v1/observability/tracing/spans) - Span lifecycle and methods
 
-### Examples
-
-- [Basic Tracing](/examples/v1/observability/basic-ai-tracing) - Getting started example
-
 ### Exporters
 
 - [DefaultExporter](/reference/v1/observability/tracing/exporters/default-exporter) - Storage persistence

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

@@ -90,6 +90,9 @@ interface Span<TType extends SpanType> {
   output?: any;
   errorInfo?: any;
 
+  /** Tags for categorizing traces (only present on root spans) */
+  tags?: string[];
+
   /** End the span */
   end(options?: EndSpanOptions<TType>): void;
 
@@ -549,6 +552,32 @@ Options passed when starting a new agent or workflow execution.
 interface TracingOptions {
   /** Metadata to add to the root trace span */
   metadata?: Record<string, any>;
+
+  /**
+   * Additional RequestContext keys to extract as metadata for this trace.
+   * These keys are added to the requestContextKeys config.
+   * Supports dot notation for nested values (e.g., 'user.id', 'session.data.experimentId').
+   */
+  requestContextKeys?: string[];
+
+  /**
+   * Trace ID to use for this execution (1-32 hexadecimal characters).
+   * If provided, this trace will be part of the specified trace rather than starting a new one.
+   */
+  traceId?: string;
+
+  /**
+   * Parent span ID to use for this execution (1-16 hexadecimal characters).
+   * If provided, the root span will be created as a child of this span.
+   */
+  parentSpanId?: string;
+
+  /**
+   * Tags to apply to this trace.
+   * Tags are string labels that can be used to categorize and filter traces
+   * Note: Tags are only applied to the root span of a trace.
+   */
+  tags?: string[];
 }
 ```
 
@@ -707,7 +736,3 @@ enum InternalSpans {
 - [Configuration](/reference/v1/observability/tracing/configuration) - Registry and configuration
 - [Tracing Classes](/reference/v1/observability/tracing/instances) - Core implementations
 - [Spans Reference](/reference/v1/observability/tracing/spans) - Span lifecycle methods
-
-### Examples
-
-- [Basic Tracing](/examples/v1/observability/basic-ai-tracing) - Implementation example

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

@@ -386,7 +386,3 @@ A span that performs no operations. All methods are no-ops:
 - [Tracing Classes](/reference/v1/observability/tracing/instances) - Core tracing classes
 - [Interfaces](/reference/v1/observability/tracing/interfaces) - Complete type reference
 - [Configuration](/reference/v1/observability/tracing/configuration) - Configuration options
-
-### Examples
-
-- [Basic Tracing](/examples/v1/observability/basic-ai-tracing) - Working with spans

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

@@ -13,7 +13,7 @@ The `LanguageDetector` is an **input processor** that identifies the language of
 import { LanguageDetector } from "@mastra/core/processors";
 
 const processor = new LanguageDetector({
-  model: "openai/gpt-4.1-nano",
+  model: "openrouter/openai/gpt-oss-safeguard-20b",
   targetLanguages: ["English", "en"],
   threshold: 0.8,
   strategy: "translate"
@@ -99,6 +99,13 @@ const processor = new LanguageDetector({
       isOptional: true,
       default: "'quality'",
     },
+    {
+      name: "providerOptions",
+      type: "ProviderOptions",
+      description: "Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., `{ openai: { reasoningEffort: 'low' } }`)",
+      isOptional: true,
+      default: "undefined",
+    },
   ]}
 />
 
@@ -139,7 +146,7 @@ export const agent = new Agent({
   model: "openai/gpt-5.1",
   inputProcessors: [
     new LanguageDetector({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       targetLanguages: ["English", "en"],
       threshold: 0.8,
       strategy: "translate",

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

@@ -0,0 +1,131 @@
+---
+title: "Reference: Message History Processor | Processors"
+description: "Documentation for the MessageHistory processor in Mastra, which handles retrieval and persistence of conversation history."
+---
+
+# MessageHistory
+
+The `MessageHistory` is a **hybrid processor** that handles both retrieval and persistence of message history. On input, it fetches historical messages from storage and prepends them to the conversation. On output, it persists new messages to storage.
+
+## Usage example
+
+```typescript copy
+import { MessageHistory } from "@mastra/core/processors";
+
+const processor = new MessageHistory({
+  storage: memoryStorage,
+  lastMessages: 50,
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "MessageHistoryOptions",
+      description: "Configuration options for the message history processor",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "storage",
+      type: "MemoryStorage",
+      description: "Storage instance for retrieving and persisting messages",
+      isOptional: false,
+    },
+    {
+      name: "lastMessages",
+      type: "number",
+      description: "Maximum number of historical messages to retrieve. If not specified, retrieves all messages",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Processor identifier set to 'message-history'",
+      isOptional: false,
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Processor display name set to 'MessageHistory'",
+      isOptional: false,
+    },
+    {
+      name: "processInput",
+      type: "(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>",
+      description: "Fetches historical messages from storage and adds them to the message list",
+      isOptional: false,
+    },
+    {
+      name: "processOutputResult",
+      type: "(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList>",
+      description: "Persists new messages (user input and assistant response) to storage, excluding system messages",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Extended usage example
+
+```typescript title="src/mastra/agents/memory-agent.ts" showLineNumbers copy
+import { Agent } from "@mastra/core/agent";
+import { MessageHistory } from "@mastra/core/processors";
+import { PostgresStorage } from "@mastra/pg";
+
+const storage = new PostgresStorage({
+  connectionString: process.env.DATABASE_URL,
+});
+
+export const agent = new Agent({
+  name: "memory-agent",
+  instructions: "You are a helpful assistant with conversation memory",
+  model: "openai:gpt-4o",
+  inputProcessors: [
+    new MessageHistory({
+      storage,
+      lastMessages: 100,
+    }),
+  ],
+  outputProcessors: [
+    new MessageHistory({
+      storage,
+    }),
+  ],
+});
+```
+
+## Behavior
+
+### Input processing
+1. Retrieves `threadId` from the request context
+2. Fetches historical messages from storage (ordered by creation date, descending)
+3. Filters out system messages (they should not be stored in the database)
+4. Merges historical messages with incoming messages, avoiding duplicates by ID
+5. Adds historical messages with `source: 'memory'` tag
+
+### Output processing
+1. Retrieves `threadId` from the request context
+2. Skips persistence if `readOnly` is set in memory config
+3. Filters out incomplete tool calls from messages
+4. Persists new user input and assistant response messages to storage
+5. Updates the thread's `updatedAt` timestamp
+
+## Related
+
+- [Guardrails](/docs/v1/agents/guardrails)

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

@@ -13,7 +13,7 @@ The `ModerationProcessor` is a **hybrid processor** that can be used for both in
 import { ModerationProcessor } from "@mastra/core/processors";
 
 const processor = new ModerationProcessor({
-  model: "openai/gpt-4.1-nano",
+  model: "openrouter/openai/gpt-oss-safeguard-20b",
   threshold: 0.7,
   strategy: "block",
   categories: ["hate", "harassment", "violence"]
@@ -85,6 +85,13 @@ const processor = new ModerationProcessor({
       isOptional: true,
       default: "0 (no context window)",
     },
+    {
+      name: "providerOptions",
+      type: "ProviderOptions",
+      description: "Provider-specific options passed to the internal moderation agent. Use this to control model behavior like reasoning effort for thinking models (e.g., `{ openai: { reasoningEffort: 'low' } }`)",
+      isOptional: true,
+      default: "undefined",
+    },
   ]}
 />
 
@@ -133,7 +140,7 @@ export const agent = new Agent({
   model: "openai/gpt-5.1",
   inputProcessors: [
     new ModerationProcessor({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       categories: ["hate", "harassment", "violence"],
       threshold: 0.7,
       strategy: "block",
@@ -163,7 +170,7 @@ export const agent = new Agent({
     }),
     // Then apply moderation on batched content
     new ModerationProcessor({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       strategy: "filter",
       chunkWindow: 1,
     }),

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

@@ -13,7 +13,7 @@ The `PIIDetector` is a **hybrid processor** that can be used for both input and
 import { PIIDetector } from "@mastra/core/processors";
 
 const processor = new PIIDetector({
-  model: "openai/gpt-4.1-nano",
+  model: "openrouter/openai/gpt-oss-safeguard-20b",
   threshold: 0.6,
   strategy: "redact",
   detectionTypes: ["email", "phone", "credit-card", "ssn"]
@@ -92,6 +92,13 @@ const processor = new PIIDetector({
       isOptional: true,
       default: "true",
     },
+    {
+      name: "providerOptions",
+      type: "ProviderOptions",
+      description: "Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., `{ openai: { reasoningEffort: 'low' } }`)",
+      isOptional: true,
+      default: "undefined",
+    },
   ]}
 />
 
@@ -140,7 +147,7 @@ export const agent = new Agent({
   model: "openai/gpt-5.1",
   inputProcessors: [
     new PIIDetector({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       detectionTypes: ["email", "phone", "credit-card", "ssn"],
       threshold: 0.6,
       strategy: "redact",
@@ -172,7 +179,7 @@ export const agent = new Agent({
     }),
     // Then apply PII detection on batched content
     new PIIDetector({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       strategy: "redact",
     })
   ]