Xcode MCP Workflow

Xcode MCP Workflow

Overview

Use this skill for end-to-end Xcode MCP tasks that need more than one focused Xcode MCP skill. It is a workflow coordinator: route to the narrower skills for details, keep state across steps, and stop when the user goal is verified or the next required input is genuinely missing.

Tool Availability

Before calling MCP tools, confirm the mcp__xcode namespace is available. If needed tools are not visible, use tool_search with the relevant tool names from the focused skill. If Xcode MCP still is not connected, report that directly and do not fall back to non-MCP Xcode actions when the user explicitly requested Xcode MCP.

Skill Routing

• Use $xcode-mcp-windows to select the Xcode tabIdentifier.
• Use $xcode-mcp-files to inspect the active file, list project groups, glob files, grep source, and read files.
• Use $xcode-mcp-edit for Xcode-aware file writes, precise replacements, group creation, moves, copies, and removals.
• Use $xcode-mcp-build to compile the active Xcode scheme.
• Use $xcode-mcp-diagnostics to inspect build logs, Issue Navigator, and single-file compiler diagnostics.
• Use $xcode-mcp-tests to list or run tests from the active scheme's active test plan.
• Use $xcode-mcp-preview to render SwiftUI previews.
• Use $xcode-mcp-snippet to execute small Swift snippets in source-file context.
• Use $xcode-mcp-docs for Apple Developer Documentation search when API behavior, migration, or framework usage is uncertain.
• For full app launch, Simulator interaction, debugging, signing, packaging, or profiling, route to a separate simulator/debugging or platform-specific skill when available.

Core Loop

1. Establish the Xcode tab with $xcode-mcp-windows.
2. Clarify only if multiple Xcode tabs match equally or the requested target is ambiguous.
3. Gather the narrowest evidence first: diagnostics, current file, grep results, tests, preview output, or documentation.
4. Read relevant files through $xcode-mcp-files before editing.
5. Apply the smallest Xcode-aware edit through $xcode-mcp-edit.
6. Verify with the narrowest relevant Xcode MCP action.
7. If verification fails, inspect the new evidence and repeat the loop only for issues plausibly caused by the current task.
8. Stop when the requested behavior is verified, or when further progress requires user input, unavailable tools, or an external state change.

Common Workflows

Fix Build Errors

1. Run $xcode-mcp-build or inspect existing diagnostics with $xcode-mcp-diagnostics.
2. Use $xcode-mcp-files to read files referenced by the highest-signal errors.
3. If an Apple API detail is uncertain, use $xcode-mcp-docs.
4. Patch with $xcode-mcp-edit.
5. Rebuild with $xcode-mcp-build.

Implement And Verify

1. Use $xcode-mcp-files to locate the owning code and call sites.
2. Use $xcode-mcp-docs only when Apple API details are relevant.
3. Edit with $xcode-mcp-edit.
4. Verify with $xcode-mcp-build, $xcode-mcp-tests, $xcode-mcp-preview, or $xcode-mcp-snippet, choosing the narrowest meaningful check.

Repair Tests

1. Use $xcode-mcp-tests to list or run the relevant tests.
2. Inspect failing diagnostics/logs with $xcode-mcp-diagnostics.
3. Read implementation and test files with $xcode-mcp-files.
4. Patch with $xcode-mcp-edit.
5. Re-run the selected tests before broadening to all tests.

Update SwiftUI Preview Or UI Code

1. Use $xcode-mcp-files to locate the SwiftUI file and preview definition.
2. Search Apple docs with $xcode-mcp-docs if framework behavior is unclear.
3. Edit with $xcode-mcp-edit.
4. Render with $xcode-mcp-preview.
5. If rendering fails because of compile errors, inspect diagnostics and loop once through the fix path.

Guardrails

• Do not edit files before reading the current Xcode project path and relevant content.
• Do not use XcodeWrite for existing files when XcodeUpdate can make a precise replacement.
• Do not use broad replaceAll, XcodeRM, or project moves without a clear user request and checked matches.
• Do not chase unrelated warnings, unrelated tests, or unrelated existing repository changes.
• Do not switch to shell xcodebuild, filesystem edits, or simulator tooling when the user explicitly asked for Apple Xcode MCP unless they approve the fallback.
• Do not present this package as covering full app launch, Simulator interaction, debugger sessions, signing, packaging, or profiling unless a separate skill/tool has been loaded for that work.

Reporting

• State the selected Xcode tab/workspace.
• Summarize the evidence gathered, the files changed, and the verification run.
• If work stops early, state the exact blocker: missing Xcode MCP tools, no open Xcode workspace, ambiguous tab, unavailable active scheme/test plan, or external user action needed.