stop_app_device
Stop an app on an Apple device using its device UDID and process ID. Ideal for managing app processes during development or debugging on XcodeBuildMCP.
Instructions
Stops an app running on a physical Apple device (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro). Requires deviceId and processId.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| deviceId | Yes | UDID of the device (obtained from list_devices) | |
| processId | Yes | Process ID (PID) of the app to stop |
Implementation Reference
- Core handler logic that terminates the app process on the device using xcrun devicectl device process terminate.
export async function stop_app_deviceLogic( params: StopAppDeviceParams, executor: CommandExecutor, ): Promise<ToolResponse> { const { deviceId, processId } = params; log('info', `Stopping app with PID ${processId} on device ${deviceId}`); try { const result = await executor( [ 'xcrun', 'devicectl', 'device', 'process', 'terminate', '--device', deviceId, '--pid', processId.toString(), ], 'Stop app on device', true, // useShell undefined, // env ); if (!result.success) { return { content: [ { type: 'text', text: `Failed to stop app: ${result.error}`, }, ], isError: true, }; } return { content: [ { type: 'text', text: `✅ App stopped successfully\n\n${result.output}`, }, ], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log('error', `Error stopping app on device: ${errorMessage}`); return { content: [ { type: 'text', text: `Failed to stop app on device: ${errorMessage}`, }, ], isError: true, }; } } - Zod schema for input validation: deviceId (string UDID) and processId (number PID).
const stopAppDeviceSchema = z.object({ deviceId: z.string().describe('UDID of the device (obtained from list_devices)'), processId: z.number().describe('Process ID (PID) of the app to stop'), }); - src/mcp/tools/device/stop_app_device.ts:85-95 (registration)Default export registering the tool with name, description, schema (without deviceId), and session-aware handler.
export default { name: 'stop_app_device', description: 'Stops a running app on a connected device.', schema: stopAppDeviceSchema.omit({ deviceId: true } as const).shape, handler: createSessionAwareTool<StopAppDeviceParams>({ internalSchema: stopAppDeviceSchema as unknown as z.ZodType<StopAppDeviceParams>, logicFunction: stop_app_deviceLogic, getExecutor: getDefaultCommandExecutor, requirements: [{ allOf: ['deviceId'], message: 'deviceId is required' }], }), };