AgileBuilder logoAgileBuilder
返回文档

接入 Cursor

在 Cursor 中配置 AgileBuilder MCP 服务，让 AI 读取团队模板与规范文档

前提条件

  • 已安装 Cursor
  • 已通过 npm 全局安装 AgileBuilder CLI（要求 Node.js 20 或更高版本）：
npm install -g agilebuilder

安装完成后，确认安装成功：运行 npm ls -g agilebuilder 应能看到 agilebuilder 及版本号；agilebuilder-mcp 会随之一并安装（它是 stdio 服务，不要直接在终端运行它，运行时没有输出属正常现象）。

npm ls -g agilebuilder

配置 MCP 服务

Cursor 通过 mcp.json 配置文件管理 MCP 服务，支持两个层级：

  • 全局配置：~/.cursor/mcp.json（Windows 上为 %USERPROFILE%\.cursor\mcp.json），对所有项目生效
  • 项目配置：项目根目录下的 .cursor/mcp.json，只对当前项目生效

在任一配置文件中添加：

{
  "mcpServers": {
    "agilebuilder": {
      "command": "agilebuilder-mcp"
    }
  }
}

也可以在 Cursor 中通过 Settings → MCP 入口添加新的 MCP 服务，类型选择 command，命令填写 agilebuilder-mcp，效果相同。

AgileBuilder 的 MCP 服务是 stdio 模式：Cursor 会在需要时自动拉起进程，无需手动启动，也没有端口需要配置。

验证配置

保存配置后：

  1. 打开 Settings → MCP，列表中应出现 agilebuilder，状态为已连接。
  2. 展开该服务，应能看到 4 个工具：list_resources、search_resources、get_resource、create_project。

然后在 Cursor 的 AI 对话中验证，例如输入：

List the template resources in my AgileBuilder workspace.

AI 应调用 list_resources 并返回当前工作空间中的资源列表。

如果服务未连接，请检查：

  • agilebuilder-mcp 是否在 PATH 中（全局安装是否成功）
  • mcp.json 的 JSON 语法是否正确

典型用法

让 AI 列出可用模板

What templates are available in my AgileBuilder workspace?

AI 会调用 list_resources（可带 type: "template"）或 search_resources，列出模板及其 ID、描述和标签。

让 AI 读取团队规范

Read the coding standards document from AgileBuilder before writing this module.

AI 会先读取 agilebuilder://docs/catalog 找到文档，再通过 agilebuilder://local/docs/<id> 或 agilebuilder://cloud/docs/<id> 读取正文，把团队规范作为后续生成的上下文。

让 AI 按模板生成项目

Create a project called my-admin in ./my-admin using the vue-admin template.

AI 会先查询模板资源拿到 resourceId，再调用 create_project 并传入 targetPath 和模板变量。如果目标目录非空，AI 需要显式设置 overwrite: true 才能写入；模板 Hook 只有在 allowHooks: true 时才会执行。

访问云端空间的资源

默认情况下，MCP 服务读取的是本地工作空间。要让 AI 访问团队云端空间中的模板和规范文档：

ag login                    # 打开浏览器完成登录
ag space list               # 查看可用的云端空间
ag space use <space-id>     # 切换到目标云端空间

切换后无需改动 Cursor 配置——MCP 服务与 CLI 共用当前工作空间，下一次对话中 AI 查询到的就是云端资源。关于空间、成员与权限的更多内容，见空间与成员。

下一步