launch_app
Launch installed Android or iOS apps on devices or simulators to test functionality across platforms. Specify platform, app identifier, and optional device selection or data clearing.
Instructions
Launch an installed app on a device or simulator.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| platform | Yes | Target platform | |
| appId | Yes | Package name (Android) or bundle ID (iOS) | |
| deviceId | No | Device ID or name (optional, uses first running device if not specified) | |
| clearData | No | Clear app data before launch (Android only, default: false) | |
| launchArguments | No | Arguments to pass to the app (iOS only) |
Implementation Reference
- src/tools/build/launch-app.ts:42-60 (handler)Main handler function for the 'launch_app' MCP tool. Validates inputs and dispatches to platform-specific launch functions.export async function launchApp(args: LaunchAppArgs): Promise<LaunchResult> { const { platform, appId, deviceId, clearData = false, launchArguments } = args; // Validate platform if (!isPlatform(platform)) { throw Errors.invalidArguments(`Invalid platform: ${platform}. Must be 'android' or 'ios'`); } // Validate app ID if (!appId || appId.trim().length === 0) { throw Errors.invalidArguments('appId is required'); } if (platform === 'android') { return launchAndroid(appId, deviceId, clearData); } else { return launchIOS(appId, deviceId, launchArguments); } }
- src/tools/build/launch-app.ts:15-37 (schema)TypeScript interfaces defining input arguments (LaunchAppArgs) and output (LaunchResult) for the launch_app tool.export interface LaunchAppArgs { /** Target platform */ platform: string; /** Package name (Android) or bundle ID (iOS) */ appId: string; /** Target device ID or name (optional, uses first available if not specified) */ deviceId?: string; /** Clear app data before launch (Android only) */ clearData?: boolean; /** Arguments to pass to the app (iOS only) */ launchArguments?: string[]; } /** * Result of launch operation */ export interface LaunchResult { success: boolean; platform: Platform; deviceId: string; deviceName: string; appId: string; }
- src/tools/build/launch-app.ts:144-179 (registration)Registers the 'launch_app' tool with the global tool registry, providing description, JSON input schema, and the handler function.export function registerLaunchAppTool(): void { getToolRegistry().register( 'launch_app', { description: 'Launch an installed app on a device or simulator.', inputSchema: createInputSchema( { platform: { type: 'string', enum: ['android', 'ios'], description: 'Target platform', }, appId: { type: 'string', description: 'Package name (Android) or bundle ID (iOS)', }, deviceId: { type: 'string', description: 'Device ID or name (optional, uses first running device if not specified)', }, clearData: { type: 'boolean', description: 'Clear app data before launch (Android only, default: false)', }, launchArguments: { type: 'array', items: { type: 'string' }, description: 'Arguments to pass to the app (iOS only)', }, }, ['platform', 'appId'] ), }, (args) => launchApp(args as unknown as LaunchAppArgs) ); }
- src/tools/build/launch-app.ts:65-101 (helper)Internal helper function to launch Android app: finds device, launches via adb, returns result.async function launchAndroid( packageName: string, deviceId?: string, clearData?: boolean ): Promise<LaunchResult> { // Find device if not specified let targetDevice: { id: string; name: string }; if (deviceId) { const devices = await listAndroidDevices(); const found = devices.find( (d) => d.id === deviceId || d.name === deviceId || d.model === deviceId ); if (!found) { throw Errors.deviceNotFound(deviceId, devices.map((d) => `${d.id} (${d.name})`)); } targetDevice = { id: found.id, name: found.name }; } else { const devices = await listAndroidDevices(); const bootedDevice = devices.find((d) => d.status === 'booted'); if (!bootedDevice) { throw Errors.invalidArguments('No running Android device found. Boot a device first.'); } targetDevice = { id: bootedDevice.id, name: bootedDevice.name }; } // Launch the app await launchAndroidApp(packageName, targetDevice.id, { clearData }); return { success: true, platform: 'android', deviceId: targetDevice.id, deviceName: targetDevice.name, appId: packageName, }; }
- Internal helper function to launch iOS app: finds simulator, launches via simctl, returns result.async function launchIOS( bundleId: string, deviceId?: string, launchArguments?: string[] ): Promise<LaunchResult> { // Find device if not specified let targetDevice: { id: string; name: string }; if (deviceId) { const devices = await listIOSDevices(); const found = devices.find((d) => d.id === deviceId || d.name === deviceId); if (!found) { throw Errors.deviceNotFound(deviceId, devices.map((d) => `${d.id} (${d.name})`)); } targetDevice = { id: found.id, name: found.name }; } else { const bootedDevice = await getBootedDevice(); if (!bootedDevice) { throw Errors.invalidArguments('No running iOS simulator found. Boot a simulator first.'); } targetDevice = { id: bootedDevice.id, name: bootedDevice.name }; } // Launch the app await launchIOSApp(bundleId, targetDevice.id, { arguments: launchArguments }); return { success: true, platform: 'ios', deviceId: targetDevice.id, deviceName: targetDevice.name, appId: bundleId, }; }