preflight-ios-mcp 1.0.0

package/dist/helpers/coordinate-mapper.js

@@ -0,0 +1,132 @@
+import { execSimctlBuffer, runAppleScript } from './simctl.js';
+import * as logger from './logger.js';
+const TITLE_BAR_HEIGHT = 28;
+/**
+ * Get the Simulator.app front window position and size using AppleScript.
+ */
+export async function getSimulatorWindowGeometry() {
+    const script = `
+tell application "System Events"
+  tell process "Simulator"
+    set frontWindow to front window
+    set winPos to position of frontWindow
+    set winSize to size of frontWindow
+    return (item 1 of winPos as text) & "," & (item 2 of winPos as text) & "," & (item 1 of winSize as text) & "," & (item 2 of winSize as text)
+  end tell
+end tell`;
+    const result = await runAppleScript(script, 'coordinate-mapper');
+    const parts = result.split(',').map(Number);
+    if (parts.length !== 4 || parts.some(isNaN)) {
+        throw new Error(`Failed to parse window geometry: "${result}"`);
+    }
+    const geometry = {
+        windowX: parts[0],
+        windowY: parts[1],
+        windowWidth: parts[2],
+        windowHeight: parts[3],
+    };
+    logger.debug('coordinate-mapper', 'Window geometry', geometry);
+    return geometry;
+}
+/**
+ * Get the device screen dimensions in points by taking a screenshot and reading its pixel dimensions.
+ * Returns { pointWidth, pointHeight, scaleFactor }.
+ */
+export async function getDeviceScreenDimensions(device) {
+    // Take a screenshot and get its pixel dimensions
+    const { stdout } = await execSimctlBuffer(['io', device, 'screenshot', '--type=png', '-'], 'coordinate-mapper');
+    // Parse PNG header to get dimensions (IHDR chunk at offset 16)
+    // PNG signature (8 bytes) + IHDR length (4 bytes) + "IHDR" (4 bytes) + width (4 bytes) + height (4 bytes)
+    if (stdout.length < 24) {
+        throw new Error('Screenshot too small to parse dimensions');
+    }
+    const pixelWidth = stdout.readUInt32BE(16);
+    const pixelHeight = stdout.readUInt32BE(20);
+    // Determine scale factor from known device resolutions
+    // Common: 3x for iPhones (Pro), 2x for iPads, 2x for older iPhones
+    let scaleFactor = 3; // default to 3x for modern iPhones
+    if (pixelWidth > 1500 && pixelHeight < 2000) {
+        scaleFactor = 2; // likely iPad
+    }
+    // Try to infer from common resolutions
+    const knownScales = {
+        // iPhone pixel widths → scale
+        '1179': 3, // iPhone 14/15/16 Pro
+        '1206': 3, // iPhone 15/16 Pro Max
+        '1170': 3, // iPhone 14/15/16
+        '1290': 3, // iPhone 14/15/16 Pro Max
+        '750': 2, // iPhone SE
+        '828': 2, // iPhone 11
+        // iPad pixel widths → scale
+        '2048': 2, // iPad Air/Pro 10.5"
+        '2224': 2, // iPad Pro 11"
+        '2388': 2, // iPad Pro 11" M-series
+        '2732': 2, // iPad Pro 12.9"
+    };
+    const widthStr = String(pixelWidth);
+    if (knownScales[widthStr]) {
+        scaleFactor = knownScales[widthStr];
+    }
+    const pointWidth = Math.round(pixelWidth / scaleFactor);
+    const pointHeight = Math.round(pixelHeight / scaleFactor);
+    logger.debug('coordinate-mapper', 'Device screen dimensions', {
+        pixelWidth,
+        pixelHeight,
+        scaleFactor,
+        pointWidth,
+        pointHeight,
+    });
+    return { pointWidth, pointHeight, scaleFactor, pixelWidth, pixelHeight };
+}
+// Cache screen mapping for 10 seconds to avoid repeated AppleScript + screenshot calls
+let cachedMapping = null;
+let cachedMappingTime = 0;
+const CACHE_TTL_MS = 10000;
+/**
+ * Compute the full screen mapping from simulator points to macOS screen coordinates.
+ * Cached for 10 seconds to improve performance during rapid interactions.
+ */
+export async function getScreenMapping(device) {
+    const now = Date.now();
+    if (cachedMapping && (now - cachedMappingTime) < CACHE_TTL_MS) {
+        logger.debug('coordinate-mapper', 'Using cached screen mapping');
+        return cachedMapping;
+    }
+    const [windowGeometry, screenDims] = await Promise.all([
+        getSimulatorWindowGeometry(),
+        getDeviceScreenDimensions(device),
+    ]);
+    const contentWidth = windowGeometry.windowWidth;
+    const contentHeight = windowGeometry.windowHeight - TITLE_BAR_HEIGHT;
+    const scaleX = contentWidth / screenDims.pointWidth;
+    const scaleY = contentHeight / screenDims.pointHeight;
+    const mapping = {
+        windowGeometry,
+        devicePointWidth: screenDims.pointWidth,
+        devicePointHeight: screenDims.pointHeight,
+        scaleFactor: screenDims.scaleFactor,
+        titleBarHeight: TITLE_BAR_HEIGHT,
+        contentWidth,
+        contentHeight,
+        scaleX,
+        scaleY,
+    };
+    logger.debug('coordinate-mapper', 'Screen mapping computed', mapping);
+    cachedMapping = mapping;
+    cachedMappingTime = Date.now();
+    return mapping;
+}
+/**
+ * Convert simulator screen point coordinates to macOS absolute screen coordinates.
+ */
+export function simToMac(simX, simY, mapping) {
+    const macX = mapping.windowGeometry.windowX + simX * mapping.scaleX;
+    const macY = mapping.windowGeometry.windowY +
+        mapping.titleBarHeight +
+        simY * mapping.scaleY;
+    logger.debug('coordinate-mapper', `Mapped sim(${simX},${simY}) → mac(${Math.round(macX)},${Math.round(macY)})`, {
+        scaleX: mapping.scaleX.toFixed(3),
+        scaleY: mapping.scaleY.toFixed(3),
+    });
+    return { macX, macY };
+}

