@mastra/mcp-docs-server 0.13.25-alpha.0 → 0.13.25

package/.docs/raw/observability/ai-tracing/exporters/otel.mdx

@@ -0,0 +1,250 @@
+---
+title: "OpenTelemetry Exporter | AI Tracing | Observability | Mastra Docs"
+description: "Send AI traces to any OpenTelemetry-compatible observability platform"
+---
+
+import { Callout } from "nextra/components";
+
+# OpenTelemetry Exporter
+
+<Callout type="warning">
+The OpenTelemetry exporter is currently **experimental**. APIs and configuration options may change in future releases.
+</Callout>
+
+The OpenTelemetry (OTEL) exporter sends your AI traces to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, Dash0, Traceloop, Laminar, and more.
+
+## When to Use OTEL Exporter
+
+The OTEL exporter is ideal when you need:
+- **Platform flexibility** - Send traces to any OTEL-compatible backend
+- **Standards compliance** - Follow OpenTelemetry GenAI semantic conventions
+- **Multi-vendor support** - Configure once, switch providers easily
+- **Enterprise platforms** - Integrate with existing observability infrastructure
+- **Custom collectors** - Send to your own OTEL collector
+
+## Installation
+
+Each provider requires specific protocol packages. Install the base exporter plus the protocol package for your provider:
+
+### For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar)
+
+```bash npm2yarn
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
+```
+
+### For gRPC Providers (Dash0)
+
+```bash npm2yarn
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
+```
+
+### For HTTP/JSON Providers (Traceloop)
+
+```bash npm2yarn
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-http
+```
+
+## Provider Configurations
+
+### Dash0
+
+[Dash0](https://www.dash0.com/) provides real-time observability with automatic insights.
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { OtelExporter } from "@mastra/otel-exporter";
+
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      otel: {
+        serviceName: 'my-service',
+        exporters: [
+          new OtelExporter({
+            provider: {
+              dash0: {
+                apiKey: process.env.DASH0_API_KEY,
+                endpoint: process.env.DASH0_ENDPOINT, // e.g., 'ingress.us-west-2.aws.dash0.com:4317'
+                dataset: 'production', // Optional dataset name
+              }
+            },
+          }),
+        ],
+      },
+    },
+  },
+});
+```
+
+<Callout type="info">
+Get your Dash0 endpoint from your dashboard. It should be in the format `ingress.{region}.aws.dash0.com:4317`.
+</Callout>
+
+### SigNoz
+
+[SigNoz](https://signoz.io/) is an open-source APM alternative with built-in AI tracing support.
+
+```typescript filename="src/mastra/index.ts"
+new OtelExporter({
+  provider: {
+    signoz: {
+      apiKey: process.env.SIGNOZ_API_KEY,
+      region: 'us', // 'us' | 'eu' | 'in'
+      // endpoint: 'https://my-signoz.example.com', // For self-hosted
+    }
+  },
+})
+```
+
+### New Relic
+
+[New Relic](https://newrelic.com/) provides comprehensive observability with AI monitoring capabilities.
+
+```typescript filename="src/mastra/index.ts"
+new OtelExporter({
+  provider: {
+    newrelic: {
+      apiKey: process.env.NEW_RELIC_LICENSE_KEY,
+      // endpoint: 'https://otlp.eu01.nr-data.net', // For EU region
+    }
+  },
+})
+```
+
+### Traceloop
+
+[Traceloop](https://www.traceloop.com/) specializes in LLM observability with automatic prompt tracking.
+
+```typescript filename="src/mastra/index.ts"
+new OtelExporter({
+  provider: {
+    traceloop: {
+      apiKey: process.env.TRACELOOP_API_KEY,
+      destinationId: 'my-destination', // Optional
+    }
+  },
+})
+```
+
+### Laminar
+
+[Laminar](https://www.lmnr.ai/) provides specialized LLM observability and analytics.
+
+```typescript filename="src/mastra/index.ts"
+new OtelExporter({
+  provider: {
+    laminar: {
+      apiKey: process.env.LMNR_PROJECT_API_KEY,
+      // teamId: process.env.LAMINAR_TEAM_ID, // Optional, for backwards compatibility
+    }
+  },
+})
+```
+
+### Custom/Generic OTEL Endpoints
+
+For other OTEL-compatible platforms or custom collectors:
+
+```typescript filename="src/mastra/index.ts"
+new OtelExporter({
+  provider: {
+    custom: {
+      endpoint: 'https://your-collector.example.com/v1/traces',
+      protocol: 'http/protobuf', // 'http/json' | 'http/protobuf' | 'grpc'
+      headers: {
+        'x-api-key': process.env.API_KEY,
+      },
+    }
+  },
+})
+```
+
+## Configuration Options
+
+### Complete Configuration
+
+```typescript
+new OtelExporter({
+  // Provider configuration (required)
+  provider: {
+    // Use one of: dash0, signoz, newrelic, traceloop, laminar, custom
+  },
+
+  // Export configuration
+  timeout: 30000,        // Export timeout in milliseconds
+  batchSize: 100,        // Number of spans per batch
+
+  // Debug options
+  logLevel: 'info',      // 'debug' | 'info' | 'warn' | 'error'
+})
+```
+
+## OpenTelemetry Semantic Conventions
+
+The exporter follows [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/), ensuring compatibility with observability platforms:
+
+### Span Naming
+- **LLM Operations**: `chat {model}` or `tool_selection {model}`
+- **Tool Execution**: `tool.execute {tool_name}`
+- **Agent Runs**: `agent.{agent_id}`
+- **Workflow Runs**: `workflow.{workflow_id}`
+
+### Key Attributes
+- `gen_ai.operation.name` - Operation type (chat, tool.execute, etc.)
+- `gen_ai.system` - AI provider (openai, anthropic, etc.)
+- `gen_ai.request.model` - Model identifier
+- `gen_ai.usage.input_tokens` - Number of input tokens
+- `gen_ai.usage.output_tokens` - Number of output tokens
+- `gen_ai.request.temperature` - Sampling temperature
+- `gen_ai.response.finish_reasons` - Completion reason
+
+## Buffering Strategy
+
+The exporter buffers spans until a trace is complete:
+1. Collects all spans for a trace
+2. Waits 5 seconds after root span completes
+3. Exports complete trace with preserved parent-child relationships
+4. Ensures no orphaned spans
+
+## Protocol Selection Guide
+
+Choose the right protocol package based on your provider:
+
+| Provider | Protocol | Required Package |
+|----------|----------|------------------|
+| Dash0 | gRPC | `@opentelemetry/exporter-trace-otlp-grpc` |
+| SigNoz | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
+| New Relic | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
+| Traceloop | HTTP/JSON | `@opentelemetry/exporter-trace-otlp-http` |
+| Laminar | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
+| Custom | Varies | Depends on your collector |
+
+<Callout type="warning">
+Make sure to install the correct protocol package for your provider. The exporter will provide a helpful error message if the wrong package is installed.
+</Callout>
+
+## Troubleshooting
+
+### Missing Dependency Error
+
+If you see an error like:
+```
+HTTP/Protobuf exporter is not installed (required for signoz).
+To use HTTP/Protobuf export, install the required package:
+  npm install @opentelemetry/exporter-trace-otlp-proto
+```
+
+Install the suggested package for your provider.
+
+### Common Issues
+
+1. **Wrong protocol package**: Verify you installed the correct exporter for your provider
+2. **Invalid endpoint**: Check endpoint format matches provider requirements
+3. **Authentication failures**: Verify API keys and headers are correct
+4. **No traces appearing**: Check that traces complete (root span must end)
+
+## Related
+
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [OpenTelemetry GenAI Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
+- [OTEL Exporter Reference](/reference/observability/ai-tracing/exporters/otel)

package/.docs/raw/observability/ai-tracing/overview.mdx

@@ -88,13 +88,14 @@ Mastra provides two built-in exporters that work out of the box:
 ### External Exporters
 
 In addition to the internal exporters, Mastra supports integration with popular observability platforms. These exporters allow you to leverage your existing monitoring infrastructure and take advantage of platform-specific features like alerting, dashboards, and correlation with other application metrics.
- 
-- **[Langfuse](/docs/observability/ai-tracing/exporters/langfuse)** - Sends traces to the Langfuse open-source LLM engineering platform
+
 - **[Braintrust](/docs/observability/ai-tracing/exporters/braintrust)** - Exports traces to Braintrust's eval and observability platform
+- **[Langfuse](/docs/observability/ai-tracing/exporters/langfuse)** - Sends traces to the Langfuse open-source LLM engineering platform
+- **[LangSmith](/docs/observability/ai-tracing/exporters/langsmith)** - Pushes traces into LangSmith’s observability and evaluation toolkit
+- **[OpenTelemetry](/docs/observability/ai-tracing/exporters/otel)** - Deliver traces to any OpenTelemetry-compatible observability system
+  - Supports: Dash0, Laminar, New Relic, SigNoz, Traceloop, Zipkin, and others!
 
 - **Arize** - Coming soon!
-- **LangSmith** - Coming soon!
-- **OpenTelemetry** - Coming soon!
 
 ## Sampling Strategies
 
@@ -386,15 +387,15 @@ execute: async ({ input, tracingContext }) => {
     const results = await db.query(input.query);
     querySpan?.end({
       output: results.data,
-      metadata: { 
+      metadata: {
         rowsReturned: results.length,
         queryTimeMs: results.executionTime,
-        cacheHit: results.fromCache 
+        cacheHit: results.fromCache
       }
     });
     return results;
   } catch (error) {
-    querySpan?.error({ 
+    querySpan?.error({
       error,
       metadata: { retryable: isRetryableError(error) }
     });
@@ -403,7 +404,7 @@ execute: async ({ input, tracingContext }) => {
 }
 ```
 
