sl-test

Instructions

Implementation Reference

• src/tools/simulator.ts:279-383 (handler)

  The core handler function for the 'launch_app_sim' tool. It validates inputs, checks if the app is installed using 'xcrun simctl get_app_container', launches the app with 'xcrun simctl launch', handles success/error responses, and suggests next steps for log capturing.

      async (params): Promise<ToolResponse> => {
        const simulatorUuidValidation = validateRequiredParam('simulatorUuid', params.simulatorUuid);
        if (!simulatorUuidValidation.isValid) {
          return simulatorUuidValidation.errorResponse!;
        }
  
        const bundleIdValidation = validateRequiredParam('bundleId', params.bundleId);
        if (!bundleIdValidation.isValid) {
          return bundleIdValidation.errorResponse!;
        }
  
        log('info', `Starting xcrun simctl launch request for simulator ${params.simulatorUuid}`);
  
        // Check if the app is installed in the simulator
        try {
          const getAppContainerCmd = [
            'xcrun',
            'simctl',
            'get_app_container',
            params.simulatorUuid,
            params.bundleId,
            'app',
          ];
          const getAppContainerResult = await executeCommand(
            getAppContainerCmd,
            'Check App Installed',
          );
          if (!getAppContainerResult.success) {
            return {
              content: [
                {
                  type: 'text',
                  text: `App is not installed on the simulator. Please use install_app_in_simulator before launching.\n\nWorkflow: build → install → launch.`,
                },
              ],
              isError: true,
            };
          }
        } catch {
          return {
            content: [
              {
                type: 'text',
                text: `App is not installed on the simulator (check failed). Please use install_app_in_simulator before launching.\n\nWorkflow: build → install → launch.`,
              },
            ],
            isError: true,
          };
        }
  
        try {
          const command = ['xcrun', 'simctl', 'launch', params.simulatorUuid, params.bundleId];
  
          if (params.args && params.args.length > 0) {
            command.push(...params.args);
          }
  
          const result = await executeCommand(command, 'Launch App in Simulator');
  
          if (!result.success) {
            return {
              content: [
                {
                  type: 'text',
                  text: `Launch app in simulator operation failed: ${result.error}`,
                },
              ],
            };
          }
  
          return {
            content: [
              {
                type: 'text',
                text: `App launched successfully in simulator ${params.simulatorUuid}`,
              },
              {
                type: 'text',
                text: `Next Steps:
  1. You can now interact with the app in the simulator.
  2. Log capture options:
     - Option 1: Capture structured logs only (app continues running):
       start_sim_log_cap({ simulatorUuid: "${params.simulatorUuid}", bundleId: "${params.bundleId}" })
     - Option 2: Capture both console and structured logs (app will restart):
       start_sim_log_cap({ simulatorUuid: "${params.simulatorUuid}", bundleId: "${params.bundleId}", captureConsole: true })
     - Option 3: Restart with logs in one step:
       launch_app_logs_sim({ simulatorUuid: "${params.simulatorUuid}", bundleId: "${params.bundleId}" })
  
  3. When done with any option, use: stop_sim_log_cap({ logSessionId: 'SESSION_ID' })`,
              },
            ],
          };
        } catch (error) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          log('error', `Error during launch app in simulator operation: ${errorMessage}`);
          return {
            content: [
              {
                type: 'text',
                text: `Launch app in simulator operation failed: ${errorMessage}`,
              },
            ],
          };
        }
      },

• src/tools/simulator.ts:270-278 (schema)

  Zod schema defining the input parameters for the 'launch_app_sim' tool: required simulatorUuid and bundleId, optional args array.

  {
    simulatorUuid: z
      .string()
      .describe('UUID of the simulator to use (obtained from list_simulators)'),
    bundleId: z
      .string()
      .describe("Bundle identifier of the app to launch (e.g., 'com.example.MyApp')"),
    args: z.array(z.string()).optional().describe('Additional arguments to pass to the app'),
  },

