# codex-mcp

一个 MCP Server，让 Claude Code 通过 MCP 协议将编码任务委托给 Codex 执行。

## 解决什么问题

Claude Code 擅长理解需求、拆分任务、审查代码，但逐行写代码效率受限。Codex 擅长在 sandbox 中快速实现代码，但缺乏全局视野和审查能力。

手动在两个工具间切换的问题：

- 需要人工复制粘贴上下文，容易丢失信息
- 没有统一的状态管理，任务进度散落在聊天记录中
- Codex 可能越界修改不该动的文件，缺乏自动化的安全检查
- 返工缺乏流程控制，可能无限循环

**codex-mcp 通过 MCP 工具自动化整个委托流程**：Claude Code 调用 `delegate-task` 发起任务，调用 `check-task` 查看状态，调用 `accept-task` 审查验收——全程不离开 Claude Code。

核心保障：

- **安全边界** — 双层约束（sandbox 硬约束 + Allowed Paths 软约束），越界自动拒绝验收
- **结果验收** — 自动校验返回结果完整性（Summary / Tests / Files Changed），不完整则要求补全
- **返工控制** — 最多 3 次返工，超限自动阻塞，防止无限循环
- **并发安全** — 同仓库串行调度，不同仓库可并行
- **异常恢复** — MCP 调用失败、线程丢失均有明确恢复路径

## 架构

```
Claude Code
    │  调用 MCP 工具 / CLI 命令
    ▼
codex-mcp (本项目)         ← CLI + MCP Server
    │  任务管理 / 安全校验 / 结果验收
    │  调用 codex exec --json subprocess
    ▼
Codex CLI (codex exec)     ← 直接 subprocess 调用
    │
    ▼
Codex 执行环境 (sandbox)
    │
    ▼
目标仓库
```

codex-mcp 提供两种使用方式：**CLI 命令**和 **MCP Server**，共享同一套服务层。底层通过 `codex exec --json` subprocess 调用 Codex（无需嵌套 MCP Client），从 JSON 事件流中提取 `thread_id` 和 `agent_messages`。

## 安装

### 前置依赖

