前言¶

在 DSH（DeepSeek Harness）裏做 macOS / iOS 開發，有一個現實問題：構建工程、跑單元測試、看 SwiftUI Preview、操作模擬器，這些事平時都在 Xcode UI 裏完成，agent 插不上手。DSH 的理念是「一切皆插件」，這類能力缺口通常靠插件來補。

Xcode 27 起，系統內置了 headless MCP 服務（xcrun mcp-server / xcrun mcpbridge），把上述能力以 MCP 工具的形式暴露出來。但要在 DSH 裏用上它們，還需要一層橋接，把這些 MCP 工具轉成 DSH 原生工具。本文介紹的 dsh-mcp-xcode 就是這樣一個插件。

這是什麼¶

dsh-mcp-xcode 是 nanshanyi 維護的 DSH 插件，定位一句話：把 Xcode Headless MCP（xcrun mcpbridge）橋接爲 DSH 原生工具。裝上之後，DSH agent 無需打開 Xcode UI，就能直接調用 Xcode 的全部 headless 能力。

實現上，插件通過 subprocess 啓動 /usr/bin/xcrun mcpbridge，在 stdio 上自行實現 MCP（JSON-RPC 2.0）客戶端，連接建立後把 tools/list 返回的工具逐個註冊爲 DSH 工具。運行環境要求 Node >= 20，零運行時依賴。

核心功能¶

橋接之後，agent 可用的能力包括：

• 創建 / 打開工程、構建、測試；
• 渲染 SwiftUI Preview 爲 PNG；
• 啓動模擬器並交互（tap / type / swipe）；
• 讀取截圖與無障礙層級；
• 讀取 OSLog。

Xcode 27 實測共有 54 個工具，插件把它們統一註冊爲 xcode_<原名> 格式的 DSH 工具。工具調用過程中的截圖會自動存入 attachment，並通過 deferContext 注入下一輪模型上下文。

插件自帶一個控制工具 xcode_mcp_status，用於查看連接狀態、強制重連、查看 bridge stderr。

另外有斷橋自愈機制：xcrun mcpbridge 進程崩潰或被終止後，xcode_* 工具保持註冊，下一次調用會自動重連並同步註冊（按名對賬，不會出現 already registered），不需要人工干預。

安裝與啓用¶

先確認前置條件：macOS + Xcode 27 或更高（headless MCP 自 Xcode 27 beta 5 起內置，更早版本沒有這些命令；本項目在 27.0 27A5237l 上開發驗證），並保證 headless 服務已開啓並運行：

xcrun mcp-server status          # Permission: enabled / mcp-server: running
sudo xcrun mcp-server enable     # 若未啓用
xcrun mcp-server start           # 若未運行

然後一條命令安裝：

# 從 GitHub 安裝（推薦）
dsh plugin --profile web add "github:nanshanyi/dsh-mcp-xcode#v1.0.0"

# 或本地路徑
dsh plugin --profile web add file:/path/to/dsh-mcp-xcode

本包通過 dsh.bundle.patch 自描述掛載：安裝後無需編輯任何 profile 文件，重啓 DSH 即生效，插件列表裏可見，xcode_* 工具對所有會話可用。如果你之前手動在 cordis.patch.yml 裏寫過本插件的行，請先刪掉，避免雙掛載。

首次連接會彈出 Xcode agent 授權框，批准一次即可。DSH 是簽名應用，授權永久有效；未簽名客戶端則約 24 小時過期。構建報 Operation not permitted 時，需要給 headless 服務授權工程所在文件夾：

sudo xcrun mcp-server allow-folder /path/to/your/projects

配置（可選）¶

全部配置寫在 patch 行的 config 下：

config:
  clientName: deepseek-harness   # 顯示在 Xcode 授權彈窗裏的客戶端名
  bridgePath: /usr/bin/xcrun     # 橋可執行文件
  bridgeArgs: ['mcpbridge']      # 橋參數
  includeTools: ['BuildProject', 'XcodeList*']   # 只註冊匹配的工具
  excludeTools: ['StringCatalog*']               # 排除匹配的工具

includeTools / excludeTools 按 Xcode 工具原名做錨定匹配，支持 * 與 ? 通配，大小寫敏感，excludeTools 優先。xcode_mcp_status 是控制通道，不受篩選影響，永遠註冊。篩選的常見用途是給模型瘦身——54 個工具的 schema 描述會佔用不少上下文。

典型用法¶

經過上面的步驟，工具已經全部可用。直接用自然語言描述任務即可，比如：

打開 /path/to/Project.xcodeproj，跑一遍單元測試，把失敗的用例列出來

遇到連接問題時，讓 agent 調用 xcode_mcp_status（必要時帶 reconnect: true）排障。

適用場景與注意¶

適合在 DSH 裏搭建 macOS / iOS agent 工作流的開發者：構建驗證、批量跑測試、查看 Preview 渲染結果、模擬器交互這一類需要 Xcode 能力的任務。

使用前注意幾點：

• 和所有第三方插件一樣，dsh-mcp-xcode 以當前 dsh 進程的權限運行，安裝前建議先檢查源碼與許可證（MIT，README 與 package.json 均有註明）；
• 連接走的是 Xcode 官方 headless 權限模型，簽名應用一次批准長期有效；
• 插件不發佈任何 service，也不修改 Xcode 權限存儲；停止或禁用插件會終止它持有的 mcpbridge 子進程。

小結¶

dsh-mcp-xcode 做的事情很剋制：把 xcrun mcpbridge 暴露的 54 個工具原樣接進 DSH，配上授權引導、斷橋自愈和狀態排查工具，讓 agent 在不開 Xcode UI 的情況下完成構建、測試和模擬器操作。

• 社區目錄頁：https://www.skillhub.cn/plugins/nanshanyi/dsh-mcp-xcode
• GitHub 倉庫：https://github.com/nanshanyi/dsh-mcp-xcode