• src/tools/simulator.ts:266-385 (registration)

  The registration function that defines and registers the 'launch_app_sim' tool on the MCP server using server.tool(), including name, description, schema, and handler.

  export function registerLaunchAppInSimulatorTool(server: McpServer): void {
    server.tool(
      'launch_app_sim',
      "Launches an app in an iOS simulator. IMPORTANT: You MUST provide both the simulatorUuid and bundleId parameters.\n\nNote: You must install the app in the simulator before launching. The typical workflow is: build → install → launch. Example: launch_app_sim({ simulatorUuid: 'YOUR_UUID_HERE', bundleId: 'com.example.MyApp' })",
      {
        simulatorUuid: z
          .string()
          .describe('UUID of the simulator to use (obtained from list_simulators)'),
        bundleId: z
          .string()
          .describe("Bundle identifier of the app to launch (e.g., 'com.example.MyApp')"),
        args: z.array(z.string()).optional().describe('Additional arguments to pass to the app'),
      },
      async (params): Promise<ToolResponse> => {
        const simulatorUuidValidation = validateRequiredParam('simulatorUuid', params.simulatorUuid);
        if (!simulatorUuidValidation.isValid) {
          return simulatorUuidValidation.errorResponse!;
        }
  
        const bundleIdValidation = validateRequiredParam('bundleId', params.bundleId);
        if (!bundleIdValidation.isValid) {
          return bundleIdValidation.errorResponse!;
        }
  
        log('info', `Starting xcrun simctl launch request for simulator ${params.simulatorUuid}`);
  
        // Check if the app is installed in the simulator
        try {
          const getAppContainerCmd = [
            'xcrun',
            'simctl',
            'get_app_container',
            params.simulatorUuid,
            params.bundleId,
            'app',
          ];
          const getAppContainerResult = await executeCommand(
            getAppContainerCmd,
            'Check App Installed',
          );
          if (!getAppContainerResult.success) {
            return {
              content: [
                {
                  type: 'text',
                  text: `App is not installed on the simulator. Please use install_app_in_simulator before launching.\n\nWorkflow: build → install → launch.`,
                },
              ],
              isError: true,
            };
          }
        } catch {
          return {
            content: [
              {
                type: 'text',
                text: `App is not installed on the simulator (check failed). Please use install_app_in_simulator before launching.\n\nWorkflow: build → install → launch.`,
              },
            ],
            isError: true,
          };
        }
  
        try {
          const command = ['xcrun', 'simctl', 'launch', params.simulatorUuid, params.bundleId];
  
          if (params.args && params.args.length > 0) {
            command.push(...params.args);
          }
  
          const result = await executeCommand(command, 'Launch App in Simulator');
  
          if (!result.success) {
            return {
              content: [
                {
                  type: 'text',
                  text: `Launch app in simulator operation failed: ${result.error}`,
                },
              ],
            };
          }
  
          return {
            content: [
              {
                type: 'text',
                text: `App launched successfully in simulator ${params.simulatorUuid}`,
              },
              {
                type: 'text',
                text: `Next Steps:
  1. You can now interact with the app in the simulator.
  2. Log capture options:
     - Option 1: Capture structured logs only (app continues running):
       start_sim_log_cap({ simulatorUuid: "${params.simulatorUuid}", bundleId: "${params.bundleId}" })
     - Option 2: Capture both console and structured logs (app will restart):
       start_sim_log_cap({ simulatorUuid: "${params.simulatorUuid}", bundleId: "${params.bundleId}", captureConsole: true })
     - Option 3: Restart with logs in one step:
       launch_app_logs_sim({ simulatorUuid: "${params.simulatorUuid}", bundleId: "${params.bundleId}" })
  
  3. When done with any option, use: stop_sim_log_cap({ logSessionId: 'SESSION_ID' })`,
              },
            ],
          };
        } catch (error) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          log('error', `Error during launch app in simulator operation: ${errorMessage}`);
          return {
            content: [
              {
                type: 'text',
                text: `Launch app in simulator operation failed: ${errorMessage}`,
              },
            ],
          };
        }
      },
    );
  }

• src/utils/register-tools.ts:365-369 (registration)

  Entry in the toolRegistrations array that includes the registerLaunchAppInSimulatorTool function, which is invoked by registerTools() to conditionally register the tool based on environment variables and tool groups.

  {
    register: registerLaunchAppInSimulatorTool,
    groups: [ToolGroup.APP_DEPLOYMENT, ToolGroup.IOS_SIMULATOR_WORKFLOW],
    envVar: 'XCODEBUILDMCP_TOOL_LAUNCH_APP_IN_SIMULATOR',
  },