copilot-codex-review-mcp

v0.1.1

Published

a month ago

Review-only Codex MCP server for GitHub Copilot CLI with async code and task completion review workflows.

0High
0Medium
0Low

leenbj

copilot github-copilot-cli codex mcp review ai

copilot-codex-review-mcp

一个专门给 GitHub Copilot CLI 使用的、基于 OpenAI Codex 的代码审查 MCP 服务。

它解决的是这样一类工作流：

你先完成一个任务
让 Copilot CLI 调用 Codex 对当前改动做审查
你可以继续并行做下一个任务
审查结束后，再根据结构化结果决定是否修复、补测试或重新审查

这个 MCP 只做 review，不负责直接修改代码。它当前提供两类核心能力：

codex_review：代码变更审查
codex_review_completion：任务完成度审查

此外还支持：

codex_status：查询异步任务状态
codex_result：读取异步任务结果
codex_cancel：取消异步任务

1. 适用场景

这个 MCP 适合以下场景：

在提交前让 Codex 做一次严格代码审查
检查“这个任务到底算不算完成”
用验收标准、测试结果、git diff 来评估任务完成度
启动异步审查后继续开发，不阻塞当前工作
让 Copilot CLI 把 Codex 的结论作为后续决策输入

它不适合这些场景：

直接让 Codex 写代码
让 Codex 自动修改当前工作区
作为通用代理执行器使用

2. 功能总览

2.1 `codex_review`

用于审查当前工作树或分支 diff。

它会重点关注：

安全风险
逻辑错误
竞态条件
边界条件遗漏
潜在回归
高风险设计问题

返回结果是结构化的，典型字段包括：

verdict
summary
findings
next_steps

其中 verdict 取值为：

approve
needs-attention

2.2 `codex_review_completion`

用于判断“任务是否真的完成”。

它不是只看代码是否能跑，而是看：

任务描述是否满足
验收标准是否满足
Definition of Done 是否满足
测试 / lint / build 等验证证据是否支持“完成”这个结论

返回结果是结构化的，典型字段包括：

verdict
summary
completed_items
missing_items
risks
next_actions

其中 verdict 取值为：

complete
partial
blocked

2.3 异步审查

这个 MCP 支持同步和异步两种模式：

sync：阻塞直到审查完成
async：立即返回 job_id，后续再查状态和结果

异步模式适合你描述的真实工作流：

完成任务 A
发起 Codex 审查
继续开发任务 B
审查结果回来后再处理任务 A 的修复

3. 前置要求

使用前请先确认以下条件已经满足：

3.1 Node.js

要求：

Node.js 20 或更高版本

检查命令：

node -v

3.2 Codex CLI

你必须已经安装并登录 Codex CLI。

检查命令：

codex --version

如果还没登录：

codex login

3.3 Git 仓库

被审查的目标目录必须是 Git 仓库，因为这个 MCP 会读取：

working tree diff
branch diff
git status

检查命令：

git rev-parse --is-inside-work-tree

3.4 GitHub Copilot CLI

你需要已经安装 GitHub Copilot CLI，并且你的版本支持 MCP 配置和自定义 agent。

4. 安装方式

支持两种安装方式。

4.1 全局安装，推荐

适合你想在多个项目里复用。

npm install -g copilot-codex-review-mcp

安装后可执行命令是：

copilot-codex-review-mcp

检查是否安装成功：

which copilot-codex-review-mcp

4.2 项目内安装

适合你想把版本固定在某个项目里。

npm install -D copilot-codex-review-mcp

这种方式下，Copilot CLI MCP 配置通常要显式写 node 和本地路径。

5. GitHub Copilot CLI MCP 配置

GitHub Copilot CLI 的 MCP 配置通常放在：

~/.copilot/mcp-config.json

5.1 全局安装后的推荐配置

如果你已经全局安装了本包，推荐使用下面这份配置：

{
  "mcpServers": {
    "codex-review": {
      "type": "local",
      "command": "copilot-codex-review-mcp",
      "args": [],
      "env": {},
      "tools": ["*"]
    }
  }
}

你也可以直接参考：

docs/copilot-mcp-config.example.json

