@mastra/mcp-docs-server 0.13.31 → 0.13.32-alpha.1

package/.docs/raw/frameworks/agentic-uis/ai-sdk.mdx

@@ -82,6 +82,30 @@ const { error, status, sendMessage, messages, regenerate, stop } =
     }),
   });
 ```
+
+Pass extra agent stream execution options:
+
+```typescript
+const { error, status, sendMessage, messages, regenerate, stop } =
+  useChat({
+    transport: new DefaultChatTransport({
+      api: 'http://localhost:4111/chat',
+      prepareSendMessagesRequest({ messages }) {
+        return {
+          body: {
+            messages,
+            // Pass memory config
+            memory: {
+              thread: "user-1",
+              resource: "user-1"
+            }
+          },
+        }
+      }
+    }),
+  });
+```
+
 ### `workflowRoute()`
 
 Use the `workflowRoute()` utility to create a route handler that automatically formats the workflow stream into an AI SDK-compatible format.
@@ -155,7 +179,7 @@ const { error, status, sendMessage, messages, regenerate, stop } =
 
 ### Custom UI
 
-The `@mastra/ai-sdk` package transforms and emits Mastra streams (e.g workflow, network streams) into AI SDK-compatible format.
+The `@mastra/ai-sdk` package transforms and emits Mastra streams (e.g workflow, network streams) into AI SDK-compatible [uiMessages DataParts](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message#datauipart) format.
 
 - **Top-level parts**: These are streamed via direct workflow and network stream transformations (e.g in `workflowRoute()` and `networkRoute()`)
   - `data-workflow`: Aggregates a workflow run with step inputs/outputs and final usage.
@@ -221,6 +245,38 @@ export const AgentTool = ({ id, text, status }: AgentDataPart) => {
   );
 };
 ```
+### Custom Tool streaming
+To stream custom data parts from within your tool execution function, use the
+`writer.custom()` method.
+
+```typescript {5,8,15} showLineNumbers copy
+import { createTool } from "@mastra/core/tools";
+
+export const testTool = createTool({
+  // ...
+  execute: async ({ context, writer }) => {
+    const { value } = context;
+
+   await writer?.custom({
+      type: "data-tool-progress",
+      status: "pending"
+    });
+
+    const response = await fetch(...);
+
+   await writer?.custom({
+      type: "data-tool-progress",
+      status: "success"
+    });
+
+    return {
+      value: ""
+    };
+  }
+});
+```
+
+For more information about tool streaming see [Tool streaming documentation](/docs/streaming/tool-streaming)
 
 ### Stream Transformations
 
@@ -252,6 +308,41 @@ export async function POST(req: Request) {
 }
 ```
 
+### Client Side Stream Transformations
+
+If you have a client-side `response` from `agent.stream(...)` and want AI SDK-formatted parts without custom SSE parsing, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and pipe it through `toAISdkFormat`:
+
+```typescript filename="client-stream-to-ai-sdk.ts" copy
+import { createUIMessageStream } from 'ai';
+import { toAISdkFormat } from '@mastra/ai-sdk';
+import type { ChunkType, MastraModelOutput } from '@mastra/core/stream';
+
+// Client SDK agent stream
+const response = await agent.stream({ messages: 'What is the weather in Tokyo' });
+
+const chunkStream: ReadableStream<ChunkType> = new ReadableStream<ChunkType>({
+  start(controller) {
+    response.processDataStream({
+      onChunk: async (chunk) => {
+        controller.enqueue(chunk as ChunkType);
+      },
+    }).finally(() => controller.close());
+  },
+});
+
+const uiMessageStream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    for await (const part of toAISdkFormat(chunkStream as unknown as MastraModelOutput, { from: 'agent' })) {
+      writer.write(part);
+    }
+  },
+});
+
+for await (const part of uiMessageStream) {
+  console.log(part);
+}
+```
+
 ## UI Hooks
 
 Mastra supports AI SDK UI hooks for connecting frontend components directly to agents using HTTP streams.

package/.docs/raw/getting-started/installation.mdx

@@ -15,8 +15,8 @@ For more control over setup, or to add Mastra to an existing project, see the [m
 
 ## Before you start
 
-- You'll need an API key from a [model provider](/models) to complete setup. We recommend starting with [Gemini](https://aistudio.google.com/app/api-keys), as you likely already have a Google account and they don't require a card.
-- Node.js 20 or later.
+- You'll need an API key from a [model provider](/models) to complete setup. We suggest starting with [OpenAI](https://platform.openai.com/api-keys), but if you need a provider that doesn't require a credit card, Google's [Gemini](https://aistudio.google.com/app/api-keys) is also an option.
+- [Install](https://nodejs.org/en/download) Node.js 20 or later.
 
 ## Install with `create mastra`
 
@@ -89,15 +89,15 @@ If you prefer not to use our automatic `create mastra` CLI tool, you can set up
 
 <Steps>
 
-### Create a new project
+### Create project
 
 Create a new project and change directory:
 
 ```bash copy
