cursor-codex-review-mcp

将 OpenAI Codex 的代码审查能力集成到 Cursor IDE 的 MCP 服务器。

支持对代码变更进行自动化审查、任务完成度验证，以及对方案/Spec 文档的合理性评估。支持同步和异步两种模式，异步模式下可以在 Codex 审查的同时继续开发下一个任务。

功能概述

代码审查（codex_review）

基于 git diff 对代码变更进行深度审查，返回结构化的审查发现：

• 识别安全风险、逻辑缺陷、竞态条件等问题
• 按严重等级（high / medium / low）分类
• 精确到文件和行号的问题定位
• 包含具体的修复建议
• 返回 approve（通过）或 needs-attention（需要关注）判定

任务完成度验证（codex_review_completion）

基于验收标准和 git 证据，检查任务是否真正完成：

• 逐条核对验收标准的满足情况
• 列出已完成项和缺失项
• 评估风险和阻塞因素
• 返回 complete（完成）/ partial（部分完成）/ blocked（阻塞）判定

方案 / Spec 文档审查

通过 focus 参数引导 Codex 从方案质量角度进行评估：

• 评估问题定义是否清晰
• 判断方案是否为最优解
• 检查验收标准是否可测量
• 发现遗漏的风险和边缘情况
• 提供改进建议

异步审查

• 启动审查后不阻塞，可继续其他工作
• 通过 codex_status 轮询状态
• 通过 codex_result 获取完整结果
• 通过 codex_cancel 取消运行中的审查
• Diff 在启动时快照固化，后续编辑不影响审查结果

前置要求

• Node.js 20+
• Codex CLI — 已安装并认证（codex auth login）
• Git 仓库 — 审查目标必须是 git 管理的项目

安装

全局安装（推荐）

npm install -g cursor-codex-review-mcp

项目本地安装

npm install -D cursor-codex-review-mcp

从源码构建

git clone https://github.com/leenbj/cursor-codex-review-mcp.git
cd cursor-codex-review-mcp
npm install
npm run build

Cursor MCP 配置

全局配置

在 Cursor 的 MCP 设置中添加：

{
  "mcpServers": {
    "codex-review": {
      "command": "cursor-codex-review-mcp",
      "args": []
    }
  }
}

项目本地配置

如果使用项目本地安装：

{
  "mcpServers": {
    "codex-review": {
      "command": "node",
      "args": [
        "./node_modules/cursor-codex-review-mcp/dist/src/server.js"
      ]
    }
  }
}

详见 docs/cursor-mcp-example.json。

MCP 工具详细说明

codex_review — 代码审查

审查当前工作树或分支的代码变更。

| 参数 | 必填 | 说明 | |------|------|------| | cwd | 是 | 目标项目的绝对路径 | | mode | 否 | sync（默认，阻塞等待结果）或 async（后台运行） | | scope | 否 | auto（默认）/ working-tree / branch | | base_ref | 否 | 分支比较基准（如 main） | | task_id | 否 | 任务关联 ID | | focus | 否 | 引导 Codex 关注的特定方面 | | project_summary | 否 | 项目背景描述 |

返回结构（sync 模式）：

{
  "verdict": "approve | needs-attention",
  "summary": "审查总结",
  "findings": [
    {
      "title": "问题标题",
      "body": "问题详细描述",
      "file": "src/example.ts",
      "line_start": 10,
      "line_end": 20,
      "severity": "high | medium | low",
      "recommendation": "修复建议"
    }
  ],
  "next_steps": ["建议的后续操作"]
}

codex_review_completion — 任务完成度验证

检查任务是否满足验收标准。

| 参数 | 必填 | 说明 | |------|------|------| | cwd | 是 | 目标项目的绝对路径 | | task | 是 | 任务描述 | | acceptance_criteria | 是 | 验收标准数组 | | mode | 否 | sync（默认）或 async | | definition_of_done | 否 | 完成定义 | | base_ref | 否 | 不传则审查工作树，传入则审查分支 diff | | task_id | 否 | 任务关联 ID | | project_summary | 否 | 项目背景描述 | | verification | 否 | 验证证据（tests/lint/build/notes） |

返回结构（sync 模式）：

{
  "verdict": "complete | partial | blocked",
  "summary": "完成度总结",
  "completed_items": ["已完成项"],
  "missing_items": ["缺失项"],
  "next_actions": ["建议的后续操作"],
  "risks": ["风险项"]
}

codex_status — 查询异步任务状态

| 参数 | 必填 | 说明 | |------|------|------| | cwd | 是 | 目标项目的绝对路径 | | job_id | 是 | 异步任务 ID |

