preflight-ios-mcp 1.0.0

package/dist/index.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as logger from './helpers/logger.js';
+// Tool imports
+import { screenshotParams, handleScreenshot } from './tools/screenshot.js';
+import { listDevicesParams, handleListDevices, bootParams, handleBoot, shutdownParams, handleShutdown, eraseParams, handleErase, openUrlParams, handleOpenUrl, openSimulatorParams, handleOpenSimulator, getBootedSimIdParams, handleGetBootedSimId, } from './tools/device.js';
+import { listAppsParams, handleListApps, appInfoParams, handleAppInfo, launchAppParams, handleLaunchApp, terminateAppParams, handleTerminateApp, installAppParams, handleInstallApp, uninstallAppParams, handleUninstallApp, } from './tools/app.js';
+import { tapParams, handleTap, swipeParams, handleSwipe, longPressParams, handleLongPress, describePointParams, handleDescribePoint, typeTextParams, handleTypeText, pressKeyParams, handlePressKey, } from './tools/interaction.js';
+import { setLocationParams, handleSetLocation, sendPushParams, handleSendPush, setClipboardParams, handleSetClipboard, getClipboardParams, handleGetClipboard, addMediaParams, handleAddMedia, grantPermissionParams, handleGrantPermission, } from './tools/system.js';
+import { setAppearanceParams, handleSetAppearance, overrideStatusBarParams, handleOverrideStatusBar, recordVideoParams, handleRecordVideo, stopRecordingParams, handleStopRecording, navigateBackParams, handleNavigateBack, } from './tools/ui.js';
+import { getLogsParams, handleGetLogs, streamLogsParams, handleStreamLogs, getAppContainerParams, handleGetAppContainer, listAppFilesParams, handleListAppFiles, readAppFileParams, handleReadAppFile, getCrashLogsParams, handleGetCrashLogs, diagnoseParams, handleDiagnose, accessibilityAuditParams, handleAccessibilityAudit, getScreenInfoParams, handleGetScreenInfo, } from './tools/debug.js';
+import { icloudSyncParams, handleIcloudSync, keychainParams, handleKeychain, contentSizeParams, handleContentSize, increaseContrastParams, handleIncreaseContrast, locationScenarioParams, handleLocationScenario, locationRouteParams, handleLocationRoute, verboseLoggingParams, handleVerboseLogging, installAppDataParams, handleInstallAppData, getEnvParams, handleGetEnv, memoryWarningParams, handleMemoryWarning, biometricParams, handleBiometric, networkStatusParams, handleNetworkStatus, defaultsReadParams, handleDefaultsRead, defaultsWriteParams, handleDefaultsWrite, } from './tools/advanced.js';
+import { snapshotParams, handleSnapshot, waitForElementParams, handleWaitForElement, elementExistsParams, handleElementExists, } from './tools/playwright.js';
+// Support tool filtering via environment variable
+const filteredTools = new Set((process.env.PREFLIGHT_FILTERED_TOOLS || process.env.IOS_SIMULATOR_MCP_FILTERED_TOOLS || '')
+    .split(',').map(s => s.trim()).filter(Boolean));
+const server = new McpServer({
+    name: 'preflight-mcp',
+    version: '1.0.0',
+});
+// Register a tool, skipping if it's in the filtered list
+function registerTool(name, description, params, handler) {
+    if (filteredTools.has(name)) {
+        logger.debug('server', `Tool ${name} filtered out by PREFLIGHT_FILTERED_TOOLS`);
+        return;
+    }
+    server.tool(name, description, params, handler);
+}
+// Helper to wrap tool handlers with logging and error handling
+function wrapHandler(name, handler) {
+    return async (args) => {
+        const start = Date.now();
+        logger.toolStart(name, args);
+        try {
+            const result = await handler(args);
+            logger.toolEnd(name, Date.now() - start, true);
+            return result;
+        }
+        catch (err) {
+            const e = err;
+            logger.toolEnd(name, Date.now() - start, false);
+            logger.error(`tool:${name}`, e.message, { stack: e.stack });
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error: ${e.message}`,
+                    }],
+                isError: true,
+            };
+        }
+    };
+}
+// ========== Observation Tools ==========
+registerTool('simulator_screenshot', 'Take a screenshot of the iOS Simulator screen. Returns the image directly for viewing.', screenshotParams, wrapHandler('simulator_screenshot', handleScreenshot));
+registerTool('simulator_list_devices', 'List iOS Simulator devices. Shows name, UDID, state, and runtime.', listDevicesParams, wrapHandler('simulator_list_devices', handleListDevices));
+registerTool('simulator_list_apps', 'List all installed apps on the simulator with their bundle IDs.', listAppsParams, wrapHandler('simulator_list_apps', handleListApps));
+registerTool('simulator_app_info', 'Get detailed metadata about an installed app (bundle ID, paths, version, etc.).', appInfoParams, wrapHandler('simulator_app_info', handleAppInfo));
+registerTool('simulator_get_clipboard', 'Read the text content of the simulator clipboard.', getClipboardParams, wrapHandler('simulator_get_clipboard', handleGetClipboard));
+registerTool('simulator_get_screen_info', 'Get diagnostic info about the Simulator window geometry and coordinate mapping. Useful for debugging tap/swipe accuracy.', getScreenInfoParams, wrapHandler('simulator_get_screen_info', handleGetScreenInfo));
+// ========== User Interaction Tools ==========
+registerTool('simulator_tap', 'Tap at a point on the simulator screen. Coordinates are in simulator screen points (e.g., 0-393 for iPhone width). Take a screenshot first to identify coordinates.', tapParams, wrapHandler('simulator_tap', handleTap));
+registerTool('simulator_swipe', 'Swipe/drag from one point to another on the simulator screen. Coordinates are in simulator screen points. Use for scrolling, pulling down, or any drag gesture.', swipeParams, wrapHandler('simulator_swipe', handleSwipe));
+registerTool('simulator_long_press', 'Long press at a point on the simulator screen. Useful for context menus, drag-and-drop initiation, etc.', longPressParams, wrapHandler('simulator_long_press', handleLongPress));
+registerTool('simulator_describe_point', 'Returns the accessibility element at given coordinates on the iOS Simulator screen. Shows element type, label, value, and frame.', describePointParams, wrapHandler('simulator_describe_point', handleDescribePoint));
+registerTool('simulator_type_text', 'Type text into the currently focused text field in the simulator. Make sure a text field is focused first (tap on it).', typeTextParams, wrapHandler('simulator_type_text', handleTypeText));
+registerTool('simulator_press_key', 'Press a special key (return, escape, delete, tab, arrows, etc.) with optional modifiers (command, shift, option, control).', pressKeyParams, wrapHandler('simulator_press_key', handlePressKey));
+// ========== Device Management Tools ==========
+registerTool('simulator_boot', 'Boot an iOS Simulator device. Opens the Simulator app. Use simulator_list_devices to find device names/UDIDs.', bootParams, wrapHandler('simulator_boot', handleBoot));
+registerTool('simulator_shutdown', 'Shut down a running simulator device.', shutdownParams, wrapHandler('simulator_shutdown', handleShutdown));
+registerTool('simulator_erase', 'Factory reset a simulator device. Erases all content and settings.', eraseParams, wrapHandler('simulator_erase', handleErase));
+registerTool('simulator_open_url', 'Open a URL or deep link in the simulator (e.g., "https://example.com" or "myapp://screen").', openUrlParams, wrapHandler('simulator_open_url', handleOpenUrl));
+registerTool('simulator_open_simulator', 'Opens the iOS Simulator application.', openSimulatorParams, wrapHandler('simulator_open_simulator', handleOpenSimulator));
+registerTool('simulator_get_booted_sim_id', 'Get the UDID of the currently booted iOS Simulator.', getBootedSimIdParams, wrapHandler('simulator_get_booted_sim_id', handleGetBootedSimId));
+// ========== App Management Tools ==========
+registerTool('simulator_launch_app', 'Launch an app by bundle ID. Optionally pass launch arguments and environment variables.', launchAppParams, wrapHandler('simulator_launch_app', handleLaunchApp));
+registerTool('simulator_terminate_app', 'Force-terminate a running app by bundle ID.', terminateAppParams, wrapHandler('simulator_terminate_app', handleTerminateApp));
+registerTool('simulator_install_app', 'Install a .app bundle onto the simulator from a local file path.', installAppParams, wrapHandler('simulator_install_app', handleInstallApp));
+registerTool('simulator_uninstall_app', 'Uninstall an app from the simulator by bundle ID.', uninstallAppParams, wrapHandler('simulator_uninstall_app', handleUninstallApp));
+// ========== Developer Debugging Tools ==========
+registerTool('simulator_get_logs', 'Get recent device/app logs. Filter by process name, subsystem, log level, time range, and message content. Essential for debugging app behavior.', getLogsParams, wrapHandler('simulator_get_logs', handleGetLogs));
+registerTool('simulator_stream_logs', 'Start/read/stop a live log stream. Use action="start" to begin, "read" to get the buffer, "stop" to end. Great for watching app behavior in real-time.', streamLogsParams, wrapHandler('simulator_stream_logs', handleStreamLogs));
+registerTool('simulator_get_app_container', 'Get the filesystem path to an app\'s container (bundle, data, or shared groups). Use this to find where the app stores its files.', getAppContainerParams, wrapHandler('simulator_get_app_container', handleGetAppContainer));
+registerTool('simulator_list_app_files', 'List files in an app\'s data container. Shows Documents, Library, Preferences, Caches, tmp, etc. Use to find databases, plists, caches.', listAppFilesParams, wrapHandler('simulator_list_app_files', handleListAppFiles));
+registerTool('simulator_read_app_file', 'Read a file from an app\'s data container. Handles plists (converts to JSON), SQLite databases (shows schema), and text files. Specify path relative to data container.', readAppFileParams, wrapHandler('simulator_read_app_file', handleReadAppFile));
+registerTool('simulator_get_crash_logs', 'Retrieve crash reports from ~/Library/Logs/DiagnosticReports/. Shows stack traces, exception info, and thread states. Filter by process name.', getCrashLogsParams, wrapHandler('simulator_get_crash_logs', handleGetCrashLogs));
+registerTool('simulator_diagnose', 'Generate a diagnostic summary: booted devices, Xcode version, disk usage, and system info.', diagnoseParams, wrapHandler('simulator_diagnose', handleDiagnose));
+registerTool('simulator_accessibility_audit', 'Get the accessibility element tree of the current Simulator screen. Shows roles, labels, values, and positions of UI elements.', accessibilityAuditParams, wrapHandler('simulator_accessibility_audit', handleAccessibilityAudit));
+// ========== System Simulation Tools ==========
+registerTool('simulator_set_location', 'Set the simulated GPS location (latitude, longitude). Useful for testing location-based features.', setLocationParams, wrapHandler('simulator_set_location', handleSetLocation));
+registerTool('simulator_send_push', 'Send a push notification to an app. Provide the full APNs payload JSON (e.g., {"aps": {"alert": "Hello"}}).', sendPushParams, wrapHandler('simulator_send_push', handleSendPush));
+registerTool('simulator_set_clipboard', 'Set text on the simulator clipboard. Useful for pasting content into apps.', setClipboardParams, wrapHandler('simulator_set_clipboard', handleSetClipboard));
+registerTool('simulator_add_media', 'Add photos or videos to the simulator\'s camera roll from local file paths.', addMediaParams, wrapHandler('simulator_add_media', handleAddMedia));
+registerTool('simulator_grant_permission', 'Grant, revoke, or reset app permissions (camera, location, photos, contacts, microphone, etc.).', grantPermissionParams, wrapHandler('simulator_grant_permission', handleGrantPermission));
+// ========== UI Configuration Tools ==========
+registerTool('simulator_set_appearance', 'Switch the simulator between light and dark mode.', setAppearanceParams, wrapHandler('simulator_set_appearance', handleSetAppearance));
+registerTool('simulator_override_status_bar', 'Override the simulator status bar: set time, battery, signal bars, carrier name, network type. Use clear=true to reset.', overrideStatusBarParams, wrapHandler('simulator_override_status_bar', handleOverrideStatusBar));
+registerTool('simulator_record_video', 'Start recording the simulator screen to a video file. Use simulator_stop_recording to stop. Supports H.264 and HEVC codecs.', recordVideoParams, wrapHandler('simulator_record_video', handleRecordVideo));
+registerTool('simulator_stop_recording', 'Stop an active video recording and save the file.', stopRecordingParams, wrapHandler('simulator_stop_recording', handleStopRecording));
+registerTool('simulator_navigate_back', 'Navigate back in the current app. Sends Cmd+[ (standard back navigation). Works in Safari and apps with standard UINavigationController. Workaround for edge-swipe-back gesture limitation.', navigateBackParams, wrapHandler('simulator_navigate_back', handleNavigateBack));
+// ========== Advanced Tools ==========
+registerTool('simulator_icloud_sync', 'Trigger iCloud sync on the device. Requires the device to be signed into an Apple ID.', icloudSyncParams, wrapHandler('simulator_icloud_sync', handleIcloudSync));
+registerTool('simulator_keychain', 'Manipulate the device keychain: add root certificates, add certificates, or reset the entire keychain.', keychainParams, wrapHandler('simulator_keychain', handleKeychain));
+registerTool('simulator_set_content_size', 'Set the preferred content size for Dynamic Type testing. Test your app with accessibility text sizes without changing device settings manually.', contentSizeParams, wrapHandler('simulator_set_content_size', handleContentSize));
+registerTool('simulator_set_increase_contrast', 'Enable or disable the Increase Contrast accessibility setting. Test how your app responds to high contrast mode.', increaseContrastParams, wrapHandler('simulator_set_increase_contrast', handleIncreaseContrast));
+registerTool('simulator_location_scenario', 'Run predefined GPS location scenarios (Freeway Drive, City Run, City Bicycle Ride). Simulates realistic movement patterns for testing location features.', locationScenarioParams, wrapHandler('simulator_location_scenario', handleLocationScenario));
+registerTool('simulator_location_route', 'Simulate movement along a custom route with waypoints. Specify GPS coordinates and speed for realistic location testing.', locationRouteParams, wrapHandler('simulator_location_route', handleLocationRoute));
+registerTool('simulator_verbose_logging', 'Enable or disable verbose device logging for deep debugging. Requires device reboot to take effect.', verboseLoggingParams, wrapHandler('simulator_verbose_logging', handleVerboseLogging));
+registerTool('simulator_install_app_data', 'Install an .xcappdata package to replace the current app container contents. Useful for restoring test data snapshots.', installAppDataParams, wrapHandler('simulator_install_app_data', handleInstallAppData));
+registerTool('simulator_get_env', 'Read an environment variable from the running simulator device (e.g., HOME, TMPDIR, PATH).', getEnvParams, wrapHandler('simulator_get_env', handleGetEnv));
+registerTool('simulator_memory_warning', 'Trigger a simulated memory warning. Apps will receive didReceiveMemoryWarning and can be tested for proper memory cleanup.', memoryWarningParams, wrapHandler('simulator_memory_warning', handleMemoryWarning));
+registerTool('simulator_biometric', 'Set Face ID / Touch ID enrollment state. Test biometric authentication flows.', biometricParams, wrapHandler('simulator_biometric', handleBiometric));
+registerTool('simulator_network_status', 'Get the current network configuration inside the simulator — interfaces, IP addresses, DNS config.', networkStatusParams, wrapHandler('simulator_network_status', handleNetworkStatus));
+registerTool('simulator_defaults_read', 'Read UserDefaults values from inside the simulator. Inspect app preferences, feature flags, and configuration.', defaultsReadParams, wrapHandler('simulator_defaults_read', handleDefaultsRead));
+registerTool('simulator_defaults_write', 'Write UserDefaults values inside the simulator. Set feature flags, change app configuration, or inject test data.', defaultsWriteParams, wrapHandler('simulator_defaults_write', handleDefaultsWrite));
+// ========== Playwright-Inspired Tools ==========
+registerTool('simulator_snapshot', 'Capture a structured accessibility snapshot of the current screen — like Playwright\'s browser_snapshot. Returns roles, labels, values, and positions. PREFERRED over screenshots for understanding UI structure and targeting interactions. No vision model needed.', snapshotParams, wrapHandler('simulator_snapshot', handleSnapshot));
+registerTool('simulator_wait_for_element', 'Wait for an accessibility element to appear on screen. Polls until the element matching your criteria (label, role, or text) appears, or times out. Like Playwright\'s browser_wait_for.', waitForElementParams, wrapHandler('simulator_wait_for_element', handleWaitForElement));
+registerTool('simulator_element_exists', 'Quick check: does an element matching your criteria exist on screen right now? Returns true/false. Useful for conditional logic.', elementExistsParams, wrapHandler('simulator_element_exists', handleElementExists));
+// ========== Start Server ==========
+async function main() {
+    logger.info('server', 'Preflight MCP server starting...');
+    // Detect idb for cursor-free touch injection
+    const { checkIdbAvailable } = await import('./helpers/idb.js');
+    const hasIdb = await checkIdbAvailable();
+    if (hasIdb) {
+        logger.info('server', 'idb detected — using cursor-free touch injection (IndigoHID)');
+    }
+    else {
+        logger.warn('server', 'idb not found — using CGEvent fallback. Install for cursor-free touch: brew tap facebook/fb && brew install idb-companion && pip3 install fb-idb');
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('server', 'Preflight MCP server connected and ready.');
+}
+main().catch((err) => {
+    logger.error('server', 'Fatal error', { error: err.message, stack: err.stack });
+    process.exit(1);
+});

package/dist/tools/advanced.d.ts

@@ -0,0 +1,203 @@
+import { z } from 'zod';
+export declare const icloudSyncParams: {
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleIcloudSync(args: {
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const keychainParams: {
+    action: z.ZodEnum<["add-root-cert", "add-cert", "reset"]>;
+    path: z.ZodOptional<z.ZodString>;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleKeychain(args: {
+    action: string;
+    path?: string;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const contentSizeParams: {
+    size: z.ZodEnum<["extra-small", "small", "medium", "large", "extra-large", "extra-extra-large", "extra-extra-extra-large", "accessibility-medium", "accessibility-large", "accessibility-extra-large", "accessibility-extra-extra-large", "accessibility-extra-extra-extra-large"]>;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleContentSize(args: {
+    size: string;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const increaseContrastParams: {
+    enabled: z.ZodBoolean;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleIncreaseContrast(args: {
+    enabled: boolean;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const locationScenarioParams: {
+    action: z.ZodEnum<["list", "run", "clear"]>;
+    scenario: z.ZodOptional<z.ZodString>;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleLocationScenario(args: {
+    action: string;
+    scenario?: string;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const locationRouteParams: {
+    waypoints: z.ZodArray<z.ZodObject<{
+        lat: z.ZodNumber;
+        lng: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        lat: number;
+        lng: number;
+    }, {
+        lat: number;
+        lng: number;
+    }>, "many">;
+    speed: z.ZodOptional<z.ZodNumber>;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleLocationRoute(args: {
+    waypoints: Array<{
+        lat: number;
+        lng: number;
+    }>;
+    speed?: number;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const verboseLoggingParams: {
+    enabled: z.ZodBoolean;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleVerboseLogging(args: {
+    enabled: boolean;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const installAppDataParams: {
+    path: z.ZodString;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleInstallAppData(args: {
+    path: string;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const getEnvParams: {
+    variable: z.ZodString;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleGetEnv(args: {
+    variable: string;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const memoryWarningParams: {
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleMemoryWarning(args: {
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const biometricParams: {
+    enrolled: z.ZodBoolean;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleBiometric(args: {
+    enrolled: boolean;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const networkStatusParams: {
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleNetworkStatus(args: {
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const defaultsReadParams: {
+    domain: z.ZodString;
+    key: z.ZodOptional<z.ZodString>;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleDefaultsRead(args: {
+    domain: string;
+    key?: string;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const defaultsWriteParams: {
+    domain: z.ZodString;
+    key: z.ZodString;
+    value: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<["string", "int", "float", "bool"]>>;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleDefaultsWrite(args: {
+    domain: string;
+    key: string;
+    value: string;
+    type?: string;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/advanced.js

@@ -0,0 +1,275 @@
+import { z } from 'zod';
+import { execSimctl, resolveDevice } from '../helpers/simctl.js';
+// --- icloud_sync ---
+export const icloudSyncParams = {
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleIcloudSync(args) {
+    const device = await resolveDevice(args.deviceId);
+    try {
+        await execSimctl(['icloud_sync', device], 'tool:icloudSync');
+        return { content: [{ type: 'text', text: 'iCloud sync triggered.' }] };
+    }
+    catch (err) {
+        const e = err;
+        return { content: [{ type: 'text', text: `iCloud sync failed (device may not be signed in): ${e.message}` }] };
+    }
+}
+// --- keychain ---
+export const keychainParams = {
+    action: z.enum(['add-root-cert', 'add-cert', 'reset']).describe('"add-root-cert" to add trusted root CA, "add-cert" to add certificate, "reset" to clear keychain'),
+    path: z.string().optional().describe('Path to certificate file (required for add-root-cert and add-cert)'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleKeychain(args) {
+    const device = await resolveDevice(args.deviceId);
+    if (args.action === 'reset') {
+        await execSimctl(['keychain', device, 'reset'], 'tool:keychain');
+        return { content: [{ type: 'text', text: 'Keychain reset.' }] };
+    }
+    if (!args.path) {
+        return { content: [{ type: 'text', text: `Certificate path is required for ${args.action}.` }] };
+    }
+    await execSimctl(['keychain', device, args.action, args.path], 'tool:keychain');
+    return { content: [{ type: 'text', text: `Certificate added via ${args.action}: ${args.path}` }] };
+}
+// --- content_size (Dynamic Type) ---
+export const contentSizeParams = {
+    size: z.enum([
+        'extra-small', 'small', 'medium', 'large', 'extra-large', 'extra-extra-large', 'extra-extra-extra-large',
+        'accessibility-medium', 'accessibility-large', 'accessibility-extra-large',
+        'accessibility-extra-extra-large', 'accessibility-extra-extra-extra-large',
+    ]).describe('Preferred content size category for Dynamic Type testing'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleContentSize(args) {
+    const device = await resolveDevice(args.deviceId);
+    await execSimctl(['ui', device, 'content_size', args.size], 'tool:contentSize');
+    return { content: [{ type: 'text', text: `Content size set to "${args.size}". Apps using Dynamic Type will update.` }] };
+}
+// --- increase_contrast ---
+export const increaseContrastParams = {
+    enabled: z.boolean().describe('Enable or disable Increase Contrast accessibility setting'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleIncreaseContrast(args) {
+    const device = await resolveDevice(args.deviceId);
+    await execSimctl(['ui', device, 'increase_contrast', args.enabled ? 'enabled' : 'disabled'], 'tool:increaseContrast');
+    return { content: [{ type: 'text', text: `Increase Contrast ${args.enabled ? 'enabled' : 'disabled'}.` }] };
+}
+// --- location_scenario ---
+export const locationScenarioParams = {
+    action: z.enum(['list', 'run', 'clear']).describe('"list" available scenarios, "run" a scenario, "clear" to stop'),
+    scenario: z.string().optional().describe('Scenario name (e.g., "Freeway Drive", "City Run", "City Bicycle Ride", "Apple")'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleLocationScenario(args) {
+    const device = await resolveDevice(args.deviceId);
+    if (args.action === 'list') {
+        const { stdout } = await execSimctl(['location', device, 'list'], 'tool:locationScenario');
+        return { content: [{ type: 'text', text: `Available location scenarios:\n${stdout}` }] };
+    }
+    if (args.action === 'clear') {
+        await execSimctl(['location', device, 'clear'], 'tool:locationScenario');
+        return { content: [{ type: 'text', text: 'Location scenario stopped and location cleared.' }] };
+    }
+    if (!args.scenario) {
+        return { content: [{ type: 'text', text: 'Scenario name required for "run". Use action="list" to see available scenarios.' }] };
+    }
+    await execSimctl(['location', device, 'run', args.scenario], 'tool:locationScenario');
+    return { content: [{ type: 'text', text: `Running location scenario: "${args.scenario}". Use action="clear" to stop.` }] };
+}
+// --- location_route (simulate movement between waypoints) ---
+export const locationRouteParams = {
+    waypoints: z.array(z.object({
+        lat: z.number().describe('Latitude'),
+        lng: z.number().describe('Longitude'),
+    })).describe('Array of {lat, lng} waypoints to traverse'),
+    speed: z.number().optional().describe('Speed in meters/second (default: ~walking speed)'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleLocationRoute(args) {
+    const device = await resolveDevice(args.deviceId);
+    if (args.waypoints.length < 2) {
+        return { content: [{ type: 'text', text: 'At least 2 waypoints required.' }] };
+    }
+    const waypointData = args.waypoints.map(w => `${w.lat},${w.lng}`).join('\n') + '\n';
+    const cmdArgs = ['simctl', 'location', device, 'start'];
+    if (args.speed)
+        cmdArgs.push('--speed=' + args.speed);
+    try {
+        const { spawn } = await import('node:child_process');
+        await new Promise((resolve, reject) => {
+            const child = spawn('xcrun', cmdArgs, { stdio: ['pipe', 'pipe', 'pipe'] });
+            let stderr = '';
+            child.stderr.on('data', (d) => { stderr += d.toString(); });
+            child.on('close', (code) => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(stderr || `exit code ${code}`));
+            });
+            child.stdin.write(waypointData);
+            child.stdin.end();
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Simulating route with ${args.waypoints.length} waypoints${args.speed ? ` at ${args.speed}m/s` : ''}. Use simulator_location_scenario action="clear" to stop.`,
+                }],
+        };
+    }
+    catch (err) {
+        const e = err;
+        return { content: [{ type: 'text', text: `Route simulation failed: ${e.message}` }] };
+    }
+}
+// --- verbose_logging ---
+export const verboseLoggingParams = {
+    enabled: z.boolean().describe('Enable or disable verbose logging (device reboot may be required)'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleVerboseLogging(args) {
+    const device = await resolveDevice(args.deviceId);
+    await execSimctl(['logverbose', device, args.enabled ? 'enable' : 'disable'], 'tool:verboseLogging');
+    return {
+        content: [{
+                type: 'text',
+                text: `Verbose logging ${args.enabled ? 'enabled' : 'disabled'}. Reboot the device for changes to take effect.`,
+            }],
+    };
+}
+// --- install_app_data ---
+export const installAppDataParams = {
+    path: z.string().describe('Path to .xcappdata package to install'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleInstallAppData(args) {
+    const device = await resolveDevice(args.deviceId);
+    await execSimctl(['install_app_data', device, args.path], 'tool:installAppData');
+    return { content: [{ type: 'text', text: `App data installed from: ${args.path}` }] };
+}
+// --- get_env ---
+export const getEnvParams = {
+    variable: z.string().describe('Environment variable name to read (e.g., "HOME", "TMPDIR", "PATH")'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleGetEnv(args) {
+    const device = await resolveDevice(args.deviceId);
+    const { stdout } = await execSimctl(['getenv', device, args.variable], 'tool:getEnv');
+    return { content: [{ type: 'text', text: `${args.variable}=${stdout.trim()}` }] };
+}
+// --- simulate_memory_warning ---
+export const memoryWarningParams = {
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleMemoryWarning(args) {
+    const device = await resolveDevice(args.deviceId);
+    try {
+        // Trigger UIKit memory warning via notification
+        await execSimctl(['spawn', device, 'notifyutil', '-p', 'com.apple.UIKit.lowMemory'], 'tool:memoryWarning');
+        return { content: [{ type: 'text', text: 'Memory warning triggered. Apps will receive didReceiveMemoryWarning.' }] };
+    }
+    catch {
+        // Fallback: try via launchctl
+        try {
+            await execSimctl(['spawn', device, 'notifyutil', '-p', 'com.apple.system.memorystatus.level.warning'], 'tool:memoryWarning');
+            return { content: [{ type: 'text', text: 'Memory pressure warning triggered.' }] };
+        }
+        catch (err) {
+            const e = err;
+            return { content: [{ type: 'text', text: `Memory warning simulation failed: ${e.message}. Use Xcode Debug > Simulate Memory Warning as alternative.` }] };
+        }
+    }
+}
+// --- biometric_enrollment ---
+export const biometricParams = {
+    enrolled: z.boolean().describe('Whether Face ID / Touch ID is enrolled'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleBiometric(args) {
+    const device = await resolveDevice(args.deviceId);
+    // Use notifyutil to toggle biometric enrollment
+    try {
+        const val = args.enrolled ? '1' : '0';
+        await execSimctl(['spawn', device, 'notifyutil', '-s', 'com.apple.BiometricKit.enrollmentChanged', val], 'tool:biometric');
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Biometric enrollment set to ${args.enrolled ? 'enrolled' : 'not enrolled'}.`,
+                }],
+        };
+    }
+    catch (err) {
+        const e = err;
+        return { content: [{ type: 'text', text: `Biometric enrollment change failed: ${e.message}. Use Simulator > Features > Face ID/Touch ID menu.` }] };
+    }
+}
+// --- network_status (read/display network configuration) ---
+export const networkStatusParams = {
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleNetworkStatus(args) {
+    const device = await resolveDevice(args.deviceId);
+    const results = [];
+    // Get network info from host perspective (simulator shares host network)
+    try {
+        const { execFile: ef } = await import('node:child_process');
+        const { promisify: p } = await import('node:util');
+        const exec = p(ef);
+        const { stdout } = await exec('networksetup', ['-listallhardwareports'], { encoding: 'utf-8', timeout: 5000 });
+        const lines = stdout.split('\n').filter(l => l.includes('Hardware Port:') || l.includes('Device:'));
+        results.push('Host Network Ports:\n' + lines.join('\n'));
+    }
+    catch { /* skip */ }
+    // Check connectivity from inside simulator
+    try {
+        const { stdout } = await execSimctl(['spawn', device, 'nslookup', 'apple.com'], 'tool:networkStatus');
+        const serverLine = stdout.split('\n').find(l => l.includes('Server:'));
+        results.push('\nDNS Resolution: ' + (serverLine || 'working'));
+    }
+    catch {
+        results.push('\nDNS Resolution: failed (may be offline)');
+    }
+    // Get simulator's env for network-related vars
+    try {
+        const { stdout: home } = await execSimctl(['getenv', device, 'HOME'], 'tool:networkStatus');
+        results.push(`\nSimulator data path: ${home.trim()}`);
+    }
+    catch { /* skip */ }
+    return { content: [{ type: 'text', text: results.join('\n') || 'No network info available.' }] };
+}
+// --- defaults_read (read UserDefaults from inside simulator) ---
+export const defaultsReadParams = {
+    domain: z.string().describe('Defaults domain (bundle ID like "com.apple.mobilesafari" or "NSGlobalDomain")'),
+    key: z.string().optional().describe('Specific key to read (omit for all keys)'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleDefaultsRead(args) {
+    const device = await resolveDevice(args.deviceId);
+    const cmdArgs = ['spawn', device, 'defaults', 'read', args.domain];
+    if (args.key)
+        cmdArgs.push(args.key);
+    try {
+        const { stdout } = await execSimctl(cmdArgs, 'tool:defaultsRead');
+        return { content: [{ type: 'text', text: `${args.domain}${args.key ? '.' + args.key : ''}:\n${stdout.trim()}` }] };
+    }
+    catch (err) {
+        const e = err;
+        return { content: [{ type: 'text', text: `defaults read failed: ${e.message}` }] };
+    }
+}
+// --- defaults_write (write UserDefaults inside simulator) ---
+export const defaultsWriteParams = {
+    domain: z.string().describe('Defaults domain (bundle ID)'),
+    key: z.string().describe('Key to write'),
+    value: z.string().describe('Value to set'),
+    type: z.enum(['string', 'int', 'float', 'bool']).optional().describe('Value type (default: string)'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleDefaultsWrite(args) {
+    const device = await resolveDevice(args.deviceId);
+    const typeFlag = args.type === 'int' ? '-int' : args.type === 'float' ? '-float' : args.type === 'bool' ? '-bool' : '-string';
+    await execSimctl(['spawn', device, 'defaults', 'write', args.domain, args.key, typeFlag, args.value], 'tool:defaultsWrite');
+    return { content: [{ type: 'text', text: `Set ${args.domain}.${args.key} = ${args.value} (${args.type || 'string'})` }] };
+}