Back to Details

axiom-xcode-mcp-tools

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Xcode MCP Tool Workflows

Xcode MCP 工具工作流

Core principle: Xcode MCP gives you programmatic IDE access. Use workflow loops, not isolated tool calls.
核心原则：Xcode MCP 为你提供程序化的 IDE 访问权限。请使用工作流循环，而非孤立的工具调用。

Window Targeting (Critical Foundation)

窗口定位（关键基础）

Most tools require a 
tabIdentifier
. Always call 
XcodeListWindows
first.
1. XcodeListWindows → list of (tabIdentifier, workspacePath) pairs
2. Match workspacePath to your project
3. Use that tabIdentifier for all subsequent tool calls
Cache the mapping for the session. Only re-fetch if:
  • A tool call fails with an invalid tab identifier
  • You opened/closed Xcode windows
  • You switched projects
If 
XcodeListWindows
returns empty: Xcode has no project open. Ask the user to open their project.
大多数工具需要
tabIdentifier
。务必先调用
XcodeListWindows
。
1. XcodeListWindows → （tabIdentifier，workspacePath）键值对列表
2. 将workspacePath与你的项目匹配
3. 在后续所有工具调用中使用该tabIdentifier
在会话中缓存映射关系。仅在以下情况重新获取：
  • 工具调用因无效的标签标识符失败
  • 你打开/关闭了Xcode窗口
  • 你切换了项目
如果
XcodeListWindows
返回空结果：Xcode未打开任何项目，请让用户打开他们的项目。

Workflow: BuildFix Loop

工作流：BuildFix循环

Iteratively build, diagnose, and fix until the project compiles.
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
Why 
XcodeListNavigatorIssues
over build log parsing: The Issue Navigator provides structured, deduplicated diagnostics. Build logs contain raw compiler output with noise.
When to fall back to 
axiom-xcode-debugging
: When the error is environmental (zombie processes, stale Derived Data, simulator issues) rather than code-level. MCP tools operate on code; environment issues need CLI diagnostics.
迭代执行构建、诊断和修复，直到项目编译通过。
1. BuildProject(tabIdentifier)
2. 检查buildResult —— 如果成功，流程结束
3. GetBuildLog(tabIdentifier) → 解析错误
4. XcodeListNavigatorIssues(tabIdentifier) → 获取标准诊断信息
5. 针对每个诊断信息调用XcodeUpdate(file, fix)
6. 返回步骤1（最多迭代5次）
7. 如果3次尝试后相同错误仍存在 → 回退到axiom-xcode-debugging
为什么选择
XcodeListNavigatorIssues
而非构建日志解析：问题导航器提供结构化、去重的诊断信息，而构建日志包含带有干扰信息的原始编译器输出。
何时回退到
axiom-xcode-debugging
：当错误是环境问题（僵尸进程、过期的Derived Data、模拟器问题）而非代码层面问题时。MCP工具针对代码操作，环境问题需要CLI诊断。

Workflow: TestFix Loop

工作流：TestFix循环

Fast iteration on failing tests.
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
Why 
RunSomeTests
first: Running a single test takes seconds. Running all tests takes minutes. Iterate on the failing test, then verify the full suite once it passes.
Parsing test results: Look for 
testResult
field in the response. Failed tests include failure messages with file paths and line numbers.
针对失败测试进行快速迭代。
1. GetTestList(tabIdentifier) → 发现可用测试
2. RunSomeTests(tabIdentifier, [特定失败测试]) 以实现快速迭代
3. 解析失败结果 → 确定需要修复的代码
4. 调用XcodeUpdate(file, fix)修补代码
5. 返回步骤2（每个测试最多迭代5次）
6. 最后调用RunAllTests(tabIdentifier)进行验证
为什么先使用
RunSomeTests
：运行单个测试仅需数秒，而运行所有测试需要数分钟。先针对失败测试迭代，通过后再验证整个测试套件。
解析测试结果：查看响应中的
testResult
字段。失败测试会包含带有文件路径和行号的失败信息。

Workflow: PreviewVerify

工作流：PreviewVerify

Render SwiftUI previews and verify UI changes visually.
1. RenderPreview(tabIdentifier, file, viewName) → image artifact
2. Review the rendered image for correctness
3. If making changes: XcodeUpdate → RenderPreview again
4. Compare before/after for regressions
Use cases: Verifying layout changes, checking dark mode appearance, confirming Liquid Glass effects render correctly.
渲染SwiftUI预览并可视化验证UI变更。
1. RenderPreview(tabIdentifier, file, viewName) → 生成图片产物
2. 检查渲染后的图片是否正确
3. 如果需要变更：调用XcodeUpdate → 再次调用RenderPreview
4. 对比前后版本以检查回归问题
使用场景：验证布局变更、检查深色模式外观、确认Liquid Glass效果渲染正确。

