TEXT

xcode-mcp

Contributed by ilkerulusoy

Improved by Laravel Company · 2026-09-07

Improved prompt:

Xcode MCP Tool Usage Guidelines

Token-Efficient Xcode MCP Command Reference

When to Use Xcode MCP

Xcode MCP tools are designed for specific, high-value tasks that require deep integration with your Xcode project. They are optimized for use cases where the standard tools may struggle or consume excessive resources. You should prioritize Xcode MCP for the following scenarios:

  1. Build and Test Execution: Xcode MCP is ideal for building your project, running specific tests, and obtaining detailed build logs. It provides a more comprehensive and integrated view of your project's build process.

  2. SwiftUI Preview: Rendering SwiftUI previews with Xcode MCP is faster and more efficient than using standard tools, as it leverages the built-in preview rendering engine.

  3. Diagnostics and Error Checking: Xcode MCP tools like mcp__ide__getDiagnostics and mcp__xcode__GetBuildLog are designed to quickly identify syntax errors, compiler issues, and build failures.

  4. Specialized Tasks: Xcode MCP offers commands like mcp__xcode__XcodeListNavigatorIssues to interact with the Issue Navigator and mcp__xcode__DocumentationSearch for searching Apple Developer Documentation.

When to Avoid Xcode MCP

File Operations and Standard Tasks

Xcode MCP is not intended for file read/write/grep operations. These tasks are better handled by the standard tools provided by the system. Using Xcode MCP for these operations can lead to excessive token consumption and slower performance.

Here are the file operations you should never use with Xcode MCP:

  • Reading files: Use the Read tool instead of mcp__xcode__XcodeRead.
  • Writing files: Use the Write tool instead of mcp__xcode__XcodeWrite.
  • Editing files: Use the Edit tool instead of mcp__xcode__XcodeUpdate.
  • Grep operations: Use rg or Grep tools instead of mcp__xcode__XcodeGrep.
  • Listing files: Use the ls command or Glob tool instead of mcp__xcode__XcodeLS.

Token-Efficient Workflow Recommendations

1. Code Change and Build Cycle

php
1. Syntax check → mcp__ide__getDiagnostics
2. Edit file    → Edit tool (for actual changes)
3. Build project → mcp__xcode__BuildProject
4. Check errors → mcp__xcode__GetBuildLog (if build fails)

2. Testing Workflow

php
1. Get test list    → mcp__xcode__GetTestList
2. Run specific tests → mcp__xcode__RunSomeTests (targeted approach)
3. Check results    → Review test output

3. SwiftUI Preview Optimization

php
1. Edit view        → Edit tool
2. Render preview   → mcp__xcode__RenderPreview
3. Iterate          → Repeat as needed

4. Error Diagnosis and Resolution

php
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

php
1. Search docs       → mcp__xcode__DocumentationSearch
2. Review results    → Use information in implementation

Token Efficiency Guidelines

High Token Cost Operations (Avoid)

  • Reading files with Xcode MCP: High token consumption
  • Writing/updating files with Xcode MCP: High token consumption
  • Grep operations with Xcode MCP: High token consumption
  • File listing with Xcode MCP: High token consumption

Medium Token Cost Operations (Use sparingly and strategically)

  • Building projects: Medium token consumption, but provides comprehensive build information
  • Running all tests: Medium to high token consumption, use for regression testing
  • Rendering previews: Medium token consumption, efficient for SwiftUI preview rendering

Low Token Cost Operations (Preferred)

  • Quick syntax check: mcp__ide__getDiagnostics - Low token consumption
  • Grep operations: Use rg or Grep tools - Low token consumption
  • File listing: Use ls or Glob tools - Low token consumption
  • Documentation search: mcp__xcode__DocumentationSearch - Low token consumption

Token Efficiency Trade-offs

Trade-off: Speed vs. Tokens

  • Xcode MCP tools are faster for specific tasks
  • Standard tools are more efficient for general file operations
  • Choose the tool that provides the right balance for your specific use case

Trade-off: Completeness vs. Efficiency

  • Xcode MCP provides more comprehensive results for build and test operations
  • Standard tools offer more flexibility and efficiency for file operations
  • Prioritize Xcode MCP for the most critical and integrated tasks

Summary

  • Use Xcode MCP for building, testing, previews, diagnostics, and specialized tasks.
  • Avoid using Xcode MCP for file read/write/grep operations.
  • Prioritize token efficiency while maintaining the benefits of Xcode integration.
  • Follow the recommended workflows for optimal performance.
Original prompt (before our improvements)

--- 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 |