XcodeBuildMCP

Instructions

Implementation Reference

• src/mcp/tools/simulator/build_run_sim.ts:503-521 (registration)

  Registration of the 'build_run_sim' tool, which matches the pattern of the queried tool name. This is where the tool is defined and exported with its name, description, schema, and handler.
  export default { name: 'build_run_sim', description: 'Builds and runs an app on an iOS simulator.', schema: publicSchemaObject.shape, handler: createSessionAwareTool<BuildRunSimulatorParams>({ internalSchema: buildRunSimulatorSchema as unknown as z.ZodType<BuildRunSimulatorParams>, logicFunction: build_run_simLogic, getExecutor: getDefaultCommandExecutor, requirements: [ { allOf: ['scheme'], message: 'scheme is required' }, { oneOf: ['projectPath', 'workspacePath'], message: 'Provide a project or workspace' }, { oneOf: ['simulatorId', 'simulatorName'], message: 'Provide simulatorId or simulatorName' }, ], exclusivePairs: [ ['projectPath', 'workspacePath'], ['simulatorId', 'simulatorName'], ], }), };
• src/mcp/tools/simulator/build_run_sim.ts:131-491 (handler)

  The core handler function 'build_run_simLogic' that implements the tool's execution logic: builds the app, determines simulator UUID, boots if needed, installs and launches the app on iOS simulator.
  export async function build_run_simLogic( params: BuildRunSimulatorParams, executor: CommandExecutor, executeXcodeBuildCommandFn: typeof executeXcodeBuildCommand = executeXcodeBuildCommand, ): Promise<ToolResponse> { const projectType = params.projectPath ? 'project' : 'workspace'; const filePath = params.projectPath ?? params.workspacePath; log( 'info', `Starting iOS Simulator build and run for scheme ${params.scheme} from ${projectType}: ${filePath}`, ); try { // --- Build Step --- const buildResult = await _handleSimulatorBuildLogic( params, executor, executeXcodeBuildCommandFn, ); if (buildResult.isError) { return buildResult; // Return the build error } // --- Get App Path Step --- // Create the command array for xcodebuild with -showBuildSettings option const command = ['xcodebuild', '-showBuildSettings']; // Add the workspace or project if (params.workspacePath) { command.push('-workspace', params.workspacePath); } else if (params.projectPath) { command.push('-project', params.projectPath); } // Add the scheme and configuration command.push('-scheme', params.scheme); command.push('-configuration', params.configuration ?? 'Debug'); // Handle destination for simulator let destinationString: string; if (params.simulatorId) { destinationString = `platform=iOS Simulator,id=${params.simulatorId}`; } else if (params.simulatorName) { destinationString = `platform=iOS Simulator,name=${params.simulatorName}${(params.useLatestOS ?? true) ? ',OS=latest' : ''}`; } else { // This shouldn't happen due to validation, but handle it destinationString = 'platform=iOS Simulator'; } command.push('-destination', destinationString); // Add derived data path if provided if (params.derivedDataPath) { command.push('-derivedDataPath', params.derivedDataPath); } // Add extra args if provided if (params.extraArgs && params.extraArgs.length > 0) { command.push(...params.extraArgs); } // Execute the command directly const result = await executor(command, 'Get App Path', true, undefined); // If there was an error with the command execution, return it if (!result.success) { return createTextResponse( `Build succeeded, but failed to get app path: ${result.error ?? 'Unknown error'}`, true, ); } // Parse the output to extract the app path const buildSettingsOutput = result.output; // Try both approaches to get app path - first the project approach (CODESIGNING_FOLDER_PATH) let appBundlePath: string | null = null; // Project approach: Extract CODESIGNING_FOLDER_PATH from build settings to get app path const appPathMatch = buildSettingsOutput.match(/CODESIGNING_FOLDER_PATH = (.+\.app)/); if (appPathMatch?.[1]) { appBundlePath = appPathMatch[1].trim(); } else { // Workspace approach: Extract BUILT_PRODUCTS_DIR and FULL_PRODUCT_NAME const builtProductsDirMatch = buildSettingsOutput.match( /^\s*BUILT_PRODUCTS_DIR\s*=\s*(.+)$/m, ); const fullProductNameMatch = buildSettingsOutput.match(/^\s*FULL_PRODUCT_NAME\s*=\s*(.+)$/m); if (builtProductsDirMatch && fullProductNameMatch) { const builtProductsDir = builtProductsDirMatch[1].trim(); const fullProductName = fullProductNameMatch[1].trim(); appBundlePath = `${builtProductsDir}/${fullProductName}`; } } if (!appBundlePath) { return createTextResponse( `Build succeeded, but could not find app path in build settings.`, true, ); } log('info', `App bundle path for run: ${appBundlePath}`); // --- Find/Boot Simulator Step --- // Use our helper to determine the simulator UUID const uuidResult = await determineSimulatorUuid( { simulatorId: params.simulatorId, simulatorName: params.simulatorName }, executor, ); if (uuidResult.error) { return createTextResponse(`Build succeeded, but ${uuidResult.error.content[0].text}`, true); } if (uuidResult.warning) { log('warning', uuidResult.warning); } const simulatorId = uuidResult.uuid; if (!simulatorId) { return createTextResponse( 'Build succeeded, but no simulator specified and failed to find a suitable one.', true, ); } // Check simulator state and boot if needed try { log('info', `Checking simulator state for UUID: ${simulatorId}`); const simulatorListResult = await executor( ['xcrun', 'simctl', 'list', 'devices', 'available', '--json'], 'List Simulators', ); if (!simulatorListResult.success) { throw new Error(simulatorListResult.error ?? 'Failed to list simulators'); } const simulatorsData = JSON.parse(simulatorListResult.output) as { devices: Record<string, unknown[]>; }; let targetSimulator: { udid: string; name: string; state: string } | null = null; // Find the target simulator for (const runtime in simulatorsData.devices) { const devices = simulatorsData.devices[runtime]; if (Array.isArray(devices)) { for (const device of devices) { if ( typeof device === 'object' && device !== null && 'udid' in device && 'name' in device && 'state' in device && typeof device.udid === 'string' && typeof device.name === 'string' && typeof device.state === 'string' && device.udid === simulatorId ) { targetSimulator = { udid: device.udid, name: device.name, state: device.state, }; break; } } if (targetSimulator) break; } } if (!targetSimulator) { return createTextResponse( `Build succeeded, but could not find simulator with UUID: ${simulatorId}`, true, ); } // Boot if needed if (targetSimulator.state !== 'Booted') { log('info', `Booting simulator ${targetSimulator.name}...`); const bootResult = await executor( ['xcrun', 'simctl', 'boot', simulatorId], 'Boot Simulator', ); if (!bootResult.success) { throw new Error(bootResult.error ?? 'Failed to boot simulator'); } } else { log('info', `Simulator ${simulatorId} is already booted`); } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log('error', `Error checking/booting simulator: ${errorMessage}`); return createTextResponse( `Build succeeded, but error checking/booting simulator: ${errorMessage}`, true, ); } // --- Open Simulator UI Step --- try { log('info', 'Opening Simulator app'); const openResult = await executor(['open', '-a', 'Simulator'], 'Open Simulator App'); if (!openResult.success) { throw new Error(openResult.error ?? 'Failed to open Simulator app'); } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log('warning', `Warning: Could not open Simulator app: ${errorMessage}`); // Don't fail the whole operation for this } // --- Install App Step --- try { log('info', `Installing app at path: ${appBundlePath} to simulator: ${simulatorId}`); const installResult = await executor( ['xcrun', 'simctl', 'install', simulatorId, appBundlePath], 'Install App', ); if (!installResult.success) { throw new Error(installResult.error ?? 'Failed to install app'); } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log('error', `Error installing app: ${errorMessage}`); return createTextResponse( `Build succeeded, but error installing app on simulator: ${errorMessage}`, true, ); } // --- Get Bundle ID Step --- let bundleId; try { log('info', `Extracting bundle ID from app: ${appBundlePath}`); // Try multiple methods to get bundle ID - first PlistBuddy, then plutil, then defaults let bundleIdResult = null; // Method 1: PlistBuddy (most reliable) try { bundleIdResult = await executor( [ '/usr/libexec/PlistBuddy', '-c', 'Print :CFBundleIdentifier', `${appBundlePath}/Info.plist`, ], 'Get Bundle ID with PlistBuddy', ); if (bundleIdResult.success) { bundleId = bundleIdResult.output.trim(); } } catch { // Continue to next method } // Method 2: plutil (workspace approach) if (!bundleId) { try { bundleIdResult = await executor( ['plutil', '-extract', 'CFBundleIdentifier', 'raw', `${appBundlePath}/Info.plist`], 'Get Bundle ID with plutil', ); if (bundleIdResult?.success) { bundleId = bundleIdResult.output?.trim(); } } catch { // Continue to next method } } // Method 3: defaults (fallback) if (!bundleId) { try { bundleIdResult = await executor( ['defaults', 'read', `${appBundlePath}/Info`, 'CFBundleIdentifier'], 'Get Bundle ID with defaults', ); if (bundleIdResult?.success) { bundleId = bundleIdResult.output?.trim(); } } catch { // All methods failed } } if (!bundleId) { throw new Error('Could not extract bundle ID from Info.plist using any method'); } log('info', `Bundle ID for run: ${bundleId}`); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log('error', `Error getting bundle ID: ${errorMessage}`); return createTextResponse( `Build and install succeeded, but error getting bundle ID: ${errorMessage}`, true, ); } // --- Launch App Step --- try { log('info', `Launching app with bundle ID: ${bundleId} on simulator: ${simulatorId}`); const launchResult = await executor( ['xcrun', 'simctl', 'launch', simulatorId, bundleId], 'Launch App', ); if (!launchResult.success) { throw new Error(launchResult.error ?? 'Failed to launch app'); } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log('error', `Error launching app: ${errorMessage}`); return createTextResponse( `Build and install succeeded, but error launching app on simulator: ${errorMessage}`, true, ); } // --- Success --- log('info', '✅ iOS simulator build & run succeeded.'); const target = params.simulatorId ? `simulator UUID '${params.simulatorId}'` : `simulator name '${params.simulatorName}'`; const sourceType = params.projectPath ? 'project' : 'workspace'; const sourcePath = params.projectPath ?? params.workspacePath; return { content: [ { type: 'text', text: `✅ iOS simulator build and run succeeded for scheme ${params.scheme} from ${sourceType} ${sourcePath} targeting ${target}. The app (${bundleId}) is now running in the iOS Simulator. If you don't see the simulator window, it may be hidden behind other windows. The Simulator app should be open. Next Steps: - Option 1: Capture structured logs only (app continues running): start_simulator_log_capture({ simulatorId: '${simulatorId}', bundleId: '${bundleId}' }) - Option 2: Capture both console and structured logs (app will restart): start_simulator_log_capture({ simulatorId: '${simulatorId}', bundleId: '${bundleId}', captureConsole: true }) - Option 3: Launch app with logs in one step (for a fresh start): launch_app_with_logs_in_simulator({ simulatorId: '${simulatorId}', bundleId: '${bundleId}' }) When done with any option, use: stop_sim_log_cap({ logSessionId: 'SESSION_ID' })`, }, ], isError: false, }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log('error', `Error in iOS Simulator build and run: ${errorMessage}`); return createTextResponse(`Error in iOS Simulator build and run: ${errorMessage}`, true); } }
• src/mcp/tools/simulator/build_run_sim.ts:67-80 (schema)

  Zod schema definition for the tool parameters, including projectPath/workspacePath (XOR), simulatorId/simulatorName (XOR), scheme, configuration, etc. Supports 'name_ws' combination via simulatorName and workspacePath.
  const buildRunSimulatorSchema = baseSchema .refine((val) => val.projectPath !== undefined || val.workspacePath !== undefined, { message: 'Either projectPath or workspacePath is required.', }) .refine((val) => !(val.projectPath !== undefined && val.workspacePath !== undefined), { message: 'projectPath and workspacePath are mutually exclusive. Provide only one.', }) .refine((val) => val.simulatorId !== undefined || val.simulatorName !== undefined, { message: 'Either simulatorId or simulatorName is required.', }) .refine((val) => !(val.simulatorId !== undefined && val.simulatorName !== undefined), { message: 'simulatorId and simulatorName are mutually exclusive. Provide only one.', });
• src/mcp/tools/simulator/build_run_sim.ts:84-128 (helper)

  Helper function for the build logic step, called by the main handler.
  async function _handleSimulatorBuildLogic( params: BuildRunSimulatorParams, executor: CommandExecutor, executeXcodeBuildCommandFn: typeof executeXcodeBuildCommand = executeXcodeBuildCommand, ): Promise<ToolResponse> { const projectType = params.projectPath ? 'project' : 'workspace'; const filePath = params.projectPath ?? params.workspacePath; // Log warning if useLatestOS is provided with simulatorId if (params.simulatorId && params.useLatestOS !== undefined) { log( 'warning', `useLatestOS parameter is ignored when using simulatorId (UUID implies exact device/OS)`, ); } log( 'info', `Starting iOS Simulator build for scheme ${params.scheme} from ${projectType}: ${filePath}`, ); // Create SharedBuildParams object with required configuration property const sharedBuildParams: SharedBuildParams = { workspacePath: params.workspacePath, projectPath: params.projectPath, scheme: params.scheme, configuration: params.configuration ?? 'Debug', derivedDataPath: params.derivedDataPath, extraArgs: params.extraArgs, }; return executeXcodeBuildCommandFn( sharedBuildParams, { platform: XcodePlatform.iOSSimulator, simulatorId: params.simulatorId, simulatorName: params.simulatorName, useLatestOS: params.simulatorId ? false : params.useLatestOS, logPrefix: 'iOS Simulator Build', }, params.preferXcodebuild as boolean, 'build', executor, ); }