前言¶

在 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