使用 AI 构建

有关使用 Mastra Skill 和 CLI 进行日常 AI 辅助开发的信息，请参阅开发。本页介绍让编码 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 文件，其中包含所有可用文档页面的概览。Mastra 不提供 llms-full.txt 文件，因为将所有文档放在一个文件中并无益处。

相反，每个文档页面都有自己的 llms.txt 文件。这些文件是经过精简的 Markdown 文件。每个文档页面末尾都有指向相应 llms.txt 文件的链接。

在任意 Mastra 文档 URL 后添加 /llms.txt 即可访问。也可以在 URL 末尾添加 .md 扩展名来请求该文件。

介绍页面的示例：

• /docs/llms.txt
• /docs.md

MCP 文档服务器

注意

不建议在日常开发中使用 MCP 文档服务器。请改用 Mastra Skill，因为它更新更及时且性能更好。

@mastra/mcp-docs-server 包通过 Model Context Protocol (MCP) 提供对 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 命令不会配置 MCP 文档服务器。需要迁移 Tool 等 MCP 专用 Tool 时，请手动添加该服务器。

如果下文没有针对你的 Tool 的具体说明，可以尝试使用以下通用 JSON 配置添加 MCP server。

mcp.json

{
  "mcpServers": {
    "mastra": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mastra/mcp-docs-server@latest"]
    }
  }
}

Claude Code CLI

使用以下终端命令安装：

claude mcp add --scope project mastra -- npx -y @mastra/mcp-docs-server@latest

如果项目范围的 .mcp.json 文件尚不存在，此命令会创建该文件。将 Claude Code 用作 Visual Studio Code 扩展时也可以使用同一命令。

详细了解如何在 Claude Code 中使用 MCP server

OpenAI Codex CLI

1. 在终端中注册：

   codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@latest

2. 运行 codex mcp list，确认服务器显示为 enabled。

详细了解如何在 OpenAI Codex 中使用 MCP server

Cursor

选择下方按钮进行安装：

如果使用自动安装，打开 Cursor 时左下角会出现弹窗，提示启用 Mastra Docs MCP Server。

详细了解如何在 Cursor 中使用 MCP server

Antigravity

Google Antigravity 是一个 Agent 优先的开发平台，支持使用 MCP server 访问外部文档、API 和项目上下文。

1. 打开 Antigravity MCP 配置文件：

   • 点击 Agent session，选择编辑器侧边面板顶部的 “…” dropdown，然后选择 MCP Servers 以访问 MCP Store。
   • 也可以通过 Antigravity 中的 MCP Store 界面访问

   

2. 要添加自定义 MCP server，请选择 MCP Store 顶部的 Manage MCP Servers，然后在主选项卡中选择 View raw config。

   

3. 添加 Mastra MCP server 配置：

   {
     "mcpServers": {
       "mastra-docs": {
         "command": "npx",
         "args": ["-y", "@mastra/mcp-docs-server"]
       }
     }
   }

4. 保存配置并重启 Antigravity

   

配置完成后，Mastra MCP server 会向 Antigravity Agent 提供以下内容：

• Mastra 的索引文档和 API schema，使其能在生成代码时以编程方式检索相关上下文
• 访问 Mastra Docs 中存储的示例代码片段和用法模式
• 用于编辑器中错误处理和调试参考的结构化数据
• 关于当前 Mastra 项目模式的 metadata，用于代码建议和补全

MCP server 会显示在 Antigravity 的 MCP Store 中，你可以在其中按需管理连接状态和身份验证。

详细了解如何在 Antigravity 中使用 MCP server

Visual Studio Code

1. 在 Workspace 中创建 .vscode/mcp.json 文件

2. 插入以下配置：

   .vscode/mcp.json

   {
     "servers": {
       "mastra": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@mastra/mcp-docs-server@latest"]
       }
     }
   }

安装 MCP server 后，可以按以下方式使用：

1. 打开 VSCode 设置。

2. 前往 MCP 设置。

3. 点击 Chat > MCP 选项中的“enable”。

   

MCP 只能在 VSCode 的 Agent 模式下工作。进入 Agent 模式后，打开 mcp.json 文件并选择“start”按钮。请注意，只有当包含 mcp.json 的 .vscode 文件夹位于 Workspace 根目录或编辑器内文件资源管理器的最高层级时，才会显示“start”按钮。

启动 MCP server 后，选择 Copilot 窗格中的 Tool 按钮以查看可用 Tool。

详细了解如何在 Visual Studio Code 中使用 MCP server

Windsurf

1. 在编辑器中打开 ~/.codeium/windsurf/mcp_config.json

2. 插入以下配置：

   ~/.codeium/windsurf/mcp_config.json

   {
     "mcpServers": {
       "mastra": {
         "command": "npx",
         "args": ["-y", "@mastra/mcp-docs-server@latest"]
       }
     }
   }

3. 保存配置并重启 Windsurf

详细了解如何在 Windsurf 中使用 MCP server

OpenCode

可以在 OpenCode 配置的 mcp 下定义 MCP server。在项目根目录创建 opencode.jsonc 文件，内容如下：

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mastra": {
      "type": "local",
      "command": ["npx", "-y", "@mastra/mcp-docs-server@latest"],
      "enabled": true
    }
  }
}

详细了解如何在 OpenCode 中使用 MCP server

Zed

1. 在编辑器中打开 ~/.config/zed/settings.json
2. 插入以下配置：

~/.config/zed/settings.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 且其运行正常。
   • 检查是否存在冲突的 MCP server。
   • 验证配置文件语法。

2. Tool 调用失败

   • 重启 MCP server 和/或 IDE。
   • 将 IDE 更新到最新版本。