XcodeBuildMCP

# Reloaderoo + XcodeBuildMCP: Curated CLI Primer Use this primer to drive XcodeBuildMCP entirely through Reloaderoo—treating it like a CLI. It is designed to be included in your agent’s context to show exactly how to invoke the specific tools your project needs. Why this file: - XcodeBuildMCP exposes many tools. Dumping the full tool surface into the context wastes tokens. - Instead, copy this file into your project and delete everything you don’t need. Keep only the commands relevant to your workflow (e.g., just Simulator tools). - Your trimmed version becomes a small, project‑specific reference that tells your agent precisely which Reloaderoo tool calls to make. How to use this primer: 1. Copy this file into your repo (e.g., docs/xcodebuildmcp_primer.md or AGENTS.md). 2. Remove all sections and commands you don’t use. Keep it minimal. 3. Replace placeholders with your real values (paths, schemes, simulator UUIDs/Names, bundle IDs, etc.). 4. Use the quiet (-q) examples to reduce noise; pipe output to jq when you only need the content. 5. Include your curated file in the agent context whenever you want it to call XcodeBuildMCP via Reloaderoo. Conventions in the examples: - Calls use: npx reloaderoo@latest inspect … -q -- npx xcodebuildmcp@latest - Parameters are passed as JSON via --params. - Resources are read with read-resource (e.g., xcodebuildmcp://simulators). - Use jq -r '.contents[].text' to extract the textual results when needed. Keep it small. The smaller your curated primer, the less context your agent needs—and the cheaper, faster, and more reliable your interactions will be. ## Installation Reloaderoo is available via npm and can be used with npx for universal compatibility. ```bash # Use npx to run reloaderoo npx reloaderoo@latest --help ``` ## Hint Use jq to parse the output to get just the content response: ```bash npx reloaderoo@latest inspect read-resource "xcodebuildmcp://simulators" -q -- npx xcodebuildmcp@latest | jq -r '.contents[].text' ``` **Example Tool Calls:** ## Dynamic Tool Discovery - **`discover_tools`**: Analyzes a task description to enable relevant tools. ```bash npx reloaderoo@latest inspect call-tool discover_tools --params '{"task_description": "I want to build and run my iOS app on a simulator."}' -q -- npx xcodebuildmcp@latest ``` ## iOS Device Development - **`build_device`**: Builds an app for a physical device. ```bash npx reloaderoo@latest inspect -q call-tool build_device --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest ``` - **`get_device_app_path`**: Gets the `.app` bundle path for a device build. ```bash npx reloaderoo@latest inspect call-tool get_device_app_path --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest ``` - **`install_app_device`**: Installs an app on a physical device. ```bash npx reloaderoo@latest inspect call-tool install_app_device --params '{"deviceId": "DEVICE_UDID", "appPath": "/path/to/MyApp.app"}' -q -- npx xcodebuildmcp@latest ``` - **`launch_app_device`**: Launches an app on a physical device. ```bash npx reloaderoo@latest inspect call-tool launch_app_device --params '{"deviceId": "DEVICE_UDID", "bundleId": "com.example.MyApp"}' -q -- npx xcodebuildmcp@latest ``` - **`list_devices`**: Lists connected physical devices. ```bash npx reloaderoo@latest inspect call-tool list_devices --params '{}' -q -- npx xcodebuildmcp@latest ``` - **`stop_app_device`**: Stops an app on a physical device. ```bash npx reloaderoo@latest inspect call-tool stop_app_device --params '{"deviceId": "DEVICE_UDID", "processId": 12345}' -q -- npx xcodebuildmcp@latest ``` - **`test_device`**: Runs tests on a physical device. ```bash npx reloaderoo@latest inspect call-tool test_device --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme", "deviceId": "DEVICE_UDID"}' -q -- npx xcodebuildmcp@latest ``` ## iOS Simulator Development - **`boot_sim`**: Boots a simulator. ```bash npx reloaderoo@latest inspect call-tool boot_sim --params '{"simulatorUuid": "SIMULATOR_UUID"}' -q -- npx xcodebuildmcp@latest ``` - **`build_run_sim`**: Builds and runs an app on a simulator. ```bash npx reloaderoo@latest inspect call-tool build_run_sim --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme", "simulatorName": "iPhone 16"}' -q -- npx xcodebuildmcp@latest ``` - **`build_sim`**: Builds an app for a simulator. ```bash npx reloaderoo@latest inspect call-tool build_sim --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme", "simulatorName": "iPhone 16"}' -q -- npx xcodebuildmcp@latest ``` - **`get_sim_app_path`**: Gets the `.app` bundle path for a simulator build. ```bash npx reloaderoo@latest inspect call-tool get_sim_app_path --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme", "platform": "iOS Simulator", "simulatorName": "iPhone 16"}' -q -- npx xcodebuildmcp@latest ``` - **`install_app_sim`**: Installs an app on a simulator. ```bash npx reloaderoo@latest inspect call-tool install_app_sim --params '{"simulatorUuid": "SIMULATOR_UUID", "appPath": "/path/to/MyApp.app"}' -q -- npx xcodebuildmcp@latest ``` - **`launch_app_logs_sim`**: Launches an app on a simulator with log capture. ```bash npx reloaderoo@latest inspect call-tool launch_app_logs_sim --params '{"simulatorUuid": "SIMULATOR_UUID", "bundleId": "com.example.MyApp"}' -q -- npx xcodebuildmcp@latest ``` - **`launch_app_sim`**: Launches an app on a simulator. ```bash npx reloaderoo@latest inspect call-tool launch_app_sim --params '{"simulatorName": "iPhone 16", "bundleId": "com.example.MyApp"}' -q -- npx xcodebuildmcp@latest ``` - **`list_sims`**: Lists available simulators. ```bash npx reloaderoo@latest inspect call-tool list_sims --params '{}' -q -- npx xcodebuildmcp@latest ``` - **`open_sim`**: Opens the Simulator application. ```bash npx reloaderoo@latest inspect call-tool open_sim --params '{}' -q -- npx xcodebuildmcp@latest ``` - **`stop_app_sim`**: Stops an app on a simulator. ```bash npx reloaderoo@latest inspect call-tool stop_app_sim --params '{"simulatorName": "iPhone 16", "bundleId": "com.example.MyApp"}' -q -- npx xcodebuildmcp@latest ``` - **`test_sim`**: Runs tests on a simulator. ```bash npx reloaderoo@latest inspect call-tool test_sim --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme", "simulatorName": "iPhone 16"}' -q -- npx xcodebuildmcp@latest ``` ## Log Capture & Management - **`start_device_log_cap`**: Starts log capture for a physical device. ```bash npx reloaderoo@latest inspect call-tool start_device_log_cap --params '{"deviceId": "DEVICE_UDID", "bundleId": "com.example.MyApp"}' -q -- npx xcodebuildmcp@latest ``` - **`start_sim_log_cap`**: Starts log capture for a simulator. ```bash npx reloaderoo@latest inspect call-tool start_sim_log_cap --params '{"simulatorUuid": "SIMULATOR_UUID", "bundleId": "com.example.MyApp"}' -q -- npx xcodebuildmcp@latest ``` - **`stop_device_log_cap`**: Stops log capture for a physical device. ```bash npx reloaderoo@latest inspect call-tool stop_device_log_cap --params '{"logSessionId": "SESSION_ID"}' -q -- npx xcodebuildmcp@latest ``` - **`stop_sim_log_cap`**: Stops log capture for a simulator. ```bash npx reloaderoo@latest inspect call-tool stop_sim_log_cap --params '{"logSessionId": "SESSION_ID"}' -q -- npx xcodebuildmcp@latest ``` ## macOS Development - **`build_macos`**: Builds a macOS app. ```bash npx reloaderoo@latest inspect call-tool build_macos --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest ``` - **`build_run_macos`**: Builds and runs a macOS app. ```bash npx reloaderoo@latest inspect call-tool build_run_macos --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest ``` - **`get_mac_app_path`**: Gets the `.app` bundle path for a macOS build. ```bash npx reloaderoo@latest inspect call-tool get_mac_app_path --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest ``` - **`launch_mac_app`**: Launches a macOS app. ```bash npx reloaderoo@latest inspect call-tool launch_mac_app --params '{"appPath": "/Applications/Calculator.app"}' -q -- npx xcodebuildmcp@latest ``` - **`stop_mac_app`**: Stops a macOS app. ```bash npx reloaderoo@latest inspect call-tool stop_mac_app --params '{"appName": "Calculator"}' -q -- npx xcodebuildmcp@latest ``` - **`test_macos`**: Runs tests for a macOS project. ```bash npx reloaderoo@latest inspect call-tool test_macos --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest ``` ## Project Discovery - **`discover_projs`**: Discovers Xcode projects and workspaces. ```bash npx reloaderoo@latest inspect call-tool discover_projs --params '{"workspaceRoot": "/path/to/workspace"}' -q -- npx xcodebuildmcp@latest ``` - **`get_app_bundle_id`**: Gets an app's bundle identifier. ```bash npx reloaderoo@latest inspect call-tool get_app_bundle_id --params '{"appPath": "/path/to/MyApp.app"}' -q -- npx xcodebuildmcp@latest ``` - **`get_mac_bundle_id`**: Gets a macOS app's bundle identifier. ```bash npx reloaderoo@latest inspect call-tool get_mac_bundle_id --params '{"appPath": "/Applications/Calculator.app"}' -q -- npx xcodebuildmcp@latest ``` - **`list_schemes`**: Lists schemes in a project or workspace. ```bash npx reloaderoo@latest inspect call-tool list_schemes --params '{"projectPath": "/path/to/MyProject.xcodeproj"}' -q -- npx xcodebuildmcp@latest ``` - **`show_build_settings`**: Shows build settings for a scheme. ```bash npx reloaderoo@latest inspect call-tool show_build_settings --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest ``` ## Project Scaffolding - **`scaffold_ios_project`**: Scaffolds a new iOS project. ```bash npx reloaderoo@latest inspect call-tool scaffold_ios_project --params '{"projectName": "MyNewApp", "outputPath": "/path/to/projects"}' -q -- npx xcodebuildmcp@latest ``` - **`scaffold_macos_project`**: Scaffolds a new macOS project. ```bash npx reloaderoo@latest inspect call-tool scaffold_macos_project --params '{"projectName": "MyNewMacApp", "outputPath": "/path/to/projects"}' -q -- npx xcodebuildmcp@latest ``` ## Project Utilities - **`clean`**: Cleans build artifacts. ```bash # For a project npx reloaderoo@latest inspect call-tool clean --params '{"projectPath": "/path/to/MyProject.xcodeproj"}' -q -- npx xcodebuildmcp@latest # For a workspace npx reloaderoo@latest inspect call-tool clean --params '{"workspacePath": "/path/to/MyWorkspace.xcworkspace", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest ``` ## Simulator Management - **`reset_sim_location`**: Resets a simulator's location. ```bash npx reloaderoo@latest inspect call-tool reset_sim_location --params '{"simulatorUuid": "SIMULATOR_UUID"}' -q -- npx xcodebuildmcp@latest ``` - **`set_sim_appearance`**: Sets a simulator's appearance (dark/light mode). ```bash npx reloaderoo@latest inspect call-tool set_sim_appearance --params '{"simulatorUuid": "SIMULATOR_UUID", "mode": "dark"}' -q -- npx xcodebuildmcp@latest ``` - **`set_sim_location`**: Sets a simulator's GPS location. ```bash npx reloaderoo@latest inspect call-tool set_sim_location --params '{"simulatorUuid": "SIMULATOR_UUID", "latitude": 37.7749, "longitude": -122.4194}' -q -- npx xcodebuildmcp@latest ``` - **`sim_statusbar`**: Overrides a simulator's status bar. ```bash npx reloaderoo@latest inspect call-tool sim_statusbar --params '{"simulatorUuid": "SIMULATOR_UUID", "dataNetwork": "wifi"}' -q -- npx xcodebuildmcp@latest ``` ## Swift Package Manager - **`swift_package_build`**: Builds a Swift package. ```bash npx reloaderoo@latest inspect call-tool swift_package_build --params '{"packagePath": "/path/to/package"}' -q -- npx xcodebuildmcp@latest ``` - **`swift_package_clean`**: Cleans a Swift package. ```bash npx reloaderoo@latest inspect call-tool swift_package_clean --params '{"packagePath": "/path/to/package"}' -q -- npx xcodebuildmcp@latest ``` - **`swift_package_list`**: Lists running Swift package processes. ```bash npx reloaderoo@latest inspect call-tool swift_package_list --params '{}' -q -- npx xcodebuildmcp@latest ``` - **`swift_package_run`**: Runs a Swift package executable. ```bash npx reloaderoo@latest inspect call-tool swift_package_run --params '{"packagePath": "/path/to/package"}' -q -- npx xcodebuildmcp@latest ``` - **`swift_package_stop`**: Stops a running Swift package process. ```bash npx reloaderoo@latest inspect call-tool swift_package_stop --params '{"pid": 12345}' -q -- npx xcodebuildmcp@latest ``` - **`swift_package_test`**: Tests a Swift package. ```bash npx reloaderoo@latest inspect call-tool swift_package_test --params '{"packagePath": "/path/to/package"}' -q -- npx xcodebuildmcp@latest ``` ## System Doctor - **`doctor`**: Runs system diagnostics. ```bash npx reloaderoo@latest inspect call-tool doctor --params '{}' -q -- npx xcodebuildmcp@latest ``` ## UI Testing & Automation - **`button`**: Simulates a hardware button press. ```bash npx reloaderoo@latest inspect call-tool button --params '{"simulatorUuid": "SIMULATOR_UUID", "buttonType": "home"}' -q -- npx xcodebuildmcp@latest ``` - **`describe_ui`**: Gets the UI hierarchy of the current screen. ```bash npx reloaderoo@latest inspect call-tool describe_ui --params '{"simulatorUuid": "SIMULATOR_UUID"}' -q -- npx xcodebuildmcp@latest ``` - **`gesture`**: Performs a pre-defined gesture. ```bash npx reloaderoo@latest inspect call-tool gesture --params '{"simulatorUuid": "SIMULATOR_UUID", "preset": "scroll-up"}' -q -- npx xcodebuildmcp@latest ``` - **`key_press`**: Simulates a key press. ```bash npx reloaderoo@latest inspect call-tool key_press --params '{"simulatorUuid": "SIMULATOR_UUID", "keyCode": 40}' -q -- npx xcodebuildmcp@latest ``` - **`key_sequence`**: Simulates a sequence of key presses. ```bash npx reloaderoo@latest inspect call-tool key_sequence --params '{"simulatorUuid": "SIMULATOR_UUID", "keyCodes": [40, 42, 44]}' -q -- npx xcodebuildmcp@latest ``` - **`long_press`**: Performs a long press at coordinates. ```bash npx reloaderoo@latest inspect call-tool long_press --params '{"simulatorUuid": "SIMULATOR_UUID", "x": 100, "y": 200, "duration": 1500}' -q -- npx xcodebuildmcp@latest ``` - **`screenshot`**: Takes a screenshot. ```bash npx reloaderoo@latest inspect call-tool screenshot --params '{"simulatorUuid": "SIMULATOR_UUID"}' -q -- npx xcodebuildmcp@latest ``` - **`swipe`**: Performs a swipe gesture. ```bash npx reloaderoo@latest inspect call-tool swipe --params '{"simulatorUuid": "SIMULATOR_UUID", "x1": 100, "y1": 200, "x2": 100, "y2": 400}' -q -- npx xcodebuildmcp@latest ``` - **`tap`**: Performs a tap at coordinates. ```bash npx reloaderoo@latest inspect call-tool tap --params '{"simulatorUuid": "SIMULATOR_UUID", "x": 100, "y": 200}' -q -- npx xcodebuildmcp@latest ``` - **`touch`**: Simulates a touch down or up event. ```bash npx reloaderoo@latest inspect call-tool touch --params '{"simulatorUuid": "SIMULATOR_UUID", "x": 100, "y": 200, "down": true}' -q -- npx xcodebuildmcp@latest ``` - **`type_text`**: Types text into the focused element. ```bash npx reloaderoo@latest inspect call-tool type_text --params '{"simulatorUuid": "SIMULATOR_UUID", "text": "Hello, World!"}' -q -- npx xcodebuildmcp@latest ``` ## Resources - **Read devices resource**: ```bash npx reloaderoo@latest inspect read-resource "xcodebuildmcp://devices" -q -- npx xcodebuildmcp@latest ``` - **Read simulators resource**: ```bash npx reloaderoo@latest inspect read-resource "xcodebuildmcp://simulators" -q -- npx xcodebuildmcp@latest ``` - **Read doctor resource**: ```bash npx reloaderoo@latest inspect read-resource "xcodebuildmcp://doctor" -q -- npx xcodebuildmcp@latest ```