- Node.js >= 18
- [Codex CLI](https://github.com/openai/codex) 已安装并可用（`codex` 命令在 PATH 中）

### 方式 1：全局安装（推荐）

```bash
npm install -g codex-mcp
```

### 方式 2：从源码安装

```bash
git clone <repo-url> && cd codex-mcp
npm install
npm run build
npm link        # 注册全局命令 codex-mcp
```

### 方式 3：npx 直接运行

```bash
npx codex-mcp --help
npx codex-mcp serve
```

## CLI 使用

安装后可通过 `codex-mcp` 命令使用：

```bash
codex-mcp --help
```

### 委托任务

```bash
# 创建新任务并委托给 Codex
codex-mcp delegate --goal "实现 OAuth2 登录" --paths src/auth/,src/types/ \
  --constraints "不修改数据库 schema" \
  --criteria "单元测试通过"

# 从已有任务文件委托
codex-mcp delegate --file T-001
```

### 查看任务状态

```bash
codex-mcp check T-001
codex-mcp check T-001 --pretty    # 格式化输出
```

### 审查验收

```bash
codex-mcp accept T-001
```

### 返工

```bash
codex-mcp rework T-001 --items "修复越界问题,补充边界测试"
```

### 重试

```bash
codex-mcp retry T-001    # 从 blocked 恢复为 todo
```

### 启动 MCP Server

```bash
codex-mcp serve
```

### 全局选项

| 选项 | 说明 |
|------|------|
| `--pretty` | 人类可读 JSON 输出（默认紧凑 JSON） |
| `--cwd <dir>` | 指定工作目录（默认当前目录） |
| `--codex-cmd <cmd>` | 指定 Codex 命令（默认 `codex`，也可通过 `CODEX_CMD` 环境变量设置） |

所有命令输出 JSON 格式（AI 友好），`--pretty` 时格式化缩进。

## MCP Server 配置

### 方式 1：`claude mcp add`（推荐）

```bash
claude mcp add codex-mcp -s user -- npx codex-mcp serve
```

### 方式 2：编辑 `~/.claude/settings.json`

```json
{
  "mcpServers": {
    "codex-mcp": {
      "command": "npx",
      "args": ["codex-mcp", "serve"]
    }
  }
}
```

### 方式 3：项目级 `.mcp.json`

```json
{
  "mcpServers": {
    "codex-mcp": {
      "command": "npx",
      "args": ["codex-mcp", "serve"]
    }
  }
}
```

### 方式 4：从源码启动

```json
{
  "mcpServers": {
    "codex-mcp": {
      "command": "node",
      "args": ["<path-to-codex-mcp>/dist/serve.js"]
    }
  }
}
```

配置后 Claude Code 即可使用 codex-mcp 暴露的 MCP 工具。

## MCP 工具

codex-mcp 向 Claude Code 暴露以下 5 个工具（CLI 和 MCP Server 共享同一逻辑）：

### `delegate-task` — 委托新任务给 Codex

自动生成任务 ID、创建任务文件、委托给 Codex 执行。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `goal` | string | 是 | 任务目标 |
| `allowedPaths` | string[] | 是 | 允许 Codex 修改的路径列表 |
| `constraints` | string | 否 | 约束条件 |
| `acceptanceCriteria` | string | 否 | 验收标准 |
| `cwd` | string | 否 | 项目根目录，默认当前目录 |

返回：`{ taskId, threadId, status, filePath }`

### `check-task` — 查看任务状态

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `taskId` | string | 是 | 任务 ID（如 `T-001`） |

返回：`{ taskId, status, reworkCount, goal, codexThreadId, lastCodexResultSummary, lastCodexTestReport }`

### `accept-task` — 审查并验收 Codex 返回的结果

运行完整审查流水线：解析结果 → 权限检查 → 完整性校验 → 越界检测。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `taskId` | string | 是 | 任务 ID |

返回：`{ taskId, action, reason, status }`

`action` 取值：
- `done` — 验收通过
- `rework` — 需要返工（越界/质量不达标）
- `blocked` — 阻塞（返工超限/权限拒绝/补全失败）
- `boundary_confirmation` — 需要 Claude Code 确认是否扩大改动范围

### `rework-task` — 发起返工

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `taskId` | string | 是 | 任务 ID |
| `reviewItems` | string[] | 是 | 需要修改的具体项 |

返回：`{ taskId, threadId, status, reworkCount }`

### `retry-task` — 从 blocked 恢复重试

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `taskId` | string | 是 | 任务 ID |

返回：`{ taskId, status }`

## 典型使用场景

在 Claude Code 中对话：

```
用户：把 src/auth/ 下的登录逻辑改成支持 OAuth2

Claude Code：
  1. 拆分任务，定义 allowedPaths: ["src/auth/", "src/types/auth.ts"]
  2. 调用 delegate-task 委托给 Codex
  3. Codex 在 sandbox 中实现，返回结果
  4. 调用 accept-task 自动审查：
     - 检查结果完整性（Summary/Tests/Files Changed）
     - 检查是否越界修改了 allowedPaths 之外的文件
     - 全部通过 → done
     - 越界 → 自动调用 rework-task 要求回滚
```

## 任务状态机

```
todo ──→ doing ──→ review ──→ done
  │        │         │ ↺
  └→ blocked ←───────┘
         │
         └→ todo (retry-task)
```

| 转换 | 触发条件 |
|------|----------|
| `todo → doing` | `delegate-task` 调用成功 |
| `doing → review` | Codex 返回结果 |
| `review → done` | `accept-task` 验收通过 |
| `review → doing` | `rework-task` 发起返工（最多 3 次）|
| `review → blocked` | 返工超限 / 越界且超限 |
| `* → blocked` | MCP 调用失败 / 权限拒绝 |
| `blocked → todo` | `retry-task` 人工重试 |

## 安全机制

**硬约束**：`sandbox=workspace-write` 限制 Codex 只能写入 cwd 及其子目录，操作系统级别阻止仓库外写入。

**软约束**：`developer-instructions` 注入 Allowed Paths 列表，指示 Codex 只在指定路径内工作。Codex 可能不严格遵守，因此 `accept-task` 在验收时自动核查 Files Changed 是否越界，越界则拒绝验收。

## 项目结构

```
src/
├── cli/
│   ├── index.ts              # CLI 入口（parseArgs 分发）
│   ├── task-io.ts            # 任务文件 filesystem I/O
│   ├── codex-runner.ts       # codex exec --json subprocess 封装（实现 McpCaller）
│   └── services.ts           # 共享服务层（CLI + MCP 共用）
├── mcp-server/
│   └── index.ts              # MCP Server 工具注册
├── main.ts                   # bin 入口：CLI
├── serve.ts                  # bin 入口：MCP Server
├── types/                    # TaskDocument, MCP 接口, 结果类型
├── task-manager/             # 状态机, 任务文件读写, 返工控制, 审查验收
├── delegation-engine/        # Prompt 生成, MCP 调用封装
├── result-processor/         # 结果解析, 完整性校验, 补全请求
├── security/                 # 越界检测, developer-instructions, 确认处理
├── scheduler/                # 并发锁, 调度器
└── error-handler/            # MCP 异常处理, 线程恢复

agents/tasks/                 # 任务文件事实源（Markdown 格式）
```

## 开发

```bash
npm install             # 安装依赖
npm run build           # TypeScript 编译
npm test                # 运行全部测试（151 个）
```

### 本地调试

```bash
# 直接运行 CLI（无需 build）
npx tsx src/main.ts --help
npx tsx src/main.ts check T-001 --pretty

# 构建后运行
npm run build
node dist/main.js check T-001

# 启动 MCP Server
node dist/serve.js
```

## 许可

MIT