package/dist/helpers/idb.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Check if idb CLI is installed and available.
+ * Checks PATH via `which`, then searches common install locations.
+ * Caches the result for the lifetime of the server process.
+ */
+export declare function checkIdbAvailable(): Promise<boolean>;
+/**
+ * Tap at simulator screen coordinates using idb.
+ * No macOS coordinate mapping needed — idb uses sim points directly.
+ */
+export declare function idbTap(x: number, y: number, deviceId: string, duration?: number): Promise<void>;
+/**
+ * Swipe between two points using idb.
+ * idb takes duration in fractional seconds.
+ */
+export declare function idbSwipe(startX: number, startY: number, endX: number, endY: number, durationMs: number, deviceId: string, delta?: number): Promise<void>;
+/**
+ * Long press at simulator screen coordinates using idb.
+ * idb uses `tap --duration` for long presses (no separate long-press command).
+ */
+export declare function idbLongPress(x: number, y: number, durationMs: number, deviceId: string): Promise<void>;
+/**
+ * Get the full iOS accessibility tree via idb.
+ * Returns actual iOS UI elements (UIButton, UILabel, etc.) with labels, frames, and enabled state.
+ */
+export declare function idbDescribeAll(deviceId: string): Promise<string>;
+/**
+ * Describe the iOS UI element at a specific point.
+ */
+export declare function idbDescribePoint(x: number, y: number, deviceId: string): Promise<string>;

package/dist/helpers/idb.js

