MCP Server for iOS Simulator

Implementation Reference

• src/mcp/mcp-server.ts:102-214 (registration)

  Registration of the 'create-simulator-session' MCP tool, including Zod input schema and the complete handler function that delegates to simulatorManager.createSession and handles autoboot, warnings, and errors.
  'create-simulator-session', { deviceName: z.string().optional(), platformVersion: z.string().optional(), timeout: z.number().optional(), autoboot: z.boolean().optional() }, async (params) => { fileLogger.info('Creating simulator session', params); // Adding a warning before even trying to create a session fileLogger.info('Warning user about session-based approach'); const warningText = "\n⚠️ WARNING: You're using the complex session-based approach ⚠️\n" + "For most users, we recommend the simpler direct UDID approach instead:\n\n" + "1. First run: list-available-simulators\n" + "2. Then use: boot-simulator-by-udid with the UDID from the list\n\n" + "Proceeding with session creation anyway...\n"; try { // Get available simulators to provide helpful error messages if needed const availableSimulators = await simulatorManager.getAllSimulators(); const session = await simulatorManager.createSession({ deviceName: params.deviceName, platformVersion: params.platformVersion, timeout: params.timeout }); // Automatically boot the simulator if requested (default to true) const shouldBoot = params.autoboot !== false; let bootResult = null; if (shouldBoot) { fileLogger.info(`Auto-booting simulator session: ${session.id}`); bootResult = await simulatorManager.bootSimulator(session.id); if (!bootResult) { fileLogger.warn(`Failed to auto-boot simulator session: ${session.id}`); } else { fileLogger.info(`Successfully auto-booted simulator session: ${session.id}`); } } return { content: [{ type: 'text', text: warningText + JSON.stringify({ ...session, booted: shouldBoot ? bootResult : false }) }] }; } catch (error) { fileLogger.error('Failed to create simulator session', { error }); // Get available simulators to provide helpful error messages let helpText = ""; try { const availableSimulators = await simulatorManager.getAllSimulators(); // Group by iOS version for better readability const devicesByVersion: Record<string, string[]> = {}; availableSimulators.forEach(simulator => { const version = simulator.runtime.replace('com.apple.CoreSimulator.SimRuntime.iOS-', '').replace(/\./g, '-'); if (!devicesByVersion[version]) { devicesByVersion[version] = []; } devicesByVersion[version].push(simulator.name); }); // Generate helpful message with available devices helpText = "\n\n⚠️ ERROR, BUT DON'T WORRY! There's a much easier way: ⚠️\n\n"; helpText += "Instead of using sessions, try the direct UDID approach:\n"; helpText += "1. Run 'list-available-simulators' to see all available simulators\n"; helpText += "2. Choose one from the list and boot it directly with its UDID\n\n"; helpText += "Available simulators you can use:\n"; for (const [version, devices] of Object.entries(devicesByVersion)) { const formattedVersion = version.replace(/-/g, '.'); helpText += `\n📱 iOS ${formattedVersion}:\n`; helpText += devices.sort().map((d: string) => ` - ${d}`).join('\n'); helpText += '\n'; } // Try to suggest a specific device if possible if (params.deviceName) { const matchSimulators = availableSimulators.filter(sim => sim.name.toLowerCase().includes(params.deviceName?.toLowerCase() || "") ); if (matchSimulators.length > 0) { const suggestedSim = matchSimulators[0]; helpText += "\n💡 Try this instead:\n"; helpText += `Run: list-available-simulators\n`; helpText += `Then: boot-simulator-by-udid with udid='${suggestedSim.udid}'\n`; } } } catch (helpError) { helpText = "\nCould not retrieve list of available simulators."; } return { content: [{ type: 'text', text: `${helpText}\n\nOriginal error: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } } );
• src/mcp/mcp-server.ts:109-213 (handler)

  Execution handler for create-simulator-session tool. Creates warning about preferred UDID methods, calls simulatorManager.createSession, optionally boots the simulator, provides detailed error messages with available simulators, and returns structured response.
  async (params) => { fileLogger.info('Creating simulator session', params); // Adding a warning before even trying to create a session fileLogger.info('Warning user about session-based approach'); const warningText = "\n⚠️ WARNING: You're using the complex session-based approach ⚠️\n" + "For most users, we recommend the simpler direct UDID approach instead:\n\n" + "1. First run: list-available-simulators\n" + "2. Then use: boot-simulator-by-udid with the UDID from the list\n\n" + "Proceeding with session creation anyway...\n"; try { // Get available simulators to provide helpful error messages if needed const availableSimulators = await simulatorManager.getAllSimulators(); const session = await simulatorManager.createSession({ deviceName: params.deviceName, platformVersion: params.platformVersion, timeout: params.timeout }); // Automatically boot the simulator if requested (default to true) const shouldBoot = params.autoboot !== false; let bootResult = null; if (shouldBoot) { fileLogger.info(`Auto-booting simulator session: ${session.id}`); bootResult = await simulatorManager.bootSimulator(session.id); if (!bootResult) { fileLogger.warn(`Failed to auto-boot simulator session: ${session.id}`); } else { fileLogger.info(`Successfully auto-booted simulator session: ${session.id}`); } } return { content: [{ type: 'text', text: warningText + JSON.stringify({ ...session, booted: shouldBoot ? bootResult : false }) }] }; } catch (error) { fileLogger.error('Failed to create simulator session', { error }); // Get available simulators to provide helpful error messages let helpText = ""; try { const availableSimulators = await simulatorManager.getAllSimulators(); // Group by iOS version for better readability const devicesByVersion: Record<string, string[]> = {}; availableSimulators.forEach(simulator => { const version = simulator.runtime.replace('com.apple.CoreSimulator.SimRuntime.iOS-', '').replace(/\./g, '-'); if (!devicesByVersion[version]) { devicesByVersion[version] = []; } devicesByVersion[version].push(simulator.name); }); // Generate helpful message with available devices helpText = "\n\n⚠️ ERROR, BUT DON'T WORRY! There's a much easier way: ⚠️\n\n"; helpText += "Instead of using sessions, try the direct UDID approach:\n"; helpText += "1. Run 'list-available-simulators' to see all available simulators\n"; helpText += "2. Choose one from the list and boot it directly with its UDID\n\n"; helpText += "Available simulators you can use:\n"; for (const [version, devices] of Object.entries(devicesByVersion)) { const formattedVersion = version.replace(/-/g, '.'); helpText += `\n📱 iOS ${formattedVersion}:\n`; helpText += devices.sort().map((d: string) => ` - ${d}`).join('\n'); helpText += '\n'; } // Try to suggest a specific device if possible if (params.deviceName) { const matchSimulators = availableSimulators.filter(sim => sim.name.toLowerCase().includes(params.deviceName?.toLowerCase() || "") ); if (matchSimulators.length > 0) { const suggestedSim = matchSimulators[0]; helpText += "\n💡 Try this instead:\n"; helpText += `Run: list-available-simulators\n`; helpText += `Then: boot-simulator-by-udid with udid='${suggestedSim.udid}'\n`; } } } catch (helpError) { helpText = "\nCould not retrieve list of available simulators."; } return { content: [{ type: 'text', text: `${helpText}\n\nOriginal error: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } }
• src/mcp/mcp-server.ts:103-107 (schema)

  Input schema using Zod for validating tool parameters: deviceName, platformVersion, timeout (optional), autoboot (optional boolean).
  { deviceName: z.string().optional(), platformVersion: z.string().optional(), timeout: z.number().optional(), autoboot: z.boolean().optional()
• src/simulator/simulator-manager.ts:128-177 (helper)

  Core helper method implementing simulator session creation logic. Finds matching simulator using tiered search strategies based on deviceName/platformVersion, wraps appium-ios-simulator instance with session metadata and unique ID, manages in-memory session tracking.
  async createSession(options: SimulatorOptions = {}): Promise<SimulatorSession> { try { // Use provided options or defaults from config const deviceName = options.deviceName || config.simulator.defaultDevice; const platformVersion = options.platformVersion || config.simulator.defaultOS; const timeout = options.timeout || config.simulator.timeout; fileLogger.info(`Creating simulator session with device: ${deviceName}, OS: ${platformVersion}`); // Get all available simulators const simulators = await this.getAllSimulators(); // Log available matching simulators for debugging this.logMatchingSimulators(simulators, deviceName); // If UDID is provided directly, use it if (deviceName.match(/^[0-9A-F]{8}-([0-9A-F]{4}-){3}[0-9A-F]{12}$/i)) { const udidMatch = simulators.find(sim => sim.udid === deviceName); if (udidMatch && udidMatch.isAvailable) { fileLogger.info(`Found simulator with exact UDID match: ${udidMatch.name}`); return this.createSessionFromSimulator(udidMatch, timeout); } } // Find matching simulator using a tiered approach let matchingSimulator: SimulatorInfo | undefined; // Tier 1: Exact name match (most strict) matchingSimulator = this.findExactNameMatch(simulators, deviceName, platformVersion); // Tier 2: Word boundary matching (prevent "iPhone 14" from matching "iPhone 14 Pro") if (!matchingSimulator) { matchingSimulator = this.findWordBoundaryMatch(simulators, deviceName, platformVersion); } // Tier 3: Substring matching (most lenient, last resort) if (!matchingSimulator) { matchingSimulator = this.findSubstringMatch(simulators, deviceName, platformVersion); } if (!matchingSimulator) { throw new Error(`No matching simulator found for device: ${deviceName}, OS: ${platformVersion}`); } return this.createSessionFromSimulator(matchingSimulator, timeout); } catch (error) { fileLogger.error('Failed to create simulator session', { error }); throw error; } }