MCP Server的完整實(shí)踐)
讓你的Tweak向Codex提供MCP工具通過Codex清單注冊(cè)MCP Server的完整實(shí)踐【免費(fèi)下載鏈接】codex-plusplusCodex tweak system for the Codex desktop app項(xiàng)目地址: https://gitcode.com/gh_mirrors/co/codex-plusplus這是一份面向新手的完整實(shí)踐指南通過 Codex 的 Tweak 清單manifest中的mcp字段注冊(cè) MCP Server讓你的 Tweak 自動(dòng)向 Codex 桌面應(yīng)用提供 MCP 工具——無需手動(dòng)編輯 Codex 配置同步、沖突處理、清理全部自動(dòng)完成。一、這個(gè)功能解決什么問題MCPModel Context Protocol是一種讓 AI 調(diào)用外部工具的標(biāo)準(zhǔn)協(xié)議。Codex 通過~/.codex/config.toml里的mcp_servers配置加載 MCP 工具但傳統(tǒng)做法需要你手動(dòng)編輯這個(gè)文件——改錯(cuò)了還會(huì)影響整個(gè) Codex 環(huán)境。從 Codex 0.1.2 版本起見 0.1.2 發(fā)布說明Tweak 只需在清單里聲明一個(gè)mcp字段Codex 主進(jìn)程就會(huì)幫你完成配置同步。整個(gè)鏈路如下manifest.json 的 mcp 字段 ↓ Codex 主進(jìn)程自動(dòng)掃描 ~/.codex/config.toml受管配置塊 ↓ Codex 啟動(dòng) MCP Server ↓ 對(duì)話中直接調(diào)用你提供的 MCP 工具二、核心概念清單里的 mcp 字段一個(gè)會(huì)提供 MCP 工具的 Tweak和普通 Tweak 的唯一區(qū)別就是 manifest.json 里多了一個(gè)可選的mcp字段{ id: com.you.my-tweak, name: My Tweak, version: 0.1.0, githubRepo: you/my-tweak, description: 給 Codex 加上我的工具。, mcp: { command: node, args: [mcp-server.js], env: { MY_FLAG: 1 } } }mcp字段只有三個(gè)屬性類型定義見 TweakMcpServer字段必填說明command?啟動(dòng) MCP Server 的命令如node、pythonargs?啟動(dòng)參數(shù)Tweak 目錄下存在的相對(duì)路徑會(huì)自動(dòng)轉(zhuǎn)成絕對(duì)路徑env?傳給 Server 的環(huán)境變量值必須全部是字符串三、動(dòng)手實(shí)踐三步注冊(cè)你的 MCP Server第 1 步準(zhǔn)備 Tweak 目錄一個(gè) Tweak 就是一個(gè)包含manifest.json和入口腳本的文件夾放到各平臺(tái)的 Tweak 目錄詳見 編寫 Tweak 官方指南macOS~/Library/Application Support/codex-plusplus/tweaks/Linux~/.local/share/codex-plusplus/tweaks/Windows%APPDATA%/codex-plusplus/tweaks/推薦結(jié)構(gòu)my-tweak/ ├── manifest.json ├── index.js # Tweak 入口UI 邏輯可參考官方指南的最小示例 └── mcp-server.js # 你的 MCP Server任意通過 stdio 協(xié)議實(shí)現(xiàn)的進(jìn)程第 2 步寫入 mcp 清單在manifest.json中加入上面第二節(jié)展示的mcp字段。如果 Server 腳本叫mcp-server.jsargs直接寫文件名即可Codex 會(huì)自動(dòng)解析成絕對(duì)路徑例如.../tweaks/my-tweak/mcp-server.js。第 3 步放置 Server 并重新加載mcp-server.js可以是任何語言的實(shí)現(xiàn)只要能通過 stdin/stdout 講 MCP 協(xié)議即可。然后把 Tweak 放入目錄后在 Codex 窗口按Cmd/CtrlR重新加載或重啟應(yīng)用打開Settings → Tweaks確認(rèn) Tweak 已加載MCP 配置即已同步完成。四、Codex 的同步機(jī)制三個(gè)貼心設(shè)計(jì)Codex 在加載 Tweak 時(shí)調(diào)用 syncMcpServersFromEnabledTweaks 掃描已啟用的 Tweak由 syncManagedMcpServers 把聲明寫進(jìn)config.toml中一個(gè)帶標(biāo)記的受管塊# BEGIN CODEX MANAGED MCP SERVERS [mcp_servers.my-tweak] command node args [/path/to/tweaks/my-tweak/mcp-server.js] env { MY_FLAG 1 } # END CODEX MANAGED MCP SERVERS服務(wù)名自動(dòng)生成由 Tweak 的id派生——去掉co.bennett.前綴、特殊字符替換為連字符并轉(zhuǎn)小寫。例如co.bennett.native-widgets→native-widgetscom.example.my-widget→com-example-my-widget推導(dǎo)規(guī)則見 mcpServerNameFromTweakId 及其測(cè)試用例。名稱沖突時(shí)自動(dòng)追加-2、-3。絕不覆蓋你的手動(dòng)配置如果你在config.toml里已手動(dòng)定義了同名 ServerCodex 會(huì)跳過該 Tweak 只在日志中提示保留你的配置不動(dòng)。卸載即清理禁用或移除 Tweak 后Codex 只刪除受管塊內(nèi)的條目塊外內(nèi)容原樣保留該行為有完整回歸測(cè)試保障。五、Tweak 商店中的真實(shí)例子商店的 index.json 收錄了兩個(gè)真實(shí)使用mcp字段的 TweakProject Home項(xiàng)目看板讓 Codex 通過 MCP 管理任務(wù)和 Windows Computer UseWindows 桌面自動(dòng)化。它們的清單都只有極簡(jiǎn)的mcp: { command: node, args: [mcp-server.js] }——這正是你寫自己 Tweak 時(shí)可以直接套用的形態(tài)。六、快速排錯(cuò)清單如果 MCP Server 沒有出現(xiàn)在 Codex 里按順序自查command是非空字符串且是系統(tǒng)里可用的可執(zhí)行程序args里的相對(duì)路徑文件確實(shí)存在于Tweak 目錄內(nèi)env的值是否全部為字符串Tweak 是否處于啟用狀態(tài)只有啟用的 Tweak 會(huì)同步 MCP 配置Tweak 清單是否通過了校驗(yàn)SDK 的校驗(yàn)邏輯會(huì)檢查mcp.command必填、mcp.args為字符串?dāng)?shù)組、mcp.env為字符串對(duì)象現(xiàn)象可能原因Tweak 未出現(xiàn)在 Tweaks 列表manifest.json缺少必填字段或格式錯(cuò)誤對(duì)照字段說明表修正聲明了mcp卻未被同步command為空或args/env類型不合法會(huì)被靜默跳過用validateTweakManifest檢查日志顯示 skipped ... already configured by user你手動(dòng)配置了同名 ServerCodex 主動(dòng)讓位懷疑配置沒生效查看 Codex 主進(jìn)程日志log/main.log中 synced Codex MCP config 記錄七、總結(jié)通過 Codex 清單注冊(cè) MCP Server 的完整流程可以濃縮為一句話寫一個(gè)帶mcp字段的manifest.json放入 Tweak 目錄重載 Codex。服務(wù)命名、路徑解析、與手動(dòng)配置的沖突處理、卸載清理都由 mcp-sync.ts 自動(dòng)完成?，F(xiàn)在你可以開始動(dòng)手讓你的第一個(gè) Tweak 為 Codex 提供專屬 MCP 工具了 【免費(fèi)下載鏈接】codex-plusplusCodex tweak system for the Codex desktop app項(xiàng)目地址: https://gitcode.com/gh_mirrors/co/codex-plusplus創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 讓你的Tweak向Codex提供MCP工具：通過Codex++清單注冊(cè)MCP Server的完整實(shí)踐
讓你的Tweak向Codex提供MCP工具通過Codex清單注冊(cè)MCP Server的完整實(shí)踐【免費(fèi)下載鏈接】codex-plusplusCodex tweak system for the Codex desktop app項(xiàng)目地址: https://gitcode.com/gh_mirrors/co/codex-plusplus這是一份面向新手的完整實(shí)踐指南通過 Codex 的 Tweak 清單manifest中的mcp字段注冊(cè) MCP Server讓你的 Tweak 自動(dòng)向 Codex 桌面應(yīng)用提供 MCP 工具——無需手動(dòng)編輯 Codex 配置同步、沖突處理、清理全部自動(dòng)完成。一、這個(gè)功能解決什么問題MCPModel Context Protocol是一種讓 AI 調(diào)用外部工具的標(biāo)準(zhǔn)協(xié)議。Codex 通過~/.codex/config.toml里的mcp_servers配置加載 MCP 工具但傳統(tǒng)做法需要你手動(dòng)編輯這個(gè)文件——改錯(cuò)了還會(huì)影響整個(gè) Codex 環(huán)境。從 Codex 0.1.2 版本起見 0.1.2 發(fā)布說明Tweak 只需在清單里聲明一個(gè)mcp字段Codex 主進(jìn)程就會(huì)幫你完成配置同步。整個(gè)鏈路如下manifest.json 的 mcp 字段 ↓ Codex 主進(jìn)程自動(dòng)掃描 ~/.codex/config.toml受管配置塊 ↓ Codex 啟動(dòng) MCP Server ↓ 對(duì)話中直接調(diào)用你提供的 MCP 工具二、核心概念清單里的 mcp 字段一個(gè)會(huì)提供 MCP 工具的 Tweak和普通 Tweak 的唯一區(qū)別就是 manifest.json 里多了一個(gè)可選的mcp字段{ id: com.you.my-tweak, name: My Tweak, version: 0.1.0, githubRepo: you/my-tweak, description: 給 Codex 加上我的工具。, mcp: { command: node, args: [mcp-server.js], env: { MY_FLAG: 1 } } }mcp字段只有三個(gè)屬性類型定義見 TweakMcpServer字段必填說明command?啟動(dòng) MCP Server 的命令如node、pythonargs?啟動(dòng)參數(shù)Tweak 目錄下存在的相對(duì)路徑會(huì)自動(dòng)轉(zhuǎn)成絕對(duì)路徑env?傳給 Server 的環(huán)境變量值必須全部是字符串三、動(dòng)手實(shí)踐三步注冊(cè)你的 MCP Server第 1 步準(zhǔn)備 Tweak 目錄一個(gè) Tweak 就是一個(gè)包含manifest.json和入口腳本的文件夾放到各平臺(tái)的 Tweak 目錄詳見 編寫 Tweak 官方指南macOS~/Library/Application Support/codex-plusplus/tweaks/Linux~/.local/share/codex-plusplus/tweaks/Windows%APPDATA%/codex-plusplus/tweaks/推薦結(jié)構(gòu)my-tweak/ ├── manifest.json ├── index.js # Tweak 入口UI 邏輯可參考官方指南的最小示例 └── mcp-server.js # 你的 MCP Server任意通過 stdio 協(xié)議實(shí)現(xiàn)的進(jìn)程第 2 步寫入 mcp 清單在manifest.json中加入上面第二節(jié)展示的mcp字段。如果 Server 腳本叫mcp-server.jsargs直接寫文件名即可Codex 會(huì)自動(dòng)解析成絕對(duì)路徑例如.../tweaks/my-tweak/mcp-server.js。第 3 步放置 Server 并重新加載mcp-server.js可以是任何語言的實(shí)現(xiàn)只要能通過 stdin/stdout 講 MCP 協(xié)議即可。然后把 Tweak 放入目錄后在 Codex 窗口按Cmd/CtrlR重新加載或重啟應(yīng)用打開Settings → Tweaks確認(rèn) Tweak 已加載MCP 配置即已同步完成。四、Codex 的同步機(jī)制三個(gè)貼心設(shè)計(jì)Codex 在加載 Tweak 時(shí)調(diào)用 syncMcpServersFromEnabledTweaks 掃描已啟用的 Tweak由 syncManagedMcpServers 把聲明寫進(jìn)config.toml中一個(gè)帶標(biāo)記的受管塊# BEGIN CODEX MANAGED MCP SERVERS [mcp_servers.my-tweak] command node args [/path/to/tweaks/my-tweak/mcp-server.js] env { MY_FLAG 1 } # END CODEX MANAGED MCP SERVERS服務(wù)名自動(dòng)生成由 Tweak 的id派生——去掉co.bennett.前綴、特殊字符替換為連字符并轉(zhuǎn)小寫。例如co.bennett.native-widgets→native-widgetscom.example.my-widget→com-example-my-widget推導(dǎo)規(guī)則見 mcpServerNameFromTweakId 及其測(cè)試用例。名稱沖突時(shí)自動(dòng)追加-2、-3。絕不覆蓋你的手動(dòng)配置如果你在config.toml里已手動(dòng)定義了同名 ServerCodex 會(huì)跳過該 Tweak 只在日志中提示保留你的配置不動(dòng)。卸載即清理禁用或移除 Tweak 后Codex 只刪除受管塊內(nèi)的條目塊外內(nèi)容原樣保留該行為有完整回歸測(cè)試保障。五、Tweak 商店中的真實(shí)例子商店的 index.json 收錄了兩個(gè)真實(shí)使用mcp字段的 TweakProject Home項(xiàng)目看板讓 Codex 通過 MCP 管理任務(wù)和 Windows Computer UseWindows 桌面自動(dòng)化。它們的清單都只有極簡(jiǎn)的mcp: { command: node, args: [mcp-server.js] }——這正是你寫自己 Tweak 時(shí)可以直接套用的形態(tài)。六、快速排錯(cuò)清單如果 MCP Server 沒有出現(xiàn)在 Codex 里按順序自查command是非空字符串且是系統(tǒng)里可用的可執(zhí)行程序args里的相對(duì)路徑文件確實(shí)存在于Tweak 目錄內(nèi)env的值是否全部為字符串Tweak 是否處于啟用狀態(tài)只有啟用的 Tweak 會(huì)同步 MCP 配置Tweak 清單是否通過了校驗(yàn)SDK 的校驗(yàn)邏輯會(huì)檢查mcp.command必填、mcp.args為字符串?dāng)?shù)組、mcp.env為字符串對(duì)象現(xiàn)象可能原因Tweak 未出現(xiàn)在 Tweaks 列表manifest.json缺少必填字段或格式錯(cuò)誤對(duì)照字段說明表修正聲明了mcp卻未被同步command為空或args/env類型不合法會(huì)被靜默跳過用validateTweakManifest檢查日志顯示 skipped ... already configured by user你手動(dòng)配置了同名 ServerCodex 主動(dòng)讓位懷疑配置沒生效查看 Codex 主進(jìn)程日志log/main.log中 synced Codex MCP config 記錄七、總結(jié)通過 Codex 清單注冊(cè) MCP Server 的完整流程可以濃縮為一句話寫一個(gè)帶mcp字段的manifest.json放入 Tweak 目錄重載 Codex。服務(wù)命名、路徑解析、與手動(dòng)配置的沖突處理、卸載清理都由 mcp-sync.ts 自動(dòng)完成?，F(xiàn)在你可以開始動(dòng)手讓你的第一個(gè) Tweak 為 Codex 提供專屬 MCP 工具了 【免費(fèi)下載鏈接】codex-plusplusCodex tweak system for the Codex desktop app項(xiàng)目地址: https://gitcode.com/gh_mirrors/co/codex-plusplus創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考