# codex-mcp-server

MCP server（stdio）封裝 OpenAI Codex CLI，讓 pi / Codex 可將 8 個 Codex 工具作為 named tools 呼叫。

**來源：** `C:\Users\hsi67063\.codex\mcp\codex-mcp-server`  
**打包目的：** 可攜至其他電腦使用。

---

## 目錄結構

```
codex-mcp-server/
├── index.js           # MCP server 本體（已標記需修改路徑）
├── package.json       # 依賴：@modelcontextprotocol/sdk + zod
├── README.md          # 本檔
├── install.bat        # ★ 新電腦安裝腳本（全自動）
└── setup-git.bat      # ★ Git 初始化 + Push 腳本
```

---

## 快速安裝（新電腦）

### 方式一：一鍵安裝（建議）

```cmd
cd C:\path\to\codex-mcp-server
install.bat
```

腳本會自動：
1. 執行 `npm install`
2. 偵測 Codex CLI 路徑，寫入 `index.js` 的 `CODEX_BIN`
3. 在 `pi settings.json` 中注册 `mcpServers.codex`
4. 驗證 server 可載入

### 方式二：手動安裝

```bash
# 1. 安裝依賴
cd codex-mcp-server
npm install

# 2. 編輯 index.js，更新 CODEX_BIN 為正確路徑

# 3. 在 pi settings.json 新增：
{
  "mcpServers": {
    "codex": {
      "command": "node",
      "args": ["C:/path/to/codex-mcp-server/index.js"]
    }
  }
}

# 4. 重啟 pi
```

---

## 已注册的工具（8 個）

| 工具 | 模式 | 說明 |
|---|---|---|
| `codex_exec` | background | 非互動執行 Codex，即時返回 job_id |
| `codex_review` | sync (5min) | 程式碼審查 |
| `codex_skill_list` | sync | 列出 Codex skills |
| `codex_skill_run` | background | 執行指定 skill |
| `codex_status` | sync (5min) | `codex doctor` 健康檢查 |
| `codex_poll` | sync | 查詢背景工作狀態 |
| `codex_list_jobs` | sync | 列出所有工作 |
| `codex_kill` | sync | 終止執行中的工作 |

---

## 複製到新電腦前需確認

| 項目 | 現有設定 | 新電腦是否需修改 |
|---|---|---|
| `CODEX_BIN` in `index.js` | `C:/Users/hsi67063/.codex/tools/npm-global/codex.cmd` | **是**，install.bat 會自動更新 |
| `DEFAULT_SKILLS_DIR` | `C:/Users/hsi67063/.codex/skills` | 視需求 |
| `settings.json` 的 `args` | 絕對路徑 | **是**，install.bat 會自動更新 |

---

## Git Push

```cmd
.\setup-git.bat [remote_url]
```

範例：
```cmd
.\setup-git.bat "https://github.com/your_user/codex-mcp-server.git"
```

若未提供 remote_url，脚本只會初始化 repo 並顯示後續指令。

---

## 前置需求

- **Node.js** 18+
- **Codex CLI** 已安裝並在 PATH
- **pi** 或 **Codex** 已設定 `settings.json`

---

## 疑難排解

**Q: `npm install` 失敗**
- 確認網路暢通
- 嘗試：`npm install --legacy-peer-deps`

**Q: 找不到 Codex CLI**
- 手動確認路徑後編輯 `index.js` 中的 `CODEX_BIN`
- Codex CLI 常見位置：
  - `C:\Users\<user>\.codex\tools\npm-global\codex.cmd`
  - `C:\Users\<user>\AppData\Local\OpenAI\Codex\bin\codex.exe`

**Q: pi 重啟後看不到 codex_* 工具**
- 確認 `settings.json` 中 `mcpServers.codex` 區塊已正確寫入
- 檢查 pi 日誌是否有錯誤輸出