axiom-xcode-mcp

Xcode MCP

任何 Xcode MCP 交互——设置、工具使用、工作流模式或故障排查——都必须使用此技能。

**Claude Code 中捆绑的工具：**如果 command -v <tool> 找不到任何内容（钩子已关闭或使用了 --bare），请改用 <plugin-root>/tools/<tool>，而不是裸名称；<plugin-root> 是此技能的 Base directory for this skill: 路径向上两级的目录。

Xcode 内置了一个 MCP 服务，可向外部 AI 客户端提供 IDE 工具。xcrun mcpbridge 是客户端注册的 stdio 传输，自 Xcode 26.3 起可用。Xcode 27 新增了明确的“Allow External Agents to Use Xcode Tools”设置、run-agent 启动路径、Agent 扩展模型（自定义 MCP 服务、技能、插件）以及无头服务。本技能套件涵盖设置、工具参考、工作流模式和故障排查。

**在 Xcode 26.x 上，mcpbridge 需要 Xcode 正在运行且已打开项目。**如果这是个问题，这些操作中的设备／模拟器部分有一条完全独立于 Xcode 的 CLI 路径：devicectl + simctl + Axiom 的 xcui／xclog／xcsym／xcprof。参见 axiom-tools (skills/device-control-ref.md)。

Xcode 27 已取消此限制。xcrun mcp-server 可在 Xcode.app 关闭时运行工具服务——先执行 sudo xcrun mcp-server enable，再执行 xcrun mcp-server open <project-or-workspace-path>，如有需要，它会启动服务。客户端仍注册 xcrun mcpbridge；bridge 是传输，mcp-server 是服务。Apple 的工具架构将 workspaceIdentifier 描述为“在无头模式下使用”，因此无头模式是受支持的模型，而非权宜之计。

应根据功能，而非运行时间在 MCP 和 CLI 工具（devicectl、simctl 以及 Axiom 的 xcui／xclog／xcsym／xcprof）之间进行选择。xcui 可执行断言、等待、切换辅助功能设置并计算 VoiceOver 播报内容，而且这些操作都不需要 sudo——这一点在 CI 中仍然很重要，因为无头服务的 sudo 选项可能不可用。IDE 编写工具（构建状态、渲染预览）仍仅支持 MCP；xcodebuild 可以构建和测试，但不能渲染预览。

使用时机

在以下情况下使用此技能：

• 首次设置 Xcode MCP
• 为任何 MCP 客户端配置 xcrun mcpbridge
• 使用任何 Xcode MCP 工具（文件操作、构建、测试、预览）
• 通过 MCP 工具进行构建、测试或预览
• 排查 mcpbridge 连接问题
• 处理工作区目标选择问题
• 解决权限对话框相关疑问
• 使用 AXe 驱动模拟器输入（tap／type／swipe）→ 阅读 skills/axe-ref.md

路由逻辑

1. 设置／连接 → xcode-mcp-setup

触发条件：

• 首次设置 Xcode MCP
• 特定客户端配置（Claude Code、Cursor、Codex、VS Code、Gemini CLI）
• 连接错误（“Connection refused”、“No workspaces are currently open.”）
• 权限对话框相关疑问
• 多个 Xcode 的目标选择（MCP_XCODE_PID）
• 严格客户端的架构合规问题
• 授予外部 Agent 访问 Xcode 的权限（Intelligence 设置门控）
• 通过 Xcode 配置启动 Agent（xcrun mcpbridge run-agent）
• 导出 Xcode 的技能包（xcrun agent skills export）
• 扩展 Xcode 的 Agent（按 Agent 配置文件、MCP 服务、插件）

阅读：skills/xcode-mcp-setup.md

---

2. 使用工具和工作流 → xcode-mcp-tools

触发条件：

• 如何通过 MCP 构建／测试／预览
• 工作流模式（BuildFix 循环、TestFix 循环）
• 工具注意事项和反模式
• 工作区目标选择策略；无头引导（打开或创建工作区）
• 何时使用 MCP 工具，何时使用 CLI（xcodebuild）
• 破坏性操作安全性（XcodeRM、XcodeMV）