@@ -0,0 +1,169 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { listDevices } from './simctl.js';
+import * as logger from './logger.js';
+const execFileAsync = promisify(execFile);
+// Module-level cache for idb availability
+let idbAvailable = null;
+let idbPath = null;
+// Common install locations for idb (pip3 installs to user bin)
+const IDB_SEARCH_PATHS = [
+    '/opt/homebrew/bin/idb',
+    '/usr/local/bin/idb',
+    `${process.env.HOME}/Library/Python/3.9/bin/idb`,
+    `${process.env.HOME}/Library/Python/3.10/bin/idb`,
+    `${process.env.HOME}/Library/Python/3.11/bin/idb`,
+    `${process.env.HOME}/Library/Python/3.12/bin/idb`,
+    `${process.env.HOME}/Library/Python/3.13/bin/idb`,
+    `${process.env.HOME}/.local/bin/idb`,
+];
+/**
+ * Check if idb CLI is installed and available.
+ * Checks PATH via `which`, then searches common install locations.
+ * Caches the result for the lifetime of the server process.
+ */
+export async function checkIdbAvailable() {
+    if (idbAvailable !== null)
+        return idbAvailable;
+    // Check env var first (custom idb path)
+    const envPath = process.env.PREFLIGHT_IDB_PATH || process.env.IOS_SIMULATOR_MCP_IDB_PATH;
+    if (envPath) {
+        const { access } = await import('node:fs/promises');
+        try {
+            await access(envPath);
+            idbPath = envPath;
+            idbAvailable = true;
+            logger.debug('idb', `idb found via env var: ${idbPath}`);
+            return true;
+        }
+        catch {
+            logger.warn('idb', `idb path from env var not found: ${envPath}`);
+        }
+    }
+    // Try `which idb` (respects PATH)
+    try {
+        const { stdout } = await execFileAsync('which', ['idb'], {
+            encoding: 'utf-8',
+            timeout: 5000,
+        });
+        const found = stdout.trim();
+        if (found) {
+            idbPath = found;
+            idbAvailable = true;
+            logger.debug('idb', `idb found via PATH: ${idbPath}`);
+            return true;
+        }
+    }
+    catch { /* not in PATH */ }
+    // Search common install locations
+    const { access } = await import('node:fs/promises');
+    for (const candidate of IDB_SEARCH_PATHS) {
+        try {
+            await access(candidate);
+            idbPath = candidate;
+            idbAvailable = true;
+            logger.debug('idb', `idb found at: ${idbPath}`);
+            return true;
+        }
+        catch { /* not here */ }
+    }
+    idbAvailable = false;
+    logger.debug('idb', 'idb not found in PATH or common locations');
+    return false;
+}
+/**
+ * Resolve a device identifier to an actual UDID.
+ * idb requires real UDIDs — it doesn't support "booted".
+ */
+async function resolveUdid(deviceId) {
+    if (deviceId === 'booted') {
+        const booted = await listDevices('booted');
+        if (booted.length === 0) {
+            throw new Error('No booted simulator found');
+        }
+        return booted[0].udid;
+    }
+    return deviceId;
+}
+/**
+ * Execute an idb command. Throws on failure.
+ */
+async function runIdb(args, ctx) {
+    const cmd = idbPath || 'idb';
+    logger.debug(ctx, `Running: idb ${args.join(' ')}`);
+    try {
+        const result = await execFileAsync(cmd, args, {
+            maxBuffer: 10 * 1024 * 1024,
+            encoding: 'utf-8',
+            timeout: 30000,
+        });
+        return result.stdout;
+    }
+    catch (err) {
+        const e = err;
+        logger.error(ctx, `idb failed: ${e.stderr || e.message}`);
+        throw new Error(`idb ${args[0]} failed: ${e.stderr || e.message}`);
+    }
+}
+/**
+ * Tap at simulator screen coordinates using idb.
+ * No macOS coordinate mapping needed — idb uses sim points directly.
+ */
+export async function idbTap(x, y, deviceId, duration) {
+    const udid = await resolveUdid(deviceId);
+    const args = ['ui', 'tap', '--udid', udid, String(Math.round(x)), String(Math.round(y))];
+    if (duration !== undefined)
+        args.push('--duration', String(duration));
+    await runIdb(args, 'idb:tap');
+}
+/**
+ * Swipe between two points using idb.
+ * idb takes duration in fractional seconds.
+ */
+export async function idbSwipe(startX, startY, endX, endY, durationMs, deviceId, delta) {
+    const udid = await resolveUdid(deviceId);
+    const durationSec = (durationMs / 1000).toFixed(2);
+    const args = [
+        'ui', 'swipe',
+        '--udid', udid,
+        String(Math.round(startX)), String(Math.round(startY)),
+        String(Math.round(endX)), String(Math.round(endY)),
+        '--duration', durationSec,
+    ];
+    if (delta !== undefined)
+        args.push('--delta', String(delta));
+    await runIdb(args, 'idb:swipe');
+}
+/**
+ * Long press at simulator screen coordinates using idb.
+ * idb uses `tap --duration` for long presses (no separate long-press command).
+ */
+export async function idbLongPress(x, y, durationMs, deviceId) {
+    const udid = await resolveUdid(deviceId);
+    const durationSec = (durationMs / 1000).toFixed(2);
+    await runIdb([
+        'ui', 'tap',
+        '--udid', udid,
+        '--duration', durationSec,
+        String(Math.round(x)), String(Math.round(y)),
+    ], 'idb:longPress');
+}
+/**
+ * Get the full iOS accessibility tree via idb.
+ * Returns actual iOS UI elements (UIButton, UILabel, etc.) with labels, frames, and enabled state.
+ */
+export async function idbDescribeAll(deviceId) {
+    const udid = await resolveUdid(deviceId);
+    return await runIdb(['ui', 'describe-all', '--udid', udid], 'idb:describeAll');
+}
+/**
+ * Describe the iOS UI element at a specific point.
+ */
+export async function idbDescribePoint(x, y, deviceId) {
+    const udid = await resolveUdid(deviceId);
+    return await runIdb([
+        'ui', 'describe-point',
+        '--udid', udid,
+        String(Math.round(x)), String(Math.round(y)),
+    ], 'idb:describePoint');
+}

