codex-controller-mcp

MCP server để spawn, điều khiển và quan sát các thread Codex CLI (OpenAI Codex) từ bất kỳ MCP client nào (Claude Code, Claude Desktop, IDE, hoặc client tự viết). Là phiên bản song song của claude-code-controller-mcp nhưng cho Codex.

Cách nó hoạt động

Server dùng @openai/codex-sdk làm backend — SDK đã spawn codex exec --experimental-json và parse JSONL events. Lớp wrapper thêm:

1. Multi-thread session pool: Map<processId, Thread> (Thread = đối tượng SDK của Codex). Khác Claude Code (giữ child_process xuyên suốt), Codex chạy 1 turn = 1 lần spawn — controller giữ Thread để có thể runStreamed nhiều turn liên tiếp dưới cùng threadId.
2. Event buffer: parse ThreadEvent stream của SDK, lưu vào ring buffer 5000 events/thread. Poll qua codex_get_output(sinceIndex).
3. Abort/cancel: dùng AbortController (SDK forward signal vào child process).
4. Transcript reader: walk ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl, parse session_meta ở line đầu và response_item / compacted ở các line sau thành chat-style.

Tools

| Tool | Mô tả | |---|---| | codex_run_oneshot | Thread.run(prompt) của SDK, trả finalResponse, items, usage. | | codex_start_thread | Tạo thread mới (hoặc resume từ threadId), tuỳ chọn chạy prompt đầu. Trả processId, status. | | codex_continue_thread | Gửi prompt mới (turn kế tiếp) vào thread đang idle. Reject nếu turn cũ chưa xong. | | codex_get_output | Đọc events đã buffer + summary (status, threadId, usage). Hỗ trợ sinceIndex để poll incremental. | | codex_list_processes | List các process controller theo status. | | codex_kill_process | Abort turn đang chạy (qua AbortController). | | codex_list_sessions | Walk ~/.codex/sessions, đọc session_meta của mỗi rollout, filter cwd. | | codex_read_transcript | Đọc 1 rollout .jsonl, parse user/assistant/tool messages, hỗ trợ sinceUuid tail. | | codex_list_transcripts | Như list_sessions nhưng kèm preview prompt đầu + last message. | | codex_mcp | Passthrough codex mcp list/get/add/remove/login/logout. | | codex_doctor | Spawn codex doctor. |

Khác biệt thiết kế so với claude-code-controller-mcp

| | Claude Code | Codex | |---|---|---| | Cách gửi turn tiếp theo | Ghi JSON line vào stdin của process đang sống (stream-json input) | Spawn 1 turn mới (codex exec resume <id>) — SDK đã làm sẵn | | Multi-turn streaming | 1 process = nhiều turn | 1 Thread = nhiều turn nhưng mỗi turn = 1 child process | | *_send_message | Có (ghi vào stdin) | codex_continue_thread thay thế | | Lưu transcript | ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl | ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl (cwd ở trong session_meta, không trong path) |

Yêu cầu

• Node.js 18+
• Codex CLI đã cài: npm i -g @openai/codex (SDK tự tìm binary, hoặc đặt CODEX_BIN).

Cài đặt

cd F:\Redon\DuAn\project01\codex-controller-mcp
npm install
npm run build

Smoke test

.\scripts\smoke-test.ps1
# Sẽ in JSON-RPC initialize + tools/list response

Đăng ký với Claude Code

.\scripts\register-with-claude.ps1
# Mặc định tìm claude.exe trong ~/.claude/downloads; truyền -ClaudeBin <path> để override.

Hoặc thủ công:

& <claude.exe> mcp add --transport stdio codex-controller `
    powershell -- -NoProfile -ExecutionPolicy Bypass `
    -File "F:\Redon\DuAn\project01\codex-controller-mcp\scripts\start-mcp.ps1"

Đăng ký với Claude Desktop

{
  "mcpServers": {
    "codex-controller": {
      "command": "node",
      "args": ["F:\\Redon\\DuAn\\project01\\codex-controller-mcp\\dist\\server.js"],
      "env": {
        "CODEX_BIN": "C:\\nvm4w\\nodejs\\node_modules\\@openai\\codex\\bin\\codex.js"
      }
    }
  }
}

Biến môi trường

| Var | Ý nghĩa | |---|---| | CODEX_BIN | Override path tới codex binary (npm-cli, native, hoặc codex.js). Nếu không set, SDK sẽ tự require.resolve('@openai/codex'). | | CODEX_HOME | Override ~/.codex (mặc định homedir()/.codex). Quyết định sessionsDir. | | CODEX_CONTROLLER_CWD | Cwd mặc định khi spawn (default = process.cwd()). |

Ví dụ luồng dùng

// 1. Spawn thread nền với prompt đầu
{"tool":"codex_start_thread","args":{
  "cwd":"F:\\Redon\\DuAn\\project01\\redai-v201-be-app",
  "prompt":"Liệt kê các controller trong src/",
  "model":"gpt-5-codex",
  "sandboxMode":"workspace-write",
  "skipGitRepoCheck": true
}}
// → { processId: "abc-...", threadId: null, status: "running", ... }

// 2. Poll output (sau vài giây)
{"tool":"codex_get_output","args":{"processId":"abc-...","sinceIndex":0}}

// 3. Khi turn xong (status: "completed"), gửi follow-up
{"tool":"codex_continue_thread","args":{
  "processId":"abc-...",
  "prompt":"Tóm tắt từng controller làm gì."
}}

// 4. Đọc transcript của session đã chạy ở terminal khác
{"tool":"codex_list_sessions","args":{"cwdFilter":"F:\\Redon\\DuAn\\project01"}}
{"tool":"codex_read_transcript","args":{"sessionId":"<uuid-from-list>"}}

Hạn chế đã biết

• Mỗi turn = 1 child process: không thể gửi message giữa turn (Codex CLI không hỗ trợ stream-stdin multi-turn như Claude). Workaround: chờ status: completed rồi codex_continue_thread.
• thread.id chưa có ngay khi start: SDK chỉ populate sau khi event thread.started được nhận. Trong vài giây đầu của turn 1, record.threadId là null — poll codex_get_output để chờ.
• Transcript reader chỉ surface 4 loại item: message / reasoning / function_call / function_call_output (+ local_shell_call). Các event types khác (web_search, todo_list) bị bỏ qua — sẽ thêm khi cần.
• Windows-first: scripts dùng .ps1. SDK đã chạy được trên Linux/macOS, chỉ cần thay launcher.

Thư mục

src/
├── server.ts             # MCP server + 11 tool handlers
├── config.ts             # Tìm codex bin, sessionsDir
├── thread-manager.ts     # Thread pool + AbortController + event buffer
├── session-tracker.ts    # Walk ~/.codex/sessions, đọc session_meta
└── transcript-reader.ts  # Parse rollout JSONL → chat-style messages
scripts/
├── start-mcp.ps1
├── register-with-claude.ps1
└── smoke-test.ps1