Xcode Build Workflows

Xcode Workflows

Use the execute_xcode_command MCP tool for all iOS build operations

The xclaude-plugin provides the execute_xcode_command MCP tool which consolidates all xcodebuild operations into a single, token-efficient dispatcher.

⚠️ CRITICAL: Always Use MCP Tools First

This is the most important rule: When working with iOS builds, you MUST use the execute_xcode_command MCP tool.

• ✅ DO: Invoke execute_xcode_command for all build/test/clean operations
• ✅ DO: If the MCP tool fails, adjust parameters and retry
• ✅ DO: Read error messages and debug the parameters
• ❌ NEVER: Fall back to bash xcodebuild commands
• ❌ NEVER: Use xcodebuild directly in bash
• ❌ NEVER: Run xcrun xcodebuild in a terminal

Why? The MCP tool provides:

• Structured error handling
• Token efficiency (consolidated into 1 tool vs. verbose bash output)
• Proper integration with the xclaude-plugin architecture
• Consistent response formatting

If execute_xcode_command fails, the issue is with parameters or the project - not that you should use bash.

When to Use Bash (And When NOT to)

❌ NEVER Use Bash For These (Use MCP Tools Instead)

✅ Bash is Acceptable For (Non-Build Tasks)

• File operations: mkdir, cp, rm, ls, etc.
• Text inspection: grep, find, cat, etc.
• Git operations: git status, git log, etc.
• Environment checks: which, xcode-select --version, etc.
• Project exploration: find . -name "*.swift", etc.

The Rule: If it's about Xcode building/testing → Use MCP tool, not bash

Quick Reference

Standard Workflows

1. Building an App

Step 1: Discover Schemes - Use execute_xcode_command with operation: "list"

Invoke the execute_xcode_command MCP tool:

{
  "operation": "list",
  "project_path": "/path/to/Project.xcodeproj"
}

Note: project_path is optional - auto-detected from current directory.

Returns:

{
  "schemes": ["MyApp", "MyAppTests", "MyAppUITests"],
  "targets": ["MyApp", "MyAppKit", "MyAppTests"]
}

Step 2: Build - Use execute_xcode_command with operation: "build"

Invoke the execute_xcode_command MCP tool with build parameters:

{
  "operation": "build",
  "scheme": "MyApp",
  "configuration": "Debug",
  "destination": "platform=iOS Simulator,name=iPhone 15"
}

Common Destinations:

• iOS Simulator (explicit - recommended): "platform=iOS Simulator,name=iPhone 15,OS=18.0"
• iOS Simulator (auto-resolve): "platform=iOS Simulator,name=iPhone 15" (will auto-detect latest OS)
• iOS Device: "platform=iOS,id=<device-udid>"
• Any Simulator: "platform=iOS Simulator,name=Any iOS Simulator Device"
• macOS: "platform=macOS"

Note: The destination parameter now supports auto-resolution! If you omit the OS version, the tool will automatically query available simulators and select the latest OS version for the specified device name. For explicit control, include the OS version in your destination string.

2. Running Tests

Unit Tests:

{
  "operation": "test",
  "scheme": "MyApp",
  "destination": "platform=iOS Simulator,name=iPhone 15"
}

Specific Test Plan:

{
  "operation": "test",
  "scheme": "MyApp",
  "destination": "platform=iOS Simulator,name=iPhone 15",
  "options": {
    "test_plan": "UnitTests"
  }
}

Run Specific Tests:

{
  "operation": "test",
  "scheme": "MyApp",
  "destination": "platform=iOS Simulator,name=iPhone 15",
  "options": {
    "only_testing": [
      "MyAppTests/LoginTests/testSuccessfulLogin",
      "MyAppTests/LoginTests/testInvalidCredentials"
    ]
  }
}

Skip Specific Tests:

{
  "operation": "test",
  "scheme": "MyApp",
  "destination": "platform=iOS Simulator,name=iPhone 15",
  "options": {
    "skip_testing": ["MyAppUITests"]
  }
}

3. Clean Build

When to Clean:

• Build artifacts corrupted
• Switching branches significantly
• Mysterious build failures
• Before release builds

{
  "operation": "clean",
  "scheme": "MyApp"
}

Clean + Build Pattern:

{
  "operation": "build",
  "scheme": "MyApp",
  "configuration": "Debug",
  "options": {
    "clean_before_build": true
  }
}

Configurations

Debug vs Release

Debug (Default):

• Optimizations disabled
• Debug symbols included
• Faster compile time
• Larger binary
• Use for: Development, testing

Release:

• Optimizations enabled
• Debug symbols optional
• Slower compile time
• Smaller binary
• Use for: Production, App Store, performance testing

{
  "operation": "build",
  "scheme": "MyApp",
  "configuration": "Release"
}

Build Options

Common Options

{
  "operation": "build",
  "scheme": "MyApp",
  "options": {
    "clean_before_build": true,
    "parallel": true,
    "sdk": "iphoneos17.0",
    "arch": "arm64",
    "quiet": false
  }
}

Options Explained:

• clean_before_build: Clean before building (ensures fresh build)
• parallel: Enable parallel builds (faster on multi-core)
• sdk: Specific SDK version (usually auto-selected)
• arch: Target architecture (arm64 for devices, x86_64 for old simulators)
• quiet: Reduce build output verbosity

Interpreting Build Results

Success Response

{
  "success": true,
  "summary": "Build succeeded",
  "warnings": 3,
  "build_time": "45.2s",
  "scheme": "MyApp",
  "configuration": "Debug"
}

Failure Response

{
  "success": false,
  "error": "Build failed",
  "errors": 2,
  "warnings": 5,
  "failure_reason": "Compilation errors in ViewController.swift"
}

Progressive Disclosure

Large build logs use progressive disclosure:

{
  "success": true,
  "summary": "Build succeeded with 15 warnings",
  "cache_id": "build-abc123",
  "quick_stats": {
    "warnings": 15,
    "build_time": "62.3s"
  },
  "next_steps": [
    "Use cache_id to get full build log if needed",
    "Review warnings for potential issues"
  ]
}

Common Build Errors