package/dist/helpers/logger.d.ts

@@ -0,0 +1,9 @@
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare function log(level: LogLevel, context: string, message: string, data?: unknown): void;
+export declare function debug(context: string, message: string, data?: unknown): void;
+export declare function info(context: string, message: string, data?: unknown): void;
+export declare function warn(context: string, message: string, data?: unknown): void;
+export declare function error(context: string, message: string, data?: unknown): void;
+export declare function toolStart(toolName: string, params: unknown): void;
+export declare function toolEnd(toolName: string, durationMs: number, success: boolean): void;
+export {};

package/dist/helpers/logger.js

@@ -0,0 +1,47 @@
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+const currentLevel = process.env.LOG_LEVEL || 'info';
+function shouldLog(level) {
+    return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+function formatMessage(level, context, message) {
+    const timestamp = new Date().toISOString();
+    return `[${timestamp}] [${level.toUpperCase()}] [${context}] ${message}`;
+}
+export function log(level, context, message, data) {
+    if (!shouldLog(level))
+        return;
+    let line = formatMessage(level, context, message);
+    if (data !== undefined) {
+        try {
+            line += ' ' + JSON.stringify(data);
+        }
+        catch {
+            line += ' [unserializable data]';
+        }
+    }
+    process.stderr.write(line + '\n');
+}
+export function debug(context, message, data) {
+    log('debug', context, message, data);
+}
+export function info(context, message, data) {
+    log('info', context, message, data);
+}
+export function warn(context, message, data) {
+    log('warn', context, message, data);
+}
+export function error(context, message, data) {
+    log('error', context, message, data);
+}
+export function toolStart(toolName, params) {
+    debug(`tool:${toolName}`, 'Invoked', params);
+}
+export function toolEnd(toolName, durationMs, success) {
+    const level = success ? 'debug' : 'error';
+    log(level, `tool:${toolName}`, `Completed in ${durationMs}ms, success=${success}`);
+}

package/dist/helpers/simctl.d.ts

@@ -0,0 +1,47 @@
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+}
+export interface ExecBufferResult {
+    stdout: Buffer;
+    stderr: Buffer;
+}
+export interface SimDevice {
+    name: string;
+    udid: string;
+    state: string;
+    runtime: string;
+    isAvailable: boolean;
+    deviceTypeIdentifier?: string;
+}
+/**
+ * Execute an xcrun simctl command and return stdout/stderr as strings.
+ */
+export declare function execSimctl(args: string[], ctx?: string): Promise<ExecResult>;
+/**
+ * Execute an xcrun simctl command and return stdout as a Buffer (for binary data like screenshots).
+ */
+export declare function execSimctlBuffer(args: string[], ctx?: string): Promise<ExecBufferResult>;
+/**
+ * Execute an arbitrary command (not simctl).
+ */
+export declare function execCommand(command: string, args: string[], ctx?: string): Promise<ExecResult>;
+/**
+ * List all simulator devices. Optionally filter by state.
+ */
+export declare function listDevices(filter?: 'booted' | 'available' | 'all'): Promise<SimDevice[]>;
+/**
+ * Resolve a device identifier to a UDID. Accepts:
+ * - undefined / "booted" → "booted" (with validation)
+ * - A UDID string → returned as-is
+ * - A device name → resolved to UDID
+ */
+export declare function resolveDevice(deviceId?: string): Promise<string>;
+/**
+ * Run osascript (AppleScript) and return stdout.
+ */
+export declare function runAppleScript(script: string, ctx?: string): Promise<string>;
+/**
+ * Run osascript with the ObjC bridge (for CGEvents).
+ */
+export declare function runJXA(script: string, ctx?: string): Promise<string>;

