list_simulators
Display available Apple simulators for iOS, macOS, tvOS, watchOS, or visionOS. Filter by platform or show all simulators, including unavailable ones, for efficient development and testing within Xcode projects.
Instructions
List all available Apple simulators
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| platform | No | Filter by platform (iOS, macOS, tvOS, watchOS, visionOS) | |
| showAll | No | Show all simulators including unavailable ones |
Implementation Reference
- The execute method of ListSimulatorsController is the main handler for the 'list_simulators' MCP tool. It processes input arguments, validates them, executes the use case, and formats the response as MCP content.async execute(args: unknown): Promise<{ content: Array<{ type: string; text: string }> }> { try { // Cast to expected shape const input = args as { platform?: string; state?: string; name?: string }; // Use the new validation functions const platform = Platform.parseOptional(input.platform); const state = SimulatorState.parseOptional(input.state); const request = ListSimulatorsRequest.create(platform, state, input.name); const result = await this.useCase.execute(request); if (!result.isSuccess) { return { content: [{ type: 'text', text: `❌ ${ErrorFormatter.format(result.error!)}` }] }; } if (result.count === 0) { return { content: [{ type: 'text', text: '🔍 No simulators found' }] }; } const lines: string[] = [ `✅ Found ${result.count} simulator${result.count === 1 ? '' : 's'}`, '' ]; for (const simulator of result.simulators) { lines.push(`• ${simulator.name} (${simulator.udid}) - ${simulator.state} - ${simulator.runtime}`); } return { content: [{ type: 'text', text: lines.join('\n') }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ ${ErrorFormatter.format(error as Error)}` }] }; }
- The inputSchema getter defines the JSON schema for the tool's input parameters, including optional filters for platform, state, and name.get inputSchema() { return { type: 'object' as const, properties: { platform: { type: 'string' as const, description: 'Filter by platform', enum: ['iOS', 'tvOS', 'watchOS', 'visionOS'] as const }, state: { type: 'string' as const, description: 'Filter by simulator state', enum: ['Booted', 'Shutdown'] as const }, name: { type: 'string' as const, description: 'Filter by device name (partial match, case-insensitive)' } }, required: [] as const }; }
- src/index.ts:112-115 (registration)In the registerTools method of XcodeServer, the ListSimulatorsController instance (created via factory at line 81) is registered in the tools Map using its name 'list_simulators'.for (const tool of toolInstances) { const definition = tool.getToolDefinition(); this.tools.set(definition.name, tool); }
- The factory creates the ListSimulatorsController with its dependencies: ShellCommandExecutorAdapter, DeviceRepository, and ListSimulatorsUseCase.static create(): ListSimulatorsController { const execAsync = promisify(exec); const executor = new ShellCommandExecutorAdapter(execAsync); const deviceRepository = new DeviceRepository(executor); const useCase = new ListSimulatorsUseCase(deviceRepository); return new ListSimulatorsController(useCase); }
- The ListSimulatorsUseCase.execute method contains the core business logic for listing and filtering simulators using the DeviceRepository.async execute(request: ListSimulatorsRequest): Promise<ListSimulatorsResult> { try { let allDevices; try { allDevices = await this.deviceRepository.getAllDevices(); } catch (error) { // JSON parsing errors from the repository return ListSimulatorsResult.failed(new SimulatorListParseError()); } const simulatorInfos: SimulatorInfo[] = []; for (const [runtime, devices] of Object.entries(allDevices)) { const platform = this.extractPlatformFromRuntime(runtime); const runtimeVersion = this.extractVersionFromRuntime(runtime); for (const device of devices) { if (!device.isAvailable) continue; const simulatorInfo: SimulatorInfo = { udid: device.udid, name: device.name, state: SimulatorState.parse(device.state), platform: platform, runtime: `${platform} ${runtimeVersion}` }; if (this.matchesFilter(simulatorInfo, request)) { simulatorInfos.push(simulatorInfo); } } } return ListSimulatorsResult.success(simulatorInfos); } catch (error) { return ListSimulatorsResult.failed( error instanceof Error ? error : new Error(String(error)) ); }