MCP Server for iOS Simulator

Implementation Reference

• src/mcp/mcp-server.ts:515-577 (handler)

  The main handler function for the 'list-available-simulators' tool. It calls simulatorManager.getAllSimulators(), groups by iOS version, formats a readable table with UDIDs, states, and provides workflow instructions.

  async () => {
    fileLogger.info('Listing all available simulators');
    try {
      const availableSimulators = await simulatorManager.getAllSimulators();
      
      // Group by iOS version for better readability
      const devicesByVersion: Record<string, string[]> = {};
      const udidMap: 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);
        udidMap[`${simulator.name}-${version}`] = simulator.udid;
      });
      
      // Generate table format with UDIDs
      let tableText = "⭐️ AVAILABLE SIMULATORS - USE THESE UDIDs TO BOOT DIRECTLY ⭐️\n";
      tableText += "─────────────────────────────────────────────────────\n";
      tableText += "NAME                 | iOS VERSION | STATE    | UDID\n";
      tableText += "─────────────────────────────────────────────────────\n";
      
      for (const [version, devices] of Object.entries(devicesByVersion)) {
        const formattedVersion = version.replace(/-/g, '.');
        devices.sort().forEach((deviceName: string) => {
          const simulator = availableSimulators.find(s => s.name === deviceName && s.runtime.includes(version.replace(/-/g, '.')));
          const state = simulator ? simulator.state : 'Unknown';
          const udid = simulator ? simulator.udid : 'Unknown';
          tableText += `${deviceName.padEnd(20)} | iOS ${formattedVersion.padEnd(9)} | ${state.padEnd(8)} | ${udid}\n`;
        });
      }
      tableText += "─────────────────────────────────────────────────────\n";
      
      tableText += "\n💡 RECOMMENDED WORKFLOW:\n";
      tableText += "1️⃣ FIRST: Find the simulator you want from the list above\n";
      tableText += "2️⃣ THEN: Use 'boot-simulator-by-udid' with udid='COPY_UDID_FROM_ABOVE'\n";
      tableText += "3️⃣ FINALLY: When done, use 'shutdown-simulator-by-udid' with the same UDID\n\n";
      tableText += "❌ AVOID using session-based methods like 'create-simulator-session' unless you specifically need advanced features\n";
      
      // For debugging, append the original JSON at the bottom
      tableText += "\nOriginal JSON data:\n```\n";
      tableText += JSON.stringify(availableSimulators, null, 2);
      tableText += "\n```";
      
      return {
        content: [{
          type: 'text',
          text: tableText
        }]
      };
    } catch (error) {
      fileLogger.error('Failed to list available simulators', { error });
      return {
        content: [{
          type: 'text',
          text: `Error: ${error instanceof Error ? error.message : String(error)}`
        }],
        isError: true
      };
    }
  }

• src/mcp/mcp-server.ts:512-578 (registration)

  Registration of the 'list-available-simulators' MCP tool in the registerSimulatorControl method using this.server.tool with empty input schema.

  this.server.tool(
    'list-available-simulators',
    {},
    async () => {
      fileLogger.info('Listing all available simulators');
      try {
        const availableSimulators = await simulatorManager.getAllSimulators();
        
        // Group by iOS version for better readability
        const devicesByVersion: Record<string, string[]> = {};
        const udidMap: 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);
          udidMap[`${simulator.name}-${version}`] = simulator.udid;
        });
        
        // Generate table format with UDIDs
        let tableText = "⭐️ AVAILABLE SIMULATORS - USE THESE UDIDs TO BOOT DIRECTLY ⭐️\n";
        tableText += "─────────────────────────────────────────────────────\n";
        tableText += "NAME                 | iOS VERSION | STATE    | UDID\n";
        tableText += "─────────────────────────────────────────────────────\n";
        
        for (const [version, devices] of Object.entries(devicesByVersion)) {
          const formattedVersion = version.replace(/-/g, '.');
          devices.sort().forEach((deviceName: string) => {
            const simulator = availableSimulators.find(s => s.name === deviceName && s.runtime.includes(version.replace(/-/g, '.')));
            const state = simulator ? simulator.state : 'Unknown';
            const udid = simulator ? simulator.udid : 'Unknown';
            tableText += `${deviceName.padEnd(20)} | iOS ${formattedVersion.padEnd(9)} | ${state.padEnd(8)} | ${udid}\n`;
          });
        }
        tableText += "─────────────────────────────────────────────────────\n";
        
        tableText += "\n💡 RECOMMENDED WORKFLOW:\n";
        tableText += "1️⃣ FIRST: Find the simulator you want from the list above\n";
        tableText += "2️⃣ THEN: Use 'boot-simulator-by-udid' with udid='COPY_UDID_FROM_ABOVE'\n";
        tableText += "3️⃣ FINALLY: When done, use 'shutdown-simulator-by-udid' with the same UDID\n\n";
        tableText += "❌ AVOID using session-based methods like 'create-simulator-session' unless you specifically need advanced features\n";
        
        // For debugging, append the original JSON at the bottom
        tableText += "\nOriginal JSON data:\n```\n";
        tableText += JSON.stringify(availableSimulators, null, 2);
        tableText += "\n```";
        
        return {
          content: [{
            type: 'text',
            text: tableText
          }]
        };
      } catch (error) {
        fileLogger.error('Failed to list available simulators', { error });
        return {
          content: [{
            type: 'text',
            text: `Error: ${error instanceof Error ? error.message : String(error)}`
          }],
          isError: true
        };
      }
    }
  );

• src/simulator/simulator-manager.ts:553-583 (helper)

  Core helper function that executes 'xcrun simctl list devices -j', parses the JSON output, and returns structured list of all available simulators with UDID, name, state, runtime, and availability.

  async getAllSimulators(): Promise<SimulatorInfo[]> {
    try {
      const execAsync = promisify(exec);
      // Use simctl directly to avoid potential stdout corruption
      const { stdout } = await execAsync('xcrun simctl list devices -j');
      
      // Safely parse the JSON output
      const devices = JSON.parse(stdout).devices;
      const allSimulators: SimulatorInfo[] = [];
      
      // Parse the output to find all devices
      for (const runtime in devices) {
        const runtimeDevices = devices[runtime];
        for (const device of runtimeDevices) {
          allSimulators.push({
            udid: device.udid,
            name: device.name,
            state: device.state,
            runtime: runtime,
            isAvailable: device.isAvailable !== false
          });
        }
      }
      
      fileLogger.info(`Found ${allSimulators.length} simulators`);
      return allSimulators;
    } catch (error) {
      fileLogger.error('Failed to get simulators', { error });
      return [];
    }
  }