create-simulator-session

Generate and manage iOS simulator sessions programmatically by specifying device details, platform version, timeout, and autoboot settings using MCP Server for iOS Simulator.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`autoboot`	No
`deviceName`	No
`platformVersion`	No
`timeout`	No

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;
  }
}

MCP Server for iOS Simulator