|
| 1 | +# XcodeBuildMCP Tool Options |
| 2 | + |
| 3 | +This document explains how to configure tool registration in XcodeBuildMCP to optimise for different workflows and reduce the number of tools presented to LLM clients. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +XcodeBuildMCP supports selective tool registration based on environment variables. This allows you to: |
| 8 | + |
| 9 | +1. **Opt-in to individual tools** - Enable only specific tools you need |
| 10 | +2. **Enable tool groups** - Enable logical groups of tools for specific workflows |
| 11 | +3. **Default "all tools enabled"** - Without any configuration, all tools are enabled (default behaviour) |
| 12 | + |
| 13 | +## Why Use Selective Tool Registration? |
| 14 | + |
| 15 | +- **Reduced context window usage for LLMs** - Only register tools needed for a specific workflow |
| 16 | +- **Optimised for different use cases** - Configure for iOS development, macOS development, UI testing, etc. |
| 17 | + |
| 18 | +## Available Tool Groups and Environment Variables |
| 19 | + |
| 20 | +XcodeBuildMCP provides workflow-based tool groups that organise tools logically based on common developer workflows. |
| 21 | + |
| 22 | +### Workflow-based Groups |
| 23 | + |
| 24 | +These groups organise tools based on common developer workflows, making it easier to enable just the tools needed for specific tasks: |
| 25 | + |
| 26 | +- **XCODEBUILDMCP_GROUP_PROJECT_DISCOVERY=true** - Project/target discovery and analysis tools |
| 27 | + - _e.g., Discover projects, list schemes, show build settings._ |
| 28 | +- **XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW=true** - Complete iOS simulator development workflow tools |
| 29 | + - _e.g., Building, running, debugging on simulators._ |
| 30 | +- **XCODEBUILDMCP_GROUP_IOS_DEVICE_WORKFLOW=true** - iOS physical device development workflow tools |
| 31 | + - _e.g., Building and deploying to physical iOS devices._ |
| 32 | +- **XCODEBUILDMCP_GROUP_MACOS_WORKFLOW=true** - macOS application development workflow tools |
| 33 | + - _e.g., Building, running, debugging macOS applications._ |
| 34 | +- **XCODEBUILDMCP_GROUP_SIMULATOR_MANAGEMENT=true** - Simulator device management tools |
| 35 | + - _e.g., Managing simulator lifecycle (boot, open, set appearance)._ |
| 36 | +- **XCODEBUILDMCP_GROUP_APP_DEPLOYMENT=true** - Application deployment tools |
| 37 | + - _e.g., Installing and launching apps across platforms._ |
| 38 | +- **XCODEBUILDMCP_GROUP_DIAGNOSTICS=true** - Logging and diagnostics tools |
| 39 | + - _e.g., Log capture, debugging information._ |
| 40 | +- **XCODEBUILDMCP_GROUP_UI_TESTING=true** - UI testing and automation tools |
| 41 | + - _e.g., Tools for interacting with UI elements, typically via IDB._ |
| 42 | + |
| 43 | +## Enabling Individual Tools |
| 44 | + |
| 45 | +To enable specific tools rather than entire groups, use the following environment variables. Each tool is enabled by setting its corresponding variable to `true`. |
| 46 | + |
| 47 | +### Project Discovery & Information |
| 48 | +- **XCODEBUILDMCP_TOOL_DISCOVER_PROJECTS=true** - Discover Xcode projects and workspaces. |
| 49 | +- **XCODEBUILDMCP_TOOL_LIST_SCHEMES_WORKSPACE=true** - List schemes in an Xcode workspace. |
| 50 | +- **XCODEBUILDMCP_TOOL_LIST_SCHEMES_PROJECT=true** - List schemes in an Xcode project. |
| 51 | +- **XCODEBUILDMCP_TOOL_LIST_SIMULATORS=true** - List available iOS/tvOS/watchOS simulators. |
| 52 | +- **XCODEBUILDMCP_TOOL_SHOW_BUILD_SETTINGS_WORKSPACE=true** - Show build settings for an Xcode workspace. |
| 53 | +- **XCODEBUILDMCP_TOOL_SHOW_BUILD_SETTINGS_PROJECT=true** - Show build settings for an Xcode project. |
| 54 | + |
| 55 | +### Build, Clean & Run Tools |
| 56 | + |
| 57 | +#### Clean |
| 58 | +- **XCODEBUILDMCP_TOOL_CLEAN_WORKSPACE=true** - Clean build products for an Xcode workspace. |
| 59 | +- **XCODEBUILDMCP_TOOL_CLEAN_PROJECT=true** - Clean build products for an Xcode project. |
| 60 | + |
| 61 | +#### macOS Build & Run |
| 62 | +- **XCODEBUILDMCP_TOOL_MACOS_BUILD_WORKSPACE=true** - Build a macOS application from a workspace. |
| 63 | +- **XCODEBUILDMCP_TOOL_MACOS_BUILD_PROJECT=true** - Build a macOS application from a project. |
| 64 | +- **XCODEBUILDMCP_TOOL_MACOS_BUILD_AND_RUN_WORKSPACE=true** - Build and run a macOS application from a workspace. |
| 65 | +- **XCODEBUILDMCP_TOOL_MACOS_BUILD_AND_RUN_PROJECT=true** - Build and run a macOS application from a project. |
| 66 | + |
| 67 | +#### iOS Simulator Build & Run |
| 68 | +- **XCODEBUILDMCP_TOOL_IOS_SIMULATOR_BUILD_BY_NAME_WORKSPACE=true** - Build for iOS Simulator by name from a workspace. |
| 69 | +- **XCODEBUILDMCP_TOOL_IOS_SIMULATOR_BUILD_BY_NAME_PROJECT=true** - Build for iOS Simulator by name from a project. |
| 70 | +- **XCODEBUILDMCP_TOOL_IOS_SIMULATOR_BUILD_BY_ID_WORKSPACE=true** - Build for iOS Simulator by UDID from a workspace. |
| 71 | +- **XCODEBUILDMCP_TOOL_IOS_SIMULATOR_BUILD_BY_ID_PROJECT=true** - Build for iOS Simulator by UDID from a project. |
| 72 | +- **XCODEBUILDMCP_TOOL_IOS_SIMULATOR_BUILD_AND_RUN_BY_NAME_WORKSPACE=true** - Build and run on iOS Simulator by name (workspace). |
| 73 | +- **XCODEBUILDMCP_TOOL_IOS_SIMULATOR_BUILD_AND_RUN_BY_NAME_PROJECT=true** - Build and run on iOS Simulator by name (project). |
| 74 | +- **XCODEBUILDMCP_TOOL_IOS_SIMULATOR_BUILD_AND_RUN_BY_ID_WORKSPACE=true** - Build and run on iOS Simulator by UDID (workspace). |
| 75 | +- **XCODEBUILDMCP_TOOL_IOS_SIMULATOR_BUILD_AND_RUN_BY_ID_PROJECT=true** - Build and run on iOS Simulator by UDID (project). |
| 76 | + |
| 77 | +#### iOS Device Build |
| 78 | +- **XCODEBUILDMCP_TOOL_IOS_DEVICE_BUILD_TOOLS=true** - Build iOS apps for physical devices (collection of tools). |
| 79 | + |
| 80 | +### App Path & Bundle ID Retrieval |
| 81 | + |
| 82 | +#### App Path |
| 83 | +- **XCODEBUILDMCP_TOOL_GET_MACOS_APP_PATH_WORKSPACE=true** - Get path to a built macOS app (workspace). |
| 84 | +- **XCODEBUILDMCP_TOOL_GET_MACOS_APP_PATH_PROJECT=true** - Get path to a built macOS app (project). |
| 85 | +- **XCODEBUILDMCP_TOOL_GET_IOS_DEVICE_APP_PATH_WORKSPACE=true** - Get path to a built iOS device app (workspace). |
| 86 | +- **XCODEBUILDMCP_TOOL_GET_IOS_DEVICE_APP_PATH_PROJECT=true** - Get path to a built iOS device app (project). |
| 87 | +- **XCODEBUILDMCP_TOOL_GET_SIMULATOR_APP_PATH_BY_NAME_WORKSPACE=true** - Get path to a built simulator app by name (workspace). |
| 88 | +- **XCODEBUILDMCP_TOOL_GET_SIMULATOR_APP_PATH_BY_NAME_PROJECT=true** - Get path to a built simulator app by name (project). |
| 89 | +- **XCODEBUILDMCP_TOOL_GET_SIMULATOR_APP_PATH_BY_ID_WORKSPACE=true** - Get path to a built simulator app by UDID (workspace). |
| 90 | +- **XCODEBUILDMCP_TOOL_GET_SIMULATOR_APP_PATH_BY_ID_PROJECT=true** - Get path to a built simulator app by UDID (project). |
| 91 | + |
| 92 | +#### Bundle ID |
| 93 | +- **XCODEBUILDMCP_TOOL_GET_MACOS_BUNDLE_ID=true** - Get the bundle ID of a macOS app. |
| 94 | +- **XCODEBUILDMCP_TOOL_GET_IOS_BUNDLE_ID=true** - Get the bundle ID of an iOS app. |
| 95 | + |
| 96 | +### Simulator Management & App Lifecycle |
| 97 | + |
| 98 | +#### Management |
| 99 | +- **XCODEBUILDMCP_TOOL_BOOT_SIMULATOR=true** - Boot an iOS/tvOS/watchOS simulator. |
| 100 | +- **XCODEBUILDMCP_TOOL_OPEN_SIMULATOR=true** - Open the Simulator application. |
| 101 | +- **XCODEBUILDMCP_TOOL_SET_SIMULATOR_APPEARANCE=true** - Set simulator appearance (dark/light mode). |
| 102 | + |
| 103 | +#### App Installation & Launch |
| 104 | +- **XCODEBUILDMCP_TOOL_INSTALL_APP_IN_SIMULATOR=true** - Install an app in a simulator. |
| 105 | +- **XCODEBUILDMCP_TOOL_LAUNCH_APP_IN_SIMULATOR=true** - Launch an app in a simulator. |
| 106 | +- **XCODEBUILDMCP_TOOL_LAUNCH_APP_WITH_LOGS_IN_SIMULATOR=true** - Launch an app in simulator and capture logs. |
| 107 | +- **XCODEBUILDMCP_TOOL_LAUNCH_MACOS_APP=true** - Launch a macOS application. |
| 108 | + |
| 109 | +### Logging & Diagnostics |
| 110 | + |
| 111 | +#### Log Capture |
| 112 | +- **XCODEBUILDMCP_TOOL_START_SIMULATOR_LOG_CAPTURE=true** - Start capturing logs from a simulator. |
| 113 | +- **XCODEBUILDMCP_TOOL_STOP_AND_GET_SIMULATOR_LOG=true** - Stop capturing logs and retrieve them. |
| 114 | + |
| 115 | +#### UI Automation (IDB) |
| 116 | +- **XCODEBUILDMCP_TOOL_UI_AUTOMATION_TOOLS=true** - Enable UI automation tools (e.g., tap, swipe - requires IDB). |
| 117 | + |
| 118 | +#### Diagnostics |
| 119 | +- **XCODEBUILDMCP_DEBUG=true** - Enable diagnostic tool for XcodeBuildMCP server. |
| 120 | + |
| 121 | +## Recommended Tool Combinations for Common Use Cases |
| 122 | + |
| 123 | +Workflow-based groups make it easier to enable just the right tools for specific development tasks. Here are some recommended combinations: |
| 124 | + |
| 125 | +### iOS Simulator Developer |
| 126 | + |
| 127 | +For developers focussed on iOS simulator development: |
| 128 | + |
| 129 | +```json |
| 130 | +{ |
| 131 | + // Rest of your MCP configuration |
| 132 | + "env": { |
| 133 | + "XCODEBUILDMCP_GROUP_PROJECT_DISCOVERY": "true", |
| 134 | + "XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW": "true" |
| 135 | + } |
| 136 | + // Rest of your MCP configuration |
| 137 | +} |
| 138 | +``` |
| 139 | + |
| 140 | +This provides all tools needed to: |
| 141 | +1. Discover and analyse projects |
| 142 | +2. Build for iOS simulators |
| 143 | +3. Install and launch on simulators |
| 144 | +4. Capture logs |
| 145 | + |
| 146 | +### macOS Application Developer |
| 147 | + |
| 148 | +For developers focussed on macOS application development: |
| 149 | + |
| 150 | +```json |
| 151 | +{ |
| 152 | + // Rest of your MCP configuration |
| 153 | + "env": { |
| 154 | + "XCODEBUILDMCP_GROUP_PROJECT_DISCOVERY": "true", |
| 155 | + "XCODEBUILDMCP_GROUP_MACOS_WORKFLOW": "true" |
| 156 | + } |
| 157 | + // Rest of your MCP configuration |
| 158 | +} |
| 159 | +``` |
| 160 | + |
| 161 | +This provides all tools needed to: |
| 162 | +1. Discover and analyse projects |
| 163 | +2. Build for macOS |
| 164 | +3. Launch macOS applications |
| 165 | + |
| 166 | +### UI Automation Testing |
| 167 | + |
| 168 | +For developers focussed on UI automation testing: |
| 169 | + |
| 170 | +```json |
| 171 | +{ |
| 172 | + // Rest of your MCP configuration |
| 173 | + "env": { |
| 174 | + "XCODEBUILDMCP_GROUP_UI_TESTING": "true", |
| 175 | + "XCODEBUILDMCP_GROUP_SIMULATOR_MANAGEMENT": "true", |
| 176 | + "XCODEBUILDMCP_GROUP_APP_DEPLOYMENT": "true" |
| 177 | + } |
| 178 | + // Rest of your MCP configuration |
| 179 | +} |
| 180 | +``` |
| 181 | + |
| 182 | +This provides tools for: |
| 183 | +1. Managing simulators |
| 184 | +2. Installing and launching apps |
| 185 | +3. Running UI automation tests |
| 186 | + |
| 187 | +## Example Cursor/Windsurf Configuration |
| 188 | + |
| 189 | +Here is a fully worked example of how to configure Cursor/Windsurf to use specific tool groups: |
| 190 | + |
| 191 | +```json |
| 192 | +{ |
| 193 | + "mcpServers": { |
| 194 | + "XcodeBuildMCP": { |
| 195 | + "command": "mise", |
| 196 | + "args": [ |
| 197 | + "x", |
| 198 | + "npm:xcodebuildmcp@1.3.5", |
| 199 | + "--", |
| 200 | + "xcodebuildmcp" |
| 201 | + ], |
| 202 | + "env": { |
| 203 | + "XCODEBUILDMCP_GROUP_PROJECT_DISCOVERY": "true", |
| 204 | + "XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW": "true" |
| 205 | + } |
| 206 | + } |
| 207 | + } |
| 208 | +} |
| 209 | +``` |
| 210 | + |
| 211 | +This example configures the MCP client to only enable tools related to iOS simulator development. |
0 commit comments