[feature] 新增 MCP server，把 codex-pro skill 能力暴露為 typed tools

[kiki830621]

Problem

Original text:
「這邊我在想要不要作一個plugin和mcp，讓claude可以容易呼叫codex」
— Source: 使用者於 2026-08-16 直接提出（/idd-issue invocation）

Plain language interpretation：讓 Claude 呼叫 Codex 的介面應該從「skill prose + bash」升級為「typed MCP tools」。

一句話先把「plugin」那半答掉：plugin 已經存在——本 repo 的 codex-pro v0.8.0 就是那個 plugin，9 個 skill 全部落地。所以本 issue 真正新增的是 MCP 層，兩者共存而非取代：plugin 繼續提供 skill 介面與 profile 治理，MCP 提供 typed tool 介面。

而 MCP 這半，README 兩處已經明文把它列為刻意未做：

Marketplace metadata 讓同一份 Git snapshot 可被 Codex CLI／App 或 Claude Code 安裝；本版仍維持 single plugin，沒有新增 MCP server、hook 或 app。

本版不修正上述上游問題，也不新增 Linux／Windows producer、改寫 batch、品牌資產、MCP server 或 hook。

本 issue 把它從「明示延後」轉為「決定要做」。

Type

feature

Expected

在 codex-pro 內新增一個 MCP server，把現有 skill 能力暴露為 typed MCP tools（scope 已裁定為「高階」，非 thin codex_call wrapper）。

Tool surface（沿用 CLAUDE.md 既有四分類，不另立分類法）

現有分類	Skill	建議 MCP tool	屬性
Mutating producer	codex-review	codex_review	呼叫 Codex、寫 result file
Mutating producer	codex-rescue	codex_rescue	同上
Mutating producer	codex-adversarial-review	codex_adversarial_review	同上
Read-only consumer	codex-status	codex_status	純讀 .codex-pro/
Read-only consumer	codex-result	codex_result	純讀單一 result file
Read-only consumer	codex-config	codex_config	純讀 resolved profile
Read-only environment	codex-setup	codex_setup	環境檢查
Read-only consumer	codex-cancel	（待裁定）	informational only，tool 化價值最低
Mutating exception	codex-batch	（待裁定）	fan-out shell job control，與 MCP 單次 request/response 模型不合

三個 producer 是價值核心——它們才真正燒 Codex quota，也是參數契約最需要保證的地方。

為什麼 typed tool 比現行 skill prose 好

現行路徑是 SKILL.md（散文指令）→ Claude 讀懂 → 自己組 bash → 呼叫 codex-call。這代表以下邏輯全部靠 Claude 照著散文做對：

• profile resolve（global ~/.codex-pro/profile.yaml + project .codex-pro/profile.yaml 兩層 merge、per-field 優先序）
• diff 收集（git diff HEAD + untracked enumeration + binary path-only + per-file 64KB / aggregate 512KB size cap）
• fail-fast 四類（rate_limit / oauth_invalid / timeout / target_invalid）
• result file 結構（frontmatter 欄位、必要 H2 heading）

其中至少兩項已經有踩過的實績：#1 是 Codex 輸出 heading 漂移、#6 是 producer skill 在 claude --print 下自行背景化導致 result file 孤兒。散文約束的失效方式是安靜的；typed tool 的 schema 由 server 驗證，參數錯誤是 loud failure。

關鍵設計約束（實作期必守）

