XC-MCP: XCode CLI wrapper

Instructions

Implementation Reference

• src/tools/simctl/shutdown.ts:44-109 (handler)

  Core handler function that executes the simctl shutdown command with validation, error handling, and response formatting.

  export async function simctlShutdownTool(args: any) {
    const { deviceId } = args as SimctlShutdownToolArgs;
  
    try {
      // Validate inputs
      validateDeviceId(deviceId);
  
      // Build shutdown command
      const command = buildSimctlCommand('shutdown', { deviceId });
  
      console.error(`[simctl-shutdown] Executing: ${command}`);
  
      // Execute shutdown command
      const startTime = Date.now();
      const result = await executeCommand(command, {
        timeout: 60000, // 1 minute for shutdown
      });
      const duration = Date.now() - startTime;
  
      let shutdownStatus = {
        success: result.code === 0,
        command,
        output: result.stdout,
        error: result.stderr,
        exitCode: result.code,
        duration,
      };
  
      // Handle common shutdown scenarios
      if (!shutdownStatus.success) {
        // Device already shutdown
        if (result.stderr.includes('Unable to shutdown device in current state: Shutdown')) {
          shutdownStatus = {
            ...shutdownStatus,
            success: true,
            error: 'Device was already shut down',
          };
        }
        // Invalid device ID
        else if (result.stderr.includes('Invalid device')) {
          throw new McpError(ErrorCode.InvalidParams, `Invalid device ID: ${deviceId}`);
        }
      }
  
      // Format response
      const responseText = JSON.stringify(shutdownStatus, null, 2);
  
      return {
        content: [
          {
            type: 'text' as const,
            text: responseText,
          },
        ],
        isError: !shutdownStatus.success,
      };
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `simctl-shutdown failed: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/tools/simctl/shutdown.ts:6-8 (schema)

  Type definition for the tool input parameters.

  interface SimctlShutdownToolArgs {
    deviceId: string;
  }

• src/tools/simctl/device/index.ts:84-89 (handler)

  Router dispatcher that calls the shutdown handler for 'shutdown' operation in the consolidated simctl-device tool.

  case 'shutdown':
    if (!args.deviceId) {
      throw new McpError(ErrorCode.InvalidRequest, 'deviceId is required for shutdown operation');
    }
    return simctlShutdownTool({ deviceId: args.deviceId });
  case 'create':

• src/registry/simctl.ts:111-141 (registration)

  Registers the consolidated 'simctl-device' tool, which implements simctl-shutdown functionality via operation='shutdown'.

  // simctl-device
  server.registerTool(
    'simctl-device',
    {
      description: getDescription(SIMCTL_DEVICE_DOCS, SIMCTL_DEVICE_DOCS_MINI),
      inputSchema: {
        operation: z.enum(['boot', 'shutdown', 'create', 'delete', 'erase', 'clone', 'rename']),
        deviceId: z.string().optional(),
        waitForBoot: z.boolean().default(true),
        openGui: z.boolean().default(true),
        name: z.string().optional(),
        deviceType: z.string().optional(),
        runtime: z.string().optional(),
        force: z.boolean().default(false),
        newName: z.string().optional(),
      },
      ...DEFER_LOADING_CONFIG,
    },
    async args => {
      try {
        await validateXcodeInstallation();
        return await simctlDeviceTool(args);
      } catch (error) {
        if (error instanceof McpError) throw error;
        throw new McpError(
          ErrorCode.InternalError,
          `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`
        );
      }
    }
  );

• src/tools/simctl/device/index.ts:3-3 (helper)

  Import statement that brings in the shutdown handler for use in the device router.

  import { simctlShutdownTool } from '../shutdown.js';