set_simulator_location

Set custom GPS coordinates for a simulator to test location-based features by specifying latitude and longitude.

Instructions

Sets a custom GPS location for the simulator.

Input Schema

TableJSON Schema

Name	Required	Description
`simulatorUuid`	Yes	UUID of the simulator to use (obtained from list_simulators)
`latitude`	Yes	The latitude for the custom location.
`longitude`	Yes	The longitude for the custom location.

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',
},
```

sl-test