MCP Engineering Team

安装指令

如果你是一个具备 shell 执行能力的 agent（Claude Code、Codex CLI、opencode、Kimi CLI、GLM Code 等），且用户要求"帮我安装/接入这个 MCP"，请按以下步骤顺序执行，每步失败就停止并向用户报告，不要跳步或臆测缺失信息。

本 MCP 的 npm 包名为 @frutacloud/mcp-engineering-team，通过 npx -y @frutacloud/mcp-engineering-team 拉起，无需克隆仓库或本地构建。运行要求为 Node.js 20 或更高版本。

步骤 0：自我识别 判断你当前运行在哪个客户端里（可通过可执行文件名、已知配置目录是否存在等方式判断）。如果无法判断，直接询问用户"你正在用哪个 code 客户端"，不要猜测。

步骤 1：确认配置来源 本服务需要三个环境变量：MODEL_API_KEY、BASE_OPENAI_URL、MODEL_NAME。首次安装且用户没有提供这些值时，主动询问用户，不要编造或写入空值。

读取宿主当前 MCP 条目，向用户确认三个必填变量的值；缺失值必须询问，不得编造、写入占位符或空值。

用户可能额外提供角色级别的模型覆盖（如 SCOUT_MODEL_NAME=deepseek-v4-flash 等），如果用户主动贴了就同步写入 env 对象；如果用户没提，不要主动询问，默认所有角色共用 MODEL_NAME 即可。完整角色列表和命名规则见配置。

步骤 2：定位该客户端的全局 MCP 配置文件 不同客户端的配置文件路径不同，见下方客户端配置对照表。找不到对应客户端时，尝试读取该客户端官方文档中 "MCP server" / "MCP 配置" 相关说明，或询问用户配置文件路径。

步骤 3：写入配置，禁止整体覆盖 读取该配置文件的当前内容，只在其 mcpServers（或该客户端等价字段，如 TOML 里的 mcp_servers）对象中新增或更新 mcp-engineering-team 这一个键（这是注册名/标识符，与 npm 包名不同，见下方说明），保留文件中其他已存在的 MCP 配置项不变。如果文件不存在，创建文件并写入最小合法结构。任何情况下都不要用只包含本服务的新内容整体覆盖已有配置文件。

最小配置如下：

{
  "command": "npx",
  "args": ["-y", "@frutacloud/mcp-engineering-team"],
  "env": {
    "MODEL_API_KEY": "<用户提供的值>",
    "BASE_OPENAI_URL": "<用户提供的值>",
    "MODEL_NAME": "<用户提供的值>"
  }
}

TOML 客户端（如 Codex）按对应语法转写同样的三元组（command / args / env），不要遗漏字段。

步骤 4：验证服务可拉起 不要使用 --help 验证：本服务是 stdio MCP server，不提供命令行帮助输出，标准输出保留给 MCP 协议。

配置写入宿主后，重启该客户端，并使用其 MCP 列表/工具探测功能确认服务已连接。例如 Codex 可执行 codex mcp list 或在 TUI 中使用 /mcp，Claude Code 使用其 MCP 状态查看命令。宿主会把本配置中 env 对象的值传给 MCP 进程；不要把这些值写入系统级环境变量。

手动执行独立的 npx 只适合作为可选的包入口测试。它不会读取 Codex、Claude Code 或其他宿主的配置文件，因此没有同一进程环境时出现 MODEL_NAME is required 等错误是预期行为，不能据此判断已注册的 MCP 配置失败。若从本仓库源码目录测试，先切换到目标项目目录或其他临时目录；不要在包自身的源码目录中用同名 npx 包做发布验证，以免 npm 把当前工作区误当作待执行的本地包。

每次 Job 或 initiative 调用都提供项目的 workspace_root。MCP 根据它把内部状态、Worker 报告、initiative、archive 和 graph 统一存放在 <workspace_root>/.engineering-team/；用户要求交付的 plans/、docs/ 和源码文件仍按指定路径写入项目工作区。

步骤 5：写入全局总工提示词 读取该客户端对应的全局提示词文件（见下表），只确保当前固定启动区块存在且最多一份。这个区块是稳定的宿主引导契约，不承载运行时版本、预算或调度细节：

• 存在一个完整 marker 且内容一致：保持不变。
• 存在一个完整 marker 且内容不一致：替换该 marker 区块为下面的当前固定文本，保留 marker 外的用户内容。
• 存在多个完整 marker：保留第一份当前固定区块，删除其余 marker 区块，保留 marker 外的用户内容。
• 不存在完整 marker：在文件末尾追加下面的固定 marker 区块，不解析其他文本。

如果 marker 只有 start 或 end，或多个 marker 边界无法唯一判断，停止修改并向用户报告，不要盲目覆盖。完成后确认 start/end 各恰好一次，marker 外的其他提示词内容必须保留。

start/end 仅用于安全定位，不是运行时协议；运行时版本和完整规则只以 get_chief_instructions 返回的 src/chief-prompt.mjs 为准。禁止整体覆盖已有提示词文件内容：