1. 不得 spawn codex-call 當 subprocess — 那會直接違反 codex-pro Design constraint review/adversarial-review Step 3 system-instruction hardening — required H2 headings unreliable in Codex output #1（「No subprocess spawn for Codex — 一律走 codex-call HTTPS direct」，防上游 #330 IPC deadlock）。MCP server 應吃下 codex-call 的 HTTPS 邏輯，而非包裝它。
2. profile 契約不可分岔 — references/defaults.json 與 references/profile-contract.md 是 EXTERNAL-CONSUMER CONTRACT（feat: officialize EXTERNAL-CONSUMER CONTRACT — profile-contract.md + machine-readable defaults.json (consumer: issue-driven-dev) #7）。MCP server 必須讀同一份 source of truth，不得複製第三份 hardcoded default。
3. Skill 與 MCP 不得語意分歧 — 同一個 codex_review 從 skill 走或從 tool 走，profile resolve、size cap、fail-fast 分類必須產出相同結果。

Actual

• 樹內沒有任何 .mcp.json，沒有 MCP server。
• 全部 9 個 skill 都是 SKILL.md 散文 → Claude 組 bash → 呼叫 PATH 上的 codex-call。
• codex-call 是 #!/usr/bin/swift script，住在 parallel-ai-agents plugin cache（v2.20.0）；它自己讀 ~/.codex/auth.json、在 token 剩 5 分鐘內自動 refresh、並用 file lock 防並發 refresh 競態。
• 其 flag surface：--output / --model / --effort / --service-tier / --max-time / --instructions / --prompt-file。

Impact

與 #15 的耦合（必須一起裁定，否則會做兩次）

#15 正在推「codex-call executable 歸位到 codex-pro、依賴方向收斂為單向」。本 issue 的約束 1（MCP server 吃下 HTTPS 邏輯、不 spawn）本身就是 #15 的一條實作路徑：Swift MCP server 內含 HTTPS 呼叫，等於 executable 已經在 codex-pro 樹內。

兩者的先後順序會實質改變工作量：

• 先做 codex-pro 樹內沒有呼叫 Codex 的程式碼 — codex-call 歸屬與雙向依賴 #15 再做本 issue → MCP server 包既有的 in-tree Swift 呼叫層
• 先做本 issue 且吃下 HTTPS → codex-pro 樹內沒有呼叫 Codex 的程式碼 — codex-call 歸屬與雙向依賴 #15 大半自動達成，剩 pai 端的 governance 收尾
• 各做各的 → 高機率產出兩份分歧的 HTTPS 呼叫實作，正是 codex-pro 樹內沒有呼叫 Codex 的程式碼 — codex-call 歸屬與雙向依賴 #15 已經在抱怨的「解析區塊已有三份複本」的重演

建議在 /idd-diagnose 階段一併裁定順序。

既有基礎設施可直接沿用

• Swift MCP server 的 sign / notarize pipeline 已建立且驗證可用（che-mcps-notary keychain profile，見全域 CLAUDE.md）。macOS 26 TCC 下 ad-hoc signed binary 無法正常取得授權，這條 pipeline 是對外分發的必經路徑。
• codex-call 本身就是 Swift，語言一致，邏輯可直接吸收而非改寫。

待裁定（留給 diagnose）

• codex-batch（fan-out shell job control）與 codex-cancel（informational only）是否納入 tool surface
• MCP server 與 plugin 的分發關係：同一 repo 內 .mcp.json + plugin 並存，或拆獨立 binary release
• 平台範圍：codex-pro 現為 macOS only（Design constraint feat: officialize EXTERNAL-CONSUMER CONTRACT — profile-contract.md + machine-readable defaults.json (consumer: issue-driven-dev) #7）；MCP server 是否沿用

Next

/issue-driven-dev:idd-diagnose #NNN

---

Clarity Surface(idd-clarify run 2026-08-16T04:42:02Z)

