axiom-xcode-mcp-tools

Xcode MCP 工具工作流

核心原则：Xcode MCP 提供对 IDE 的编程式访问。使用工作流循环，而不是孤立地调用工具。

窗口定位（关键基础）

大多数工具都需要 tabIdentifier。请始终先调用 XcodeListWindows。

1. XcodeListWindows → list of (tabIdentifier, workspacePath) pairs
2. Match workspacePath to your project
3. Use that tabIdentifier for all subsequent tool calls

在本次会话中缓存映射关系。仅在以下情况重新获取：

• 工具调用因 tab 标识符无效而失败
• 打开或关闭了 Xcode 窗口
• 切换了项目

如果 XcodeListWindows 返回空结果：Xcode 中没有打开项目。请让用户打开项目。

工作流：BuildFix 循环

反复构建、诊断并修复，直到项目编译通过。

1. BuildProject(tabIdentifier)
2. Check buildResult — if success, done
3. GetBuildLog(tabIdentifier) → parse errors
4. XcodeListNavigatorIssues(tabIdentifier) → canonical diagnostics
5. XcodeUpdate(file, fix) for each diagnostic
6. Go to step 1 (max 5 iterations)
7. If same error persists after 3 attempts → fall back to axiom-xcode-debugging

为何使用 XcodeListNavigatorIssues，而不解析构建日志：Issue Navigator 提供结构化且去重后的诊断信息。构建日志包含未经整理、带有冗余信息的编译器输出。

何时改用 axiom-xcode-debugging：当错误来自环境（僵尸进程、过时的 Derived Data、模拟器问题），而非代码时。MCP 工具用于操作代码；环境问题需要通过 CLI 进行诊断。

工作流：TestFix 循环

快速迭代修复失败的测试。

1. GetTestList(tabIdentifier) → discover available tests
2. RunSomeTests(tabIdentifier, [specific failing tests]) for fast iteration
3. Parse failures → identify code to fix
4. XcodeUpdate(file, fix) to patch code
5. Go to step 2 (max 5 iterations per test)
6. RunAllTests(tabIdentifier) as final verification

为何先运行 RunSomeTests：运行单个测试只需几秒，而运行所有测试需要几分钟。先针对失败的测试进行迭代，修复后再验证完整测试套件。

解析测试结果：查找响应中的 testResult 字段。失败的测试会包含错误消息、文件路径和行号。

工作流：PreviewVerify

渲染 SwiftUI 预览，并通过视觉方式验证 UI 更改。

1. RenderPreview(tabIdentifier, sourceFilePath, previewDefinitionIndexInFile: 0) → image artifact
2. Review the rendered image for correctness
3. If making changes: XcodeUpdate → RenderPreview again
4. Compare before/after for regressions

适用场景：验证布局更改、检查深色模式下的外观，以及确认 Liquid Glass 效果是否正确渲染。

工作流：IssueTriage

将 Xcode 的 Issue Navigator 用作规范的诊断信息来源。

1. XcodeListNavigatorIssues(tabIdentifier) → all current issues
2. For specific files: XcodeRefreshCodeIssuesInFile(tabIdentifier, file)
3. Prioritize: errors > warnings > notes
4. Fix errors first, rebuild, re-check

为何优于通过 grep 搜索错误：Issue Navigator 会跟踪实时诊断信息，包括类型检查错误、缺少导入和约束问题等，只有 Xcode 的编译器前端才能发现的问题。

工作流：DocumentationSearch

通过 MCP 查询 Apple 文档库。

1. DocumentationSearch(query) → documentation results
2. Cross-reference with axiom-apple-docs for bundled Xcode guides

注意：DocumentationSearch 搜索 Apple 在线文档和 WWDC 文字稿。对于 Xcode 内置的 20 份面向大模型的指南，请改用 axiom-apple-docs。

通过 MCP 执行文件操作

读取和写入

