multi-agent-builder

多智能体构建流水线 MCP Server。在 Cursor / Claude Code 等任意 MCP 宿主里说一句"做一个纪念日h5"，宿主模型会扮演梳理(产品经理)→ 开发(工程师)→ 测试(QA) 三个智能体接力工作，最终交付一个完整可运行的前后端项目。

设计哲学：宿主模型当大脑，MCP 只当流水线。 服务器内置 0 个模型调用——不需要任何 API Key。编排纪律(阶段门禁、产物校验、失败回传、修复轮数上限)全部由服务器代码强制执行，不依赖模型的自觉。

架构

Cursor / Claude Code / 任意 MCP 宿主   ← 宿主模型 = 三个智能体的大脑
        │ 调用 MCP 工具
        ▼
┌─────────────────────────────────────┐
│  multi-agent-builder (MCP Server)     │
│  · 阶段状态机: PLANNING→DEVELOPING→  │
│    TESTING→(失败回传,≤3轮)→DONE      │
│  · 权限门禁(代码强制,见下表)           │
│  · 产物校验: PRD 章节/构建结构/测试报告 │
│  · 工具: 文件读写 / shell / 后台服务 /  │
│    HTTP 检查(均限定在任务目录内)        │
└─────────────────────────────────────┘
        │ 产物落盘(会话中断也不丢)
        ▼
~/.multi-agent-builder/projects/<任务名>/  ├─ 01-prd/PRD.md
                                           ├─ 02-src/        ← 完整前后端项目
                                           └─ 03-report/test-report.md

安装

# 方式一:npx 直接跑(推荐,注册宿主时用的就是这种方式)
npx -y multi-agent-builder

# 方式二:全局安装后直接执行
npm install -g multi-agent-builder

从源码开发:

cd multi-agent-builder
npm install
npm run build

要求 Node.js ≥ 18.17(开发环境用 Node 22 验证)。

注册到宿主

Cursor

编辑 MCP 配置(~/.cursor/mcp.json 或 Cursor 设置 → MCP → Add Server):

{
  "mcpServers": {
    "multi-agent-builder": {
      "command": "npx",
      "args": ["-y", "multi-agent-builder"]
    }
  }
}

Claude Code

claude mcp add multi-agent-builder -- npx -y multi-agent-builder

从源码注册(开发本仓库时)

{
  "mcpServers": {
    "multi-agent-builder": {
      "command": "node",
      "args": ["C:/work/multi-agent-builder/dist/index.js"]
    }
  }
}

Windows 下 JSON 里用正斜杠 C:/... 或双反斜杠 C:\\... 均可。路径按实际仓库位置修改。

指定产物目录(可选)

默认情况下,任务产物生成在用户主目录的 ~/.multi-agent-builder/projects/ 下(Windows 为 C:\Users\<用户名>\.multi-agent-builder\projects)。不能用包安装目录——npx 的安装位置在 npm 缓存里,会被清理。想让生成代码落到固定的工作目录,注册时加环境变量 MAB_PROJECTS_DIR:

Cursor:

{
  "mcpServers": {
    "multi-agent-builder": {
      "command": "npx",
      "args": ["-y", "multi-agent-builder"],
      "env": { "MAB_PROJECTS_DIR": "D:/work/ai-projects" }
    }
  }
}

Claude Code:

claude mcp remove --scope user multi-agent-builder
claude mcp add --scope user -e MAB_PROJECTS_DIR="D:/work/ai-projects" multi-agent-builder -- npx -y multi-agent-builder

状态管理(resume_task)、路径越界检查都会跟着新目录走。服务器启动时会在日志里打印实际生效的产物目录,方便确认。

使用方式

在宿主对话里直接说:

用 multi-agent-builder 做一个纪念日 h5

宿主模型会依次调用 start_task → 按返回的阶段指令工作 → 提交各阶段产物。中途想插手,直接对话即可(比如"PRD 里加上背景音乐",宿主会在提交 PRD 前修改)。

工具清单与阶段权限矩阵

| 工具 | 作用 | 梳理 | 开发 | 测试 | 完成 | |---|---|:-:|:-:|:-:|:-:| | start_task | 创建任务,返回梳理指令 | ● | | | | | resume_task | 恢复历史任务 | ● | | | | | get_task_status | 查状态/轮次/待修复项 | ● | ● | ● | ● | | get_stage_instructions | 取当前阶段角色提示词 | ● | ● | ● | ● | | write_file | 写文件 | 仅 01-prd/ | 禁改 01-prd/ | 仅 03-report/ | ✕ | | read_file / list_files | 读文件/文件树 | ● | ● | ● | ● | | run_command | 在 02-src/ 执行命令 | ✕ | ● | ✕ | ✕ | | start_server / stop_server | 后台启停服务 | ✕ | ● | ● | ✕ | | http_check | HTTP 接口/页面检查 | ✕ | ● | ● | ✕ | | submit_prd | PRD 校验→进入开发 | ● | | | | | submit_build | 构建校验→进入测试 | | ● | | | | submit_test_report | 解析报告→交付或回传修复 | | | ● | |

三道校验均为程序化检查(不靠模型判断):PRD 必含 6 个规定章节;构建必须有 package.json + 启动脚本 + 足够的源码文件;测试报告的表格会被逐行解析,"通过/失败"结果与结论交叉校验,失败项自动生成修复清单回传开发阶段,最多 3 轮。

阶段流转

start_task ──→ 梳理 ──submit_prd✓──→ 开发(第1轮) ──submit_build✓──→ 测试
                │                        ↑ │                          │
                └ submit_prd ✗ 修改重交    │ └ submit_build ✗ 补全重交 │ submit_test_report
                                         │                            │   ├─ 全部通过 → 完成🎉 交付
                                         └──── 失败清单回传,轮次+1 ────┤   └─ 有失败且轮次<3 → 开发(下一轮)
                                                                      └─ 有失败且轮次=3 → 完成(遗留问题如实交付)

开发本仓库

npm run dev        # tsx 直接跑 src/index.ts
npm run typecheck  # 类型检查
npm run build      # 编译到 dist/(注册用 dist/index.js)
npm run smoke      # 端到端冒烟测试(门禁/流转/重试闭环共 18 项断言)
npm pack           # 本地打 tarball 验证包内容(加 --dry-run 只预览不落盘)
npm publish        # 发布到 npm(自动触发 prepublishOnly → build)

安全边界与已知限制

• 所有文件工具限定在 projects/<任务名>/ 内,拒绝绝对路径与 .. 越界
• run_command 的工作目录钉死在 02-src/,另有破坏性命令黑名单;但 shell 本质上是宿主机执行,请勿在不可信环境使用
• 流水线依赖宿主模型驱动力:阶段纪律是强制的,但每一步的产出质量取决于宿主选择的模型
• 测试阶段"源码只读"约束的是本 MCP 的 write_file 工具;宿主自身的写文件能力不受本服务器控制(选择可信宿主)

Roadmap

• [ ] Web 控制台:输入框 + 三智能体实时进度 + 交付物预览
• [ ] 开发阶段拆分前端/后端两个并行子流水线
• [ ] 可选内置模型接入(脱离宿主独立/定时运行)
• [ ] Docker 沙箱执行环境