Type	Source	Question for you	Status
ambiguity	"MCP server 應吃下 codex-call 的 HTTPS 邏輯，而非包裝它"	「吃下」是指把 codex-call 的 Swift 原始碼搬進 codex-pro 樹內、重寫一份、還是讓它變成 Swift package dependency？這三種對 #15 的「歸位」算不算數不一樣。	resolved @ 2026-08-16T05:16:23Z (reason: 採 vendor：codex-call Swift 原始碼收進 codex-pro 樹內成為 MCP server 一部分；v0.8.0 已在分發帶 SHA-256 provenance 的 snapshot，順現有方向且 #15 直接達成)
ambiguity	"codex-setup → codex_setup（Read-only environment）"	MCP server 自己發 HTTPS 之後，codex_setup 還要檢查「codex-call 在 PATH」嗎？如果不用，那它剩下要檢查什麼？	resolved @ 2026-08-16T05:16:23Z (reason: 改檢 OAuth token 有效性 + server 自身健康，不再檢查 codex-call 在 PATH)
missing-context	"它自己讀 ~/.codex/auth.json、在 token 剩 5 分鐘內自動 refresh、並用 file lock 防並發 refresh 競態"	MCP server 是 long-lived process，會跟 pai ensemble 仍在跑的 codex-call 同時碰同一個 token store——這個並發邊界要怎麼處理？沿用同一把 file lock 夠嗎？	resolved @ 2026-08-16T05:16:23Z (reason: 沿用 codex-call 既有的同一把 file lock（相同 lock 檔路徑），跨 process 相容，改動最小)
missing-context	"呼叫 Codex、寫 result file"	MCP server 由 client spawn、cwd 未必是使用者的 project root，那 producer tool 的 .codex-pro/<skill>-<ts>.md 要寫到哪裡？由 tool 參數帶 project root 進來嗎？	resolved @ 2026-08-16T05:16:23Z (reason: tool 參數顯式帶 project_root，schema 可驗證，與現行 skill 寫進 repo 內 .codex-pro/ 的行為一致)

---

Current Status

Phase: diagnosed
Last updated: 2026-08-16 by idd-diagnose

Key Decisions

• 前提修正：codex-call 已於本地 v0.8.0 vendored 進樹（bin/ + .codex/bin/ + plugins/codex-pro/runtime/ 三份 byte-identical + provenance），真正工作是執行模型轉換而非搬檔案
• Clarity 裁決 1：採 vendor 原始碼進樹內（既成事實，順現有方向）
• Clarity 裁決 2：codex_setup 改檢 OAuth 有效性 + server 健康，移除 PATH 檢查
• Clarity 裁決 3：token 並發沿用 ~/.codex/.token-refresh.lock 同一把 file lock
• Clarity 裁決 4：producer tool 以顯式 project_root 參數決定 result file 位置
• Complexity = Spectra（Layer 2 命中：MCP tool surface 是對外 published protocol，已有外部 consumer 在 pin 契約；Layer 3 命中 2/3）
• Conflict Class = C_shared_module_coord（共享資源：vendored codex-call snapshot 三份 bundle 複本，由 scripts/generate-codex-skills.sh 同步）

Scope Changes

• 新增 S1：修正 codex-pro 樹內沒有呼叫 Codex 的程式碼 — codex-call 歸屬與雙向依賴 #15 與本 issue 的「樹內無 Codex code」過時敘述（已 comment errata 到 codex-pro 樹內沒有呼叫 Codex 的程式碼 — codex-call 歸屬與雙向依賴 #15）
• 新增 S8：修正 Design constraint review/adversarial-review Step 3 system-instruction hardening — required H2 headings unreliable in Codex output #1 措辭 — 現行 codex-pro-call 本身即 spawn swift subprocess，字面與原文矛盾（原意是防上游 #330 IPC deadlock）

Blocking