package/dist/helpers/simctl.js

@@ -0,0 +1,174 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import * as logger from './logger.js';
+const execFileAsync = promisify(execFile);
+/**
+ * Execute an xcrun simctl command and return stdout/stderr as strings.
+ */
+export async function execSimctl(args, ctx = 'simctl') {
+    const cmd = ['simctl', ...args];
+    logger.debug(ctx, `Running: xcrun ${cmd.join(' ')}`);
+    try {
+        const result = await execFileAsync('xcrun', cmd, {
+            maxBuffer: 50 * 1024 * 1024,
+            encoding: 'utf-8',
+        });
+        logger.debug(ctx, `Exit code: 0, stdout=${result.stdout.length}b, stderr=${result.stderr.length}b`);
+        return result;
+    }
+    catch (err) {
+        const e = err;
+        logger.error(ctx, `Command failed: xcrun ${cmd.join(' ')}`, {
+            code: e.code,
+            stderr: e.stderr?.slice(0, 500),
+        });
+        throw new Error(`simctl ${args[0]} failed: ${e.stderr || e.message || 'unknown error'}`);
+    }
+}
+/**
+ * Execute an xcrun simctl command and return stdout as a Buffer (for binary data like screenshots).
+ */
+export async function execSimctlBuffer(args, ctx = 'simctl') {
+    const cmd = ['simctl', ...args];
+    logger.debug(ctx, `Running (buffer): xcrun ${cmd.join(' ')}`);
+    try {
+        const result = await execFileAsync('xcrun', cmd, {
+            maxBuffer: 50 * 1024 * 1024,
+            encoding: 'buffer',
+        });
+        logger.debug(ctx, `Exit code: 0, stdout=${result.stdout.length}b`);
+        return result;
+    }
+    catch (err) {
+        const e = err;
+        const stderrStr = e.stderr ? e.stderr.toString('utf-8').slice(0, 500) : '';
+        logger.error(ctx, `Command failed: xcrun ${cmd.join(' ')}`, {
+            code: e.code,
+            stderr: stderrStr,
+        });
+        throw new Error(`simctl ${args[0]} failed: ${stderrStr || e.message || 'unknown error'}`);
+    }
+}
+/**
+ * Execute an arbitrary command (not simctl).
+ */
+export async function execCommand(command, args, ctx = 'exec') {
+    logger.debug(ctx, `Running: ${command} ${args.join(' ')}`);
+    try {
+        const result = await execFileAsync(command, args, {
+            maxBuffer: 50 * 1024 * 1024,
+            encoding: 'utf-8',
+        });
+        return result;
+    }
+    catch (err) {
+        const e = err;
+        logger.error(ctx, `Command failed: ${command} ${args.join(' ')}`, {
+            code: e.code,
+            stderr: e.stderr?.slice(0, 500),
+        });
+        throw new Error(`${command} failed: ${e.stderr || e.message || 'unknown error'}`);
+    }
+}
+/**
+ * List all simulator devices. Optionally filter by state.
+ */
+export async function listDevices(filter) {
+    const { stdout } = await execSimctl(['list', '-j', 'devices'], 'listDevices');
+    const data = JSON.parse(stdout);
+    const devices = [];
+    for (const [runtime, devs] of Object.entries(data.devices)) {
+        for (const dev of devs) {
+            devices.push({
+                name: dev.name,
+                udid: dev.udid,
+                state: dev.state,
+                runtime,
+                isAvailable: dev.isAvailable ?? false,
+                deviceTypeIdentifier: dev.deviceTypeIdentifier,
+            });
+        }
+    }
+    if (filter === 'booted')
+        return devices.filter(d => d.state === 'Booted');
+    if (filter === 'available')
+        return devices.filter(d => d.isAvailable);
+    return devices;
+}
+/**
+ * Resolve a device identifier to a UDID. Accepts:
+ * - undefined / "booted" → "booted" (with validation)
+ * - A UDID string → returned as-is
+ * - A device name → resolved to UDID
+ */
+export async function resolveDevice(deviceId) {
+    if (!deviceId || deviceId === 'booted') {
+        const booted = await listDevices('booted');
+        if (booted.length === 0) {
+            const available = await listDevices('available');
+            const suggestions = available
+                .filter(d => d.runtime.includes('iOS'))
+                .slice(0, 5)
+                .map(d => `  - ${d.name} (${d.udid})`)
+                .join('\n');
+            throw new Error(`No simulator is currently booted. Use simulator_boot to start one.\n\nAvailable iOS devices:\n${suggestions}`);
+        }
+        return 'booted';
+    }
+    // Check if it's a UDID pattern
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(deviceId)) {
+        return deviceId;
+    }
+    // Try name match
+    const devices = await listDevices();
+    const match = devices.find(d => d.name.toLowerCase() === deviceId.toLowerCase());
+    if (match)
+        return match.udid;
+    throw new Error(`Device "${deviceId}" not found. Use simulator_list_devices to see available devices.`);
+}
+/**
+ * Run osascript (AppleScript) and return stdout.
+ */
+export async function runAppleScript(script, ctx = 'applescript') {
+    logger.debug(ctx, 'Executing AppleScript', { scriptLength: script.length });
+    try {
+        const result = await execFileAsync('osascript', ['-e', script], {
+            maxBuffer: 10 * 1024 * 1024,
+            encoding: 'utf-8',
+            timeout: 15000,
+        });
+        return result.stdout.trim();
+    }
+    catch (err) {
+        const e = err;
+        const stderr = e.stderr || '';
+        if (stderr.includes('not allowed') || stderr.includes('accessibility')) {
+            throw new Error('Accessibility permission required. Go to System Settings → Privacy & Security → Accessibility and add your terminal app.');
+        }
+        logger.error(ctx, 'AppleScript failed', { stderr, script: script.slice(0, 200) });
+        throw new Error(`AppleScript failed: ${stderr || e.message}`);
+    }
+}
+/**
+ * Run osascript with the ObjC bridge (for CGEvents).
+ */
+export async function runJXA(script, ctx = 'jxa') {
+    logger.debug(ctx, 'Executing JXA script', { scriptLength: script.length });
+    try {
+        const result = await execFileAsync('osascript', ['-l', 'JavaScript', '-e', script], {
+            maxBuffer: 10 * 1024 * 1024,
+            encoding: 'utf-8',
+            timeout: 15000,
+        });
+        return result.stdout.trim();
+    }
+    catch (err) {
+        const e = err;
+        const stderr = e.stderr || '';
+        if (stderr.includes('not allowed') || stderr.includes('accessibility')) {
+            throw new Error('Accessibility permission required. Go to System Settings → Privacy & Security → Accessibility and add your terminal app.');
+        }
+        logger.error(ctx, 'JXA script failed', { stderr });
+        throw new Error(`JXA script failed: ${stderr || e.message}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};