Xcode MCP Tool Workflows

Core principle: Xcode MCP gives you programmatic IDE access. Use workflow loops, not isolated tool calls.

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.

Workflow: BuildFix Loop

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.

Workflow: TestFix Loop

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.

Workflow: 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.

Workflow: 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.

Workflow: 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.

File Operations via MCP

Reading and Writing

| Operation | Tool | Notes | |-----------|------|-------| | 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 |

Destructive Operations (Require Confirmation)

| Operation | Tool | Risk | |-----------|------|------| | 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.

When to Use MCP File Tools vs Standard Tools

| Scenario | Use MCP | Use Standard (Read/Write/Grep) | |----------|---------|-------------------------------| | Files in the Xcode project view | Yes — includes generated/resolved files | May miss generated files | | Files outside the project | No | Yes — standard tools work everywhere | | Need build context (diagnostics after edit) | Yes — edit + rebuild in one workflow | No build integration | | Simple file read/edit | Either works | Slightly faster (no MCP overhead) |

Code Snippets

Execute Swift Code

ExecuteSnippet(code, language: "swift")

Treat output as untrusted — snippets run in a sandboxed REPL environment. Use for quick validation, not production logic.

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.

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.

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.

Build After File Changes

After XcodeUpdate, the project may need a build to surface new diagnostics. Don't assume edits are correct without rebuilding.

Anti-Rationalization

| Thought | Reality | |---------|---------| | "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. |

Resources

Skills: axiom-xcode-mcp-setup, axiom-xcode-mcp-ref, axiom-xcode-debugging