codex-workbuddy-mcp

让 Codex 负责规划和评审，WorkBuddy 负责本地开发与自测 的独立 MCP 服务。

需求 → Codex 规划和验收标准 → WorkBuddy 开发/自测
                                   ↓
交付 ← Codex 验收通过 ← 代码检查和独立验证
                                   ↓ 不通过
                            原 WorkBuddy 会话返工

使用本机 WorkBuddy 桌面版内置 CLI，通过 stdio MCP 暴露任务执行、查询、评审、续接和取消能力。参考 LinHaiJ/workbuddy-mcp 的 CLI 桥接设计，服务与任务管理由本项目实现，无需 DSH。参考项目许可证保留在 THIRD_PARTY_NOTICES.md。

环境要求

• Node.js 22 或更新版本。

• 本机已安装并登录 WorkBuddy；已在 macOS / WorkBuddy 5.5.6 验证。

• 默认调用 /Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy，可以用 WB_CLI 指定其他 JavaScript CLI 启动脚本。

当前实现面向 macOS，其他平台与 WorkBuddy 版本需另行验证。模型和账号可用性由 WorkBuddy 提供。

Related MCP server: sub-antigravity

安装与接入

git clone git@github.com:Aaperture/codex-workbuddy-mcp.git
cd codex-workbuddy-mcp
npm ci --ignore-scripts
npm test

在 Codex 的 MCP 配置中添加以下内容，并将示例路径替换成实际绝对路径：

[mcp_servers.workbuddy_local]
command = "node"
args = ["/absolute/path/to/codex-workbuddy-mcp/src/server.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 30

[mcp_servers.workbuddy_local.env]
WB_CLI = "/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy"
WB_MODEL = ""
WB_ALLOWED_ROOTS = '["/absolute/path/to/your/projects"]'
WB_STATE_DIR = "/absolute/path/to/codex-workbuddy-mcp/.state"

如果桌面客户端找不到 node，把 command 改成 node -p 'process.execPath' 输出的绝对路径。保存后重新加载 MCP 或重启客户端。Codex 官方 MCP 配置文档

其他 MCP 客户端可参考 mcp-config.example.json。该文件包含占位路径，使用前需要修改。

MCP 参数

参数在服务启动时读取，修改后重新加载 MCP。

指定默认模型

在 MCP 环境参数中填写：

WB_MODEL = "your-model-id"

• 新任务显式传入 model 时优先使用它；否则使用 WB_MODEL，均未设置时由 WorkBuddy 自行选择。

• 新任务选定的默认模型会写入任务记录，服务默认值变化不会改变已有任务。

• 续接未传 model 时继承原任务；显式传入时切换模型。

• 没有固定模型的旧任务交给 WorkBuddy 按原会话恢复。

workbuddy_status 不传 taskId 会返回当前 defaultModel；任务结果的 model 和 modelSource 表示实际选择与来源。modelSource 取值为 request、server_default、inherited 或 workbuddy_default。

MCP 不维护固定模型清单。可运行本机 CLI 的 --help 查看其列出的模型；账号权限与实际调用结果仍由 WorkBuddy 决定。

五个工具

workbuddy_start 必填参数是 prompt、cwd、acceptanceCriteria；cwd 必须是存在的绝对路径。

可选参数：model、effort、timeoutSeconds、maxTurns、maxReviewRounds。effort 支持 minimal / low / medium / high / xhigh / max，是否生效取决于 WorkBuddy 模型。

单次执行默认最多600秒和20个执行轮次；评审总轮数默认3（包含第一次），最多可设10。续接默认继承原参数，达到评审轮数上限后不会继续。

status=succeeded 表示 CLI 正常返回，不等于测试或验收已经通过。review.verdict=approve 才表示 Codex 已记录验收。服务器保存验证证据，但不自行判断自然语言要求是否满足。

在 Codex 中使用

可以这样发出任务：

使用 workbuddy_local：先制定方案与可验证标准，让 WorkBuddy 开发、自测。你读取实际文件和差异，独立验证关键测试；不通过就记录 request_changes 并续接，满足标准后记录 approve。失败、超时或模型请求停滞时，先检查已有产物再决定如何处理。

任务以 session ID 续接，避免全局 --continue 串任务。每次续接都保留原验收标准；同一目录或父子重叠目录的未完成任务不能同时启动。

本地诊断客户端

scripts/call.mjs 使用正式 MCP SDK 连接本项目服务，通过 JSON 文件传递工具参数：

node scripts/call.mjs workbuddy_start /absolute/path/to/task.json --wait
node scripts/call.mjs workbuddy_status /absolute/path/to/status.json

任务 JSON 示例：

{
  "cwd": "/absolute/path/to/project",
  "prompt": "实现需求，运行测试并报告结果",
  "acceptanceCriteria": ["功能满足规划", "相关测试通过"],
  "timeoutSeconds": 600
}

查询 JSON 示例：{"taskId":"工具返回的任务UUID"}。--wait 保持连接到任务结束；连接断开时服务会中止未完成任务。

同一状态目录只允许一个服务进程。如果 Codex 已连接服务，请使用它暴露的 MCP 工具。独立诊断客户端可以配置其他 WB_STATE_DIR，但不同状态目录的任务锁不共享，不要向同一个代码目录并行派发任务。

执行边界与故障处理

• 使用 spawn 的参数数组和 shell:false，多行任务通过 stdin 传递。

• 限制日志大小并按 UTF-8 分块解析输出；识别错误结果，支持超时与进程组终止。

• 通过进程级设置允许 Read/Write/Edit/Glob/Grep/Bash，使用 dontAsk 模式，限制代理委托和消息类工具，并禁用其他 MCP。不会修改 WorkBuddy 的全局权限。

• 进程级关闭自动记忆与提取。WorkBuddy 自身仍会管理登录态、会话记录与运行日志。

• 工作目录检查限制派发入口，不是操作系统沙箱。允许的 Bash 与文件工具仍可能访问目录外路径；需要强隔离时应另加容器或系统沙箱。

• 正常关闭服务会停止子任务；强制杀死服务后，重启会把未完成记录标为 interrupted，需要先检查文件和可能遗留的进程。

• 没有自动选择备用模型的策略；调用方可以检查日志，再显式指定模型续接。

.state 含任务描述、代码输出与路径，默认不提交 Git。项目忽略本机环境文件、日志、密钥文件和依赖目录。

示例与验证

• 计算器示例：四则运算、括号、小数、一元号、输入限制与错误处理。

• Unicode slugify 示例：规范化、Unicode字母/数字处理与CLI。

示例源码由 WorkBuddy 开发并自测，再由 Codex 检查和验证。公开仓库保留源码和规划，本机执行日志、账号信息与私有路径不发布。

MCP测试使用假的 CLI 检查协议、进程控制、默认模型透传、续接继承和评审状态；运行 npm test 验证。可分别在两个示例目录运行 npm test 验证示例。

贡献与许可证

欢迎通过 fork/PR 提交建议，主干由 @Aaperture 推送和合入，详见 CONTRIBUTING.md。仓库规则负责执行主干访问限制。

本项目使用 Apache-2.0 许可证。参考项目的 MIT 许可证与归属信息见 THIRD_PARTY_NOTICES.md。