-mkdir hello-mastra && cd hello-mastra
+mkdir my-first-agent && cd my-first-agent
 ```
 
-Initialize a TypeScript project including the `@mastra/core` package:
+Initialize a TypeScript project and install the following dependencies:
 
 {/*
 LLM CONTEXT: This Tabs component shows manual installation commands for different package managers.
@@ -107,55 +107,42 @@ This helps users manually set up a Mastra project with their preferred package m
 */}
 
 <Tabs items={["npm", "pnpm", "yarn", "bun"]}>
-
   <Tab>
     ```bash copy
     npm init -y
-
-    npm install typescript tsx @types/node mastra@latest --save-dev
-
-    npm install @mastra/core@latest zod@^3 @ai-sdk/openai@^1
+    npm install -D typescript @types/node mastra@latest
+    npm install @mastra/core@latest zod@^4
     ```
-
   </Tab>
   <Tab>
     ```bash copy
-    pnpm init
-
-    pnpm add typescript tsx @types/node mastra@latest --save-dev
-
-    pnpm add @mastra/core@latest zod@^3 @ai-sdk/openai@^1
+    pnpm init -y
+    pnpm add -D typescript @types/node mastra@latest
+    pnpm add @mastra/core@latest zod@^4
     ```
-
   </Tab>
   <Tab>
     ```bash copy
     yarn init -y
-
-    yarn add typescript tsx @types/node mastra@latest --dev
-
-    yarn add @mastra/core@latest zod@^3 @ai-sdk/openai@^1
+    yarn add -D typescript @types/node mastra@latest
+    yarn add @mastra/core@latest zod@^4
     ```
-
   </Tab>
   <Tab>
     ```bash copy
     bun init -y
-
-    bun add typescript tsx @types/node mastra@latest --dev
-
-    bun add @mastra/core@latest zod@^3 @ai-sdk/openai@^1
+    bun add -d typescript @types/node mastra@latest
+    bun add @mastra/core@latest zod@^4
     ```
-
   </Tab>
 </Tabs>
 
-Add the `dev` and `build` scripts to `package.json`:
+Add `dev` and `build` scripts to your `package.json` file:
 
-```json filename="package.json" copy
+```json filename="package.json" copy /,/ /"dev": "mastra dev",/ /"build": "mastra build"/
 {
   "scripts": {
-    // ...
+    "test": "echo \"Error: no test specified\" && exit 1",
     "dev": "mastra dev",
     "build": "mastra build"
   }
@@ -172,9 +159,8 @@ touch tsconfig.json
 
 Add the following configuration:
 
-Mastra requires `module` and `moduleResolution` values that support modern Node.js versions. Older settings like `CommonJS` or `node` are incompatible with Mastra’s packages and will cause resolution errors.
 
-```json {4-5} filename="tsconfig.json" copy
+```json filename="tsconfig.json" copy
 {
   "compilerOptions": {
     "target": "ES2022",
@@ -192,12 +178,13 @@ Mastra requires `module` and `moduleResolution` values that support modern Node.
   ]
 }
 ```
+<Callout type="info">
+Mastra requires modern `module` and `moduleResolution` settings. Using `CommonJS` or `node` will cause resolution errors.
+</Callout>
 
-> This TypeScript configuration is optimized for Mastra projects, using modern module resolution and strict type checking.
-
-### Set up your API key
+### Set API key
 
-Create `.env` file:
+Create an `.env` file:
 
 ```bash copy
 touch .env
@@ -206,12 +193,14 @@ touch .env
 Add your API key:
 
 ```bash filename=".env" copy
-OPENAI_API_KEY=<your-api-key>
+GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>
 ```
 
-> This example uses OpenAI. Each LLM provider uses a unique name. See [Model Capabilities](/docs/getting-started/model-capability) for more information.
+<Callout type="default">
+This guide uses Google Gemini, but you can use any supported [model provider](/models), including OpenAI, Anthropic, and more.
+</Callout>
 
-### Create a Tool
+### Add tool
 
 Create a `weather-tool.ts` file:
 
@@ -242,9 +231,11 @@ export const weatherTool = createTool({
 });
 ```
 