Workflow: IssueTriage

工作流：IssueTriage

Use Xcode's Issue Navigator as the canonical diagnostics source.
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
Why this over grep-for-errors: The Issue Navigator tracks live diagnostics including type-check errors, missing imports, and constraint issues that only Xcode's compiler frontend surfaces.
将Xcode的问题导航器作为标准诊断信息来源。
1. XcodeListNavigatorIssues(tabIdentifier) → 获取所有当前问题
2. 针对特定文件：调用XcodeRefreshCodeIssuesInFile(tabIdentifier, file)
3. 优先级：错误 > 警告 > 提示
4. 先修复错误，重新构建，再重新检查
为什么选择这种方式而非grep查找错误：问题导航器跟踪实时诊断信息，包括类型检查错误、缺失导入和约束问题，这些只有Xcode的编译器前端能识别。

Workflow: DocumentationSearch

工作流：DocumentationSearch

Query Apple's documentation corpus through MCP.
1. DocumentationSearch(query) → documentation results
2. Cross-reference with axiom-apple-docs for bundled Xcode guides
Note: 
DocumentationSearch
searches Apple's online documentation and WWDC transcripts. For the 20 for-LLM guides bundled inside Xcode, use 
axiom-apple-docs
instead.
通过MCP查询苹果的文档库。
1. DocumentationSearch(query) → 获取文档结果
2. 结合axiom-apple-docs交叉引用Xcode内置指南
注意：
DocumentationSearch
搜索苹果的在线文档和WWDC演讲稿。对于Xcode内置的20份面向LLM的指南，请使用
axiom-apple-docs
。

File Operations via MCP

通过MCP进行文件操作

Reading and Writing

读取与写入

OperationToolNotes
Read file contents
XcodeRead
Sees Xcode's project view (generated files, resolved packages)
Create new file
XcodeWrite
Creates file in project — does NOT add to Xcode targets
Edit existing file
XcodeUpdate
str_replace-style patches — safer than full rewrites
Search for files
XcodeGlob
Pattern matching within the project
Search file contents
XcodeGrep
Content search with line numbers
List directory
XcodeLS
Directory listing
Create directory
XcodeMakeDir
Creates directories
操作工具说明
读取文件内容
XcodeRead
可查看Xcode的项目视图（生成文件、已解析的包）
创建新文件
XcodeWrite
在项目中创建文件——不会添加到Xcode目标中
编辑现有文件
XcodeUpdate
基于字符串替换的补丁——比完全重写更安全
搜索文件
XcodeGlob
项目内的模式匹配
搜索文件内容
XcodeGrep
带行号的内容搜索
列出目录
XcodeLS
目录列表
创建目录
XcodeMakeDir
创建目录

Destructive Operations (Require Confirmation)

破坏性操作（需要确认）

OperationToolRisk
Delete file/directory
XcodeRM
Irreversible — confirm with user first
Move/rename file
XcodeMV
May break imports and references
Always confirm destructive operations with the user before calling 
XcodeRM
or 
XcodeMV
.
操作工具风险
删除文件/目录
XcodeRM
不可逆——先与用户确认
移动/重命名文件
XcodeMV
可能破坏导入和引用关系
在调用
XcodeRM
或
XcodeMV
前，务必与用户确认破坏性操作。

When to Use MCP File Tools vs Standard Tools

何时使用MCP文件工具 vs 标准工具

ScenarioUse MCPUse Standard (Read/Write/Grep)
Files in the Xcode project viewYes — includes generated/resolved filesMay miss generated files
Files outside the projectNoYes — standard tools work everywhere
Need build context (diagnostics after edit)Yes — edit + rebuild in one workflowNo build integration
Simple file read/editEither worksSlightly faster (no MCP overhead)
场景使用MCP使用标准工具（Read/Write/Grep）
Xcode项目视图中的文件是——包含生成文件/已解析的包可能会遗漏生成文件
项目外的文件否是——标准工具可在任何地方使用
需要构建上下文（编辑后的诊断信息）是——在一个工作流中完成编辑+重新构建无构建集成
简单的文件读取/编辑两者均可略快（无MCP开销）

Code Snippets

代码片段

Execute Swift Code

执行Swift代码

