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

package/.docs/raw/agents/overview.mdx

@@ -13,12 +13,12 @@ Agents use LLMs and tools to solve open-ended tasks. They reason about goals, de
 
 > **📹 Watch**:  → An introduction to agents, and how they compare to workflows [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
 
-## Getting started
+## Setting up agents
 
 <Tabs items={["Mastra model router", "Vercel AI SDK"]}>
   <Tabs.Tab>
     <Steps>
-### Install dependencies
+### Install dependencies [#install-dependencies-mastra-router]
 
 Add the Mastra core package to your project:
 
@@ -26,7 +26,7 @@ Add the Mastra core package to your project:
 npm install @mastra/core
 ```
 
-### Set your API key
+### Set your API key [#set-api-key-mastra-router]
 
 Mastra's model router auto-detects environment variables for your chosen provider. For OpenAI, set `OPENAI_API_KEY`:
 
@@ -36,7 +36,7 @@ OPENAI_API_KEY=<your-api-key>
 
 > Mastra supports more than 600 models. Choose from the full list [here](/models).
 
-### Create an agent
+### Creating an agent [#creating-an-agent-mastra-router]
 
 Create an agent by instantiating the `Agent` class with system `instructions` and a `model`:
 
@@ -53,7 +53,8 @@ export const testAgent = new Agent({
   </Tabs.Tab>
   <Tabs.Tab>
     <Steps>
-### Install dependencies
+
+### Install dependencies [#install-dependencies-ai-sdk]
 
 Include the Mastra core package alongside the Vercel AI SDK provider you want to use:
 
@@ -61,7 +62,7 @@ Include the Mastra core package alongside the Vercel AI SDK provider you want to
 npm install @mastra/core @ai-sdk/openai
 ```
 
-### Set your API key
+### Set your API key [#set-api-key-ai-sdk]
 
 Set the corresponding environment variable for your provider. For OpenAI via the AI SDK:
 
@@ -71,7 +72,7 @@ OPENAI_API_KEY=<your-api-key>
 
 > See the [AI SDK Providers](https://ai-sdk.dev/providers/ai-sdk-providers) in the Vercel AI SDK docs for additional configuration options.
 
-### Create an agent
+### Creating an agent [#creating-an-agent-ai-sdk]
 
 To create an agent in Mastra, use the `Agent` class. Every agent must include `instructions` to define its behavior, and a `model` parameter to specify the LLM provider and model. When using the Vercel AI SDK, provide the client to your agent's `model` field:
 
@@ -125,8 +126,8 @@ instructions: {
   content:
     "You are an expert code reviewer. Analyze code for bugs, performance issues, and best practices.",
   providerOptions: {
-    openai: { reasoning_effort: "high" },        // OpenAI's reasoning models
-    anthropic: { cache_control: { type: "ephemeral" } }  // Anthropic's prompt caching
+    openai: { reasoningEffort: "high" },        // OpenAI's reasoning models
+    anthropic: { cacheControl: { type: "ephemeral" } }  // Anthropic's prompt caching
   }
 }
 ```
@@ -137,7 +138,7 @@ instructions: {
 
 Register your agent in the Mastra instance to make it available throughout your application. Once registered, it can be called from workflows, tools, or other agents, and has access to shared resources such as memory, logging, and observability features:
 
-```typescript showLineNumbers filename="src/mastra/index.ts" copy
+```typescript {6} showLineNumbers filename="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core/mastra";
 import { testAgent } from './agents/test-agent';
 
@@ -156,7 +157,7 @@ const testAgent = mastra.getAgent("testAgent");
 ```
 <Callout type="info">
   <p>
-    `mastra.getAgent()` is preferred over a direct import, since it preserves the Mastra instance configuration (tools registered, telemetry, vector stores configuration for agent memory, etc.)
+    `mastra.getAgent()` is preferred over a direct import, since it provides access to the Mastra instance configuration (logger, telemetry, storage, registered agents, and vector stores).
   </p>
 </Callout>
 
@@ -412,42 +413,9 @@ export const testAgent = new Agent({
 
 > See [Runtime Context](../server-db/runtime-context.mdx) for more information.
 
-## Testing agents locally
-There are two ways to run and test agents.
-
-<Steps>
-
-### Mastra Playground
-
-With the Mastra Dev Server running you can test an agent from the Mastra Playground by visiting [http://localhost:4111/agents](http://localhost:4111/agents) in your browser.
-
-> For more information, see the [Local Dev Playground](/docs/server-db/local-dev-playground) documentation.
-
-### Command line
-
-Create an agent response using `.generate()` or `.stream()`.
-
-```typescript {7} filename="src/test-agent.ts" showLineNumbers copy
-import "dotenv/config";
-
-import { mastra } from "./mastra";
-
-const agent = mastra.getAgent("testAgent");
-
-const response = await agent.generate("Help me organize my day");
-
-console.log(response.text);
-```
-
-> See [.generate()](../../reference/agents/generate.mdx) or [.stream()](../../reference/agents/stream.mdx) for more information.
-
-To test this agent, run the following:
-
-```bash copy
-npx tsx src/test-agent.ts
-```
+## Testing with Mastra Playground
 
-</Steps>
+Use the Mastra [Playground](../server-db/local-dev-playground.mdx) to test agents with different messages, inspect tool calls and responses, and debug agent behavior.
 
 ## Related
 

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/rag/chunking-and-embedding.mdx

@@ -73,28 +73,40 @@ We go deeper into chunking strategies in our [chunk documentation](/reference/ra
 
 ## Step 2: Embedding Generation
 
-Transform chunks into embeddings using your preferred provider. Mastra supports many embedding providers, including OpenAI and Cohere:
+Transform chunks into embeddings using your preferred provider. Mastra supports embedding models through the model router or AI SDK packages.
 
-### Using OpenAI
+### Using the Model Router (Recommended)
+
+The simplest way is to use Mastra's model router with `provider/model` strings:
 
 ```ts showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
+import { ModelRouterEmbeddingModel } from "@mastra/core";
 import { embedMany } from "ai";
 
+const embeddingModel = new ModelRouterEmbeddingModel("openai/text-embedding-3-small");
+
 const { embeddings } = await embedMany({
-  model: openai.embedding("text-embedding-3-small"),
+  model: embeddingModel,
   values: chunks.map((chunk) => chunk.text),
 });
 ```
 
-### Using Cohere
+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.
+
+### Using AI SDK Packages
+
+You can also use AI SDK embedding models directly:
 
 ```ts showLineNumbers copy
-import { cohere } from "@ai-sdk/cohere";
+import { openai } from "@ai-sdk/openai";
 import { embedMany } from "ai";
 
 const { embeddings } = await embedMany({
-  model: cohere.embedding("embed-english-v3.0"),
+  model: openai.embedding("text-embedding-3-small"),
   values: chunks.map((chunk) => chunk.text),
 });
 ```