• 本地 main 領先 origin/main 6 個未推送 commit（(#10) 系列），remote 讀者看到的仍是舊拓撲 — 待處置（S1）
• Spectra tier：需先走 /spectra-discuss 對齊方向，才進 /spectra-propose

Commits

• (none yet)

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis

需求分析。診斷過程推翻了 issue body 的一個前提，先講這個。

前提修正：vendor 已經完成，不是待辦

Issue body（與 #15）都建立在「codex-pro 樹內沒有呼叫 Codex 的程式碼」之上。這個描述在本地 v0.8.0 已經過時——codex-call 早已 vendored 進樹，而且是三份同步複本：

路徑	用途	md5
bin/codex-call	repo 根層 bundle	e60362b2…
.codex/bin/codex-call	native Codex bundle	e60362b2…
plugins/codex-pro/runtime/codex-call	Claude Code plugin bundle	e60362b2…

三份 byte-identical，附 references/codex-call-provenance.json（上游 commit 6fc6883 / blob / sha256 fa80364b… / MIT / known upstream issues 28、35），外加 bin/codex-pro-call 這支 55 行 integrity wrapper（驗 Darwin → 驗 /usr/bin/swift → 驗 runtime 非 symlink 且可執行 → 比對 sha256 → exec）。

⚠ 這批工作在本地 main，尚未 push（領先 origin/main 6 個 commit）。所以從 GitHub 上讀 #15 的人看到的仍是舊拓撲。

所以 clarity row 1 選的「vendor 原始碼進樹內」不是新工作，是既成事實。真正待做的是下一層。

真正的工作：執行模型轉換，不是搬檔案

現行呼叫鏈每次都付一次固定成本：

Claude 讀 SKILL.md 散文 → 組 bash → codex-pro-call(bash) → /usr/bin/swift codex-call(536 行) → HTTPS
                                     └── 每次呼叫都 spawn 一個 swift interpreter，現場編譯 536 行

#!/usr/bin/swift 是 interpreter 模式。MCP server 編成 binary 之後這段編譯 overhead 直接消失——這是 issue body 沒列到的附帶收益。

順帶指出一個 constraint 的字面漂移

Design constraint #1 寫「No subprocess spawn for Codex」，但 codex-pro-call 現在就是在 spawn 一個 swift subprocess。constraint 的原意是防上游 #330 的 codex exec IPC pipe deadlock，不是禁止一切 subprocess——現行實作沒有違反其精神，但字面已經對不上。MCP server 反而會讓這條 constraint 第一次真正落實（server 內直接發 HTTPS，零 spawn）。建議在實作時一併修正 constraint #1 的措辭，否則它會繼續被當成擋箭牌或被質疑。

重構可行性：比預期低風險

codex-call 536 行已經是分層良好的函式，不是一坨 script：

jwtExp / loadAuthRaw / saveAuthRaw / httpFormPost / refreshIfNeeded
extractErrorMessage / sanitizeBackendText / clampToBudget / streamCodex / parseArgs
── 以上 1–500 行皆為 func/struct，可直接抽成 library target
// MARK: - Main（line 501+）── 只有這段是 top-level，換成 MCP tool handler

全域常數（AUTH_FILE / LOCK_FILE / TOKEN_URL / CLIENT_ID / REFRESH_THRESHOLD_SEC）需改成可注入，否則測不動。

Impact

影響的檔案

範圍	內容	風險
新增（大）	Package.swift + SwiftPM target 樹 — repo 目前零 Swift build infra	高：從「純 markdown + shell」變成「有編譯產物」的 repo
新增	MCP server 實作 + .mcp.json	中
重構	bin/codex-call 1–500 行 → library target；501+ → tool handler	低（已分層）
連動	scripts/generate-codex-skills.sh（993 行，同步三份 bundle 複本）	中：generator 要知道新的 runtime 形態
連動	9 個 SKILL.md — 若 skill 與 MCP 並存，兩條路徑不得語意分歧	中
連動	tests/ 18 個檔全是 shell，run.sh 無任何 build 步驟	中：需新增 Swift test layer
連動	references/profile-contract.md + defaults.json（#7 EXTERNAL-CONSUMER CONTRACT）	高：已有外部 consumer 在 pin

影響的使用者流程

• 既有 skill 使用者：不應有任何行為改變（並存期）
• 外部 consumer（issue-driven-dev idd-verify、perspective-writer#10）：多一條 typed 呼叫路徑，但契約面積擴大——目前 profile-contract.md §4 明文把 executable 排除在契約外，MCP tool surface 一旦公開就必須進契約
• 分發：macOS 26 TCC 下未 notarize 的 binary 無法正常取得授權 → 必須走 che-mcps-notary pipeline（該 pipeline 已建立並驗證可用）

Strategy

四個 clarity row 的裁決已鎖定設計方向，以下為實作切分：

• S1 — 修正前提：更新 codex-pro 樹內沒有呼叫 Codex 的程式碼 — codex-call 歸屬與雙向依賴 #15 與本 issue 的「樹內無 Codex code」敘述（vendor 已完成）；決定 6 個未推送 commit 的處置
• S2 — 建 SwiftPM 骨架：新增 Package.swift，CodexCallCore（library）+ codex-pro-mcp（executable）兩個 target
• S3 — 抽 library：codex-call 1–500 行搬進 CodexCallCore，全域常數改可注入；bin/codex-call 暫維持原樣（並存）
• S4 — MCP server：實作 stdio transport + tool registration；project_root 為 producer tool 的必填參數（clarity row 4 裁決）
• S5 — token 並發：server 沿用 ~/.codex/.token-refresh.lock 同一把 file lock（clarity row 3 裁決），加跨 process 並發測試
• S6 — setup 語意：codex_setup 改檢 OAuth 有效性 + server 健康，移除 PATH 檢查（clarity row 2 裁決）
• S7 — 契約擴充：MCP tool surface 寫進 profile-contract.md，補 §4 對 executable 的排除條款
• S8 — constraint 措辭：修正 Design constraint review/adversarial-review Step 3 system-instruction hardening — required H2 headings unreliable in Codex output #1 的字面（見上）
• S9 — 測試層：tests/run.sh 加 build + Swift test；skill↔MCP 語意等價測試
• S10 — 分發：走 che-mcps-notary sign + notarize；generator 同步三份 bundle

建議與 #15 的關係：S2–S4 完成後 #15 的技術訴求即實質達成（executable 在樹內且是 first-class module），#15 可降為「pai 端 governance 收尾 + 契約補齊」。不建議先做 #15 再做本 issue——vendor 已完成，#15 剩下的部分正是本 issue 的 S7。

Conflict Class

C_shared_module_coord

共享資源具名：vendored codex-call snapshot 的三份 bundle 複本（bin/、.codex/bin/、plugins/codex-pro/runtime/），由 scripts/generate-codex-skills.sh 統一生成並受 codex-call-provenance.json 的 sha256 約束。任何改動 runtime 形態的工作都必須同時協調 generator、三份複本與 provenance，無法與其他觸及該 snapshot 的 issue 平行進行。

（runtime 層另有 ~/.codex/auth.json + ~/.codex/.token-refresh.lock 的單寫者性質，但那是執行期行為，非實作期的檔案衝突。）

Complexity

Spectra

Layer 1 disqualifiers：未命中（deliverable 不是 narrative、不是 one-shot analysis script、不是純 prose 更新，且多檔改動彼此有依賴非獨立）。

Layer V（Step 3.4）：未觸發，詳見下方 Vagueness Pre-check。

Layer 2（necessary，命中）：MCP tool surface 是對 future callers 公開的 protocol surface。本 repo 已有實際外部 consumer（issue-driven-dev idd-verify、籌備中的 perspective-writer#10）在 pin profile-contract.md，tool surface 一旦公開就落入同一契約義務。

Layer 3（confirmation，命中 2/3）：

• ✅ 影響 2+ 既有 specs 需 consistency-checking — openspec/specs/ 下的 codex-native-plugin 等 spec 與 9 個 skill spec 都需協調
• ✅ Architectural decision with long-term maintenance implications — 引入 SwiftPM build + notarize pipeline，執行模型從「每次 spawn interpreter」轉為「long-lived compiled server」，是 future engineers 會繼承的結構性決定
• ➖ 修改既有 published spec 的 normative behavior — 部分（profile-contract.md §4 需擴充，但非推翻）

Layer 2 + Layer 3 皆命中 → Spectra（優先於硬閘與 Layer P，不再往下評）。

Risks

風險	說明	緩解
契約面積擴大不可逆	tool surface 公開後，外部 consumer 會 pin；改名/改參數即 breaking	S7 先寫契約再實作，schema 版本化
skill 與 MCP 語意分歧	同一個 review 兩條路徑產出不同 profile resolve / size cap 結果	S9 等價測試為必要驗收條件，非 nice-to-have
build infra 從零引入	repo 目前無編譯產物，CI／release gate 全部要重新設計	S2 先只建骨架跑通，不急著搬邏輯
notarize 依賴外部服務	Apple round-trip 2–10 分鐘，keychain profile 可能失效	沿用既有 che-mcps-notary；release 前先驗 notarytool history
token 並發假設未驗證	「沿用同一把 lock 即可」是設計判斷，long-lived server 的持有時間與 short-lived script 不同	S5 必須有跨 process 並發測試，不能只靠推論
6 個未推送 commit	本地與 remote 分岔，協作者看到的是舊拓撲	S1 先處置

Residue

Foresay §4.6 — issue 意圖中無法 operationalize 的部分

原話「讓 claude 可以容易呼叫 codex」裡的「容易」，只有一部分能落成 tool schema。可 operationalize 的是：參數由 server 驗證、fail-fast 分類機械化、result 路徑顯式化。

接不進 schema 的部分：

• 發現性 — Claude 要先「知道有這個 tool 且適用當下情境」。tool description 的措辭品質決定了它會不會被叫用，而這無法用型別保證，只能靠實測觀察。
• 錯誤訊息的可讀性 — typed error 讓失敗變 loud，但「Claude 讀完錯誤訊息知道下一步怎麼辦」是散文品質問題，不是 schema 問題。
• 何時該用哪個 tool 的判斷 — review vs adversarial-review 的 mental model 差異目前寫在 CLAUDE.md 的 decision table 給人看；MCP 沒有對應承載處，tool description 塞得下多少是開放問題。

這三項標記為已知殘留，不假裝被 tool 化涵蓋。

---

Vagueness Pre-check

• V1（vague WHAT）: 2 — issue body 有具體 tool surface 對照表（9 skill → tool 名 + 屬性）、3 條具名實作約束；4 個 clarity row 已全數 resolved 並記錄裁決理由。要做什麼是清楚的。
• V4（vague ACCEPTANCE）: 3 — 有隱含驗收面（skill↔MCP 語意等價、契約不分岔），但 issue body 未寫成可勾選的 acceptance criteria；「待裁定」三項（batch/cancel 是否納入、分發關係、平台範圍）留給下一階段。略高但未達門檻。
• Triggered: no — both axes ≤ 3

Hard-gate

Hard-gate: not evaluated — Layer 2 + Layer 3 命中，routing 於 Spectra 分支終止（canonical 序列 step 4 早於 step 5 硬閘）

---

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

Concern	處置	位置
#15 的核心前提「樹內沒有任何一行呼叫 Codex 的程式碼」已被 v0.8.0 vendor 推翻	filed as errata comment（amend 既有 issue，非新開）	#15
Design constraint #1「No subprocess spawn」與現行 codex-pro-call spawn swift 的字面矛盾	in-scope，已列為本 issue Strategy S8	本 issue
本地 main 領先 origin/main 6 個未推送 commit	in-scope，已列為本 issue Strategy S1	本 issue

前者是事實更正而非新工作提案，故以 comment 回填 #15 而不另開 issue；後二者已納入本 issue Strategy，不重複開案。