-> See the full weatherTool example in [Giving an Agent a Tool](/examples/agents/using-a-tool).
+<Callout type="info">
+We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](/examples/agents/using-a-tool).
+</Callout>
 
-### Create an Agent
+### Add agent
 
 Create a `weather-agent.ts` file:
 
@@ -255,7 +246,6 @@ mkdir -p src/mastra/agents && touch src/mastra/agents/weather-agent.ts
 Add the following code:
 
 ```ts filename="src/mastra/agents/weather-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 import { weatherTool } from "../tools/weather-tool";
 
@@ -266,21 +256,21 @@ export const weatherAgent = new Agent({
 
       Your primary function is to help users get weather details for specific locations. When responding:
       - Always ask for a location if none is provided
-      - If the location name isn’t in English, please translate it
+      - If the location name isn't in English, please translate it
       - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
       - Include relevant details like humidity, wind conditions, and precipitation
       - Keep responses concise but informative
 
       Use the weatherTool to fetch current weather data.
 `,
-  model: openai('gpt-4o-mini'),
+  model: "google/gemini-2.5-pro",
   tools: { weatherTool }
 });
 ```
 
-### Register the Agent
+### Register agent
 
-Create the Mastra entry point and register agent:
+Create the Mastra entry point and register your agent:
 
 ```bash copy
 touch src/mastra/index.ts
@@ -296,28 +286,31 @@ export const mastra = new Mastra({
   agents: { weatherAgent }
 });
 ```
+### Test your agent
+You can now launch the [Playground](/docs/server-db/local-dev-playground) and test your agent.
 
-You can now launch the [Mastra Development Server](/docs/server-db/local-dev-playground) and test your agent using the Mastra Playground.
-
-</Steps>
-
-## Add to an existing project
-
-Mastra can be installed and integrated into a wide range of projects. Below are links to integration guides to help you get started:
-
-- [Next.js](/docs/frameworks/web-frameworks/next-js)
-- [Vite + React](/docs/frameworks/web-frameworks/vite-react)
-- [Astro](/docs/frameworks/web-frameworks/astro)
-- [Express](/docs/frameworks/servers/express)
-
-
-### `mastra init`
-
-To install Mastra in an existing project, use the `mastra init` command.
-
-> See [mastra init](/reference/cli/init) for more information.
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab>
+    ```bash copy
+    npm run dev
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    pnpm run dev
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    yarn run dev
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    bun run dev
+    ```
+  </Tab>
+</Tabs>
 
-### Next steps
 
-- [Local Development](/docs/server-db/local-dev-playground)
-- [Deploy to Mastra Cloud](/docs/deployment/overview)
+</Steps>

package/.docs/raw/memory/conversation-history.mdx

@@ -16,8 +16,8 @@ export const testAgent = new Agent({
   // ...
   memory: new Memory({
     options: {
-      lastMessages: 100
+      lastMessages: 20
     },
   })
 });
-```
+```

package/.docs/raw/memory/semantic-recall.mdx

@@ -98,40 +98,66 @@ const agent = new Agent({
 
 ### Embedder configuration
 
-Semantic recall relies on an [embedding model](/reference/memory/Memory#embedder) to convert messages into embeddings. You can specify any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.
+Semantic recall relies on an [embedding model](/reference/memory/Memory#embedder) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.
 
-To use FastEmbed (a local embedding model), install `@mastra/fastembed`:
+#### Using the Model Router (Recommended)
 
-```bash npm2yarn copy
-npm install @mastra/fastembed
+The simplest way is to use a `provider/model` string with autocomplete support:
+
+```ts {7}
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  memory: new Memory({
+    // ... other memory options
+    embedder: "openai/text-embedding-3-small", // TypeScript autocomplete supported
+  }),
+});
 ```
 
-Then configure it in your memory:
+Supported embedding models:
+- **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
+- **Google**: `gemini-embedding-001`, `text-embedding-004`
+
+The model router automatically handles API key detection from environment variables (`OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`).
+
+#### Using AI SDK Packages
+
+You can also use AI SDK embedding models directly:
 
 ```ts {3,8}
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { fastembed } from "@mastra/fastembed";
+import { openai } from "@ai-sdk/openai";
 
 const agent = new Agent({
   memory: new Memory({
     // ... other memory options
-    embedder: fastembed,
+    embedder: openai.embedding("text-embedding-3-small"),
   }),
 });
 ```
 