返回：queued / running / completed / failed / cancelled

codex_result — 获取异步任务结果

| 参数 | 必填 | 说明 | |------|------|------| | cwd | 是 | 目标项目的绝对路径 | | job_id | 是 | 已完成的异步任务 ID |

codex_cancel — 取消异步任务

| 参数 | 必填 | 说明 | |------|------|------| | cwd | 是 | 目标项目的绝对路径 | | job_id | 是 | 运行中的异步任务 ID |

Cursor 规则文件配置

本项目提供了两个 Cursor 规则文件（.mdc），用于让 AI agent 自动判断何时以及如何使用 Codex Review。建议将它们复制到你的项目中。

双层规则架构

.cursor/rules/
  codex-review-trigger.mdc   ← 轻量触发规则（始终加载，~20 行）
  codex-review.mdc            ← 完整使用指南（按需加载，~180 行）

第一层：自动触发规则

文件： .cursor/rules/codex-review-trigger.mdc

作用： 在每个对话中自动加载（alwaysApply: true），告诉 AI agent 在完成代码修改后检查是否需要触发 Codex Review。仅包含触发条件的摘要，消耗极少的上下文 token。

配置方式：

1. 将 .cursor/rules/codex-review-trigger.mdc 复制到你的项目 .cursor/rules/ 目录
2. 确认 frontmatter 中 alwaysApply: true

触发条件摘要：

• 必须审查：安全代码、公共 API、数据库 schema、提交前门禁
• 主动审查：跨 3+ 文件修改、数据流重构、新功能、bug 修复
• 跳过：纯格式/文档修改、<10 行的明显正确修改

第二层：完整使用指南

文件： .cursor/rules/codex-review.mdc

作用： 按需加载（alwaysApply: false），包含 Codex Review 的完整使用指南。当第一层规则判断需要 review 时，agent 会读取此文件获取详细指导。

配置方式：

1. 将 .cursor/rules/codex-review.mdc 复制到你的项目 .cursor/rules/ 目录
2. 确认 frontmatter 中 alwaysApply: false

包含内容：

• 触发条件优先级规则（强制 > 自动 > 跳过）
• 工具选择指南
• 模式选择决策树（sync vs async）
• 审查范围选择（scope / base_ref）
• 异步并行开发策略
• 异步工作流（启动/轮询/获取/取消）
• 审查结果处理（按工具类型分离）
• 方案/Spec 文档审查指南
• 调用规范

为什么采用双层架构？

| 方案 | 问题 | |------|------| | 全部 alwaysApply: true | 每个对话都注入 ~180 行规则，浪费上下文 token | | 全部 alwaysApply: false | agent 在完成代码修改后不知道应该触发 review | | 双层架构 | 轻量触发规则始终在，完整指南按需加载 |

使用示例

同步代码审查

调用 codex_review：
  cwd: "/your/project"
  mode: "sync"
  scope: "working-tree"
  focus: "检查安全性和竞态条件"
  project_summary: "电商平台后端 API"
→ 阻塞等待，直接返回审查结果

异步代码审查

1. 调用 codex_review（mode: "async"）→ 返回 job_id
2. 继续开发下一个任务...
3. 调用 codex_status（job_id）→ "running" / "completed"
4. 调用 codex_result（job_id）→ 获取完整审查结果
5. 根据审查结果修复代码

方案 / Spec 审查

调用 codex_review：
  cwd: "/your/project"
  mode: "sync"
  scope: "working-tree"
  focus: "目的：为支付系统添加退款能力。请评估：
    1) 问题定义是否清晰
    2) 方案是否最优
    3) 验收标准是否可测量
    4) 有哪些遗漏的风险"
  project_summary: "电商平台，当前支持支付但不支持退款"

任务完成度验证

调用 codex_review_completion：
  cwd: "/your/project"
  mode: "sync"
  task: "实现用户注册功能"
  acceptance_criteria:
    - "支持邮箱注册"
    - "密码强度验证"
    - "注册后发送确认邮件"
  verification:
    tests: "npm test - 15 tests passing"
    lint: "无 lint 错误"

项目本地存储

每个被审查的项目会在根目录生成 .codex-review/ 目录：

.codex-review/
  jobs/       ← 任务状态记录
  results/    ← 审查结果
  logs/       ← 运行日志
  runner.js   ← 自动生成的 runner 脚本

建议在 .gitignore 中添加：

.codex-review/

发布

npm run check      # 构建 + 测试
npm run pack:check  # 检查打包内容
npm publish         # 发布到 npm

许可

MIT