5.2 项目内安装后的配置

如果你没有全局安装，而是用项目内安装，可以写成：

{
  "mcpServers": {
    "codex-review": {
      "type": "local",
      "command": "node",
      "args": [
        "/绝对路径/到/项目/node_modules/copilot-codex-review-mcp/dist/src/server.js"
      ],
      "env": {},
      "tools": ["*"]
    }
  }
}

5.3 配置完成后要做什么

配置写完后：

重启 GitHub Copilot CLI
确认 MCP server 被识别
再开始调用 review 工具

6. 自定义 Agent

这个项目附带了一个 Copilot CLI 自定义 agent：

.github/agents/codex-review.agent.md

这个 agent 的作用是让 Copilot CLI 更容易在对话里自动选择：

什么时候用 codex_review
什么时候用 codex_review_completion
什么时候应该用异步模式

如果你想在自己的项目里使用，可以把这个文件复制到目标仓库：

.github/agents/codex-review.agent.md

7. 工具说明

下面是每个 MCP tool 的详细说明。

7.1 `codex_review`

用于代码审查。

输入参数

| 参数 | 必填 | 说明 | |------|------|------| | cwd | 是 | 目标项目的绝对路径 | | mode | 否 | sync 或 async，默认 sync | | scope | 否 | auto / working-tree / branch，默认 auto | | base_ref | 否 | 基准分支，例如 main | | task_id | 否 | 任务标识，用于异步关联 | | focus | 否 | 要重点关注的问题，例如“检查 race condition” | | project_summary | 否 | 项目背景说明 |

返回结果

同步模式下，典型返回结构：

{
  "verdict": "approve",
  "summary": "没有发现阻塞发布的问题",
  "findings": [],
  "next_steps": []
}

或者：

{
  "verdict": "needs-attention",
  "summary": "发现 2 个需要先修复的问题",
  "findings": [
    {
      "severity": "high",
      "title": "缺少权限校验",
      "body": "某条代码路径缺少权限判断",
      "file": "src/auth.ts",
      "line_start": 10,
      "line_end": 30,
      "recommendation": "增加权限校验并补回归测试"
    }
  ],
  "next_steps": [
    "修复权限校验",
    "增加回归测试"
  ]
}

7.2 `codex_review_completion`

用于任务完成度审查。

输入参数

| 参数 | 必填 | 说明 | |------|------|------| | cwd | 是 | 目标项目的绝对路径 | | task | 是 | 任务描述 | | acceptance_criteria | 是 | 验收标准数组 | | definition_of_done | 否 | 完成定义数组 | | verification | 否 | 测试、lint、build、附加说明 | | mode | 否 | sync 或 async | | task_id | 否 | 任务标识 | | base_ref | 否 | 比较基准分支 | | project_summary | 否 | 项目背景说明 |

返回结果

{
  "verdict": "partial",
  "summary": "功能已基本完成，但验收标准还缺一项",
  "completed_items": [
    "主流程已实现"
  ],
  "missing_items": [
    "缺少错误场景验证"
  ],
  "risks": [
    "异常路径行为尚未证明正确"
  ],
  "next_actions": [
    "增加错误场景测试",
    "重新发起完成度审查"
  ]
}

7.3 `codex_status`

用于查询异步任务状态。

输入参数

| 参数 | 必填 | |------|------| | cwd | 是 | | job_id | 是 |

可能状态

queued
running
completed
failed
cancelled

7.4 `codex_result`

用于读取异步任务结果。

输入参数

| 参数 | 必填 | |------|------| | cwd | 是 | | job_id | 是 |

7.5 `codex_cancel`

用于取消异步任务。

输入参数

| 参数 | 必填 | |------|------| | cwd | 是 | | job_id | 是 |

8. 如何实际使用

8.1 场景一：代码改完后做一次同步审查

例如你刚完成一项改动，想马上看有没有高风险问题：

Use codex_review with:
cwd=/absolute/path/to/project
mode=sync
scope=working-tree
task_id=task-auth-refactor
focus=Check auth and permission risks

8.2 场景二：异步审查后继续开发

先发起异步审查：

