@mastra/mcp-docs-server 1.2.1-alpha.2 → 1.2.1-alpha.5

package/.docs/docs/evals/datasets/running-experiments.md

@@ -127,6 +127,82 @@ for (const item of summary.results) {
 
 > **Info:** Visit the [Scorers overview](https://mastra.ai/docs/evals/overview) for details on available and custom scorers.
 
+## Tool mocks
+
+When an experiment runs an agent that calls side-effecting tools, you can make the run deterministic by attaching static tool mocks to individual dataset items. During the experiment, a mocked tool returns its declared output instead of executing. Tools that have no mock on the item run live.
+
+Mocks live on the dataset item, so they version with the row and travel with the test case. Each mock declares a tool name, the arguments it expects, and the output to return:
+
+```typescript
+await dataset.addItem({
+  input: 'What is the weather in Seattle?',
+  toolMocks: [
+    {
+      toolName: 'getWeather',
+      args: { city: 'Seattle' },
+      output: { temperature: 60, conditions: 'rainy' },
+    },
+  ],
+})
+```
+
+Tool mocks are supported for `agent` targets only.
+
+### Matching and consumption
+
+Arguments are matched strictly: object key order is ignored, array order is significant, and there is no type coercion. A mock is served only when the agent calls the tool with arguments that deep-equal the mock's `args`.
+
+When an item declares several mocks for the same tool and arguments, they are consumed in order — the first call gets the first mock, the next call gets the second, and so on. Ordering is tracked per `(toolName, args)` group and is independent across different arguments.
+
+### Matching mode
+
+By default each mock matches strictly on its `args`. Set `matchArgs: 'ignore'` to match on the tool name only — the mock's `args` are not compared and the next unconsumed mock for that tool is served regardless of how the agent called it:
+
+```typescript
+const subAgentMock = {
+  toolName: 'agent-balanceAgent',
+  args: { prompt: 'look up the balance for YJ' },
+  output: { text: "YJ's balance is $100." },
+  matchArgs: 'ignore',
+}
+```
+
+This is useful when a tool's arguments are noisy or generated by the model. The most common case is mocking a **sub-agent's response**: a delegated sub-agent is exposed to the parent as a tool named `agent-<name>`, and its arguments include an LLM-authored `prompt` plus runtime-injected fields. Mocking `agent-<name>` returns the canned response in place of running the sub-agent and its inner tools. When you create a mock from a trace, sub-agent delegation calls are derived with `matchArgs: 'ignore'` automatically; you can change it to `'strict'` to pin the exact arguments.
+
+### Failures
+
+A mocked tool call fails the item when the arguments do not match or all matching mocks have been consumed:
+
+- `TOOL_MOCK_MISMATCH` — the tool was called with arguments that no mock matches.
+- `TOOL_MOCK_EXHAUSTED` — every matching mock has already been consumed.
+
+When a mocked tool is mis-called, the agent run is aborted immediately, so the model cannot go on to call any further tools — including unmocked, side-effecting tools that would otherwise run live. These failures are deterministic, so they are not retried. Mocks that are declared but never used do not fail the item — they are reported as unconsumed.
+
+While an item has mocks, the agent's tools execute sequentially so repeated `(toolName, args)` mocks are consumed in the provider's call order. This serialization applies only to items that declare mocks.
+
+### Diagnostics
+
+Each item result carries a `toolMockReport` describing what the run did with the item's mocks:
+
+```typescript
+for (const item of summary.results) {
+  const report = item.toolMockReport
+  if (!report) continue
+
+  console.log(report.served) // mocks matched and returned
+  console.log(report.unconsumed) // mocks declared but never used
+  console.log(report.liveCalls) // unmocked tools that ran live
+  console.log(report.failure) // the mismatch/exhausted failure, if any
+}
+```
+
+In [Studio](https://mastra.ai/docs/studio/overview), edit a dataset item to author tool mocks as a JSON array, and open an experiment result to see the same report.
+
+### Limitations
+
+- **No tool span for mocked calls.** A mocked call returns its output before the tool executes, so it does not create a tool span. Trajectory scorers backed by stored traces may therefore not see mocked tool calls. Trajectory extraction that falls back to the agent's message output still sees them, so trajectory scoring can differ depending on your observability configuration.
+- **Storage support.** Tool mocks and tool mock reports are persisted by the LibSQL, PostgreSQL, MongoDB, and Spanner adapters. The MySQL adapter does not support them and rejects writes that carry tool mocks or a tool mock report so the feature never silently runs tools live.
+
 ## Async experiments
 
 `startExperiment()` blocks until every item completes. For long-running datasets, use [`startExperimentAsync()`](https://mastra.ai/reference/datasets/startExperimentAsync) to start the experiment in the background:

package/.docs/docs/getting-started/build-with-ai.md

@@ -2,9 +2,13 @@
 
 AI agents may not have up-to-date knowledge about Mastra's APIs, patterns, and best practices. These resources give your AI tools direct access to current Mastra documentation, enabling them to generate accurate code and help you build faster.
 
+To give your agent access to Mastra's documentation, we recommend using **skills**. While the MCP docs server also provides this information, skills will perform better. Use the MCP docs server when you need its tools, e.g. the migration tool.
+
 ## Mastra skills
 
-Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. [Mastra Skills](https://mastra.ai/docs/build-with-ai/skills) contain setup instructions, best practices, and instructions on how to fetch up-to-date information from Mastra's documentation.
+Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. Mastra skills contain setup instructions, best practices, CLI commands, and instructions on how to fetch up-to-date information from Mastra's documentation.
+
+To install all available Mastra skills, run the following command:
 
 **npm**:
 
@@ -30,15 +34,37 @@ yarn dlx skills add mastra-ai/skills
 bun x skills add mastra-ai/skills
 ```
 
-Read the dedicated [Mastra Skills](https://mastra.ai/docs/build-with-ai/skills) guide to learn more about installation options and available skills.
+Mastra skills work with any coding agent that supports the [Skills standard](https://agentskills.io/), including Claude Code, Cursor, Codex, OpenCode, and others.
 
-> **Tip:** If you're interested in giving your agent access to Mastra's documentation, we recommend using **Skills**. While the MCP Docs Server also provides this information, Skills will perform better. Use the MCP Docs Server when you need its tools, e.g. the migration tool.
+They're also available on [GitHub](https://github.com/mastra-ai/skills).
 
-## MCP docs server
+### Update skill
+
+To update to the latest version of the Mastra skill, run:
+
+**npm**:
+
+```bash
+npx skills update mastra
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx skills update mastra
+```
 
-In addition to documentation access, the [MCP Docs Server](https://mastra.ai/docs/build-with-ai/mcp-docs-server) also provides tools to help you migrate to newer versions of Mastra or follow the [Mastra 101 course](https://mastra.ai/course).
+**Yarn**:
+
+```bash
+yarn dlx skills update mastra
+```
 
-Learn how to use the [MCP Docs Server](https://mastra.ai/docs/build-with-ai/mcp-docs-server).
+**Bun**:
+
+```bash
+bun x skills update mastra
+```
 
 ## Mastra CLI
 
@@ -75,7 +101,7 @@ mastra api --url http://localhost:4111 agent run weather-agent '{"messages":"Wha
 mastra api --url http://localhost:4111 trace list
 ```
 
-See the [CLI commands reference](https://mastra.ai/reference/cli/mastra) for the full list of available commands.
+Install the [Mastra skills](#mastra-skills) to teach your agent how to use the CLI. See the [CLI commands reference](https://mastra.ai/reference/cli/mastra) for the full list of available commands.
 
 ## Embedded package docs
 
@@ -102,4 +128,243 @@ Examples for the [introduction page](https://mastra.ai/docs):
 
 ## Mastra's documentation
 
-In addition to the [context files](#context-files) each documentation page also features a "Copy markdown" button at the top of the page. It'll copy the streamlined markdown version to your clipboard. Beside it, you'll find a dropdown menu to open the page on GitHub, in ChatGPT, Claude, and others.
+In addition to the [context files](#context-files) each documentation page also features a "Copy markdown" button at the top of the page. It'll copy the streamlined markdown version to your clipboard. Beside it, you'll find a dropdown menu to open the page on GitHub, in ChatGPT, Claude, and others.
+
+## MCP docs server
+
+The `@mastra/mcp-docs-server` package provides direct access to Mastra’s full documentation via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It works with Cursor, Windsurf, Cline, Claude Code, VS Code, Codex or any tool that supports MCP.
+
+These tools are designed to help agents retrieve precise, task-specific information — whether you're adding a feature to an agent, scaffolding a new project, or exploring how something works.
+
+In this guide you'll learn how to add Mastra's MCP server to your AI tooling.
+
+[YouTube video player](https://www.youtube-nocookie.com/embed/vciV57lF0og)
+
+### Installation
+
+#### create-mastra
+
+During the interactive [create-mastra](https://mastra.ai/reference/cli/create-mastra) wizard, choose one of your tools in the MCP step.
+
+#### Manual setup
+
+If there are no specific instructions for your tool below, you may be able to add the MCP server with this common JSON configuration anyways.
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+#### Claude Code CLI
+
+Install using the terminal command:
+
+```bash
+claude mcp add --scope project mastra -- npx -y @mastra/mcp-docs-server@latest
+```
+
+This creates a project-scoped `.mcp.json` file if one doesn't already exist. You can use the same command when using Claude Code as a [Visual Studio Code extension](https://code.claude.com/docs/en/vs-code#connect-to-external-tools-with-mcp).
+
+[More info on using MCP servers with Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)
+
+#### OpenAI Codex CLI
+
+1. Register it from the terminal:
+
+   ```bash
+   codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@latest
+   ```
+
+2. Run `codex mcp list` to confirm the server shows as `enabled`.
+
+[More info on using MCP servers with OpenAI Codex](https://developers.openai.com/codex/mcp)
+
+#### Cursor
+
+Install by selecting the button below:
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=mastra\&config=eyJjb21tYW5kIjoibnB4IC15IEBtYXN0cmEvbWNwLWRvY3Mtc2VydmVyIn0%3D)
+
+If you followed the automatic installation, you'll see a popup when you open cursor in the bottom left corner to prompt you to enable the Mastra Docs MCP Server.
+
+![Popup inside Cursor showing: \"New MCP server detected: mastra\". The user can \"Skip\" or \"Enable\" it as an action.](/assets/images/enable-mastra-docs-cursor-cd5872abdc36c0e10951a59a47f25e12.png)
+
+[More info on using MCP servers with Cursor](https://cursor.com/de/docs/context/mcp)
+
+#### Antigravity
+
+Google Antigravity is an agent-first development platform that supports MCP servers for accessing external documentation, APIs, and project context.
+
+1. Open your Antigravity MCP configuration file:
+
+   - Click on **Agent session** and select the **“…” dropdown** at the top of the editor’s side panel, then select **MCP Servers** to access the **MCP Store**.
+   - You can access it through the MCP Store interface in Antigravity
+
+   ![The Antigravity MCP store. At the top is a search bar and below a list of available MCP servers. On the very top right is a dropdown menu.](/assets/images/antigravity_mcp_server-689ea495d9c7139cc431f1f1b9827f9b.png)
+
+2. To add a custom MCP server, select **Manage MCP Servers** at the top of the MCP Store and select **View raw config** in the main tab.
+
+   ![The Antigravity MCP store showing the Manage MCP Servers option and the View raw config button.](/assets/images/antigravity_managed_mcp-b661e8c04b3219000f8d842e5eb26a1a.png)
+
+3. Add the Mastra MCP server configuration:
+
+   ```json
+   {
+     "mcpServers": {
+       "mastra-docs": {
+         "command": "npx",
+         "args": ["-y", "@mastra/mcp-docs-server"]
+       }
+     }
+   }
+   ```
+
+4. Save the configuration and restart Antigravity
+
+   ![The UI shows that the MCP server is enabled. You can also toggle individual tools.](/assets/images/antigravity_final_interface_mcp-7fa132dbe76cdee9f61136a26d6e6615.png)
+
+Once configured, the Mastra MCP server exposes the following to Antigravity agents:
+
+- Indexed documentation and API schemas for Mastra, enabling programmatic retrieval of relevant context during code generation
+- Access to example code snippets and usage patterns stored in Mastra Docs
+- Structured data for error handling and debugging references in the editor
+- Metadata about current Mastra project patterns for code suggestion and completion
+
+The MCP server will appear in Antigravity's MCP Store, where you can manage its connection status and authentication if needed.
+
+[More info on using MCP servers with Antigravity](https://antigravity.google)
+
+#### Visual Studio Code
+
+1. Create a `.vscode/mcp.json` file in your workspace
+
+2. Insert the following configuration:
+
+   ```json
+   {
+     "servers": {
+       "mastra": {
+         "type": "stdio",
+         "command": "npx",
+         "args": ["-y", "@mastra/mcp-docs-server@latest"]
+       }
+     }
+   }
+   ```
+
+Once you installed the MCP server, you can use it like so:
+
+1. Open VSCode settings.
+
+2. Navigate to MCP settings.
+
+3. Click "enable" on the Chat > MCP option.
+
+   ![Entry in VSCode\'s settings page. The option is called \"Chat \> MCP: Enabled (Preview)\". The description says: \"Enables integration with Model Context Protocol servers to provide additional tools and functionality.\"](/assets/images/vscode-mcp-setting-8d1eb4f3df1e33606503f8c5e937e9e3.png)
+
+MCP only works in Agent mode in VSCode. Once you are in agent mode, open the `mcp.json` file and select the "start" button. Note that the "start" button will only appear if the `.vscode` folder containing `mcp.json` is in your workspace root, or the highest level of the in-editor file explorer.
+
+![A screenshot of the mcp.json file showing the start button in the editor](/assets/images/vscode-start-mcp-26480d86080c4907cb497a325de106a4.png)
+
+After starting the MCP server, select the tools button in the Copilot pane to see available tools.
+
+![Tools page of VSCode to see available tools](/assets/images/vscode-mcp-running-d92d6ed234d1148093dc804b0ead3515.png)
+
+[More info on using MCP servers with Visual Studio Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
+
+#### Windsurf
+
+1. Open `~/.codeium/windsurf/mcp_config.json` in your editor
+
+2. Insert the following configuration:
+
+   ```json
+   {
+     "mcpServers": {
+       "mastra": {
+         "command": "npx",
+         "args": ["-y", "@mastra/mcp-docs-server@latest"]
+       }
+     }
+   }
+   ```
+
+3. Save the configuration and restart Windsurf
+
+[More info on using MCP servers with Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json)
+
+#### OpenCode
+
+You can define MCP servers in your [OpenCode configuration](https://opencode.ai/docs/config/) under `mcp`. Create an `opencode.jsonc` file in your project root with the following content:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "mastra": {
+      "type": "local",
+      "command": ["npx", "-y", "@mastra/mcp-docs-server@latest"],
+      "enabled": true
+    }
+  }
+}
+```
+
+[More info on using MCP servers with OpenCode](https://opencode.ai/docs/mcp-servers)
+
+#### Zed
+
+1. Open `~/.config/zed/settings.json` in your editor
+2. Insert the following configuration:
+
+```json
+{
+  "context_servers": {
+    "Mastra": {
+      "command": "npx",
+      "args": ["-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+### Usage
+
+Once configured, you can ask your AI tool questions about Mastra or instruct it to take actions. For these steps, it'll take the up-to-date information from Mastra's MCP server.
+
+**Add features:**
+
+- "Add evals to my agent and write tests"
+- "Write me a workflow that does the following `[task]`"
+- "Make a new tool that allows my agent to access `[3rd party API]`"
+
+**Ask about integrations:**
+
+- "Does Mastra work with the AI SDK? How can I use it in my `[React/Svelte/etc]` project?"
+- "Does Mastra support `[provider]` speech and voice APIs? Show me an example in my code of how I can use it."
+
+**Debug or update existing code:**
+
+- "I'm running into a bug with agent memory, have there been any related changes or bug fixes recently?"
+- "How does working memory behave in Mastra and how can I use it to do `[task]`? It doesn't seem to work the way I expect."
+- "I saw there are new workflow features, explain them to me and then update `[workflow]` to use them."
+
+#### Troubleshooting
+
+1. **Server Not Starting**
+
+   - Ensure [npx](https://docs.npmjs.com/cli/v11/commands/npx) is installed and working.
+   - Check for conflicting MCP servers.
+   - Verify your configuration file syntax.
+
+2. **Tool Calls Failing**
+
+   - Restart the MCP server and/or your IDE.
+   - Update to the latest version of your IDE.

package/.docs/docs/server/pubsub.md

@@ -10,7 +10,7 @@ Several built-in systems publish and subscribe to events through the same pub/su
 
 - **Workflow execution**: The scheduler publishes a `workflow.start` event, and a long-lived worker consumes it to run the workflow. Step and lifecycle events flow over pub/sub during execution.
 - **Scheduled workflows**: The scheduler dispatches due runs by publishing to the workflow topic. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).
-- **Background tasks**: A task manager dispatches work to a worker group and fans task lifecycle updates out to subscribers, which is how background task streams stay live. See [Background task streaming](https://mastra.ai/docs/streaming/background-task-streaming).
+- **Background tasks**: A task manager dispatches work to a worker group and fans task lifecycle updates out to subscribers, which is how background task streams stay live. See [Background task streaming](https://mastra.ai/docs/agents/background-tasks).
 - **Agent signals**: Sending a signal to an active agent run publishes an event on a thread topic, so a run executing in another process receives the signal.
 - **Resumable streams**: Stream chunks are published per run, so a client that reconnects can replay what it missed.
 
@@ -120,5 +120,5 @@ export const mastra = new Mastra({
 
 - [PubSub reference](https://mastra.ai/reference/pubsub/base)
 - [Mastra class](https://mastra.ai/reference/core/mastra-class)
-- [Background task streaming](https://mastra.ai/docs/streaming/background-task-streaming)
+- [Background task streaming](https://mastra.ai/docs/agents/background-tasks)
 - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows)

package/.docs/docs/workflows/overview.md

@@ -405,6 +405,77 @@ Here's an example of a successful workflow result, showing the `input`, `steps`,
 }
 ```
 
+## Streaming
+
+For generic `writer` API usage, see [Streaming](https://mastra.ai/guides/concepts/streaming).
+
+### Inspecting workflow stream payloads
+
+Events written to the stream are included in the emitted chunks. These chunks can be inspected to access any custom fields, such as event types, intermediate values, or step-specific data.
+
+```typescript
+const testWorkflow = mastra.getWorkflow('testWorkflow')
+
+const run = await testWorkflow.createRun()
+
+const stream = await run.stream({
+  inputData: {
+    value: 'initial data',
+  },
+})
+
+for await (const chunk of stream) {
+  console.log(chunk)
+}
+
+if (result!.status === 'suspended') {
+  // if the workflow is suspended, we can resume it with the resumeStream method
+  const resumedStream = await run.resumeStream({
+    resumeData: { value: 'resume data' },
+  })
+
+  for await (const chunk of resumedStream) {
+    console.log(chunk)
+  }
+}
+```
+
+### Resuming an interrupted workflow stream
+
+If a workflow stream is closed or interrupted for any reason, you can resume it with the `resumeStream` method. This will return a new `ReadableStream` that you can use to observe the workflow events.
+
+```typescript
+const newStream = await run.resumeStream()
+
+for await (const chunk of newStream) {
+  console.log(chunk)
+}
+```
+
+### Workflow using an agent
+
+Pipe an agent's `textStream` to the workflow step's `writer`. This streams partial output, and Mastra automatically aggregates the agent's usage into the workflow run.
+
+```typescript
+import { createStep } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+export const testStep = createStep({
+  execute: async ({ inputData, mastra, writer }) => {
+    const { city } = inputData
+
+    const testAgent = mastra?.getAgent('testAgent')
+    const stream = await testAgent?.stream(`What is the weather in ${city}?`)
+
+    await stream!.textStream.pipeTo(writer!)
+
+    return {
+      value: await stream!.text,
+    }
+  },
+})
+```
+
 ## Restarting active workflow runs
 
 When a workflow run loses connection to the server, it can be restarted from the last active step. This is useful for long-running workflows that might still be running when the server loses connection. Restarting a workflow run will resume execution from the last active step, and the workflow will continue from there.

package/.docs/docs/workspace/skills.md

@@ -187,8 +187,16 @@ const workspace = new Workspace({
 
 When `skillSource` is provided, it's used instead of the workspace filesystem for skill discovery.
 
+## Agent-level skills
+
+You can also attach skills directly to an agent without a workspace using `createSkill()` and the agent's `skills` config. When both agent-level and workspace-level skills exist, they merge — agent-level skills take precedence on name conflicts.
+
+See [Agent skills](https://mastra.ai/docs/agents/skills) for details.
+
 ## Related
 
+- [Agent skills](https://mastra.ai/docs/agents/skills)
 - [Agent skills specification](https://agentskills.io)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)
-- [Search and indexing](https://mastra.ai/docs/workspace/search)
+- [Search and indexing](https://mastra.ai/docs/workspace/search)
+- [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)

package/.docs/guides/build-your-ui/ai-sdk-ui.md

@@ -103,7 +103,7 @@ You can also use dynamic workflow routing, see the [`workflowRoute()` reference
 
 > **Agent streaming in workflows:** When a workflow step pipes an agent's stream to the workflow writer (e.g., `await response.fullStream.pipeTo(writer)`), the agent's text chunks and tool calls are forwarded to the UI stream in real time, even when the agent runs inside workflow steps.
 >
-> See [Workflow Streaming](https://mastra.ai/docs/streaming/workflow-streaming) for more details.
+> See [Workflow Streaming](https://mastra.ai/docs/workflows/overview) for more details.
 
 **networkRoute()**:
 
@@ -676,7 +676,7 @@ export function WorkflowChat() {
 }
 ```
 
-For more details on workflow streaming, see [Workflow Streaming](https://mastra.ai/docs/streaming/workflow-streaming).
+For more details on workflow streaming, see [Workflow Streaming](https://mastra.ai/docs/workflows/overview).
 
 ### Rendering network data
 
@@ -906,7 +906,7 @@ export function TaskChat() {
 
 ### Tool streaming
 
-Tools can also stream data using `context.writer.write()` for lower-level control, or pipe an agent's stream directly to the tool's writer. For more details, see [Tool Streaming](https://mastra.ai/docs/streaming/tool-streaming).
+Tools can also stream data using `context.writer.write()` for lower-level control, or pipe an agent's stream directly to the tool's writer. For more details, see [Tool Streaming](https://mastra.ai/docs/agents/using-tools).
 
 ### Examples