操作	工具	说明
读取文件内容	XcodeRead	可查看 Xcode 的项目视图（生成的文件、已解析的软件包）
创建新文件	XcodeWrite	创建文件，并自动添加到项目结构中
编辑现有文件	XcodeUpdate	使用 str_replace 风格的补丁，比完整重写更安全
搜索文件	XcodeGlob	在项目中进行模式匹配
搜索文件内容	XcodeGrep	搜索内容并显示行号
列出目录	XcodeLS	列出目录内容
创建目录	XcodeMakeDir	创建目录

破坏性操作（需要确认）

操作	工具	风险
删除文件/目录	XcodeRM	默认移至废纸篓（deleteFiles: true）——请与用户确认
移动/重命名文件	XcodeMV	可能会破坏导入和引用

调用 XcodeRM 或 XcodeMV 前，务必先与用户确认破坏性操作。

何时使用 MCP 文件工具，而非标准工具

场景	使用 MCP	使用标准工具（Read/Write/Grep）
Xcode 项目视图中的文件	是——包含生成的文件和已解析的文件	可能会遗漏生成的文件
项目外的文件	否	是——标准工具可在任何位置工作
需要构建上下文（编辑后诊断）	是——在一个工作流中编辑并重新构建	不支持构建集成
简单的文件读取/编辑	两者均可	稍快一些（无 MCP 开销）

代码片段

执行 Swift 代码

ExecuteSnippet(tabIdentifier, codeSnippet: "print(MyModel.self)", sourceFilePath: "Sources/MyModel.swift")

在特定 Swift 文件的上下文中运行代码，可访问该文件的 fileprivate 声明。它不是通用 REPL。没有 language 参数（仅支持 Swift）。

常见问题与反模式

标签页标识符失效

以下情况会导致标签页标识符失效：

• 关闭并重新打开 Xcode 窗口
• 关闭并重新打开项目
• 重启 Xcode

解决方法：再次调用 XcodeListWindows 获取新的标识符。

XcodeWrite 与 XcodeUpdate

• XcodeWrite — 创建新文件。如果文件已存在，则会失败（部分客户端中如此）。
• XcodeUpdate — 使用 oldString/newString 替换内容来修补现有文件。每次调用只能替换一处（如需替换所有匹配项，请使用 replaceAll: true）。

常见错误：使用 XcodeWrite 编辑现有文件会覆盖其全部内容。编辑时请使用 XcodeUpdate。

架构合规性

Xcode 的 mcpbridge 存在已知的 MCP 规范违规问题：当工具声明了 outputSchema 时，它会填充 content，但省略 structuredContent。这会导致严格遵循 MCP 规范的客户端（Cursor、某些 Zed 配置）无法正常工作。

解决方法：将 XcodeMCPWrapper 用作严格客户端的代理。

文件变更后进行构建

调用 XcodeUpdate 后，项目可能需要构建才能显示新的诊断信息。不要在未重新构建的情况下假定编辑正确。

避免自我合理化

想法	实际情况
“我直接用 xcodebuild 就行”	MCP 可提供 IDE 状态、导航器诊断信息和预览，这些是 CLI 不具备的
“Read 工具读取 Xcode 文件完全没问题”	XcodeRead 可查看 Xcode 的项目视图，包括生成的文件和已解析的包
“我只有一个项目，不用管标签页标识符”	大多数工具在缺少 tabIdentifier 时会静默失败——务必先调用 XcodeListWindows
“每次都运行所有测试”	迭代时用 RunSomeTests，验证时用 RunAllTests——每轮可节省几分钟
“我会解析构建日志来查找错误”	XcodeListNavigatorIssues 可提供结构化且去重后的诊断信息
“用 XcodeWrite 更新文件”	编辑时用 XcodeUpdate。XcodeWrite 用于创建或覆盖文件。用错工具会导致数据丢失。
“调用一次工具就够了”	工作流（BuildFix、TestFix）会循环执行。孤立调用会错过迭代模式。

资源

技能：axiom-xcode-mcp-setup、axiom-xcode-mcp-ref、axiom-xcode-debugging