set_simulator_location

Instructions

Implementation Reference

• src/tools/simulator.ts:597-628 (handler)

  The tool handler that performs extra validation on latitude/longitude, logs the operation, and calls the executeSimctlCommandAndRespond helper to run the 'simctl location set' command.

  async (params: {
    simulatorUuid: string;
    latitude: number;
    longitude: number;
  }): Promise<ToolResponse> => {
    const extraValidation = (): ToolResponse | null => {
      const latitudeValidation = validateRequiredParam('latitude', params.latitude);
      if (!latitudeValidation.isValid) {
        return latitudeValidation.errorResponse!;
      }
      const longitudeValidation = validateRequiredParam('longitude', params.longitude);
      if (!longitudeValidation.isValid) {
        return longitudeValidation.errorResponse!;
      }
      return null;
    };
  
    log(
      'info',
      `Setting simulator ${params.simulatorUuid} location to ${params.latitude},${params.longitude}`,
    );
  
    return executeSimctlCommandAndRespond(
      params,
      ['location', params.simulatorUuid, 'set', `${params.latitude},${params.longitude}`],
      'Set Simulator Location',
      `Successfully set simulator ${params.simulatorUuid} location to ${params.latitude},${params.longitude}`,
      'Failed to set simulator location',
      'set simulator location',
      extraValidation,
    );
  },

• src/tools/simulator.ts:590-596 (schema)

  Zod schema for the tool's input parameters: simulatorUuid, latitude, and longitude.

  {
    simulatorUuid: z
      .string()
      .describe('UUID of the simulator to use (obtained from list_simulators)'),
    latitude: z.number().describe('The latitude for the custom location.'),
    longitude: z.number().describe('The longitude for the custom location.'),
  },

• src/tools/simulator.ts:586-630 (registration)

  Local registration function that defines and registers the 'set_simulator_location' tool on the MCP server, including name, description, schema, and handler.

  export function registerSetSimulatorLocationTool(server: McpServer): void {
    server.tool(
      'set_simulator_location',
      'Sets a custom GPS location for the simulator.',
      {
        simulatorUuid: z
          .string()
          .describe('UUID of the simulator to use (obtained from list_simulators)'),
        latitude: z.number().describe('The latitude for the custom location.'),
        longitude: z.number().describe('The longitude for the custom location.'),
      },
      async (params: {
        simulatorUuid: string;
        latitude: number;
        longitude: number;
      }): Promise<ToolResponse> => {
        const extraValidation = (): ToolResponse | null => {
          const latitudeValidation = validateRequiredParam('latitude', params.latitude);
          if (!latitudeValidation.isValid) {
            return latitudeValidation.errorResponse!;
          }
          const longitudeValidation = validateRequiredParam('longitude', params.longitude);
          if (!longitudeValidation.isValid) {
            return longitudeValidation.errorResponse!;
          }
          return null;
        };
  
        log(
          'info',
          `Setting simulator ${params.simulatorUuid} location to ${params.latitude},${params.longitude}`,
        );
  
        return executeSimctlCommandAndRespond(
          params,
          ['location', params.simulatorUuid, 'set', `${params.latitude},${params.longitude}`],
          'Set Simulator Location',
          `Successfully set simulator ${params.simulatorUuid} location to ${params.latitude},${params.longitude}`,
          'Failed to set simulator location',
          'set simulator location',
          extraValidation,
        );
      },
    );
  }

• src/tools/simulator.ts:500-557 (helper)

  Shared helper function for executing simctl commands in simulator tools: validates params, runs xcrun simctl command, handles responses and errors.

  async function executeSimctlCommandAndRespond(
    params: { simulatorUuid: string; [key: string]: unknown },
    simctlSubCommand: string[],
    operationDescriptionForXcodeCommand: string,
    successMessage: string,
    failureMessagePrefix: string,
    operationLogContext: string,
    extraValidation?: () => ToolResponse | null,
  ): Promise<ToolResponse> {
    const simulatorUuidValidation = validateRequiredParam(
      'simulatorUuid',
      params.simulatorUuid as string,
    );
    if (!simulatorUuidValidation.isValid) {
      return simulatorUuidValidation.errorResponse!;
    }
  
    if (extraValidation) {
      const validationResult = extraValidation();
      if (validationResult) {
        return validationResult;
      }
    }
  
    try {
      const command = ['xcrun', 'simctl', ...simctlSubCommand];
      const result = await executeCommand(command, operationDescriptionForXcodeCommand);
  
      if (!result.success) {
        const fullFailureMessage = `${failureMessagePrefix}: ${result.error}`;
        log(
          'error',
          `${fullFailureMessage} (operation: ${operationLogContext}, simulator: ${params.simulatorUuid})`,
        );
        return {
          content: [{ type: 'text', text: fullFailureMessage }],
        };
      }
  
      log(
        'info',
        `${successMessage} (operation: ${operationLogContext}, simulator: ${params.simulatorUuid})`,
      );
      return {
        content: [{ type: 'text', text: successMessage }],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      const fullFailureMessage = `${failureMessagePrefix}: ${errorMessage}`;
      log(
        'error',
        `Error during ${operationLogContext} for simulator ${params.simulatorUuid}: ${errorMessage}`,
      );
      return {
        content: [{ type: 'text', text: fullFailureMessage }],
      };
    }
  }

• src/utils/register-tools.ts:338-342 (registration)

  Top-level registration configuration in toolRegistrations array; calls registerSetSimulatorLocationTool if environment variable is set.

  {
    register: registerSetSimulatorLocationTool,
    groups: [ToolGroup.SIMULATOR_MANAGEMENT],
    envVar: 'XCODEBUILDMCP_TOOL_SET_SIMULATOR_LOCATION',
  },