@mastra/mcp-docs-server 0.13.24 → 0.13.25-alpha.1

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

@@ -0,0 +1,178 @@
+---
+title: "SensitiveDataFilter | Processors | AI Tracing | Reference"
+description: API reference for the SensitiveDataFilter processor
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# SensitiveDataFilter
+
+An AISpanProcessor that redacts sensitive information from span fields.
+
+## Constructor
+
+```typescript
+new SensitiveDataFilter(options?: SensitiveDataFilterOptions)
+```
+
+## SensitiveDataFilterOptions
+
+```typescript
+interface SensitiveDataFilterOptions {
+  /** 
+   * List of sensitive field names to redact.
+   * Matching is case-insensitive and normalizes separators 
+   * (api-key, api_key, Api Key → apikey).
+   * Defaults include: password, token, secret, key, apikey, auth, 
+   * authorization, bearer, bearertoken, jwt, credential, 
+   * clientsecret, privatekey, refresh, ssn.
+   */
+  sensitiveFields?: string[];
+  
+  /** 
+   * The token used for full redaction.
+   * Default: "[REDACTED]"
+   */
+  redactionToken?: string;
+  
+  /** 
+   * Style of redaction to use:
+   * - "full": always replace with redactionToken
+   * - "partial": show 3 characters from the start and end, redact the middle
+   * Default: "full"
+   */
+  redactionStyle?: RedactionStyle;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "sensitiveFields",
+      type: "string[]",
+      description: "Field names to redact (case-insensitive, separator-agnostic)",
+      required: false,
+    },
+    {
+      name: "redactionToken",
+      type: "string",
+      description: "Replacement token for full redaction",
+      required: false,
+    },
+    {
+      name: "redactionStyle",
+      type: "'full' | 'partial'",
+      description: "Redaction style",
+      required: false,
+    },
+  ]}
+/>
+
+## RedactionStyle
+
+```typescript
+type RedactionStyle = 'full' | 'partial';
+```
+
+## Methods
+
+### process
+
+```typescript
+process(span: AnyAISpan): AnyAISpan
+```
+
+Process a span by filtering sensitive data across its key fields: attributes, metadata, input, output, and errorInfo.
+
+<PropertiesTable
+  props={[
+    {
+      name: "span",
+      type: "AnyAISpan",
+      description: "The input span to filter",
+      required: true,
+    },
+  ]}
+/>
+
+**Returns:** A new span with sensitive values redacted.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+No cleanup needed for this processor.
+
+## Properties
+
+```typescript
+readonly name = 'sensitive-data-filter';
+```
+
+## Default Sensitive Fields
+
+When no custom fields are provided:
+
+```typescript
+[
+  'password',
+  'token',
+  'secret',
+  'key',
+  'apikey',
+  'auth',
+  'authorization',
+  'bearer',
+  'bearertoken',
+  'jwt',
+  'credential',
+  'clientsecret',
+  'privatekey',
+  'refresh',
+  'ssn'
+]
+```
+
+## Processing Behavior
+
+### Field Matching
+
+- **Case-insensitive**: `APIKey`, `apikey`, `ApiKey` all match
+- **Separator-agnostic**: `api-key`, `api_key`, `apiKey` are treated identically  
+- **Exact matching**: After normalization, fields must match exactly
+  - `token` matches `token`, `Token`, `TOKEN`
+  - `token` does NOT match `promptTokens` or `tokenCount`
+
+### Redaction Styles
+
+#### Full Redaction (default)
+
+All matched values replaced with redactionToken.
+
+#### Partial Redaction
+
+- Shows first 3 and last 3 characters
+- Values ≤ 6 characters are fully redacted
+- Non-string values are converted to strings before partial redaction
+
+### Error Handling
+
+If filtering a field fails, the field is replaced with:
+
+```typescript
+{ error: { processor: "sensitive-data-filter" } }
+```
+
+### Processed Fields
+
+The filter recursively processes:
+
+- `span.attributes` - Span metadata and properties
+- `span.metadata` - Custom metadata
+- `span.input` - Input data
+- `span.output` - Output data  
+- `span.errorInfo` - Error information
+
+Handles nested objects, arrays, and circular references safely.

package/.docs/raw/reference/observability/ai-tracing/span.mdx

@@ -0,0 +1,371 @@
+---
+title: "Span | AI Tracing | Reference"
+description: Span interfaces, methods, and lifecycle events
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# Span
+
+## BaseSpan
+
+Base interface for all span types.
+
+```typescript
+interface BaseSpan<TType extends AISpanType> {
+  /** Unique span identifier */
+  id: string;
+  
+  /** OpenTelemetry-compatible trace ID (32 hex chars) */
+  traceId: string;
+  
+  /** Name of the span */
+  name: string;
+  
+  /** Type of the span */
+  type: TType;
+  
+  /** When span started */
+  startTime: Date;
+  
+  /** When span ended */
+  endTime?: Date;
+  
+  /** Type-specific attributes */
+  attributes?: AISpanTypeMap[TType];
+  
+  /** User-defined metadata */
+  metadata?: Record<string, any>;
+  
+  /** Input passed at the start of the span */
+  input?: any;
+  
+  /** Output generated at the end of the span */
+  output?: any;
+  
+  /** Error information if span failed */
+  errorInfo?: {
+    message: string;
+    id?: string;
+    domain?: string;
+    category?: string;
+    details?: Record<string, any>;
+  };
+  
+  /** Is an event span? (occurs at startTime, has no endTime) */
+  isEvent: boolean;
+}
+```
+
+## AISpan
+
+AI Span interface, used internally for tracing. Extends BaseSpan with lifecycle methods and properties.
+
+```typescript
+interface AISpan<TType extends AISpanType> extends BaseSpan<TType> {
+  /** Is an internal span? (spans internal to the operation of mastra) */
+  isInternal: boolean;
+  
+  /** Parent span reference (undefined for root spans) */
+  parent?: AnyAISpan;
+  
+  /** Pointer to the AITracing instance */
+  aiTracing: AITracing;
+}
+```
+
+### Properties
+
+```typescript
+/** Returns TRUE if the span is the root span of a trace */
+get isRootSpan(): boolean
+
+/** Returns TRUE if the span is a valid span (not a NO-OP Span) */
+get isValid(): boolean
+
+/** Get the closest parent spanId that isn't an internal span */
+getParentSpanId(includeInternalSpans?: boolean): string | undefined
+
+/** Returns a lightweight span ready for export */
+exportSpan(includeInternalSpans?: boolean): ExportedAISpan<TType> | undefined
+```
+
+### Methods
+
+#### end
+
+```typescript
+end(options?: EndSpanOptions<TType>): void
+```
+
+Ends the span and triggers export to configured exporters. Sets the `endTime` and optionally updates `output`, `metadata`, and `attributes`.
+
+<PropertiesTable
+  props={[
+    {
+      name: "output",
+      type: "any",
+      description: "Final output data from the operation",
+      required: false,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>",
+      description: "Additional metadata to merge",
+      required: false,
+    },
+    {
+      name: "attributes",
+      type: "Partial<AISpanTypeMap[TType]>",
+      description: "Type-specific attributes to update",
+      required: false,
+    },
+  ]}
+/>
+
+#### error
+
+```typescript
+error(options: ErrorSpanOptions<TType>): void
+```
+
+Records an error on the span. Sets the `errorInfo` field and can optionally end the span.
+
+<PropertiesTable
+  props={[
+    {
+      name: "error",
+      type: "Error",
+      description: "The error that occurred",
+      required: true,
+    },
+    {
+      name: "endSpan",
+      type: "boolean",
+      description: "Whether to end the span after recording the error",
+      required: false,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>",
+      description: "Additional error context metadata",
+      required: false,
+    },
+    {
+      name: "attributes",
+      type: "Partial<AISpanTypeMap[TType]>",
+      description: "Type-specific attributes to update",
+      required: false,
+    },
+  ]}
+/>
+
+#### update
+
+```typescript
+update(options: UpdateSpanOptions<TType>): void
+```
+
+Updates span data while it's still active. Can modify `input`, `output`, `metadata`, and `attributes`.
+
+<PropertiesTable
+  props={[
+    {
+      name: "input",
+      type: "any",
+      description: "Update or set input data",
+      required: false,
+    },
+    {
+      name: "output",
+      type: "any",
+      description: "Update or set output data",
+      required: false,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>",
+      description: "Metadata to merge with existing",
+      required: false,
+    },
+    {
+      name: "attributes",
+      type: "Partial<AISpanTypeMap[TType]>",
+      description: "Type-specific attributes to update",
+      required: false,
+    },
+  ]}
+/>
+
+#### createChildSpan
+
+```typescript
+createChildSpan<TChildType extends AISpanType>(
+  options: ChildSpanOptions<TChildType>
+): AISpan<TChildType>
+```
+
+Creates a child span under this span. Child spans track sub-operations and inherit the trace context.
+
+<PropertiesTable
+  props={[
+    {
+      name: "type",
+      type: "TChildType",
+      description: "Type of the child span",
+      required: true,
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Name of the child span",
+      required: true,
+    },
+    {
+      name: "attributes",
+      type: "AISpanTypeMap[TChildType]",
+      description: "Type-specific attributes",
+      required: false,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>",
+      description: "Initial metadata",
+      required: false,
+    },
+    {
+      name: "input",
+      type: "any",
+      description: "Initial input data",
+      required: false,
+    },
+  ]}
+/>
+
+#### createEventSpan
+
+```typescript
+createEventSpan<TChildType extends AISpanType>(
+  options: ChildEventOptions<TChildType>
+): AISpan<TChildType>
+```
+
+Creates an event span under this span. Event spans represent point-in-time occurrences with no duration.
+
+<PropertiesTable
+  props={[
+    {
+      name: "type",
+      type: "TChildType",
+      description: "Type of the event span",
+      required: true,
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Name of the event",
+      required: true,
+    },
+    {
+      name: "attributes",
+      type: "AISpanTypeMap[TChildType]",
+      description: "Type-specific attributes",
+      required: false,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>",
+      description: "Event metadata",
+      required: false,
+    },
+    {
+      name: "input",
+      type: "any",
+      description: "Event input data",
+      required: false,
+    },
+    {
+      name: "output",
+      type: "any",
+      description: "Event output data",
+      required: false,
+    },
+  ]}
+/>
+
+## ExportedAISpan
+
+Exported AI Span interface, used for tracing exporters. A lightweight version of AISpan without methods or circular references.
+
+```typescript
+interface ExportedAISpan<TType extends AISpanType> extends BaseSpan<TType> {
+  /** Parent span id reference (undefined for root spans) */
+  parentSpanId?: string;
+  
+  /** TRUE if the span is the root span of a trace */
+  isRootSpan: boolean;
+}
+```
+
+## Span Lifecycle Events
+
+Events emitted during the span lifecycle.
+
+### AITracingEventType
+
+```typescript
+enum AITracingEventType {
+  /** Emitted when a span is created and started */
+  SPAN_STARTED = 'span_started',
+  
+  /** Emitted when a span is updated via update() */
+  SPAN_UPDATED = 'span_updated',
+  
+  /** Emitted when a span is ended via end() or error() */
+  SPAN_ENDED = 'span_ended',
+}
+```
+
+### AITracingEvent
+
+```typescript
+type AITracingEvent =
+  | { type: 'span_started'; exportedSpan: AnyExportedAISpan }
+  | { type: 'span_updated'; exportedSpan: AnyExportedAISpan }
+  | { type: 'span_ended'; exportedSpan: AnyExportedAISpan };
+```
+
+Exporters receive these events to process and send trace data to observability platforms.
+
+## Union Types
+
+### AnyAISpan
+
+```typescript
+type AnyAISpan = AISpan<keyof AISpanTypeMap>;
+```
+
+Union type for cases that need to handle any span type.
+
+### AnyExportedAISpan
+
+```typescript
+type AnyExportedAISpan = ExportedAISpan<keyof AISpanTypeMap>;
+```
+
+Union type for cases that need to handle any exported span type.
+
+## See Also
+
+### Documentation
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview) - Concepts and usage
+- [Creating Child Spans](/docs/observability/ai-tracing/overview#creating-child-spans) - Practical examples
+- [Retrieving Trace IDs](/docs/observability/ai-tracing/overview#retrieving-trace-ids) - Using trace IDs
+
+### Reference
+- [AITracing Classes](/reference/observability/ai-tracing/ai-tracing) - Core tracing classes
+- [Interfaces](/reference/observability/ai-tracing/interfaces) - Complete type reference
+- [Configuration](/reference/observability/ai-tracing/configuration) - Configuration options
+
+### Examples
+- [Basic AI Tracing](/examples/observability/basic-ai-tracing) - Working with spans

package/.docs/raw/reference/observability/{logger.mdx → logging/pino-logger.mdx}

@@ -7,7 +7,7 @@ description: Documentation for PinoLogger, which provides methods to record even
 
 A Logger instance is created using `new PinoLogger()` and provides methods to record events at various severity levels.
 
-When deploying to Mastra Cloud, logs are displayed on the [Logs](../../docs/mastra-cloud/dashboard.mdx#logs) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
+When deploying to Mastra Cloud, logs are displayed on the [Logs](../../../docs/mastra-cloud/dashboard.mdx#logs) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
 ## Usage example
 

package/.docs/raw/reference/observability/{providers → otel-tracing/providers}/index.mdx

@@ -1,11 +1,13 @@
 ---
-title: "Reference: Provider List | Observability | Mastra Docs"
-description: Overview of observability providers supported by Mastra, including Arize AX, Arize Phoenix, Dash0, SigNoz, Braintrust, Langfuse, and more.
+title: "OTLP Providers | Observability | Mastra Docs"
+description: Overview of OTLP observability providers.
 ---
 
-# Observability Providers
+import { Callout } from "nextra/components";
 
-Observability providers include:
+# OTLP Providers
+
+These providers are supported with OTLP-based tracing:
 
 - [Arize AX](./providers/arize-ax.mdx)
 - [Arize Phoenix](./providers/arize-phoenix.mdx)

package/.docs/raw/reference/scorers/create-scorer.mdx

@@ -15,6 +15,7 @@ Use the `createScorer` factory to define your scorer with a name, description, a
 const scorer = createScorer({
   name: "My Custom Scorer",
   description: "Evaluates responses based on custom criteria",
+  type: "agent", // Optional: for agent evaluation with automatic typing
   judge: {
     model: myModel,
     instructions: "You are an expert evaluator..."
@@ -50,6 +51,12 @@ const scorer = createScorer({
       required: false,
       description: "Optional judge configuration for LLM-based steps. See Judge Object section below.",
     },
+    {
+      name: "type",
+      type: "string",
+      required: false,
+      description: "Type specification for input/output. Use 'agent' for automatic agent types. For custom types, use the generic approach instead.",
+    },
   ]}
 />
 
@@ -76,28 +83,40 @@ This function returns a scorer builder that you can chain step methods onto. See
 
 ## Type Safety
 
-For better type inference and IntelliSense support, you can specify input/output types when creating scorers:
+You can specify input/output types when creating scorers for better type inference and IntelliSense support:
+
+### Agent Type Shortcut
+
+For evaluating agents, use `type: 'agent'` to automatically get the correct types for agent input/output:
 
 ```typescript