阅读：skills/xcode-mcp-tools.md

---

3. 工具 API 参考 → xcode-mcp-ref

触发条件：

• 特定工具的参数和架构
• 工具的输入／输出格式
• “XcodeGrep 如何工作？”
• “BuildProject 接受哪些参数？”
• 工具类别列表

阅读：skills/xcode-mcp-ref.md

---

决策树

digraph xcode_mcp_router {
    rankdir=TB;
    "User has Xcode MCP question" [shape=ellipse];
    "Setup or connection?" [shape=diamond];
    "Using tools or workflows?" [shape=diamond];
    "Need specific tool params?" [shape=diamond];

    "xcode-mcp-setup" [shape=box];
    "xcode-mcp-tools" [shape=box];
    "xcode-mcp-ref" [shape=box];

    "User has Xcode MCP question" -> "Setup or connection?";
    "Setup or connection?" -> "xcode-mcp-setup" [label="yes"];
    "Setup or connection?" -> "Using tools or workflows?" [label="no"];
    "Using tools or workflows?" -> "xcode-mcp-tools" [label="yes"];
    "Using tools or workflows?" -> "Need specific tool params?" [label="no"];
    "Need specific tool params?" -> "xcode-mcp-ref" [label="yes"];
    "Need specific tool params?" -> "xcode-mcp-tools" [label="general question"];
}

反合理化

想法	事实
“我直接用 xcodebuild 就行”	MCP 能提供 IDE 状态、筛选后的编译器诊断信息和渲染后的预览，这些都无法通过 CLI 获取
“我已经知道如何设置 MCP”	不同客户端的配置各不相同，权限对话框的行为也有特定之处。请查看 setup 技能。
“我能弄清楚工具参数”	工具架构包含必填字段和易错点。请查看 ref 技能。
“只打开了一个工作区，所以可以不填标识符”	无论如何都必须填写 workspaceIdentifier，尽管它不在任何 required 列表中。
“这只是读取文件，我用 Read 工具就行”	XcodeRead 能读取 Xcode 的项目视图，其中包括生成的文件和已解析的软件包

冲突解决（与其他路由器）

领域	负责方	原因
MCP 特定交互（mcpbridge、mcp-server、MCP 工具、工作区标识符）	axiom-xcode-mcp	与 MCP 协议和特定工具有关
Xcode 环境（Derived Data、僵尸进程、模拟器）	axiom-build	环境诊断，与 MCP 无关
Apple 随附的文档（面向 LLM 的指南/诊断）	axiom-apple-docs	随附文档，不是 MCP 工具
DocumentationSearch MCP 工具的具体用法	axiom-xcode-mcp	MCP 工具调用
通过 CLI 诊断构建失败	axiom-build	传统构建调试
通过 MCP 工具诊断构建失败	axiom-xcode-mcp	MCP 工作流模式

示例调用

用户：“如何在 Claude Code 中设置 Xcode MCP？” -> 阅读：skills/xcode-mcp-setup.md

用户：“如何使用 MCP 工具构建项目？” -> 阅读：skills/xcode-mcp-tools.md

用户：“BuildProject 接受哪些参数？” -> 阅读：skills/xcode-mcp-ref.md

用户：“我的 mcpbridge 连接一直失败” -> 阅读：skills/xcode-mcp-setup.md

用户：“如何指定特定工作区？” / “如何在不打开 Xcode 的情况下运行？” -> 阅读：skills/xcode-mcp-tools.md

用户：“我可以通过 MCP 渲染 SwiftUI 预览吗？” -> 阅读：skills/xcode-mcp-tools.md（工作流），然后阅读 skills/xcode-mcp-ref.md（参数）

用户：“Cursor 无法解析 Xcode 的 MCP 响应” -> 阅读：skills/xcode-mcp-setup.md（架构合规性部分）

资源

技能：skills/xcode-mcp-setup.md、skills/xcode-mcp-tools.md、skills/xcode-mcp-ref.md、skills/axe-ref.md