<!-- mcp-engineering-team:global-chief-workflow:start -->
# MCP Engineering Team Bootstrap

For engineering tasks, when the `mcp-engineering-team` MCP is available:

- The host assistant is the chief engineer. Before using any Job or initiative operation, call `get_chief_instructions` and treat its response as the authoritative runtime protocol for the current task.
- Choose the smallest valid execution for the objective. Workers provide evidence and execute assigned work; they cannot dispatch sub-workers or make final accept/reject decisions.
- When a Job is active, treat `chief_next_action` as the authoritative state pointer. After a timeout or transport error, inspect the Job status and persisted artifacts before retrying, duplicating work, or cancelling.
- Before calling `accept_job`, inspect the current diff, persisted evidence, and relevant tests. Acceptance is mode-specific: engineering acceptance means implementation evidence is ready; review acceptance means the report and evidence handoff is complete and does not mean findings are fixed. Acceptance does not authorize push, publish, merge, or deploy.
- If the MCP is unavailable, do not pretend delegation occurred; handle the task directly or explain the limitation.
- This block is a stable bootstrap only. Do not duplicate runtime budgets, retry rules, task tiers, model choices, test procedures, tool procedures, or project-specific workflows here. The `get_chief_instructions` response is authoritative.
<!-- mcp-engineering-team:global-chief-workflow:end -->

步骤 6：回报结果 向用户总结：已处理哪个配置文件、更新了哪个注册项、写入了哪些变量名（不泄露值）、总工区块校验结果、最终校验和连接验证是否通过。不要省略这一步，让用户能确认改动范围。

客户端配置对照表

| 客户端 | 全局 MCP 配置文件 | 字段名 | 全局提示词文件 | | -------------------------- | ---------------------------------- | ------------------------------ | -------------------------------- | | Codex | ~/.codex/config.toml | mcp_servers | ~/.codex/AGENTS.md | | Claude Code | ~/.claude.json（--scope user） | mcpServers | ~/.claude/CLAUDE.md | | opencode | 参见 opencode 官方 MCP 文档 | 通常为 mcpServers | 参见其全局 instructions 文件说明 | | Kimi CLI / GLM Code / 其他 | 参见各自官方 MCP 接入文档 | 通常为 mcpServers 或等价字段 | 参见其全局 instructions 文件说明 |

未在表中列出的客户端，只要支持标准 MCP stdio 协议，均可套用步骤 3 中的 command/args/env 三元组；具体文件路径以该客户端官方文档为准，不要凭经验猜测路径后直接写入。

配置

必填

| 变量 | 说明 | | ----------------- | ------------------------- | | MODEL_API_KEY | API 密钥 | | BASE_OPENAI_URL | Chat Completions 端点地址 | | MODEL_NAME | 默认模型名，所有角色共用 |

三个必填项缺一不可，服务启动时会校验。

可选：角色级别覆盖

每个角色支持独立覆盖模型名和 reasoning effort，命名规则为 <ROLE>_MODEL_NAME 和 <ROLE>_REASONING_EFFORT。未覆盖时使用 MODEL_NAME / 不传 effort。

| 角色 key | 职责 | | ------------------ | ------------------------------------------ | | SCOUT | 定位映射代码路径 | | ARCHITECT | 设计边界与权衡分析 | | REVIEWER | 审查正确性/回归/测试 | | SECURITY | 安全风险审查 | | IMPLEMENTER | 代码实现 | | TESTER | 独立验证与测试 | | IMAGE_ANALYST | 截图/UI/架构图分析（需多模态） | | VERIFIER | 对抗性验证 | | SYNTHESIZER | 聚合多 worker 证据生成共识报告 | | FRONTEND | 前端实现 | | BACKEND | 后端实现 | | UI_DESIGNER | UI/视觉设计（需多模态） | | DESIGN_REVIEWER | 方案完整性、契约、失败路径和实现就绪度审查 | | SOLUTION_AUDITOR | 独立挑战方案假设、遗漏、复杂度和运营风险 | | ENGINEER | 通用工程师 |

REASONING_EFFORT 取值：low、medium、high。完整带注释的配置示例见本仓库 .env.example。

给 agent 的注意：这些覆盖是可选的，用户不提就不问。如果用户贴了角色变量就写入 env，不要自行编造模型名——你没有可用的模型列表，让用户自己决定用什么模型。

运行预算与有界观察

服务端默认按真实工程任务放宽预算：Job 12 小时、一般 Worker 2 小时、实现类 Worker 4 小时、静默 watchdog 90 分钟；单 Worker 默认最多 300 个模型轮次、1500 次工具调用。20/40/60 分钟只用于判断何时值得观察小型、跨文件和全仓任务，不是取消期限。创建 Job 时可在服务端允许范围内通过 timeouts 设置初始预算；运行中需要增加时使用 extend_job_runtime，不要取消后重复派发。

