AgileBuilder logoAgileBuilder
返回文档

MCP 服务

了解 AgileBuilder 内置的 MCP stdio 服务，以及它向 AI 工具暴露的工具与文档资源

什么是 MCP

MCP（Model Context Protocol）是一个开放协议，让 AI 工具（如 Cursor、Claude Code、Claude Desktop）能够以标准化方式调用外部工具、读取外部数据。

AgileBuilder 内置了一个 MCP 服务。接入后，AI 可以：

  • 查询你工作空间中的模板与文档资源
  • 读取团队沉淀的规范文档，作为生成代码时的上下文
  • 直接按模板生成项目脚手架

AgileBuilder 本身不调用任何大模型——它只负责把模板和规范文档提供给 AI，由你使用的 AI 工具完成实际的代码生成。

AgileBuilder 的 MCP 服务

AgileBuilder 的 MCP 服务是一个 stdio 模式的独立进程，随 agilebuilder npm 包一起安装，提供独立的可执行命令 agilebuilder-mcp。

npm install -g agilebuilder

它不是 HTTP 服务：没有监听端口、没有守护进程，也不需要手动启动。支持 MCP 的客户端（Cursor、Claude Code 等）会在需要时通过标准输入输出（stdio）拉起这个进程，会话结束时自动退出。

MCP 服务与 CLI 共用同一份本地数据（~/.agilebuilder/v2），并使用 当前工作空间——即 ag space current 显示的那个空间。切换空间的命令对 MCP 服务同样生效：

ag space use local        # 使用本地工作空间
ag space use <space-id>   # 使用某个云端空间

MCP 工具

MCP 服务暴露 4 个工具，AI 通过调用它们来查询资源和生成项目。

list_resources

列出当前工作空间中的资源。这是 AI 发现模板的首选方式：工作空间通常很小，AI 应浏览全量列表并根据名称、描述、标签按语义判断匹配（而不是只靠关键词）。

参数：

参数类型必填说明
typetemplate | doc否按资源类型过滤

返回： 包含 workspaceId、资源列表 items 和总数 total 的对象。

search_resources

按关键词搜索当前工作空间中的资源。匹配方式是纯子串匹配（大小写不敏感，匹配名称、描述、标签、Git 地址和文档正文），没有语义理解能力——例如搜 backend 匹配不到名为 java-api 的模板，除非它的描述或标签里写了 backend。因此它只适合在资源很多时做粗筛；搜索无结果不代表没有匹配模板，AI 应回退到 list_resources 自行判断，或换多个关键词变体（backend / server / java / spring）重试。

参数：

参数类型必填说明
keywordstring否搜索关键词
typetemplate | doc否按资源类型过滤

返回： 与 list_resources 结构相同。

get_resource

读取当前工作空间中的单个资源详情。

参数：

参数类型必填说明
resourceIdstring是资源 ID

返回： 资源的完整信息（名称、类型、Git 地址、描述、标签；文档资源还包含正文内容）。模板资源会包含变量清单 variables（变量名、类型、是否必填、默认值）——本地模板在首次读取时自动从模板仓库解析并缓存。AI 在调用 create_project 前应先调用本工具获取变量清单。

create_project

从模板资源或直接的 Git 地址创建项目脚手架。

参数：

参数类型必填说明
targetPathstring是项目生成的目标目录
resourceIdstring二选一当前工作空间中的模板资源 ID
gitUrlstring二选一直接指定 Git 模板仓库地址
branchstring否Git 分支
subdirstring否仓库内的模板子目录
variablesobject否模板变量，JSON 对象
overwriteboolean否允许写入非空目录
keepGitboolean否保留模板仓库的 .git 目录
allowHooksboolean否允许执行模板 Hook

resourceId 与 gitUrl 至少需要提供一个。使用云端模板资源创建项目时，MCP 服务还会记录一次资源访问。

返回： 包含 success、目标目录 targetDir、写入文件数 filesWritten、使用的变量 variables、模板版本 templateCommit（模板仓库的 commit 哈希，用于追溯与审计）、Hook 执行情况（hooksExecuted / hooksSkipped）和警告 warnings。

错误约定： 调用失败时结果带 isError: true，正文为 { ok: false, error: { code, message, suggestion, category } }，其中 suggestion 是面向 AI 的可执行指引（如"向用户确认后以 overwrite 重试"）。

参数示例：

{
  "resourceId": "1",
  "targetPath": "./my-app",
  "variables": { "appName": "my-app" },
  "allowHooks": false
}

MCP 资源

除了工具，MCP 服务还以资源（resources）形式暴露文档内容，AI 可以按需读取：

URI说明
agilebuilder://docs/usageAgent Guide：AI 使用本服务的工作流、工具说明与错误处理指南
agilebuilder://usage/agent-policy智能体使用策略（AI 调用工具时必须遵守的编号规则）
agilebuilder://docs/catalog当前工作空间的资源目录（文档 + 模板）
agilebuilder://local/docs/<id>本地文档资源的正文内容
agilebuilder://cloud/docs/<id>云端文档资源的正文内容

agilebuilder://docs/catalog 会随着当前工作空间中的资源动态变化，同时列出文档和模板（模板含 Git 地址、分支与已解析的变量数量）；AI 通常先读目录，再通过 agilebuilder://local/docs/<id> 或 agilebuilder://cloud/docs/<id> 读取具体文档。读取云端文档要求当前工作空间是云端空间。

客户端配置

支持 MCP 的客户端通常通过一段 JSON 配置接入 stdio 类型的 MCP 服务。AgileBuilder 的通用配置如下：

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

这段配置告诉客户端：名为 agilebuilder 的 MCP 服务，通过执行 agilebuilder-mcp 命令启动。前提是已通过 npm install -g agilebuilder 全局安装，使该命令在 PATH 中可用。

各客户端具体的配置文件位置和写法，见：

与云端空间的关系

未登录时，MCP 服务工作在本地工作空间，AI 只能访问本机保存的资源。

执行 ag login 登录并用 ag space use <space-id> 切换到云端空间后，MCP 服务即可访问该空间中的模板与文档资源，AI 读取到的就是团队在云端维护的最新规范。你在云端空间中的角色权限（owner / admin / member）同样约束 MCP 侧的操作。

下一步