-import { createScorer, ScorerRunInputForAgent, ScorerRunOutputForAgent } from '@mastra/core/scorers';
+import { createScorer } from '@mastra/core/scorers';
 
-// For agent evaluation with full type safety
-const agentScorer = createScorer<ScorerRunInputForAgent, ScorerRunOutputForAgent>({
+// Agent scorer with automatic typing
+const agentScorer = createScorer({
   name: 'Agent Response Quality',
-  description: 'Evaluates agent responses'
+  description: 'Evaluates agent responses',
+  type: 'agent' // Automatically provides ScorerRunInputForAgent/ScorerRunOutputForAgent
 })
 .preprocess(({ run }) => {
-  // run.input is typed as ScorerRunInputForAgent
+  // run.input is automatically typed as ScorerRunInputForAgent
   const userMessage = run.input.inputMessages[0]?.content;
   return { userMessage };
 })
 .generateScore(({ run, results }) => {
-  // run.output is typed as ScorerRunOutputForAgent  
+  // run.output is automatically typed as ScorerRunOutputForAgent  
   const response = run.output[0]?.content;
   return response.length > 10 ? 1.0 : 0.5;
 });
+```
+
+### Custom Types with Generics
+
+For custom input/output types, use the generic approach:
+
+```typescript
+import { createScorer } from '@mastra/core/scorers';
 
-// For custom input/output types
 type CustomInput = { query: string; context: string[] };
 type CustomOutput = { answer: string; confidence: number };
 
@@ -105,7 +124,11 @@ const customScorer = createScorer<CustomInput, CustomOutput>({
   name: 'Custom Scorer',
   description: 'Evaluates custom data'
 })
-.generateScore(({ run }) => run.output.confidence);
+.generateScore(({ run }) => {
+  // run.input is typed as CustomInput
+  // run.output is typed as CustomOutput
+  return run.output.confidence;
+});
 ```
 
 ### Built-in Agent Types
@@ -115,6 +138,33 @@ const customScorer = createScorer<CustomInput, CustomOutput>({
 
 Using these types provides autocomplete, compile-time validation, and better documentation for your scoring logic.
 
+## Trace Scoring with Agent Types
+
+When you use `type: 'agent'`, your scorer is compatible for both adding directly to agents and scoring traces from agent interactions. The scorer automatically transforms trace data into the proper agent input/output format:
+
+```typescript
+const agentTraceScorer = createScorer({
+  name: 'Agent Trace Length',
+  description: 'Evaluates agent response length',
+  type: 'agent'
+})
+.generateScore(({ run }) => {
+  // Trace data is automatically transformed to agent format
+  const userMessages = run.input.inputMessages;
+  const agentResponse = run.output[0]?.content;
+  
+  // Score based on response length
+  return agentResponse?.length > 50 ? 0 : 1;
+});
+
+// Register with Mastra for trace scoring
+const mastra = new Mastra({
+  scorers: {
+    agentTraceScorer
+  }
+});
+```
+
 ## Step Method Signatures
 
 ### preprocess

package/.docs/raw/reference/scorers/mastra-scorer.mdx

@@ -67,6 +67,12 @@ const result = await scorer.run({
       required: false,
       description: "Optional runtime context from the agent or workflow step being evaluated.",
     },
+    {
+      name: "groundTruth",
+      type: "any",
+      required: false,
+      description: "Optional expected or reference output for comparison during scoring. Automatically passed when using runExperiment.",
+    },
   ]}
 />