MAX_STALE_ROUNDS 默认是 30，表示连续无新证据轮数；成功的新读取、搜索、写入、命令结果、blackboard finding 或总工提问会重置计数，重复失败仍由更早的失败保护停止。独立的 MAX_MODEL_ROUNDS 才是总轮次安全上限。到达边界会先生成 uncertain 部分报告并保留 checkpoint；reject 后可通过 update_worker_task 恢复该 Worker，下一次执行会收到 checkpoint。总工使用 watch_engineering_team 等待语义动作变化：普通模型轮次和工具遥测不会唤醒，响应也不展开完整 Worker、报告或 checkpoint。Worker 压缩只摘要执行历史，原始 system prompt、任务 brief 和有效验收条件始终原样固定；公开状态只返回 checkpoint 的有界投影，从而控制非流式宿主与长任务的上下文增长。

npx 安装

本服务已发布到 npm，包名为 @frutacloud/mcp-engineering-team。生产使用推荐直接通过 npx 拉取发布版本，不需要克隆仓库、安装依赖或本地构建。

命名说明：npm 包名（@frutacloud/mcp-engineering-team，用于 npx/npm install）与下方 MCP 注册名（mcp-engineering-team，即 mcpServers 配置里的 key、codex mcp add 的第一个参数）是两个独立的标识符，无需一致。注册名是你在客户端里给这个 MCP 起的名字，包名是 npm 上实际的发布单元；本文档统一使用不带 scope 的 mcp-engineering-team 作为注册名，避免部分客户端配置字段对 @、/ 等字符支持不佳。

1. 快速验证（可选）

注册到宿主后，建议优先重启宿主并通过 MCP 工具列表验证。宿主配置中的 env 会按 MCP 进程作用域注入，不会污染系统环境变量。

codex mcp list

如果必须手动测试 npm 包，请使用能为子进程提供临时环境映射的运行器，并从目标项目目录或其他非本 MCP 源码目录启动；不要设置持久化的系统环境变量，也不要使用 --help 代替 stdio 启动验证。

2. 注册为全局 MCP

npx 只负责"拉取并运行"这个包，不会自动把它注册进任何客户端的 MCP 列表，也不会读取本 README 的任何内容——注册和全局总工提示词仍需按下方步骤手动配置。

下面的命令和配置示例用于当前安装。写入前必须读取当前条目并只更新 mcp-engineering-team，不要把带有占位符的示例直接写回配置，也不要重复追加同名注册项或总工提示词。

本服务不依赖任何客户端私有能力，只使用标准 MCP stdio 协议，因此服务入口可运行于 Linux、macOS、Windows 上支持该协议的 code 客户端：Codex、Claude Code、opencode、Kimi CLI、GLM Code 等。注册方式的共同模式都是：

{
  "command": "npx",
  "args": ["-y", "@frutacloud/mcp-engineering-team"],
  "env": {
    "MODEL_API_KEY": "sk-xxxx",
    "BASE_OPENAI_URL": "https://xxxx",
    "MODEL_NAME": "xxxx"
  }
}

区别只在于：① 这段配置写在哪个文件/用哪个命令注册（每个客户端不同）；② 是否支持"用户级/全局" scope，还是只有项目级配置。具体注册方式请查阅对应客户端的 MCP 接入文档；下面给出目前验证过的两个客户端的完整示例，其余客户端按同样的 command/args/env 三元组套用即可。

Codex

下面的 CLI 写法会把三个值写入 MCP 的进程级 env 配置；不会修改系统环境变量。为避免密钥进入 shell 历史记录，也可以直接使用后面的 config.toml 配置。

codex mcp add mcp-engineering-team --env "MODEL_API_KEY=<用户提供的值>" --env "BASE_OPENAI_URL=<用户提供的值>" --env "MODEL_NAME=<用户提供的值>" -- npx -y @frutacloud/mcp-engineering-team

或直接编辑 ~/.codex/config.toml：

[mcp_servers.mcp-engineering-team]
command = "npx"
args = ["-y", "@frutacloud/mcp-engineering-team"]

[mcp_servers.mcp-engineering-team.env]
MODEL_API_KEY = "sk-xxxx"
BASE_OPENAI_URL = "https://xxxx"
MODEL_NAME = "xxxx"

Claude Code

下面的命令只注册启动命令；使用 CLI 注册后，仍必须按后面的完整 JSON 配置补充 env。不要把三个值设置为系统环境变量。

claude mcp add mcp-engineering-team --scope user -- npx -y @frutacloud/mcp-engineering-team

或直接编辑 ~/.claude.json 里对应 user scope 的 mcpServers 字段：

{
  "mcpServers": {
    "mcp-engineering-team": {
      "command": "npx",
      "args": ["-y", "@frutacloud/mcp-engineering-team"],
      "env": {
        "MODEL_API_KEY": "sk-xxxx",
        "BASE_OPENAI_URL": "https://xxxx",
        "MODEL_NAME": "xxxx"
      }
    }
  }
}

3. 配置项传递

MODEL_API_KEY、BASE_OPENAI_URL、MODEL_NAME 等配置项在 npx 场景下不会读取调用方项目里的 .env 文件。正式接入时必须通过宿主配置的 env 字段传入；角色专属的 model / reasoning effort 等可选项同样加入同一个 env 对象。该 env 是 MCP 进程级配置，不是系统级环境变量。