deep_link_navigate
Navigate mobile apps to specific screens using deep links or Universal Links. Supports custom URL schemes and HTTPS URLs for Android and iOS platforms.
Instructions
Navigate to a specific screen in the app using a deep link or Universal Link. Supports custom URL schemes (myapp://path) and HTTPS URLs for App Links/Universal Links.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uri | Yes | Deep link URI to navigate to (e.g., myapp://home/profile or https://example.com/app/products/123) | |
| platform | Yes | Target platform | |
| deviceId | No | Device ID (optional, uses first available). For Android: emulator-5554. For iOS: UDID or "booted" | |
| packageName | No | Android package name to target specific app (e.g., com.example.myapp) | |
| bundleId | No | iOS bundle ID to target specific app (e.g., com.example.myapp) | |
| waitAfterMs | No | Time to wait after navigation in milliseconds (default: 1000) | |
| extras | No | Android intent extras to pass with the deep link | |
| timeoutMs | No | Timeout in milliseconds (default: 15000) |
Implementation Reference
- The core handler function `deepLinkNavigate` that validates input arguments and delegates to platform-specific deep link navigation functions.export async function deepLinkNavigate(args: DeepLinkNavigateArgs): Promise<DeepLinkResult> { const { uri, platform, deviceId, packageName, bundleId, waitAfterMs = 1000, extras, timeoutMs = 15000, } = args; // Validate platform if (!isPlatform(platform)) { throw Errors.invalidArguments(`Invalid platform: ${platform}. Must be 'android' or 'ios'`); } // Validate URI if (!uri || uri.trim().length === 0) { throw Errors.invalidArguments('URI is required'); } // Route to platform-specific handler if (platform === 'android') { return navigateAndroid(uri, { deviceId, packageName, extras, timeoutMs, waitAfterMs, }); } else { return navigateIOS(uri, { deviceId, bundleId, timeoutMs, waitAfterMs, }); } }
- TypeScript interface defining the input arguments (schema) for the `deep_link_navigate` tool.export interface DeepLinkNavigateArgs { /** Deep link URI to navigate to */ uri: string; /** Target platform */ platform: string; /** Device ID (optional, uses first available) */ deviceId?: string; /** Package name for Android (helps target specific app) */ packageName?: string; /** Bundle ID for iOS (helps target specific app) */ bundleId?: string; /** Wait time after navigation in milliseconds */ waitAfterMs?: number; /** Intent extras for Android deep links */ extras?: Array<{ type: 'string' | 'int' | 'boolean'; key: string; value: string | number | boolean; }>; /** Timeout in milliseconds */ timeoutMs?: number; }
- src/tools/navigation/deep-link-navigate.ts:259-315 (registration)Tool registration function that registers `deep_link_navigate` with the global tool registry, including JSON schema and wrapped handler.export function registerDeepLinkNavigateTool(): void { getToolRegistry().register( 'deep_link_navigate', { description: 'Navigate to a specific screen in the app using a deep link or Universal Link. ' + 'Supports custom URL schemes (myapp://path) and HTTPS URLs for App Links/Universal Links.', inputSchema: createInputSchema( { uri: { type: 'string', description: 'Deep link URI to navigate to (e.g., myapp://home/profile or https://example.com/app/products/123)', }, platform: { type: 'string', enum: ['android', 'ios'], description: 'Target platform', }, deviceId: { type: 'string', description: 'Device ID (optional, uses first available). For Android: emulator-5554. For iOS: UDID or "booted"', }, packageName: { type: 'string', description: 'Android package name to target specific app (e.g., com.example.myapp)', }, bundleId: { type: 'string', description: 'iOS bundle ID to target specific app (e.g., com.example.myapp)', }, waitAfterMs: { type: 'number', description: 'Time to wait after navigation in milliseconds (default: 1000)', }, extras: { type: 'array', description: 'Android intent extras to pass with the deep link', }, timeoutMs: { type: 'number', description: 'Timeout in milliseconds (default: 15000)', }, }, ['uri', 'platform'] ), }, async (args) => { const result = await deepLinkNavigate(args as unknown as DeepLinkNavigateArgs); return { ...result, formattedOutput: formatNavigationResult(result), }; } ); }
- src/tools/register.ts:161-163 (registration)Global invocation of the tool registration during server startup in `registerAllTools()`.const { registerDeepLinkNavigateTool } = await import('./navigation/deep-link-navigate.js'); registerDeepLinkNavigateTool();
- Platform-specific helper for iOS deep link navigation (similar Android helper exists).async function navigateIOS( uri: string, options: { deviceId?: string; bundleId?: string; timeoutMs: number; waitAfterMs: number; } ): Promise<DeepLinkResult> { const startTime = Date.now(); // Validate URI format if (!isValidIOSUri(uri)) { return { success: false, platform: 'ios', uri, error: 'Invalid URI format. Must be scheme://path or https://domain/path', durationMs: Date.now() - startTime, }; } // Open deep link const result = await openIOSDeepLink(uri, { deviceId: options.deviceId || 'booted', timeoutMs: options.timeoutMs, waitAfterMs: options.waitAfterMs, }); return { success: result.success, platform: 'ios', uri: result.uri, deviceId: result.deviceId, deviceName: result.deviceName, details: result.details, error: result.error, durationMs: Date.now() - startTime, }; }