-Alternatively, use a different provider like OpenAI:
+#### Using FastEmbed (Local)
+
+To use FastEmbed (a local embedding model), install `@mastra/fastembed`:
+
+```bash npm2yarn copy
+npm install @mastra/fastembed
+```
+
+Then configure it in your memory:
 
 ```ts {3,8}
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
+import { fastembed } from "@mastra/fastembed";
 
 const agent = new Agent({
   memory: new Memory({
     // ... other memory options
-    embedder: openai.embedding("text-embedding-3-small"),
+    embedder: fastembed,
   }),
 });
 ```

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

@@ -367,6 +367,123 @@ execute: async ({ inputData, tracingContext }) => {
 
 Metadata set here will be shown in all configured exporters.
 
+### Automatic Metadata from RuntimeContext
+
+Instead of manually adding metadata to each span, you can configure Mastra to automatically extract values from RuntimeContext and attach them as metadata to all spans in a trace. This is useful for consistently tracking user identifiers, environment information, feature flags, or any request-scoped data across your entire trace.
+
+#### Configuration-Level Extraction
+
+Define which RuntimeContext keys to extract in your tracing configuration. These keys will be automatically included as metadata for all spans created with this configuration:
+
+```ts filename="src/mastra/index.ts" showLineNumbers copy
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      default: {
+        serviceName: 'my-service',
+        runtimeContextKeys: ['userId', 'environment', 'tenantId'],
+        exporters: [new DefaultExporter()],
+      },
+    },
+  },
+});
+```
+
+Now when you execute agents or workflows with a RuntimeContext, these values are automatically extracted:
+
+```ts showLineNumbers copy
+const runtimeContext = new RuntimeContext();
+runtimeContext.set('userId', 'user-123');
+runtimeContext.set('environment', 'production');
+runtimeContext.set('tenantId', 'tenant-456');
+
+// All spans in this trace automatically get userId, environment, and tenantId metadata
+const result = await agent.generate({
+  messages: [{ role: 'user', content: 'Hello' }],
+  runtimeContext,
+});
+```
+
+#### Per-Request Additions
+
+You can add trace-specific keys using `tracingOptions.runtimeContextKeys`. These are merged with the configuration-level keys:
+
+```ts showLineNumbers copy
+const runtimeContext = new RuntimeContext();
+runtimeContext.set('userId', 'user-123');
+runtimeContext.set('environment', 'production');
+runtimeContext.set('experimentId', 'exp-789');
+
+const result = await agent.generate({
+  messages: [{ role: 'user', content: 'Hello' }],
+  runtimeContext,
+  tracingOptions: {
+    runtimeContextKeys: ['experimentId'], // Adds to configured keys
+  },
+});
+
+// All spans now have: userId, environment, AND experimentId
+```
+
+#### Nested Value Extraction
+
+Use dot notation to extract nested values from RuntimeContext:
+
+```ts showLineNumbers copy
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      default: {
+        runtimeContextKeys: ['user.id', 'session.data.experimentId'],
+        exporters: [new DefaultExporter()],
+      },
+    },
+  },
+});
+
+const runtimeContext = new RuntimeContext();
+runtimeContext.set('user', { id: 'user-456', name: 'John Doe' });
+runtimeContext.set('session', { data: { experimentId: 'exp-999' } });
+
+// Metadata will include: { user: { id: 'user-456' }, session: { data: { experimentId: 'exp-999' } } }
+```
+
+#### How It Works
+
+1. **TraceState Computation**: At the start of a trace (root span creation), Mastra computes which keys to extract by merging configuration-level and per-request keys
+2. **Automatic Extraction**: Root spans (agent runs, workflow executions) automatically extract metadata from RuntimeContext
+3. **Child Span Extraction**: Child spans can also extract metadata if you pass `runtimeContext` when creating them
+4. **Metadata Precedence**: Explicit metadata passed to span options always takes precedence over extracted metadata
+
+#### Child Spans and Metadata Extraction
+
+When creating child spans within tools or workflow steps, you can pass the `runtimeContext` parameter to enable metadata extraction:
+
+```ts showLineNumbers copy
+execute: async ({ tracingContext, runtimeContext }) => {
+  // Create child span WITH runtimeContext - gets metadata extraction
+  const dbSpan = tracingContext.currentSpan?.createChildSpan({
+    type: 'generic',
+    name: 'database-query',
+    runtimeContext,  // Pass to enable metadata extraction
+  });
+
+  const results = await db.query('SELECT * FROM users');
+  dbSpan?.end({ output: results });
+
+  // Or create child span WITHOUT runtimeContext - no metadata extraction
+  const cacheSpan = tracingContext.currentSpan?.createChildSpan({
+    type: 'generic',
+    name: 'cache-check',
+    // No runtimeContext - won't extract metadata
+  });
+
+  return results;
+}
+```
+
+This gives you fine-grained control over which child spans include RuntimeContext metadata. Root spans (agent/workflow executions) always extract metadata automatically, while child spans only extract when you explicitly pass `runtimeContext`.
+
 ## Creating Child Spans
 
 Child spans allow you to track fine-grained operations within your workflow steps or tools. They provide visibility into sub-operations like database queries, API calls, file operations, or complex calculations. This hierarchical structure helps you identify performance bottlenecks and understand the exact sequence of operations.
@@ -517,6 +634,109 @@ Once you have a trace ID, you can:
 
 The trace ID is only available when tracing is enabled. If tracing is disabled or sampling excludes the request, `traceId` will be `undefined`.
 
+## Integrating with External Tracing Systems
+
+When running Mastra agents or workflows within applications that have existing distributed tracing (OpenTelemetry, Datadog, etc.), you can connect Mastra traces to your parent trace context. This creates a unified view of your entire request flow, making it easier to understand how Mastra operations fit into the broader system.
+
+### Passing External Trace IDs
+
+Use the `tracingOptions` parameter to specify the trace context from your parent system:
+
+```ts showLineNumbers copy
+// Get trace context from your existing tracing system
+const parentTraceId = getCurrentTraceId(); // Your tracing system
+const parentSpanId = getCurrentSpanId();   // Your tracing system
+
+// Execute Mastra operations as part of the parent trace
+const result = await agent.generate('Analyze this data', {
+  tracingOptions: {
+    traceId: parentTraceId,
+    parentSpanId: parentSpanId,
+  }
+});
+
+// The Mastra trace will now appear as a child in your distributed trace
+```
+
+### OpenTelemetry Integration
+
+Integration with OpenTelemetry allows Mastra traces to appear seamlessly in your existing observability platform:
+
+```ts showLineNumbers copy
+import { trace } from '@opentelemetry/api';
+
+// Get the current OpenTelemetry span
+const currentSpan = trace.getActiveSpan();
+const spanContext = currentSpan?.spanContext();
+
+if (spanContext) {
+  const result = await agent.generate(userMessage, {
+    tracingOptions: {
+      traceId: spanContext.traceId,
+      parentSpanId: spanContext.spanId,
+    }
+  });
+}
+```
+
+### Workflow Integration
+
+Workflows support the same pattern for trace propagation:
+
+```ts showLineNumbers copy
+const workflow = mastra.getWorkflow('data-pipeline');
+const run = await workflow.createRunAsync();
+
+const result = await run.start({
+  inputData: { data: '...' },
+  tracingOptions: {
+    traceId: externalTraceId,
+    parentSpanId: externalSpanId,
+  }
+});
+```
+
+### ID Format Requirements
+
+Mastra validates trace and span IDs to ensure compatibility:
+
+- **Trace IDs**: 1-32 hexadecimal characters (OpenTelemetry uses 32)
+- **Span IDs**: 1-16 hexadecimal characters (OpenTelemetry uses 16)
+
+Invalid IDs are handled gracefully — Mastra logs an error and continues:
+- Invalid trace ID → generates a new trace ID
+- Invalid parent span ID → ignores the parent relationship
+
+This ensures tracing never crashes your application, even with malformed input.
+
+### Example: Express Middleware
+
+Here's a complete example showing trace propagation in an Express application:
+
+```ts showLineNumbers copy
+import { trace } from '@opentelemetry/api';
+import express from 'express';
+
+const app = express();
+
+app.post('/api/analyze', async (req, res) => {
+  // Get current OpenTelemetry context
+  const currentSpan = trace.getActiveSpan();
+  const spanContext = currentSpan?.spanContext();
+
+  const result = await agent.generate(req.body.message, {
+    tracingOptions: spanContext ? {
+      traceId: spanContext.traceId,
+      parentSpanId: spanContext.spanId,
+    } : undefined,
+  });
+
+  res.json(result);
+});
+```
+
+This creates a single distributed trace that includes both the HTTP request handling and the Mastra agent execution, viewable in your observability platform of choice.
+
 ## What Gets Traced
 
 Mastra automatically creates spans for: