Xcode MCP Usage Guidelines

--- name: xcode-mcp description: Guidelines for efficient Xcode MCP tool usage. This skill should be used to understand when to use Xcode MCP tools vs standard tools. Xcode MCP consumes many tokens - use only for build, test, simulator, preview, and SourceKit diagnostics. Never use for file read/write/grep operations. --- # Xcode MCP Usage Guidelines Xcode MCP tools consume significant tokens. This skill defines when to use Xcode MCP and when to prefer standard tools. ## Complete Xcode MCP Tools Reference ### Window & Project Management | Tool | Description | Token Cost | |------|-------------|------------| | `mcp__xcode__XcodeListWindows` | List open Xcode windows (get tabIdentifier) | Low | ### Build Operations | Tool | Description | Token Cost | |------|-------------|------------| | `mcp__xcode__BuildProject` | Build the Xcode project | Medium | | `mcp__xcode__GetBuildLog` | Get build log with errors/warnings | Medium | | `mcp__xcode__XcodeListNavigatorIssues` | List issues in Issue Navigator | Low | ### Testing | Tool | Description | Token Cost | |------|-------------|------------| | `mcp__xcode__GetTestList` | Get available tests from test plan | Low | | `mcp__xcode__RunAllTests` | Run all tests | Medium | | `mcp__xcode__RunSomeTests` | Run specific tests (preferred) | Medium | ### Preview & Execution | Tool | Description | Token Cost | |------|-------------|------------| | `mcp__xcode__RenderPreview` | Render SwiftUI Preview snapshot | Medium | | `mcp__xcode__ExecuteSnippet` | Execute code snippet in file context | Medium | ### Diagnostics | Tool | Description | Token Cost | |------|-------------|------------| | `mcp__xcode__XcodeRefreshCodeIssuesInFile` | Get compiler diagnostics for specific file | Low | | `mcp__ide__getDiagnostics` | Get SourceKit diagnostics (all open files) | Low | ### Documentation | Tool | Description | Token Cost | |------|-------------|------------| | `mcp__xcode__DocumentationSearch` | Search Apple Developer Documentation | Low | ### File Operations (HIGH TOKEN - NEVER USE) | Tool | Alternative | Why | |------|-------------|-----| | `mcp__xcode__XcodeRead` | `Read` tool | High token consumption | | `mcp__xcode__XcodeWrite` | `Write` tool | High token consumption | | `mcp__xcode__XcodeUpdate` | `Edit` tool | High token consumption | | `mcp__xcode__XcodeGrep` | `rg` / `Grep` tool | High token consumption | | `mcp__xcode__XcodeGlob` | `Glob` tool | High token consumption | | `mcp__xcode__XcodeLS` | `ls` command | High token consumption | | `mcp__xcode__XcodeRM` | `rm` command | High token consumption | | `mcp__xcode__XcodeMakeDir` | `mkdir` command | High token consumption | | `mcp__xcode__XcodeMV` | `mv` command | High token consumption | --- ## Recommended Workflows ### 1. Code Change & Build Flow ``` 1. Search code -> rg "pattern" --type swift 2. Read file -> Read tool 3. Edit file -> Edit tool 4. Syntax check -> mcp__ide__getDiagnostics 5. Build -> mcp__xcode__BuildProject 6. Check errors -> mcp__xcode__GetBuildLog (if build fails) ``` ### 2. Test Writing & Running Flow ``` 1. Read test file -> Read tool 2. Write/edit test -> Edit tool 3. Get test list -> mcp__xcode__GetTestList 4. Run tests -> mcp__xcode__RunSomeTests (specific tests) 5. Check results -> Review test output ``` ### 3. SwiftUI Preview Flow ``` 1. Edit view -> Edit tool 2. Render preview -> mcp__xcode__RenderPreview 3. Iterate -> Repeat as needed ``` ### 4. Debug Flow ``` 1. Check diagnostics -> mcp__ide__getDiagnostics (quick syntax check) 2. Build project -> mcp__xcode__BuildProject 3. Get build log -> mcp__xcode__GetBuildLog (severity: error) 4. Fix issues -> Edit tool 5. Rebuild -> mcp__xcode__BuildProject ``` ### 5. Documentation Search ``` 1. Search docs -> mcp__xcode__DocumentationSearch 2. Review results -> Use information in implementation ``` --- ## Fallback Commands (When MCP Unavailable) If Xcode MCP is disconnected or unavailable, use these xcodebuild commands: ### Build Commands ```bash # Debug build (simulator) - replace with your project's scheme xcodebuild -scheme -configuration Debug -sdk iphonesimulator build # Release build (device) xcodebuild -scheme -configuration Release -sdk iphoneos build # Build with workspace (for CocoaPods projects) xcodebuild -workspace .xcworkspace -scheme -configuration Debug -sdk iphonesimulator build # Build with project file xcodebuild -project .xcodeproj -scheme -configuration Debug -sdk iphonesimulator build # List available schemes xcodebuild -list ``` ### Test Commands ```bash # Run all tests xcodebuild test -scheme -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -configuration Debug # Run specific test class xcodebuild test -scheme -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -only-testing: / # Run specific test method xcodebuild test -scheme -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -only-testing: / / # Run with code coverage xcodebuild test -scheme -sdk iphonesimulator \ -configuration Debug -enableCodeCoverage YES # List available simulators xcrun simctl list devices available ``` ### Clean Build ```bash xcodebuild clean -scheme ``` --- ## Quick Reference ### USE Xcode MCP For: - `BuildProject` - Building - `GetBuildLog` - Build errors - `RunSomeTests` - Running specific tests - `GetTestList` - Listing tests - `RenderPreview` - SwiftUI previews - `ExecuteSnippet` - Code execution - `DocumentationSearch` - Apple docs - `XcodeListWindows` - Get tabIdentifier - `mcp__ide__getDiagnostics` - SourceKit errors ### NEVER USE Xcode MCP For: - `XcodeRead` -> Use `Read` tool - `XcodeWrite` -> Use `Write` tool - `XcodeUpdate` -> Use `Edit` tool - `XcodeGrep` -> Use `rg` or `Grep` tool - `XcodeGlob` -> Use `Glob` tool - `XcodeLS` -> Use `ls` command - `XcodeRM` -> Use `rm` command - `XcodeMakeDir` -> Use `mkdir` command - `XcodeMV` -> Use `mv` command - File operations -> Use standard tools --- ## Token Efficiency Summary | Operation | Best Choice | Token Impact | |-----------|-------------|--------------| | Quick syntax check | `mcp__ide__getDiagnostics` | Low | | Full build | `mcp__xcode__BuildProject` | Medium | | Run specific tests | `mcp__xcode__RunSomeTests` | Medium | | Run all tests | `mcp__xcode__RunAllTests` | High | | Read file | `Read` tool | High | | Edit file | `Edit` tool | High | | Search code | `rg` / `Grep` | Low | | List files | `ls` / `Glob` | Low |

Xcode MCP Usage Guidelines

Prompt ContentSave

Usage

References

Talk