@mastra/mcp-docs-server 1.1.4 → 1.1.5-alpha.0

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

@@ -1,241 +0,0 @@
-# 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

@@ -1,35 +0,0 @@
-# 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

@@ -1,3 +0,0 @@
-# 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

@@ -1,9 +0,0 @@
-# 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

@@ -1,66 +0,0 @@
-# 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

@@ -1,15 +0,0 @@
-# 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)

package/.docs/docs/deployment/mastra-server.md

@@ -1,122 +0,0 @@
-# Deploy a Mastra Server
-
-Mastra compiles your application into a standalone Node.js server that can run on any platform supporting Node.js, Bun, or Deno.
-
-> **Tip:** This guide covers deploying the standalone server generated by `mastra build`. If you need to integrate Mastra into an existing Express or Hono application, see [Server Adapters](https://mastra.ai/docs/server/server-adapters) instead.
-
-## Building your application
-
-Run the build command from your project root:
-
-```bash
-mastra build
-```
-
-This creates a `.mastra` directory containing your production-ready server.
-
-> **Info:** Read the [`mastra build`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
-
-## Build output
-
-After building, Mastra creates the following structure:
-
-```text
-.mastra/
-├── .build/                # Intermediate build artifacts (module maps, analysis)
-└── output/
-    ├── index.mjs          # Server entry point
-    ├── mastra.mjs         # Your bundled Mastra configuration
-    ├── tools.mjs          # Aggregated tool exports
-    ├── tools/             # Individual tool bundles
-    ├── package.json       # Production dependencies
-    ├── node_modules/      # Installed dependencies
-    ├── .npmrc             # Copied from your project (if present)
-    ├── public/            # Static assets (if src/mastra/public exists)
-    └── playground/        # Studio UI (if --studio flag used)
-```
-
-The `output` directory is self-contained. You can copy it to any server and run it directly.
-
-## Running the server
-
-Start the server using the Mastra CLI:
-
-```bash
-mastra start
-```
-
-Or run directly with Node.js:
-
-```bash
-node .mastra/output/index.mjs
-```
-
-The `mastra start` command provides additional features:
-
-- Loads environment variables from `.env.production` and `.env`
-- Provides helpful error messages for missing modules
-- Handles process signals for graceful shutdown
-
-> **Info:** Read the [`mastra start`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
-
-## Build configuration
-
-### Public folder
-
-If a `public` folder exists in your Mastra directory (`src/mastra/public`), its contents are copied to the output directory during build. These files are served as static assets by the server.
-
-### Mastra configuration
-
-The build process respects configuration in your Mastra instance. For server behavior like CORS, timeouts, and middleware, see [server overview](https://mastra.ai/docs/server/mastra-server). For all available options, see the [configuration reference](https://mastra.ai/reference/configuration).
-
-## Build process
-
-The build follows these steps:
-
-1. **Locates entry file**: Finds `index.ts` or `index.js` in your Mastra directory.
-2. **Discovers tools**: Scans for tool files matching `{mastraDir}/tools/**/*.{js,ts}`, excluding test files.
-3. **Analyzes dependencies**: Determines which packages to bundle vs. install externally.
-4. **Bundles code**: Uses Rollup with tree-shaking and optional source maps.
-5. **Generates server**: Creates a Hono-based HTTP server as `index.mjs`.
-6. **Installs dependencies**: Runs `npm install` in the output directory.
-7. **Copies assets**: Copies `public` folder and `.npmrc` if present.
-
-## Environment variables
-
-| Variable             | Description                                                                 |
-| -------------------- | --------------------------------------------------------------------------- |
-| `PORT`               | Server port (default: `4111`)                                               |
-| `MASTRA_STUDIO_PATH` | Path to Studio build directory (default: `./playground`)                    |
-| `MASTRA_SKIP_DOTENV` | Skip loading `.env` files when set                                          |
-| `NODE_OPTIONS`       | Node.js options (e.g., `--max-old-space-size=4096` for build memory issues) |
-
-## Server endpoints
-
-The built server exposes endpoints for health checks, agents, workflows, and more:
-
-| Endpoint            | Description                                                            |
-| ------------------- | ---------------------------------------------------------------------- |
-| `GET /health`       | Health check endpoint, returns `200 OK`                                |
-| `GET /openapi.json` | OpenAPI specification (if `server.build.openAPIDocs` is enabled)       |
-| `GET /swagger-ui`   | Interactive API documentation (if `server.build.swaggerUI` is enabled) |
-
-This list is not exhaustive. To view all endpoints, run `mastra dev` and visit `http://localhost:4111/swagger-ui`.
-
-To add your own endpoints, see [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes).
-
-## Troubleshooting
-
-### Memory errors during build
-
-If you encounter `JavaScript heap out of memory` errors:
-
-```bash
-NODE_OPTIONS="--max-old-space-size=4096" mastra build
-```
-
-## Related
-
-- [Server Overview](https://mastra.ai/docs/server/mastra-server) - Configure server behavior, middleware, and authentication
-- [Server Adapters](https://mastra.ai/docs/server/server-adapters) - Use Express or Hono instead of `mastra build`
-- [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes) - Add custom HTTP endpoints
-- [Configuration Reference](https://mastra.ai/reference/configuration) - Full configuration options

package/.docs/docs/deployment/monorepo.md

@@ -1,142 +0,0 @@
-# Deploy in a Monorepo
-
-Deploying Mastra in a monorepo follows the same process as a standalone application. This guide covers monorepo-specific considerations. For the core build and deployment steps, see [Deploy a Mastra Server](https://mastra.ai/docs/deployment/mastra-server).
-
-## Supported monorepos
-
-Mastra works with:
-
-- npm workspaces
-- pnpm workspaces
-- Yarn workspaces
-- Turborepo
-
-Known limitations:
-
-- Bun workspaces - partial support; known issues
-- Nx - You can use Nx's [supported dependency strategies](https://nx.dev/concepts/decisions/dependency-management) but you need to have `package.json` files inside your workspace packages
-
-## Example structure
-
-In this example, the Mastra application is located at `apps/api`:
-
-```text
-apps/
-├── api/
-│   ├── src/
-│   │   └── mastra/
-│   │       ├── agents/
-│   │       ├── tools/
-│   │       ├── workflows/
-│   │       └── index.ts
-│   ├── package.json
-│   └── tsconfig.json
-└── web/
-packages/
-├── ui/
-└── utils/
-package.json
-```
-
-## Building from a monorepo
-
-Use your monorepo tool to run the build command from the correct package. There's no need for special flags.
-
-Examples:
-
-**npm**:
-
-```bash
-npm run build --workspace=apps/api
-```
-
-**pnpm**:
-
-```bash
-pnpm --filter api run build
-```
-
-**yarn**:
-
-```bash
-yarn workspace api build
-```
-
-**Turborepo**:
-
-```bash
-turbo run build --filter=api
-```
-
-Your package's `build` script should run `mastra build`:
-
-```json
-{
-  "scripts": {
-    "build": "mastra build"
-  }
-}
-```
-
-## Workspace packages
-
-When your Mastra application imports from other workspace packages, Mastra handles this automatically:
-
-- If the package is pre-compiled (e.g., built with `tsc` or `tsdown`), Mastra imports the compiled JavaScript
-- If the package contains uncompiled TypeScript, Mastra transpiles it during the build
-
-For most setups, this works without configuration. If you encounter issues with workspace package imports, add the package to [`transpilePackages`](https://mastra.ai/reference/configuration):
-
-```typescript
-export const mastra = new Mastra({
-  bundler: {
-    transpilePackages: ["@my-org/utils"],
-  },
-});
-```
-
-## Environment variables
-
-Store `.env` files in the Mastra application directory (e.g., `apps/api/.env`), not the monorepo root.
-
-## Deployment configuration
-
-When deploying to cloud providers, ensure the correct package is selected as the deploy target. Selecting the monorepo root instead of the application directory (e.g., `apps/api`) is a common mistake.
-
-Most providers let you specify the root directory in their dashboard or configuration file.
-
-### Mastra Cloud
-
-The image below shows how to select `apps/api` as the project root when deploying to [Mastra Cloud](https://mastra.ai/docs/mastra-cloud/overview). While the interface may differ between providers, the configuration remains the same.
-
-![Deployment configuration](/assets/images/monorepo-mastra-cloud-6bd3d30cb0ef7c255c8d8bb43aeff4ec.jpg)
-
-## Dependency management
-
-Keep dependencies consistent to avoid version conflicts and build errors:
-
-- Use a **single lockfile** at the monorepo root so all packages resolve the same versions
-- Align versions of **shared libraries** (like Mastra or frameworks) to prevent duplicates
-
-## Troubleshooting
-
-### Workspace package not found
-
-If Mastra can't resolve a workspace package, ensure:
-
-- The package is listed in your `package.json` dependencies
-- Your lockfile is up to date (`pnpm install`, `npm install`, etc.)
-- The package has a valid `main` or `exports` field in its `package.json`
-
-### TypeScript errors from workspace packages
-
-If you see type errors from uncompiled workspace packages, either:
-
-- Build the package first (recommended for faster Mastra builds)
-- Add the package to [`transpilePackages`](https://mastra.ai/reference/configuration) in your Mastra config
-
-## Related
-
-- [Deploy a Mastra Server](https://mastra.ai/docs/deployment/mastra-server) - Core build and deployment guide
-- [Configuration Reference](https://mastra.ai/reference/configuration) - `bundler.transpilePackages` and other options
-- [CLI Reference](https://mastra.ai/reference/cli/mastra) - Build command flags