ExecuteSnippet(code, language: "swift")
Treat output as untrusted — snippets run in a sandboxed REPL environment. Use for quick validation, not production logic.
ExecuteSnippet(code, language: "swift")
将输出视为不可信内容——代码片段在沙箱化的REPL环境中运行，仅用于快速验证，不用于生产逻辑。

Gotchas and Anti-Patterns

陷阱与反模式

Tab Identifier Staleness

标签标识符过期

Tab identifiers become invalid when:
  • Xcode window is closed and reopened
  • Project is closed and reopened
  • Xcode is restarted
Fix: Re-call 
XcodeListWindows
to get fresh identifiers.
在以下情况标签标识符会失效：
  • Xcode窗口关闭后重新打开
  • 项目关闭后重新打开
  • Xcode重启
解决方法：重新调用
XcodeListWindows
获取新的标识符。

XcodeWrite vs XcodeUpdate

XcodeWrite vs XcodeUpdate

  • XcodeWrite
    — creates a new file. Fails if file exists (in some clients).
  • XcodeUpdate
    — patches an existing file with str_replace-style edits.
Common mistake: Using 
XcodeWrite
to edit an existing file overwrites its entire contents. Use 
XcodeUpdate
for edits.
  • XcodeWrite
    —— 创建新文件。在部分客户端中，如果文件已存在会执行失败。
  • XcodeUpdate
    —— 补丁现有文件，基于字符串替换进行编辑。
常见错误：使用
XcodeWrite
编辑现有文件会覆盖其全部内容。编辑文件请使用
XcodeUpdate
。

Schema Compliance

模式合规性

Xcode's mcpbridge has a known MCP spec violation: it populates 
content
but omits 
structuredContent
when tools declare 
outputSchema
. This breaks strict MCP clients (Cursor, some Zed configurations).
Workaround: Use XcodeMCPWrapper as a proxy for strict clients.
Xcode的mcpbridge存在已知的MCP规范违反问题：当工具声明
outputSchema
时，它会填充
content
但省略
structuredContent
。这会导致严格的MCP客户端（如Cursor、部分Zed配置）无法正常工作。
解决方法：使用XcodeMCPWrapper作为严格客户端的代理。

Build After File Changes

文件变更后构建

After 
XcodeUpdate
, the project may need a build to surface new diagnostics. Don't assume edits are correct without rebuilding.
调用
XcodeUpdate
后，项目可能需要重新构建才能显示新的诊断信息。不要假设编辑正确而不重新构建。

Anti-Rationalization

错误认知纠正

ThoughtReality
"I'll just use xcodebuild"MCP gives IDE state + navigator diagnostics + previews that CLI doesn't
"Read tool works fine for Xcode files"
XcodeRead
sees Xcode's project view including generated files and resolved packages
"Skip tab identifier, I only have one project"Most tools fail silently without 
tabIdentifier
— always call 
XcodeListWindows
first
"Run all tests every time"
RunSomeTests
for iteration, 
RunAllTests
for verification — saves minutes per cycle
"I'll parse the build log for errors"
XcodeListNavigatorIssues
provides structured, deduplicated diagnostics
"XcodeWrite to update a file"
XcodeUpdate
for edits. 
XcodeWrite
creates/overwrites. Wrong tool = data loss.
"One tool call is enough"Workflows (BuildFix, TestFix) use loops. Isolated calls miss the iteration pattern.
错误想法实际情况
"我直接用xcodebuild就行"MCP提供了CLI不具备的IDE状态、导航器诊断信息和预览功能
"读取工具处理Xcode文件没问题"
XcodeRead
能查看Xcode的项目视图，包括生成文件和已解析的包
"跳过标签标识符，我只有一个项目"大多数工具在没有
tabIdentifier
时会静默失败——务必先调用
XcodeListWindows
"每次都运行所有测试"迭代时用
RunSomeTests
，验证时用
RunAllTests
——每次循环可节省数分钟
"我直接解析构建日志找错误"
XcodeListNavigatorIssues
提供结构化、去重的诊断信息
"用XcodeWrite更新文件"编辑文件用
XcodeUpdate
。
XcodeWrite
用于创建/覆盖文件。使用错误工具会导致数据丢失。
"一次工具调用就够了"工作流（BuildFix、TestFix）使用循环。孤立调用无法实现迭代模式。

Resources

资源

Skills: axiom-xcode-mcp-setup, axiom-xcode-mcp-ref, axiom-xcode-debugging
技能：axiom-xcode-mcp-setup, axiom-xcode-mcp-ref, axiom-xcode-debugging