@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/docs/agents/using-tools.md

@@ -0,0 +1,248 @@
+# Using Tools
+
+Agents use tools to call APIs, query databases, or run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/mcp/overview) to expand an agent's capabilities.
+
+## When to use tools
+
+Use tools when an agent needs additional context or information from remote resources, or when it needs to run code that performs a specific operation. This includes tasks a model can't reliably handle on its own, such as fetching live data or returning consistent, well defined outputs.
+
+## Creating a tool
+
+When creating tools, keep descriptions simple and focused on what the tool does, emphasizing its primary use case. Descriptive schema names can also help guide the agent on how to use the tool.
+
+This example shows how to create a tool that fetches weather data from an API. When the agent calls the tool, it provides the required input as defined by the tool's `inputSchema`. The tool accesses this data through its `inputData` parameter, which in this example includes the `location` used in the weather API query.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Fetches weather for a location',
+  inputSchema: z.object({
+    location: z.string(),
+  }),
+  outputSchema: z.object({
+    weather: z.string(),
+  }),
+  execute: async inputData => {
+    const { location } = inputData
+
+    const response = await fetch(`https://wttr.in/${location}?format=3`)
+    const weather = await response.text()
+
+    return { weather }
+  },
+})
+```
+
+## Shaping output for the model
+
+Use `toModelOutput` when your tool returns rich structured data for your application, but you want the model to receive a smaller or multimodal representation. This keeps model context focused while preserving the full tool result in your app.
+
+```typescript
+export const weatherTool = createTool({
+  // ...other config
+  execute: async ({ location }) => {
+    const response = await fetch(`https://wttr.in/${location}?format=j1`)
+    const data = await response.json()
+
+    return {
+      location,
+      temperature: data.current_condition[0].temp_F,
+      condition: data.current_condition[0].weatherDesc[0].value,
+      weatherIconUrl: data.current_condition[0].weatherIconUrl[0].value,
+      source: data,
+    }
+  },
+  toModelOutput: output => {
+    return {
+      type: 'content',
+      value: [
+        {
+          type: 'text',
+          text: `${output.location}: ${output.temperature}F and ${output.condition}`,
+        },
+        { type: 'image-url', url: output.weatherIconUrl },
+      ],
+    }
+  },
+})
+```
+
+## Adding tools to an agent
+
+To make a tool available to an agent, add it to `tools`. Mentioning available tools and their general purpose in the agent's system prompt helps the agent decide when to call a tool and when not to.
+
+An agent can use multiple tools to handle more complex tasks by delegating specific parts to individual tools. The agent decides which tools to use based on the user's message, the agent's instructions, and the tool descriptions and schemas.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { weatherTool } from '../tools/weather-tool'
+
+export const weatherAgent = new Agent({
+  id: 'weather-agent',
+  name: 'Weather Agent',
+  instructions: `
+      You are a helpful weather assistant.
+      Use the weatherTool to fetch current weather data.`,
+  model: 'openai/gpt-5.1',
+  tools: { weatherTool },
+})
+```
+
+## Using multiple tools
+
+When multiple tools are available, the agent may choose to use one, several, or none, depending on what's needed to answer the query.
+
+```typescript
+import { weatherTool } from '../tools/weather-tool'
+import { activitiesTool } from '../tools/activities-tool'
+
+export const weatherAgent = new Agent({
+  id: 'weather-agent',
+  name: 'Weather Agent',
+  tools: { weatherTool, activitiesTool },
+})
+```
+
+## Using agents as tools
+
+Agents can be added to other agents through the `agents` configuration. When you add subagents, the parent agent becomes a supervisor. A supervisor can delegate tasks to subagents using the [supervisor pattern](https://mastra.ai/docs/agents/supervisor-agents), with support for delegation hooks, message filtering, iteration monitoring, and task completion scoring. Mastra automatically converts each subagent to a tool that the parent agent can call, named `agent-<agentName>`.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const parentAgent = new Agent({
+  id: 'parent-agent',
+  name: 'Parent Agent',
+  description: 'Take care in writing a good description here',
+  instructions: `Instructions`,
+  model: 'openai/gpt-5.1',
+  agents: {
+    subAgent,
+  },
+})
+
+const subAgent = new Agent({
+  id: 'sub-agent',
+  name: 'Sub Agent',
+  description: 'Take care in writing a good description here',
+  instructions: `Instructions`,
+  model: 'openai/gpt-5.1',
+})
+```
+
+The subagent should include a `description` to help the parent agent understand when to use it. See the [`toolName` docs](#subagents-and-workflows-as-tools) to learn more about the tool naming scheme.
+
+## Using workflows as tools
+
+Workflows can be added to agents through the `workflows` configuration. When you add a workflow, Mastra automatically converts it to a tool that the agent can call. The generated tool is named `workflow-<workflowName>` and uses the workflow's `inputSchema` and `outputSchema`.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { researchWorkflow } from '../workflows/research-workflow'
+
+export const researchAgent = new Agent({
+  id: 'research-agent',
+  name: 'Research Agent',
+  instructions: `
+      You are a research assistant.
+      Use the research workflow to gather and compile information on topics.`,
+  model: 'openai/gpt-5.1',
+  tools: {
+    weatherTool,
+  },
+  workflows: {
+    researchWorkflow,
+  },
+})
+```
+
+The workflow should include a `description` to help the agent understand when to use it:
+
+```typescript
+import { createWorkflow } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+export const researchWorkflow = createWorkflow({
+  id: 'research-workflow',
+  description: 'Gathers information on a topic and compiles a summary report.',
+  // Rest of the workflow...
+}).commit()
+```
+
+When the agent calls the workflow tool, it receives a response containing the workflow result and a `runId` that can be used to track the execution:
+
+```typescript
+{
+  result: { summary: "...", sources: ["..."] },
+  runId: "abc-123"
+}
+```
+
+See the [`toolName` docs](#subagents-and-workflows-as-tools) to learn more about the tool naming scheme.
+
+## Controlling `toolName` in stream responses
+
+The `toolName` in stream responses is determined by the **object key** you use, not the `id` property of the tool, agent, or workflow.
+
+```typescript
+// Tool defined with id: "weather-tool"
+export const weatherTool = createTool({
+  id: "weather-tool",
+  // ...
+});
+
+// Using the variable name as the key
+tools: { weatherTool }
+// Stream returns: toolName: "weatherTool"
+
+// Using the tool's id as the key
+tools: { [weatherTool.id]: weatherTool }
+// Stream returns: toolName: "weather-tool"
+
+// Using a custom key
+tools: { "my-custom-name": weatherTool }
+// Stream returns: toolName: "my-custom-name"
+```
+
+This lets you specify how tools are identified in the stream. If you want the `toolName` to match the tool's `id`, use the tool's `id` as the object key.
+
+### Subagents and workflows as tools
+
+Subagents and workflows follow the same pattern. They are converted to tools with a prefix followed by your object key:
+
+| Property    | Prefix      | Example key | `toolName`          |
+| ----------- | ----------- | ----------- | ------------------- |
+| `agents`    | `agent-`    | `weather`   | `agent-weather`     |
+| `workflows` | `workflow-` | `research`  | `workflow-research` |
+
+```typescript
+const orchestrator = new Agent({
+  agents: {
+    weather: weatherAgent, // toolName: "agent-weather"
+  },
+  workflows: {
+    research: researchWorkflow, // toolName: "workflow-research"
+  },
+})
+```
+
+Note that for subagents, you'll see two different identifiers in stream responses:
+
+- `toolName: "agent-weather"` in tool call events — the generated tool wrapper name
+- `id: "weather-agent"` in `data-tool-agent` chunks — the subagent's actual `id` property
+
+## Tools with structured output
+
+When using tools with [structured output](https://mastra.ai/docs/agents/structured-output), some models don't support combining both features in the same API call. If your tools aren't being called when structured output is enabled, or you receive errors about incompatible options, see [Combining tools and structured output](https://mastra.ai/docs/agents/structured-output) for model compatibility information and workarounds.
+
+## Related
+
+- [MCP Overview](https://mastra.ai/docs/mcp/overview)
+- [Dynamic Tool Search](https://mastra.ai/reference/processors/tool-search-processor) - Load tools on demand for agents with large tool libraries
+- [Structured Output](https://mastra.ai/docs/agents/structured-output)
+- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)
+- [Supervisor Agents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Request Context](https://mastra.ai/docs/server/request-context)

package/.docs/docs/build-with-ai/mcp-docs-server.md

@@ -0,0 +1,238 @@
+# Mastra 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 clicking 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 click **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 click 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, click 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/build-with-ai/skills.md

@@ -0,0 +1,35 @@
+# Mastra Skills
+
+Mastra Skills are folders of instructions, scripts, and resources that agents can discover and use to gain Mastra knowledge. They contain setup instructions, best practices, and methods to fetch up-to-date information from Mastra's documentation.
+
+## Installation
+
+To install all available Mastra skills, run the following command:
+
+**npm**:
+
+```bash
+npx skills add mastra-ai/skills
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx skills add mastra-ai/skills
+```
+
+**Yarn**:
+
+```bash
+yarn dlx skills add mastra-ai/skills
+```
+
+**Bun**:
+
+```bash
+bun x skills add mastra-ai/skills
+```
+
+Mastra skills work with any coding agent that supports the [Skills standard](https://agentskills.io/), including Claude Code, Cursor, Codex, OpenCode, and others.
+
+They are also available on [GitHub](https://github.com/mastra-ai/skills).

package/.docs/docs/community/contributing-templates.md

@@ -0,0 +1,3 @@
+# Contributing Templates
+
+The Mastra community plays a vital role in creating templates that showcase innovative application patterns. We're currently reworking our template contribution process to ensure high-quality, valuable templates for the community. For the time being, we're not accepting new template contributions. Please keep an eye on this page for updates on when contributions will reopen and the new submission process.

package/.docs/docs/community/discord.md

@@ -0,0 +1,9 @@
+# Discord Community
+
+The Discord server has over 1000 members and serves as the main discussion forum for Mastra. The Mastra team monitors Discord during North American and European business hours, with community members active across other time zones.
+
+[Join the Discord server](https://discord.gg/BTYqqHKUrf)
+
+## Discord MCP Bot
+
+In addition to community members, we have an (experimental!) Discord bot that can also help answer questions. It uses [Model Context Protocol (MCP)](https://mastra.ai/docs/mcp/overview). You can ask it a question with `/ask` (either in public channels or DMs) and clear history (in DMs only) with `/cleardm`.

package/.docs/docs/community/licensing.md

@@ -0,0 +1,66 @@
+# License
+
+## Apache License 2.0
+
+Mastra is licensed under the Apache License 2.0, a permissive open-source license that provides users with broad rights to use, modify, and distribute the software.
+
+### What is Apache License 2.0?
+
+The Apache License 2.0 is a permissive open-source license that grants users extensive rights to use, modify, and distribute the software. It allows:
+
+- Free use for any purpose, including commercial use
+- Viewing, modifying, and redistributing the source code
+- Creating and distributing derivative works
+- Commercial use without restrictions
+- Patent protection from contributors
+
+The Apache License 2.0 is one of the most permissive and business-friendly open-source licenses available.
+
+### Why We Chose Apache License 2.0
+
+We selected the Apache License 2.0 for several important reasons:
+
+1. **True Open Source**: It's a recognized open-source license that aligns with open-source principles and community expectations.
+
+2. **Business Friendly**: It allows for unrestricted commercial use and distribution, making it ideal for businesses of all sizes.
+
+3. **Patent Protection**: It includes explicit patent protection for users, providing additional legal security.
+
+4. **Community Focus**: It encourages community contributions and collaboration without restrictions.
+
+5. **Widely Adopted**: It's one of the most popular and well-understood open-source licenses in the industry.
+
+### Building Your Business with Mastra
+
+The Apache License 2.0 provides maximum flexibility for building businesses with Mastra:
+
+#### Allowed Business Models
+
+- **Building Applications**: Create and sell applications built with Mastra
+- **Offering Consulting Services**: Provide expertise, implementation, and customization services
+- **Developing Custom Solutions**: Build bespoke AI solutions for clients using Mastra
+- **Creating Add-ons and Extensions**: Develop and sell complementary tools that extend Mastra's functionality
+- **Training and Education**: Offer courses and educational materials about using Mastra effectively
+- **Hosted Services**: Offer Mastra as a hosted or managed service
+- **SaaS Platforms**: Build SaaS platforms powered by Mastra
+
+#### Examples of Compliant Usage
+
+- A company builds an AI-powered customer service application using Mastra and sells it to clients
+- A consulting firm offers implementation and customization services for Mastra
+- A developer creates specialized agents and tools with Mastra and licenses them to other businesses
+- A startup builds a vertical-specific solution (e.g., healthcare AI assistant) powered by Mastra
+- A company offers Mastra as a hosted service to their customers
+- A SaaS platform integrates Mastra as their AI backend
+
+#### Compliance Requirements
+
+The Apache License 2.0 has minimal requirements:
+
+- **Attribution**: Maintain copyright notices and license information (including NOTICE file)
+- **State Changes**: If you modify the software, state that you have made changes
+- **Include License**: Include a copy of the Apache License 2.0 when distributing
+
+### Questions About Licensing?
+
+If you have specific questions about how the Apache License 2.0 applies to your use case, please [contact us](https://discord.gg/BTYqqHKUrf) on Discord for clarification. We're committed to supporting all legitimate use cases while maintaining the open-source nature of the project.

package/.docs/docs/deployment/cloud-providers.md

@@ -0,0 +1,15 @@
+# Deploy to Cloud Providers
+
+Mastra applications can be deployed to cloud providers and serverless platforms. Mastra includes optional built-in deployers for Vercel, Netlify, and Cloudflare to automate the deployment process.
+
+## Supported Cloud Providers
+
+The following guides show how to deploy Mastra to specific cloud providers:
+
+- [Amazon EC2](https://mastra.ai/guides/deployment/amazon-ec2)
+- [AWS Lambda](https://mastra.ai/guides/deployment/aws-lambda)
+- [Azure App Services](https://mastra.ai/guides/deployment/azure-app-services)
+- [Cloudflare](https://mastra.ai/guides/deployment/cloudflare)
+- [Digital Ocean](https://mastra.ai/guides/deployment/digital-ocean)
+- [Netlify](https://mastra.ai/guides/deployment/netlify)
+- [Vercel](https://mastra.ai/guides/deployment/vercel)