Use codex_review with:
cwd=/absolute/path/to/project
mode=async
scope=working-tree
task_id=task-editor-save
focus=Check save logic, race conditions, and regression risk

返回一个 job_id 后，你继续开发别的任务。

之后查询状态：

Use codex_status with:
cwd=/absolute/path/to/project
job_id=<your-job-id>

读取结果：

Use codex_result with:
cwd=/absolute/path/to/project
job_id=<your-job-id>

8.3 场景三：检查任务是否真的完成

Use codex_review_completion with:
cwd=/absolute/path/to/project
mode=sync
task=实现 review MCP
acceptance_criteria=["支持代码审查","支持完成度审查","支持异步状态查询"]
definition_of_done=["npm run check 通过","文档更新完成"]

9. 项目内状态存储

每个被审查的项目里会生成：

.codex-review/
  jobs/
  results/
  logs/

含义如下：

jobs/：任务元数据
results/：结构化审查结果
logs/：运行日志

一般建议把 .codex-review/ 加进 .gitignore。

10. 更新方式

10.1 全局安装用户更新

npm install -g copilot-codex-review-mcp@latest

10.2 指定版本更新

npm install -g [email protected]

更新后建议：

重启 GitHub Copilot CLI
再重新调用 MCP 工具

11. 常见问题

11.1 为什么提示找不到 `codex`

说明 Codex CLI 没装好，或者当前 shell 环境里不可见。

先检查：

codex --version

11.2 为什么提示不是 git 仓库

因为 review 依赖 git diff。

请先在目标项目里确认：

git rev-parse --is-inside-work-tree

11.3 为什么异步任务查不到结果

常见原因：

cwd 传错了
job_id 传错了
审查还没完成
任务失败了

先用：

Use codex_status with:
cwd=/absolute/path/to/project
job_id=<your-job-id>

11.4 为什么一定要传 `cwd`

因为这个 MCP 把状态保存在目标项目目录里，而不是全局目录。
不传 cwd，服务就无法知道应该在哪个项目下读取：

git diff
.codex-review/jobs
.codex-review/results

11.5 为什么这个 MCP 不直接帮我改代码

这是刻意的设计边界。
当前项目只负责 review，不负责写代码或自动修复，这样行为更稳定，也更容易作为审查工具复用。

12. 发布

如果你是维护者，发布流程如下：

npm run check
npm run pack:check
npm publish

如果 npm 账号开启了 2FA，发布时还需要完成一次浏览器确认或 OTP 验证。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

copilot-codex-review-mcp

1. 适用场景

2. 功能总览

2.1 codex_review

2.2 codex_review_completion

2.3 异步审查

3. 前置要求

3.1 Node.js

3.2 Codex CLI

3.3 Git 仓库

3.4 GitHub Copilot CLI

4. 安装方式

4.1 全局安装，推荐

4.2 项目内安装

5. GitHub Copilot CLI MCP 配置

5.1 全局安装后的推荐配置

5.2 项目内安装后的配置

5.3 配置完成后要做什么

6. 自定义 Agent

7. 工具说明

7.1 codex_review

输入参数

返回结果

7.2 codex_review_completion

输入参数

返回结果

7.3 codex_status

输入参数

可能状态

7.4 codex_result

输入参数

7.5 codex_cancel

输入参数

8. 如何实际使用

8.1 场景一：代码改完后做一次同步审查

8.2 场景二：异步审查后继续开发

8.3 场景三：检查任务是否真的完成

9. 项目内状态存储

10. 更新方式

10.1 全局安装用户更新

10.2 指定版本更新

11. 常见问题

11.1 为什么提示找不到 codex

11.2 为什么提示不是 git 仓库

11.3 为什么异步任务查不到结果

11.4 为什么一定要传 cwd

11.5 为什么这个 MCP 不直接帮我改代码

12. 发布

2.1 `codex_review`

2.2 `codex_review_completion`

7.1 `codex_review`

7.2 `codex_review_completion`

7.3 `codex_status`

7.4 `codex_result`

7.5 `codex_cancel`

11.1 为什么提示找不到 `codex`

11.4 为什么一定要传 `cwd`