@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.14

package/.docs/raw/observability/logging.mdx

@@ -7,18 +7,17 @@ description: Learn how to use logging in Mastra to monitor execution, capture ap
 
 Mastra's logging system captures function execution, input data, and output responses in a structured format.
 
-When deploying to Mastra Cloud, logs are shown on the [Logs](/docs/v1/deployment/mastra-cloud/observability) 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 shown on the [Logs](/docs/v1/mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
 ## Configuring logs with PinoLogger
 
 When [initializing a new Mastra project](/guides/v1/getting-started/quickstart) using the CLI, `PinoLogger` is included by default.
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core/mastra";
 import { PinoLogger } from "@mastra/loggers";
 
 export const mastra = new Mastra({
-  // ...
   logger: new PinoLogger({
     name: "Mastra",
     level: "info",
@@ -26,7 +25,11 @@ export const mastra = new Mastra({
 });
 ```
 
-> See the [PinoLogger](/reference/v1/logging/pino-logger) API reference for all available configuration options.
+:::info
+
+Visit [PinoLogger](/reference/v1/logging/pino-logger) for all available configuration options.
+
+:::
 
 ## Customizing logs
 
@@ -36,14 +39,12 @@ Mastra provides access to a logger instance via the `mastra.getLogger()` method,
 
 Within a workflow step, access the logger via the `mastra` parameter inside the `execute` function. This allows you to log messages relevant to the step’s execution.
 
-```typescript {8-9} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {6-7} title="src/mastra/workflows/test-workflow.ts"
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
 const step1 = createStep({
-  //...
   execute: async ({ mastra }) => {
-
     const logger = mastra.getLogger();
     logger.info("workflow info log");
 
@@ -62,12 +63,11 @@ export const testWorkflow = createWorkflow({...})
 
 Similarly, tools have access to the logger instance via the `mastra` parameter. Use this to log tool specific activity during execution.
 
-```typescript {8-9} title="src/mastra/tools/test-tool.ts" showLineNumbers copy
+```typescript {6-7} title="src/mastra/tools/test-tool.ts"
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 
 export const testTool = createTool({
-  // ...
   execute: async ({ mastra }) => {
     const logger = mastra?.getLogger();
     logger?.info("tool info log");
@@ -85,12 +85,11 @@ Logger methods accept an optional second argument for additional data. This can
 
 In this example, the log message includes an object with a key of `agent` and a value of the `testAgent` instance.
 
-```typescript {11} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {10} title="src/mastra/workflows/test-workflow.ts"
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
 const step1 = createStep({
-  //...
   execute: async ({ mastra }) => {
 
     const testAgent = mastra.getAgent("testAgent");

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

@@ -29,7 +29,6 @@ import { LibSqlStorage } from "@mastra/libsql";
 import { Observability } from "@mastra/observability";
 
 export const mastra = new Mastra({
-  // ... other config
   logger: new PinoLogger(),
   storage: new LibSQLStore({
     id: 'mastra-storage',

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

@@ -70,7 +70,7 @@ Using the OtelBridge requires two steps:
 
 Create an instrumentation file that initializes OTEL. This must run before your application code:
 
-```typescript title="instrumentation.ts" showLineNumbers copy
+```typescript title="instrumentation.ts"
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
@@ -99,7 +99,7 @@ export { sdk };
 
 Add the OtelBridge to your Mastra observability config:
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { Observability } from "@mastra/observability";
 import { OtelBridge } from "@mastra/otel-bridge";

package/.docs/raw/observability/tracing/exporters/cloud.mdx

@@ -112,4 +112,4 @@ CloudExporter uses intelligent batching to optimize network usage. Traces are bu
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [DefaultExporter](/docs/v1/observability/tracing/exporters/default)
-- [Mastra Cloud Documentation](/docs/v1/deployment/mastra-cloud/overview)
+- [Mastra Cloud Documentation](/docs/v1/mastra-cloud/overview)

package/.docs/raw/observability/tracing/exporters/default.mdx

@@ -11,7 +11,7 @@ The `DefaultExporter` persists traces to your configured storage backend, making
 
 ### Prerequisites
 
-1. **Storage Backend**: Configure a storage provider (LibSQL, PostgreSQL, etc.)
+1. **Storage Backend**: Configure a storage provider (libSQL, PostgreSQL, etc.)
 2. **Studio**: Install for viewing traces locally
 
 ### Basic Setup
@@ -102,7 +102,7 @@ If you set the strategy to `'auto'`, the `DefaultExporter` automatically selects
 
 | Storage Provider                                | Preferred Strategy | Supported Strategies                      | Notes                                 |
 | ----------------------------------------------- | ------------------ | ----------------------------------------- | ------------------------------------- |
-| **[LibSQL](/reference/v1/storage/libsql)**         | batch-with-updates | realtime, batch-with-updates, insert-only | Default storage, good for development |
+| **[libSQL](/reference/v1/storage/libsql)**         | batch-with-updates | realtime, batch-with-updates, insert-only | Default storage, good for development |
 | **[PostgreSQL](/reference/v1/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only           | Recommended for production            |
 
 ### Strategy Benefits
@@ -160,4 +160,4 @@ new DefaultExporter({
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [CloudExporter](/docs/v1/observability/tracing/exporters/cloud)
-- [Storage Configuration](/docs/v1/server-db/storage)
+- [Storage Configuration](/docs/v1/memory/storage)

package/.docs/raw/observability/tracing/exporters/langfuse.mdx

@@ -117,7 +117,6 @@ Use `withLangfusePrompt` with `buildTracingOptions` for the cleanest API:
 
 ```typescript title="src/agents/support-agent.ts"
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { buildTracingOptions } from "@mastra/observability";
 import { withLangfusePrompt } from "@mastra/langfuse";
 import { Langfuse } from "langfuse";
@@ -133,7 +132,7 @@ const prompt = await langfuse.getPrompt("customer-support");
 export const supportAgent = new Agent({
   name: "support-agent",
   instructions: prompt.prompt, // Use the prompt text from Langfuse
-  model: openai("gpt-4o"),
+  model: "openai/gpt-4o",
   defaultGenerateOptions: {
     tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
 ## Using Tags

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

@@ -21,12 +21,11 @@ Traces are created by:
 
 ### Basic Config
 
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { Observability } from "@mastra/observability";
 
 export const mastra = new Mastra({
-  // ... other config
   observability: new Observability({
     default: { enabled: true }, // Enables DefaultExporter and CloudExporter
   }),
@@ -50,7 +49,7 @@ When enabled, the default configuration automatically includes:
 
 This default configuration is a minimal helper that equates to this more verbose configuration:
 
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 import {
   Observability,
   CloudExporter,
@@ -59,7 +58,6 @@ import {
 } from "@mastra/observability";
 
 export const mastra = new Mastra({
-  // ... other config
   observability: new Observability({
     configs: {
       default: {
@@ -174,7 +172,7 @@ sampling: {
 
 ### Complete Example
 
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 export const mastra = new Mastra({
   observability: new Observability({
     configs: {
@@ -214,7 +212,7 @@ Note that only a single config can be used for a specific execution. But a singl
 
 Use `configSelector` to choose the appropriate tracing configuration based on request context:
 
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 export const mastra = new Mastra({
   observability: new Observability({
     configs: {
@@ -259,7 +257,7 @@ export const mastra = new Mastra({
 
 A common pattern is to select configurations based on deployment environment:
 
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 export const mastra = new Mastra({
   observability: new Observability({
     configs: {
@@ -293,7 +291,7 @@ export const mastra = new Mastra({
 
 Having both the default config enabled and adding custom configs is an invalid configuration of Observability. Use either the default or custom config, but not both.
 
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 export const mastra = new Mastra({
   observability: new Observability({
     default: { enabled: true }, // This will always be used!
@@ -311,7 +309,7 @@ export const mastra = new Mastra({
 
 When creating a custom config with external exporters, you might lose access to Studio and Cloud. To maintain access while adding external exporters, include the default exporters in your custom config:
 
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 import { DefaultExporter, CloudExporter } from "@mastra/observability";
 import { ArizeExporter } from "@mastra/arize";
 
@@ -354,7 +352,7 @@ Custom metadata allows you to attach additional context to your traces, making i
 
 You can add metadata to any span using the tracing context:
 
-```ts showLineNumbers copy
+```ts
 execute: async ({ inputData, tracingContext }) => {
   const startTime = Date.now();
   const response = await fetch(inputData.endpoint);
@@ -384,7 +382,7 @@ Instead of manually adding metadata to each span, you can configure Mastra to au
 
 Define which RequestContext keys to extract in your tracing configuration. These keys will be automatically included as metadata for all spans created with this configuration:
 
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 export const mastra = new Mastra({
   observability: new Observability({
     configs: {
@@ -400,7 +398,7 @@ export const mastra = new Mastra({
 
 Now when you execute agents or workflows with a RequestContext, these values are automatically extracted:
 
-```ts showLineNumbers copy
+```ts
 const requestContext = new RequestContext();
 requestContext.set("userId", "user-123");
 requestContext.set("environment", "production");
@@ -417,7 +415,7 @@ const result = await agent.generate({
 
 You can add trace-specific keys using `tracingOptions.requestContextKeys`. These are merged with the configuration-level keys:
 
-```ts showLineNumbers copy
+```ts
 const requestContext = new RequestContext();
 requestContext.set("userId", "user-123");
 requestContext.set("environment", "production");
@@ -438,7 +436,7 @@ const result = await agent.generate({
 
 Use dot notation to extract nested values from RequestContext:
 
-```ts showLineNumbers copy
+```ts
 export const mastra = new Mastra({
   observability: new Observability({
     configs: {
@@ -470,7 +468,7 @@ Tags are string labels that help you categorize and filter traces. Unlike metada
 
 Use `tracingOptions.tags` to add tags when executing agents or workflows:
 
-```ts showLineNumbers copy
+```ts
 // With agents
 const result = await agent.generate({
   messages: [{ role: "user", content: "Hello" }],
@@ -500,7 +498,7 @@ const result = await run.start({
   - **OtelBridge** - `mastra.tags` span attribute
 - **Combinable with metadata**: You can use both `tags` and `metadata` in the same `tracingOptions`
 
-```ts showLineNumbers copy
+```ts
 const result = await agent.generate({
   messages: [{ role: "user", content: "Analyze this" }],
   tracingOptions: {
@@ -522,7 +520,7 @@ const result = await agent.generate({
 
 When creating child spans within tools or workflow steps, you can pass the `requestContext` parameter to enable metadata extraction:
 
-```ts showLineNumbers copy
+```ts
 execute: async ({ tracingContext, requestContext }) => {
   // Create child span WITH requestContext - gets metadata extraction
   const dbSpan = tracingContext.currentSpan?.createChildSpan({
@@ -553,7 +551,7 @@ Child spans allow you to track fine-grained operations within your workflow step
 
 Create child spans inside a tool call or workflow step to track specific operations:
 
-```ts showLineNumbers copy
+```ts
 execute: async ({ inputData, tracingContext }) => {
   // Create another child span for the main database operation
   const querySpan = tracingContext.currentSpan?.createChildSpan({
@@ -598,7 +596,7 @@ Span processors allow you to transform, filter, or enrich trace data before it's
 
 You can create custom span processors by implementing the `SpanOutputProcessor` interface. Here's a simple example that converts all input text in spans to lowercase:
 
-```ts title="src/processors/lowercase-input-processor.ts" showLineNumbers copy
+```ts title="src/processors/lowercase-input-processor.ts"
 import type { SpanOutputProcessor, AnySpan } from "@mastra/observability";
 
 export class LowercaseInputProcessor implements SpanOutputProcessor {
@@ -643,7 +641,7 @@ When you execute agents or workflows with tracing enabled, the response includes
 
 Both `generate` and `stream` methods return the trace ID in their response:
 
-```ts showLineNumbers copy
+```ts
 // Using generate
 const result = await agent.generate({
   messages: [{ role: "user", content: "Hello" }],
@@ -663,7 +661,7 @@ console.log("Trace ID:", streamResult.traceId);
 
 Workflow executions also return trace IDs:
 
-```ts showLineNumbers copy
+```ts
 // Create a workflow run
 const run = await mastra.getWorkflow("myWorkflow").createRun();
 
@@ -703,7 +701,7 @@ When running Mastra agents or workflows within applications that have existing d
 
 Use the `tracingOptions` parameter to specify the trace context from your parent system:
 
-```ts showLineNumbers copy
+```ts
 // Get trace context from your existing tracing system
 const parentTraceId = getCurrentTraceId(); // Your tracing system
 const parentSpanId = getCurrentSpanId(); // Your tracing system
@@ -723,7 +721,7 @@ const result = await agent.generate("Analyze this data", {
 
 Integration with OpenTelemetry allows Mastra traces to appear seamlessly in your existing observability platform:
 
-```ts showLineNumbers copy
+```ts
 import { trace } from "@opentelemetry/api";
 
 // Get the current OpenTelemetry span
@@ -744,7 +742,7 @@ if (spanContext) {
 
 Workflows support the same pattern for trace propagation:
 
-```ts showLineNumbers copy
+```ts
 const workflow = mastra.getWorkflow("data-pipeline");
 const run = await workflow.createRun();
 
@@ -775,7 +773,7 @@ This ensures tracing never crashes your application, even with malformed input.
 
 Here's a complete example showing trace propagation in an Express application:
 
-```ts showLineNumbers copy
+```ts
 import { trace } from "@opentelemetry/api";
 import express from "express";
 

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

@@ -11,7 +11,7 @@ The Sensitive Data Filter is a span processor that automatically redacts sensiti
 
 By default, the Sensitive Data Filter is automatically enabled when you use the standard Mastra configuration:
 
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 export const mastra = new Mastra({
   observability: new Observability({
     default: { enabled: true }, // Automatically includes SensitiveDataFilter
@@ -63,7 +63,7 @@ When a sensitive field is detected, its value is replaced with `[REDACTED]` by d
 
 You can customize which fields are redacted and how redaction appears:
 
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 import { SensitiveDataFilter, DefaultExporter, Observability } from "@mastra/observability";
 
 export const mastra = new Mastra({
@@ -210,7 +210,7 @@ The Sensitive Data Filter is designed to be lightweight and efficient:
 
 If you need to disable sensitive data filtering (not recommended for production):
 
-```ts title="src/mastra/index.ts" showLineNumbers copy
+```ts title="src/mastra/index.ts"
 export const mastra = new Mastra({
   observability: new Observability({
     configs: {

package/.docs/raw/rag/chunking-and-embedding.mdx

@@ -7,7 +7,7 @@ description: Guide on chunking and embedding documents in Mastra for efficient p
 
 Before processing, create a MDocument instance from your content. You can initialize it from various formats:
 
-```ts showLineNumbers copy
+```ts
 const docFromText = MDocument.fromText("Your plain text content...");
 const docFromHTML = MDocument.fromHTML("<html>Your HTML content...</html>");
 const docFromMarkdown = MDocument.fromMarkdown("# Your Markdown content...");
@@ -28,11 +28,13 @@ Use `chunk` to split documents into manageable pieces. Mastra supports multiple
 - `latex`: LaTeX structure-aware splitting
 - `sentence`: Sentence-aware splitting
 
-**Note:** Each strategy accepts different parameters optimized for its chunking approach.
+:::note
+Each strategy accepts different parameters optimized for its chunking approach.
+:::
 
 Here's an example of how to use the `recursive` strategy:
 
-```ts showLineNumbers copy
+```ts
 const chunks = await doc.chunk({
   strategy: "recursive",
   maxSize: 512,
@@ -46,7 +48,7 @@ const chunks = await doc.chunk({
 
 For text where preserving sentence structure is important, here's an example of how to use the `sentence` strategy:
 
-```ts showLineNumbers copy
+```ts
 const chunks = await doc.chunk({
   strategy: "sentence",
   maxSize: 450,
@@ -59,7 +61,7 @@ const chunks = await doc.chunk({
 
 For markdown documents where preserving the semantic relationships between sections is important, here's an example of how to use the `semantic-markdown` strategy:
 
-```ts showLineNumbers copy
+```ts
 const chunks = await doc.chunk({
   strategy: "semantic-markdown",
   joinThreshold: 500,
@@ -67,19 +69,21 @@ const chunks = await doc.chunk({
 });
 ```
 
-**Note:** Metadata extraction may use LLM calls, so ensure your API key is set.
+:::note
+Metadata extraction may use LLM calls, so ensure your API key is set.
+:::
 
-We go deeper into chunking strategies in our [chunk documentation](/reference/v1/rag/chunk).
+We go deeper into chunking strategies in our [`chunk()` reference documentation](/reference/v1/rag/chunk).
 
 ## Step 2: Embedding Generation
 
-Transform chunks into embeddings using your preferred provider. Mastra supports embedding models through the model router or AI SDK packages.
+Transform chunks into embeddings using your preferred provider. Mastra supports embedding models through the model router.
 
-### Using the Model Router (Recommended)
+### Using the Model Router
 
 The simplest way is to use Mastra's model router with `provider/model` strings:
 
-```ts showLineNumbers copy
+```ts
 import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 import { embedMany } from "ai";
 
@@ -89,27 +93,10 @@ const { embeddings } = await embedMany({
 });
 ```
 
-Supported embedding models:
-
-- **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
-- **Google**: `gemini-embedding-001`, `text-embedding-004`
+Mastra supports OpenAI and Google embedding models. For a complete list of supported embedding models, see the [embeddings reference](/reference/v1/rag/embeddings).
 
 The model router automatically handles API key detection from environment variables.
 
-### Using AI SDK Packages
-
-You can also use AI SDK embedding models directly:
-
-```ts showLineNumbers copy
-import { embedMany } from "ai";
-import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
-
-const { embeddings } = await embedMany({
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-  values: chunks.map((chunk) => chunk.text),
-});
-```
-
 The embedding functions return vectors, arrays of numbers representing the semantic meaning of your text, ready for similarity searches in your vector database.
 
 ### Configuring Embedding Dimensions
@@ -147,15 +134,15 @@ const { embeddings } = await embedMany({
 });
 ```
 
-### Vector Database Compatibility
-
+:::important[Vector Database Compatibility]
 When storing embeddings, the vector database index must be configured to match the output size of your embedding model. If the dimensions do not match, you may get errors or data corruption.
+:::
 
 ## Example: Complete Pipeline
 
 Here's an example showing document processing and embedding generation with both providers:
 
-```ts showLineNumbers copy
+```ts
 import { embedMany } from "ai";
 
 import { MDocument } from "@mastra/rag";