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

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

@@ -7,12 +7,6 @@ import PropertiesTable from "@site/src/components/PropertiesTable";
 
 # OtelExporter
 
-:::warning
-
-The OtelExporter is currently **experimental**. APIs and configuration options may change in future releases.
-
-:::
-
 Sends Tracing data to any OpenTelemetry-compatible observability platform using standardized GenAI semantic conventions.
 
 ## Constructor
@@ -317,38 +311,6 @@ const exporter = new OtelExporter({
 });
 ```
 
-## Span Mapping
-
-The exporter maps Mastra AI spans to OpenTelemetry spans following GenAI semantic conventions:
-
-### Span Names
-
-- `MODEL_GENERATION` → `chat {model}` or `tool_selection {model}`
-- `TOOL_CALL` → `tool.execute {tool_name}`
-- `AGENT_RUN` → `agent.{agent_id}`
-- `WORKFLOW_RUN` → `workflow.{workflow_id}`
-
-### Span Kinds
-
-- Root agent/workflow spans → `SERVER`
-- LLM calls → `CLIENT`
-- Tool calls → `INTERNAL` or `CLIENT`
-- Workflow steps → `INTERNAL`
-
-### Attributes
-
-The exporter maps to standard OTEL GenAI attributes:
-
-| Mastra Attribute                    | OTEL Attribute                   |
-| ----------------------------------- | -------------------------------- |
-| `model`                             | `gen_ai.request.model`           |
-| `provider`                          | `gen_ai.system`                  |
-| `inputTokens` / `promptTokens`      | `gen_ai.usage.input_tokens`      |
-| `outputTokens` / `completionTokens` | `gen_ai.usage.output_tokens`     |
-| `temperature`                       | `gen_ai.request.temperature`     |
-| `maxOutputTokens`                   | `gen_ai.request.max_tokens`      |
-| `finishReason`                      | `gen_ai.response.finish_reasons` |
-
 ## Protocol Requirements
 
 Different providers require different OTEL exporter packages:
@@ -360,10 +322,38 @@ Different providers require different OTEL exporter packages:
 | HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`  | Traceloop, Custom          |
 | Zipkin        | `@opentelemetry/exporter-zipkin`           | Zipkin collectors          |
 
-## Parent-Child Relationships
 
-The exporter preserves span hierarchy from Mastra's Tracing:
+## Tags Support
+
+The OtelExporter supports trace tagging for categorization and filtering. Tags are only applied to root spans and are stored as the `mastra.tags` attribute.
+
+### Usage
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+### How Tags Are Stored
+
+Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute for maximum backend compatibility:
+
+```json
+{
+  "mastra.tags": "[\"production\",\"experiment-v2\",\"user-request\"]"
+}
+```
+
+:::note
+While the OpenTelemetry specification supports native array attributes, many backends (Jaeger, Zipkin, Tempo) have limited array support. JSON strings ensure consistent behavior across all observability platforms.
+:::
+
+## Related
 
-- Uses `parentSpanId` directly from Mastra spans
-- Maintains correct nesting for agents, workflows, LLM calls, and tools
-- Exports complete traces with all relationships intact
+- [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",
     })
   ]