🚀 XcodeMCPWrapper - mcpbridge-wrapper
XcodeMCPWrapper 是一個 Python 包裝器，它使 Xcode 26.3 的 MCP 橋與 Cursor 等嚴格符合 MCP 規範的客戶端兼容，解決了 Xcode mcpbridge 返回響應時缺少 structuredContent 字段的問題。
🚀 快速開始
前提條件
- 安裝了 Xcode 26.3 或更高版本的 macOS 系統。
- Python 3.9 或更高版本。
- 啟用 Xcode Tools MCP Server（詳見下文）。
⚠️ 重要提示
必須在 Xcode 設置中啟用 Xcode Tools MCP：
- 打開 Xcode > Settings（⌘,）。
- 在側邊欄中選擇 Intelligence。
- 在 Model Context Protocol 下，將 Xcode Tools 開關打開。
如果在 MCP 客戶端日誌中看到 "Found 0 tools"，則表示此設置未啟用。
Cursor 快速設置
如果使用 Cursor，無需安裝，只需將以下內容添加到 ~/.cursor/mcp.json 中：
代理模式（推薦）：
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker"]
}
}
}
使用 Web UI 儀表盤（可選，可在 http://localhost:8080 進行即時監控）：
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": [
"--from",
"mcpbridge-wrapper[webui]",
"mcpbridge-wrapper",
"--broker",
"--web-ui",
"--web-ui-config",
"/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json"
]
}
}
}
直接模式（可選）：
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"]
}
}
}
如果升級後想確認當前運行的儀表盤進程版本：
PORT=8080
PID=$(lsof -tiTCP:$PORT -sTCP:LISTEN | head -n1)
PY=$(ps -p "$PID" -o command= | awk '{print $1}')
"$PY" -c 'import importlib.metadata as m; print(m.version("mcpbridge-wrapper"))'
如有需要，進行一次性刷新啟動：
uvx --refresh --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
重啟 Cursor 即可。如需瞭解其他客戶端或安裝方法，請繼續閱讀。
代理模式
代理模式允許多個短生命週期的 MCP 客戶端會話共享一個持久的上游橋接會話。
- 模式存在原因：Apple 在 Xcode 26.4 的編碼智能文檔中指出一個已知問題，外部開發工具在正常使用過程中可能會觸發重複的 "Allow Connection?" 對話框（
170721057）。通過代理模式重用一個長生命週期的上游會話可以減少重新連接的次數，從而避免出現此提示。詳見 Apple 官方 Xcode 26.4 發行說明。
- 使用
--broker 進行自動檢測：如果守護進程存活則連接，否則啟動（推薦）。
- 當希望啟動的或守護進程的主機擁有一個共享的儀表盤端點時，添加
--web-ui（可選 --web-ui-config）。
- 如果希望有一個明確的守護進程所有者以及跨多個編輯器的可見監控界面，建議使用專用主機：啟動一次
--broker-daemon --web-ui，讓客戶端使用 --broker，並將瀏覽器儀表盤和/或 --tui 連接到該主機。
快速遷移示例：
claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker
codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker
有關完整的啟動/停止/狀態命令、Cursor JSON 代碼片段、故障排除以及回退到直接模式的信息，請參閱 代理模式指南。
多代理指導
當同時運行多個 MCP 客戶端進程時：
- 專用主機前端工作流（當可見性很重要時推薦）：啟動一個
--broker-daemon --web-ui 進程，讓每個編輯器/客戶端使用 --broker，並將瀏覽器儀表盤和/或 mcpbridge-wrapper --tui 連接到同一主機。
- 統一單配置自動啟動：當希望減少設置並能接受隱式主機所有權時，為每個客戶端配置
--broker --web-ui --web-ui-config <shared-path>。
- 運行時預期：專用主機是控制生命週期最清晰的方式；在統一自動啟動中，第一個必須啟動代理的客戶端將啟動代理主機和儀表盤，後續客戶端將重用它。
- 所有權規則：只有一個進程可以綁定給定的 Web UI
host:port（例如 127.0.0.1:8080）。
- 連接行為：當代理已經在運行時，
--broker 將重用它，並且不會將儀表盤設置應用到現有主機上。
- 回退行為：如果儀表盤綁定失敗（端口已被使用），代理 MCP 傳輸將繼續，僅跳過儀表盤啟動。
- 驗證流程：使用
mcpbridge-wrapper --broker-status、~/.mcpbridge_wrapper/ 下的文件以及共享儀表盤/TUI 狀態來驗證兩個編輯器是否連接到同一個守護進程。
詳見 代理模式指南、Web UI 設置指南 和 故障排除。
Python 環境設置（開發）
如果計劃運行 make install、pytest 或其他開發命令，請先創建並激活虛擬環境，以避免 Homebrew Python 的 externally-managed-environment（PEP 668）錯誤。
cd XcodeMCPWrapper
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
make install
快速檢查：
which python3
which pip
在環境激活時，兩者都應指向 .venv/bin/...。
✨ 主要特性
- 攔截
xcrun mcpbridge 的響應，並將 content 中的數據複製到 structuredContent 中，使 Xcode 的 MCP 工具與所有 MCP 客戶端完全兼容。
- 提供代理模式，允許多個短生命週期的 MCP 客戶端會話共享一個持久的上游橋接會話，減少重新連接的次數。
- 包含可選的 Web UI 儀表盤，用於即時監控和審計日誌記錄。
📦 安裝指南
選項 1：使用 uvx（推薦 - 最簡單）
最快的安裝方法是使用 uvx（需要安裝 uv）：
uvx --from mcpbridge-wrapper mcpbridge-wrapper
或者直接添加到 MCP 客戶端配置中（詳見下文配置部分）。
選項 2：通過 MCP 註冊表
如果 MCP 客戶端支持 MCP 註冊表：
服務器名稱：io.github.SoundBlaster/xcode-mcpbridge-wrapper
mcp-publisher install io.github.SoundBlaster/xcode-mcpbridge-wrapper
選項 3：使用 pip
python3 -m pip install mcpbridge-wrapper
然後使用 mcpbridge-wrapper 或 xcodemcpwrapper 命令。
選項 4：手動安裝（通過安裝腳本）
git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
cd XcodeMCPWrapper
./scripts/install.sh
安裝腳本將創建一個虛擬環境，安裝軟件包，並在 ~/bin/xcodemcpwrapper 處放置一個包裝器。
如果計劃使用 --web-ui MCP 參數，請顯式安裝 Web UI 額外組件：
./scripts/install.sh --webui
將以下內容添加到 ~/.bashrc 或 ~/.zshrc 中：
export PATH="$HOME/bin:$PATH"
然後重新加載：
source ~/.zshrc
. ~/.zshrc
選項 5：本地開發（venv）
如果進行開發或希望直接從克隆的存儲庫運行：
git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
cd XcodeMCPWrapper
python3 -m venv .venv
source .venv/bin/activate
make install
入口點是 .venv/bin/mcpbridge-wrapper。在配置 MCP 客戶端時，請使用 完整的絕對路徑（詳見下文配置部分）。
卸載
要從系統中移除 xcodemcpwrapper：
./scripts/uninstall.sh
選項：
--dry-run 或 -n：顯示將被移除的內容，但不實際移除。--yes 或 -y：跳過確認提示。
💻 使用示例
基礎用法
配置完成後，讓 AI 助手使用 Xcode 工具：
"Build my project"
"Run the tests"
"Find all Swift files in the project"
"Show me the build errors"
📚 詳細文檔
配置
Cursor
首先列出代理設置示例。
使用 uvx 代理模式（推薦）：
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker"]
}
}
}
使用 uvx 代理模式並啟用 Web UI（可選）：
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": [
"--from",
"mcpbridge-wrapper[webui]",
"mcpbridge-wrapper",
"--broker",
"--web-ui",
"--web-ui-config",
"/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json"
]
}
}
}
使用 uvx 直接模式：
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"]
}
}
}
使用 uvx 直接模式並啟用 Web UI（可選）：
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": [
"--from",
"mcpbridge-wrapper[webui]",
"mcpbridge-wrapper",
"--web-ui",
"--web-ui-port",
"8080"
]
}
}
}
手動安裝（直接模式）：
{
"mcpServers": {
"xcode-tools": {
"command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
"args": []
}
}
}
手動安裝並啟用 Web UI（直接模式，可選）：
需要使用 ./scripts/install.sh --webui 進行安裝（或等效的 .[webui] 依賴項）。
{
"mcpServers": {
"xcode-tools": {
"command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
"args": ["--web-ui", "--web-ui-port", "8080"]
}
}
}
本地開發（venv，直接模式）：
{
"mcpServers": {
"xcode-tools": {
"command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper"
}
}
}
本地開發並啟用 Web UI（直接模式，可選）：
{
"mcpServers": {
"xcode-tools": {
"command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
"args": ["--web-ui", "--web-ui-port", "8080"]
}
}
}
Claude Code
首先列出代理設置示例。
使用 uvx 代理模式（推薦）：
claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker
使用 uvx 代理模式並啟用 Web UI（可選）：
claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json"
使用 uvx 直接模式：
claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
使用 uvx 直接模式並啟用 Web UI（可選）：
claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
手動安裝（直接模式）：
claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper
手動安裝並啟用 Web UI（直接模式，可選）：
需要使用 ./scripts/install.sh --webui 進行安裝（或等效的 .[webui] 依賴項）。
claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080
本地開發（venv，直接模式）：
claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper
本地開發並啟用 Web UI（直接模式，可選）：
claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080
Codex CLI
首先列出代理設置示例。
使用 uvx 代理模式（推薦）：
codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker
使用 uvx 代理模式並啟用 Web UI（可選）：
codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json"
使用 uvx 直接模式：
codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
使用 uvx 直接模式並啟用 Web UI（可選）：
codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
手動安裝（直接模式）：
codex mcp add xcode -- ~/bin/xcodemcpwrapper
手動安裝並啟用 Web UI（直接模式，可選）：
需要使用 ./scripts/install.sh --webui 進行安裝（或等效的 .[webui] 依賴項）。
codex mcp add xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080
本地開發（venv，直接模式）：
codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper
本地開發並啟用 Web UI（直接模式，可選）：
codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080
Zed Agent
使用 uvx（推薦）：
編輯 ~/.zed/settings.json：
{
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"],
"env": {}
}
}
使用 uvx 並啟用 Web UI（可選）：
{
"xcode-tools": {
"command": "uvx",
"args": [
"--from",
"mcpbridge-wrapper[webui]",
"mcpbridge-wrapper",
"--web-ui",
"--web-ui-port",
"8080"
],
"env": {}
}
}
手動安裝：
{
"xcode-tools": {
"command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
"args": [],
"env": {}
}
}
手動安裝並啟用 Web UI（可選）：
需要使用 ./scripts/install.sh --webui 進行安裝（或等效的 .[webui] 依賴項）。
{
"xcode-tools": {
"command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
"args": ["--web-ui", "--web-ui-port", "8080"],
"env": {}
}
}
本地開發（venv，直接模式）：
{
"xcode-tools": {
"command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
"args": [],
"env": {}
}
}
本地開發並啟用 Web UI（直接模式，可選）：
{
"xcode-tools": {
"command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
"args": ["--web-ui", "--web-ui-port", "8080"],
"env": {}
}
}
Kimi CLI
使用 uvx（推薦）：
編輯 ~/.kimi/mcp.json：
{
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"],
"env": {}
}
}
手動安裝：
{
"xcode-tools": {
"command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
"args": [],
"env": {}
}
}
Web UI 儀表盤（可選）
包裝器包含一個可選的 Web UI 儀表盤，用於即時監控和審計日誌記錄：
make webui
python -m mcpbridge_wrapper --web-ui --web-ui-port 8080
特性：
- 即時指標：請求每秒（RPS）、延遲百分位數（p50、p95、p99）、錯誤率。
- 工具使用分析：最常用工具的可視化圖表。
- 審計日誌：所有 MCP 工具調用的持久日誌，支持導出（JSON/CSV）。
- 請求檢查器：帶有過濾功能的即時日誌流。
在瀏覽器中打開 http://localhost:8080 查看儀表盤。
多代理設置的重要注意事項：
- 儀表盤由一個包裝器進程託管，而不是由 Xcode 或
mcpbridge 託管。
- 單個
host:port 只能有一個監聽器；同一端口上的其他進程將跳過儀表盤啟動並繼續 MCP 流量。
- 對於明確的階段 6 操作員工作流，使用
--broker-daemon --web-ui 運行一個專用的代理主機，然後從瀏覽器儀表盤和/或 mcpbridge-wrapper --tui 監控同一主機。
詳見 Web UI 設置指南 以獲取詳細配置信息。
🔧 技術細節
問題描述
Xcode 的 mcpbridge 在 content 字段中返回工具響應，但當工具聲明 outputSchema 時，會省略所需的 structuredContent 字段。根據 MCP 規範，當聲明 outputSchema 時，響應 必須 包含 structuredContent。
- ✅ Claude Code 和 Codex CLI 可以正常工作（它們對 Apple 的響應有特殊處理）。
- ❌ Cursor 嚴格遵循規範，會拒絕不符合規範的響應。
解決方案
mcpbridge-wrapper 攔截 xcrun mcpbridge 的響應，並將 content 中的數據複製到 structuredContent 中，使 Xcode 的 MCP 工具與所有 MCP 客戶端完全兼容。
┌─────────────┐ MCP Protocol ┌──────────────────┐ MCP Protocol ┌────────────┐ XPC ┌─────────┐
│ Cursor │ ◄────────────────► │ mcpbridge-wrapper│ ◄──────────────► │ mcpbridge │ ◄───────► │ Xcode │
│ (MCP Client)│ │ (This Project) │ │ (Bridge) │ │ (IDE) │
└─────────────┘ └──────────────────┘ └────────────┘ └─────────┘
已知問題
- 代理冷啟動 — Xcode 批准時間競爭（顯示 0 個工具但有綠色圓點）：當代理守護進程啟動一個新的
xcrun mcpbridge 進程（首次啟動或守護進程重啟後），Xcode 會顯示一個每個進程的 "Allow Connection?" 對話框。如果 MCP 客戶端在 Xcode 批准之前發送 tools/list 請求，它將收到一個空列表並 永久緩存 — 顯示 0 個工具並帶有綠色連接指示器，且沒有錯誤消息。每個唯一的二進制路徑（直接包裝器與代理守護進程）都會觸發一個 單獨的 對話框。批准後，權限將持續存在 — 後續會話無需重新批准。解決方法：在啟用代理模式後立即關注 Xcode 對話框；點擊允許後，在客戶端中重新加載 MCP 連接（在設置中禁用 → 重新啟用）。詳見 故障排除：首次代理連接後顯示 0 個工具 以獲取特定客戶端的恢復步驟和診斷命令。
- BUG-T5 → FU-P13-T7 (P0)：空內容的工具結果仍可能違反嚴格 MCP 客戶端對
structuredContent 的嚴格要求。
- BUG-T6 → FU-P13-T8 (P0)：當多個 MCP 會話使用相同的
--web-ui-port（例如 8080）啟動時，可能會發生 Web UI 端口衝突，導致 address already in use 錯誤。
- BUG-T7 → FU-P13-T9 (P0)：在某些客戶端路徑中，
resources/list 和 resources/templates/list 探測可能會返回非標準的錯誤格式。
免責聲明（Codex App）
mcpbridge-wrapper 對 Xcode MCP 響應進行規範化處理，但它無法控制 Codex App 的內部行為。Codex App 的傳輸/會話行為可能獨立於 Codex CLI 和此包裝器發生變化。如果 App 和 CLI 表現不同，請首先將其視為客戶端特定行為，並使用確切的版本、配置和日誌進行驗證。
文檔
- 安裝指南
- 代理模式指南 - 配置、遷移、回退和操作
- Web UI 儀表盤 - 即時監控和審計日誌記錄
- Cursor 設置
- Claude Code 設置
- Codex CLI 設置
- 故障排除
- 工具參考
- 架構
- 貢獻指南 - 開發指南和質量檢查
開發
詳見 CONTRIBUTING.md 以獲取開發設置和貢獻指南。
快速質量檢查：
make test
make lint
make typecheck
或者運行所有檢查：
make test && make lint && make typecheck
性能
- 開銷：每次轉換 <0.01ms
- 內存：佔用 <10MB
- 覆蓋率：測試覆蓋率為 91.62%
📄 許可證
本項目採用 MIT 許可證，詳情請參閱 LICENSE。
致謝
- Apple 的 Xcode 團隊提供了 MCP 橋接功能。
- MCP 協議規範。
- Cursor、Claude 和 Codex 團隊提供的人工智能開發工具。
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%230080ff;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='st0'%20d='M16.2,11.1c.4.5.4,1.2,0,1.8l-4.7,7.1h-3.8l5.3-8L7.6,4h3.8l4.7,7.1Z'/%3e%3c/svg%3e)
