--- 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 <SchemeName> with your project's scheme xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # Release build (device) xcodebuild -scheme <SchemeName> -configuration Release -sdk iphoneos build # Build with workspace (for CocoaPods projects) xcodebuild -workspace <ProjectName>.xcworkspace -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # Build with project file xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # List available schemes xcodebuild -list ``` ### Test Commands ```bash # Run all tests xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -configuration Debug # Run specific test class xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -only-testing:<TestTarget>/<TestClassName> # Run specific test method xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -only-testing:<TestTarget>/<TestClassName>/<testMethodName> # Run with code coverage xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -configuration Debug -enableCodeCoverage YES # List available simulators xcrun simctl list devices available ``` ### Clean Build ```bash xcodebuild clean -scheme <SchemeName> ``` --- ## 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 - ❌ 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 |