> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt # 使用 AI 构建 有关使用 Mastra Skill 和 CLI 进行日常 AI 辅助开发的信息，请参阅[开发](https://mastra.zisheng.pro/docs/getting-started/develop)。本页介绍让编码 Agent 访问 Mastra 文档的其他方式。 ## 内嵌包文档 Mastra 包在 `dist/docs` 中提供内嵌文档。安装 Mastra 包后，AI Agent 可以直接从 `node_modules` 读取这些文件，以了解该包的 API 和模式。 每个 `dist/docs` 都包含： - `SKILL.md`：遵循 Skill 标准的 Skill 文件 - `references/`：包含与该包相关文档文件的文件夹 - `assets/SOURCE_MAP.json`：将公开 export 链接到其在 `node_modules` 中位置的 source map 文件 ## 上下文文件 Mastra 提供根 [`llms.txt`](https://mastra.ai/llms.txt) 文件，其中包含所有可用文档页面的概览。Mastra 不提供 `llms-full.txt` 文件，因为将所有文档放在一个文件中并无益处。 相反，每个文档页面都有自己的 `llms.txt` 文件。这些文件是经过精简的 Markdown 文件。每个文档页面末尾都有指向相应 `llms.txt` 文件的链接。 在任意 Mastra 文档 URL 后添加 `/llms.txt` 即可访问。也可以在 URL 末尾添加 `.md` 扩展名来请求该文件。 [介绍页面](https://mastra.zisheng.pro/docs)的示例： - [`/docs/llms.txt`](https://mastra.ai/docs/llms.txt) - [`/docs.md`](https://mastra.ai/docs.md) ## MCP 文档服务器 > **注意:** 不建议在日常开发中使用 MCP 文档服务器。请改用 [Mastra Skill](https://mastra.zisheng.pro/docs/getting-started/develop)，因为它更新更及时且性能更好。 `@mastra/mcp-docs-server` 包通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) 提供对 Mastra 完整文档的直接本地访问。它支持 Cursor、Windsurf、Cline、Claude Code、VS Code、Codex，以及任何支持 MCP 的 Tool。 这些 Tool 旨在帮助 Agent 获取精确且针对特定任务的信息，无论你是在为 Agent 添加功能、搭建新项目，还是探索某项功能的工作原理。 如果无法使用本地 MCP server 而需要连接远程服务器，请使用此 URL：`https://mastra.mcp.kapa.ai`。出于速率限制目的，你需要使用 Google Account 进行身份验证（只会传输匿名 ID）。如条件允许，Mastra 建议使用本地 MCP server，以获得更好的性能和可靠性。 ### 安装 [`create-mastra`](https://mastra.zisheng.pro/reference/cli/create-mastra) 命令不会配置 MCP 文档服务器。需要迁移 Tool 等 MCP 专用 Tool 时，请手动添加该服务器。 如果下文没有针对你的 Tool 的具体说明，可以尝试使用以下通用 JSON 配置添加 MCP server。 ```json { "mcpServers": { "mastra": { "type": "stdio", "command": "npx", "args": ["-y", "@mastra/mcp-docs-server@latest"] } } } ``` #### Claude Code CLI 使用以下终端命令安装： ```bash claude mcp add --scope project mastra -- npx -y @mastra/mcp-docs-server@latest ``` 如果项目范围的 `.mcp.json` 文件尚不存在，此命令会创建该文件。将 Claude Code 用作 [Visual Studio Code 扩展](https://code.claude.com/docs/en/vs-code#connect-to-external-tools-with-mcp)时也可以使用同一命令。 [详细了解如何在 Claude Code 中使用 MCP server](https://docs.claude.com/en/docs/claude-code/mcp) #### OpenAI Codex CLI 1. 在终端中注册： ```bash codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@latest ``` 2. 运行 `codex mcp list`，确认服务器显示为 `enabled`。 [详细了解如何在 OpenAI Codex 中使用 MCP server](https://developers.openai.com/codex/mcp) #### Cursor 选择下方按钮进行安装： [![安装 MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=mastra\&config=eyJjb21tYW5kIjoibnB4IC15IEBtYXN0cmEvbWNwLWRvY3Mtc2VydmVyIn0%3D) 如果使用自动安装，打开 Cursor 时左下角会出现弹窗，提示启用 Mastra Docs MCP Server。 ![Cursor 中的弹窗显示：“New MCP server detected: mastra”。用户可以选择“Skip”或“Enable”。](/assets/images/enable-mastra-docs-cursor-cd5872abdc36c0e10951a59a47f25e12.png) [详细了解如何在 Cursor 中使用 MCP server](https://cursor.com/de/docs/context/mcp) #### Antigravity Google Antigravity 是一个 Agent 优先的开发平台，支持使用 MCP server 访问外部文档、API 和项目上下文。 1. 打开 Antigravity MCP 配置文件： - 点击 **Agent session**，选择编辑器侧边面板顶部的 **“…” dropdown**，然后选择 **MCP Servers** 以访问 **MCP Store**。 - 也可以通过 Antigravity 中的 MCP Store 界面访问 ![Antigravity MCP Store。顶部是搜索栏，下方是可用 MCP server 列表，右上角是下拉菜单。](/assets/images/antigravity_mcp_server-689ea495d9c7139cc431f1f1b9827f9b.png) 2. 要添加自定义 MCP server，请选择 MCP Store 顶部的 **Manage MCP Servers**，然后在主选项卡中选择 **View raw config**。 ![Antigravity MCP Store 显示 Manage MCP Servers 选项和 View raw config 按钮。](/assets/images/antigravity_managed_mcp-b661e8c04b3219000f8d842e5eb26a1a.png) 3. 添加 Mastra MCP server 配置： ```json { "mcpServers": { "mastra-docs": { "command": "npx", "args": ["-y", "@mastra/mcp-docs-server"] } } } ``` 4. 保存配置并重启 Antigravity ![UI 显示 MCP server 已启用。也可以单独切换各个 Tool。](/assets/images/antigravity_final_interface_mcp-7fa132dbe76cdee9f61136a26d6e6615.png) 配置完成后，Mastra MCP server 会向 Antigravity Agent 提供以下内容： - Mastra 的索引文档和 API schema，使其能在生成代码时以编程方式检索相关上下文 - 访问 Mastra Docs 中存储的示例代码片段和用法模式 - 用于编辑器中错误处理和调试参考的结构化数据 - 关于当前 Mastra 项目模式的 metadata，用于代码建议和补全 MCP server 会显示在 Antigravity 的 MCP Store 中，你可以在其中按需管理连接状态和身份验证。 [详细了解如何在 Antigravity 中使用 MCP server](https://antigravity.google) #### Visual Studio Code 1. 在 Workspace 中创建 `.vscode/mcp.json` 文件 2. 插入以下配置： ```json { "servers": { "mastra": { "type": "stdio", "command": "npx", "args": ["-y", "@mastra/mcp-docs-server@latest"] } } } ``` 安装 MCP server 后，可以按以下方式使用： 1. 打开 VSCode 设置。 2. 前往 MCP 设置。 3. 点击 Chat > MCP 选项中的“enable”。 ![VSCode 设置页面中的条目。选项名为“Chat \> MCP: Enabled (Preview)”。说明为：“Enables integration with Model Context Protocol servers to provide additional tools and functionality.”](/assets/images/vscode-mcp-setting-8d1eb4f3df1e33606503f8c5e937e9e3.png) MCP 只能在 VSCode 的 Agent 模式下工作。进入 Agent 模式后，打开 `mcp.json` 文件并选择“start”按钮。请注意，只有当包含 `mcp.json` 的 `.vscode` 文件夹位于 Workspace 根目录或编辑器内文件资源管理器的最高层级时，才会显示“start”按钮。 ![显示编辑器中 start 按钮的 mcp.json 文件截图](/assets/images/vscode-start-mcp-26480d86080c4907cb497a325de106a4.png) 启动 MCP server 后，选择 Copilot 窗格中的 Tool 按钮以查看可用 Tool。 ![用于查看 VSCode 可用 Tool 的 Tool 页面](/assets/images/vscode-mcp-running-d92d6ed234d1148093dc804b0ead3515.png) [详细了解如何在 Visual Studio Code 中使用 MCP server](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) #### Windsurf 1. 在编辑器中打开 `~/.codeium/windsurf/mcp_config.json` 2. 插入以下配置： ```json { "mcpServers": { "mastra": { "command": "npx", "args": ["-y", "@mastra/mcp-docs-server@latest"] } } } ``` 3. 保存配置并重启 Windsurf [详细了解如何在 Windsurf 中使用 MCP server](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json) #### OpenCode 可以在 [OpenCode 配置](https://opencode.ai/docs/config/)的 `mcp` 下定义 MCP server。在项目根目录创建 `opencode.jsonc` 文件，内容如下： ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "mastra": { "type": "local", "command": ["npx", "-y", "@mastra/mcp-docs-server@latest"], "enabled": true } } } ``` [详细了解如何在 OpenCode 中使用 MCP server](https://opencode.ai/docs/mcp-servers) #### Zed 1. 在编辑器中打开 `~/.config/zed/settings.json` 2. 插入以下配置： ```json { "context_servers": { "Mastra": { "command": "npx", "args": ["-y", "@mastra/mcp-docs-server@latest"] } } } ``` ### 用法 配置完成后，可以向 AI Tool 询问有关 Mastra 的问题或指示其执行操作。在这些步骤中，它会从 Mastra 的 MCP server 获取最新信息。 **添加功能：** - “为我的 Agent 添加 Evals 并编写测试” - “为我编写一个执行以下 `[task]` 的 Workflow” - “创建一个新 Tool，让我的 Agent 可以访问 `[3rd party API]`” **询问集成：** - “Mastra 是否支持 AI SDK？ 如何在我的 `[React/Svelte/etc]` 项目中使用它？” - “Mastra 是否支持 `[provider]` 的语音 API？请在我的代码中给出用法示例。” **调试或更新现有代码：** - “我的 Agent memory 遇到了错误，最近是否有相关更改或错误修复？” - “working memory 在 Mastra 中如何工作？如何用它完成 `[task]`？它似乎没有按我的预期工作。” - “我看到新增了一些 Workflow 功能，请先向我解释，再更新 `[workflow]` 以使用这些功能。” ### 故障排除 1. **服务器未启动** - 确保已安装 [npx](https://docs.npmjs.com/cli/v11/commands/npx) 且其运行正常。 - 检查是否存在冲突的 MCP server。 - 验证配置文件语法。 2. **Tool 调用失败** - 重启 MCP server 和/或 IDE。 - 将 IDE 更新到最新版本。