-Child spans automatically inherit the trace context from their parent, maintaining the relationship hierarchy in your observability platform. 
+Child spans automatically inherit the trace context from their parent, maintaining the relationship hierarchy in your observability platform.
 
 ## Span Processors
 
@@ -411,7 +412,7 @@ Span processors allow you to transform, filter, or enrich trace data before it's
 
 ### Built-in Processors
 
-* [Sensitive Data Filter](/docs/observability/processors/sensitive-data-filter) redacts sensitive information. It is enabled in the default observability config.
+* [Sensitive Data Filter](/docs/observability/ai-tracing/processors/sensitive-data-filter) redacts sensitive information. It is enabled in the default observability config.
 
 ### Creating Custom Processors
 
@@ -422,12 +423,12 @@ import type { AISpanProcessor, AnyAISpan } from '@mastra/core/ai-tracing';
 
 export class LowercaseInputProcessor implements AISpanProcessor {
   name = 'lowercase-processor';
-  
+
   process(span: AnyAISpan): AnyAISpan {
     span.input = `${span.input}`.toLowerCase()
     return span;
   }
-  
+
   async shutdown(): Promise<void> {
     // Cleanup if needed
   }
@@ -472,7 +473,7 @@ const result = await agent.generate({
 
 console.log('Trace ID:', result.traceId);
 
-// Using stream  
+// Using stream
 const streamResult = await agent.stream({
   messages: [{ role: 'user', content: 'Tell me a story' }]
 });
@@ -545,7 +546,6 @@ Traces are available in multiple locations:
 
 ### Examples
 - [Basic AI Tracing Example](/examples/observability/basic-ai-tracing) - Working implementation
-- [Advanced Tracing Patterns](/examples/observability/advanced-tracing) - Complex scenarios
 
 ### Reference Documentation
 - [Configuration API](/reference/observability/ai-tracing/configuration) - ObservabilityConfig details
@@ -559,7 +559,7 @@ Traces are available in multiple locations:
 - [ConsoleExporter](/reference/observability/ai-tracing/exporters/console-exporter) - Debug output
 - [Langfuse](/reference/observability/ai-tracing/exporters/langfuse) - Langfuse integration
 - [Braintrust](/reference/observability/ai-tracing/exporters/braintrust) - Braintrust integration
+- [OpenTelemetry](/reference/observability/ai-tracing/exporters/otel) - OTEL-compatible platforms
 
 ### Processors
-- [Sensitive Data Filter](/docs/observability/processors/sensitive-data-filter) - Data redaction
-- [Custom Processors Guide](/docs/observability/processors/custom-processors) - Build your own
+- [Sensitive Data Filter](/docs/observability/ai-tracing/processors/sensitive-data-filter) - Data redaction

package/.docs/raw/observability/overview.mdx

@@ -56,7 +56,7 @@ export const mastra = new Mastra({
 
 With this basic setup, you will see Traces and Logs in both the Playground and in Mastra Cloud.
 
-We also support various external tracing providers like Langfuse and Braintrust. See more about this in the [AI Tracing](/docs/observability/ai-tracing.mdx) documentation.
+We also support various external tracing providers like Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the [AI Tracing](/docs/observability/ai-tracing.mdx) documentation.
 
 ## What's Next?
 

package/.docs/raw/reference/agents/network.mdx

@@ -287,4 +287,4 @@ await agent.network(`
       description: "A promise that resolves to token usage statistics",
     },
   ]}
-/>
+/>

package/.docs/raw/reference/auth/clerk.mdx

@@ -11,7 +11,7 @@ The `MastraAuthClerk` class provides authentication for Mastra applications usin
 
 ```typescript filename="src/mastra/index.ts" showLineNumbers copy
 import { Mastra } from "@mastra/core/mastra";
-import { MastraAuthClerk } from '@mastra/clerk-auth';
+import { MastraAuthClerk } from '@mastra/auth-clerk';
 
 export const mastra = new Mastra({
   // ..

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

@@ -165,26 +165,17 @@ const liveEvals = await agent.liveEvals();
 
 <StreamVNextCallout />
 
-Stream responses using the enhanced VNext 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 VNext API with improved method signatures.
 
 ```typescript
 const response = await agent.streamVNext(
   "Tell me a story",
   {
-    format: 'mastra', // Default: Mastra's native format
     threadId: "thread-1",
     clientTools: { colorChangeTool },
   }
 );
 
-// AI SDK v5 compatible format
-const response = await agent.streamVNext(
-  "Tell me a story",
-  {
-    format: 'aisdk', // Enable AI SDK v5 compatibility
-    threadId: "thread-1",
-  }
-);
 
 // Process the stream
 response.processDataStream({
@@ -194,9 +185,9 @@ response.processDataStream({
 });
 ```
 
-The `format` parameter determines the output stream format:
-- `'mastra'` (default): Returns Mastra's native format
-- `'aisdk'`: Returns AI SDK v5 compatible format for frontend integration
+Currently, AI SDK V5 format is not supported in the client SDK.
+For AI SDK v5 compatible format, leverage the `@mastra/ai-sdk` package
+[AI SDK v5 Stream Compatibility](/docs/frameworks/agentic-uis/ai-sdk#enabling-stream-compatibility)
 
 ### Generate VNext (Experimental)
 

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

@@ -142,6 +142,16 @@ export const mastraClient = new MastraClient({
       type: "string[]",
       description: "Returns the list of configured log transport types.",
     },
+    {
+      name: "getAITrace(traceId)",
+      type: "Promise<AITraceRecord>",
+      description: "Retrieves a specific AI trace by ID, including all its spans and details.",
+    },
+    {
+      name: "getAITraces(params)",
+      type: "Promise<GetAITracesResponse>",
+      description: "Retrieves paginated list of AI trace root spans with optional filtering. Use getAITrace() to get complete traces with all spans.",
+    },
   ]}
 />
 

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

@@ -0,0 +1,76 @@
+---
+title: Mastra Client Observability API
+description: Learn how to retrieve AI traces, monitor application performance, and score traces using the client-js SDK.
+---
+
+# Observability API
+
+The Observability API provides methods to retrieve AI traces, monitor your application's performance, and score traces for evaluation. This helps you understand how your AI agents and workflows are performing.
+
+## Getting a Specific AI Trace
+
+Retrieve a specific AI trace by its ID, including all its spans and details:
+
+```typescript
+const trace = await mastraClient.getAITrace("trace-id-123");
+```
+
+## Getting AI Traces with Filtering
+
+Retrieve a paginated list of AI trace root spans with optional filtering:
+
+```typescript
+const traces = await mastraClient.getAITraces({
+  pagination: {
+    page: 1,
+    perPage: 20,
+    dateRange: {
+      start: new Date('2024-01-01'),
+      end: new Date('2024-01-31')
+    }
+  },
+  filters: {
+    name: "weather-agent", // Filter by trace name
+    spanType: "agent", // Filter by span type
+    entityId: "weather-agent-id", // Filter by entity ID
+    entityType: "agent" // Filter by entity type
+  }
+});
+
+console.log(`Found ${traces.spans.length} root spans`);
+console.log(`Total pages: ${traces.pagination.totalPages}`);
+
+// To get the complete trace with all spans, use getAITrace
+const completeTrace = await mastraClient.getAITrace(traces.spans[0].traceId);
+```
+
+## Scoring Traces
+
+Score specific traces using registered scorers for evaluation:
+
+```typescript
+const result = await mastraClient.score({
+  scorerName: "answer-relevancy",
+  targets: [
+    { traceId: "trace-1", spanId: "span-1" }, // Score specific span
+    { traceId: "trace-2" }, // Score specific span which defaults to the parent span
+  ]
+});
+```
+
+## Getting Scores by Span
+
+Retrieve scores for a specific span within a trace:
+
+```typescript
+const scores = await mastraClient.getScoresBySpan({
+  traceId: "trace-123",
+  spanId: "span-456",
+  page: 1,
+  perPage: 20
+});
+```
+## Related
+
+- [Agents API](./agents) - Learn about agent interactions that generate traces
+- [Workflows API](./workflows) - Understand workflow execution monitoring  

package/.docs/raw/reference/core/getScorer.mdx

@@ -0,0 +1,75 @@
+---
+title: "Reference: getScorer() | Core | Mastra Docs"
+description: "Documentation for the `getScorer()` method in Mastra, which retrieves a specific scorer by its registration key."
+---
+
+# getScorer()
+
+The `getScorer()` method retrieves a specific scorer that was registered with the Mastra instance using its registration key. This method provides type-safe access to scorers and throws an error if the requested scorer is not found.
+
+## Usage Example
+
+```typescript
+import { mastra } from './mastra';
+
+// Get a specific scorer by key
+const relevancyScorer = mastra.getScorer('relevancyScorer');
+
+const weatherAgent = mastra.getAgent('weatherAgent')
+
+// Use the scorer to evaluate an AI output
+await weatherAgent.generate('What is the weather in Rome', {
+  scorers: {
+    answerRelevancy: {
+      scorer: relevancyScorer,
+    },
+  },
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "key",
+      type: "string",
+      description: "The registration key of the scorer to retrieve. This should match a key used when registering scorers in the Mastra constructor.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "scorer",
+      type: "MastraScorer",
+      description: "The MastraScorer instance associated with the provided key.",
+    },
+  ]}
+/>
+
+## Error Handling
+
+This method throws a `MastraError` if:
+- The scorer with the specified key is not found
+- No scorers are registered with the Mastra instance
+
+```typescript
+try {
+  const scorer = mastra.getScorer('nonExistentScorer');
+} catch (error) {
+  if (error.id === 'MASTRA_GET_SCORER_NOT_FOUND') {
+    console.log('Scorer not found, using default evaluation');
+  }
+}
+```
+
+## Related
+
+- [getScorers()](../../reference/core/getScorers.mdx) - Get all registered scorers
+- [getScorerByName()](../../reference/core/getScorerByName.mdx) - Get a scorer by its name property
+- [Custom Scorers](../../docs/scorers/custom-scorers.mdx) - Learn how to create custom scorers

package/.docs/raw/reference/core/getScorerByName.mdx

@@ -0,0 +1,75 @@
+---
+title: "Reference: getScorerByName() | Core | Mastra Docs"
+description: "Documentation for the `getScorerByName()` method in Mastra, which retrieves a scorer by its name property rather than registration key."
+---
+
+# getScorerByName()
+
+The `getScorerByName()` method retrieves a scorer by searching for its `name` property rather than the registration key. This is useful when you know the scorer's display name but not necessarily how it was registered in the Mastra instance.
+
+## Usage Example
+
+```typescript
+import { mastra } from './mastra';
+
+// Get a scorer by its name property
+const relevancyScorer = mastra.getScorerByName('Answer Relevancy');
+
+const weatherAgent = mastra.getAgent('weatherAgent')
+
+// Use the scorer to evaluate an AI output
+await weatherAgent.generate('What is the weather in Rome', {
+  scorers: {
+    answerRelevancy: {
+      scorer: relevancyScorer,
+    },
+  },
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "name",
+      type: "string",
+      description: "The name property of the scorer to retrieve. This should match the 'name' field specified when creating the scorer with createScorer().",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "scorer",
+      type: "MastraScorer",
+      description: "The MastraScorer instance that has the matching name property.",
+    },
+  ]}
+/>
+
+## Error Handling
+
+This method throws a `MastraError` if:
+- No scorer with the specified name is found
+- No scorers are registered with the Mastra instance
+
+```typescript
+try {
+  const scorer = mastra.getScorerByName('Non-existent Scorer');
+} catch (error) {
+  if (error.id === 'MASTRA_GET_SCORER_BY_NAME_NOT_FOUND') {
+    console.log('Scorer with that name not found');
+  }
+}
+```
+
+## Related
+
+- [getScorer()](../../reference/core/getScorer) - Get a scorer by its registration key
+- [getScorers()](../../reference/core/getScorers) - Get all registered scorers
+- [createScorer()](../../reference/scorers/create-scorer) - Learn how to create scorers with names