preflight-ios-mcp 1.0.0

package/dist/tools/screenshot.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { execSimctlBuffer, resolveDevice } from '../helpers/simctl.js';
+import * as logger from '../helpers/logger.js';
+import { writeFile, mkdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+// Optimized for AI chat: small images that fit in context windows
+// Target ~200-400KB JPEG — enough detail for UI analysis, minimal token waste
+const MAX_BYTES = 1.5 * 1024 * 1024; // 1.5MB absolute cap
+export const screenshotParams = {
+    deviceId: z.string().optional().describe('Device UDID, name, or "booted" (default: booted)'),
+    format: z.enum(['png', 'jpeg']).optional().describe('Image format (default: jpeg). JPEG recommended for AI — smaller, faster.'),
+    display: z.enum(['internal', 'external']).optional().describe('Display to capture (default: internal)'),
+    mask: z.enum(['ignored', 'alpha', 'black']).optional().describe('For non-rectangular displays, handle mask by policy'),
+    savePath: z.string().optional().describe('Optional: save a copy to this path on disk'),
+};
+/**
+ * Compress a PNG buffer to JPEG using sips, optimized for AI chat.
+ * Targets ~200-400KB — enough for UI analysis without wasting tokens.
+ */
+async function compressToJpeg(pngBuffer) {
+    const tmpPng = join(tmpdir(), `simscr-${Date.now()}.png`);
+    const tmpJpg = join(tmpdir(), `simscr-${Date.now()}.jpg`);
+    try {
+        await writeFile(tmpPng, pngBuffer);
+        // First pass: quality 60 (good for AI analysis, small file)
+        await execFileAsync('sips', ['-s', 'format', 'jpeg', '-s', 'formatOptions', '60', tmpPng, '--out', tmpJpg], { timeout: 10000 });
+        const { readFile: rf } = await import('node:fs/promises');
+        let jpgBuffer = await rf(tmpJpg);
+        // If still too large, compress harder
+        if (jpgBuffer.length > MAX_BYTES) {
+            await execFileAsync('sips', ['-s', 'format', 'jpeg', '-s', 'formatOptions', '35', tmpPng, '--out', tmpJpg], { timeout: 10000 });
+            jpgBuffer = await rf(tmpJpg);
+        }
+        return jpgBuffer;
+    }
+    catch (err) {
+        logger.debug('tool:screenshot', `JPEG compression failed: ${err.message}`);
+        return pngBuffer;
+    }
+    finally {
+        await unlink(tmpPng).catch(() => { });
+        await unlink(tmpJpg).catch(() => { });
+    }
+}
+export async function handleScreenshot(args) {
+    const device = await resolveDevice(args.deviceId);
+    const requestedFormat = args.format || 'jpeg';
+    // Capture PNG from simctl (always start with PNG for best quality source)
+    const simctlArgs = ['io', device, 'screenshot', '--type=png'];
+    if (args.display)
+        simctlArgs.push(`--display=${args.display}`);
+    if (args.mask)
+        simctlArgs.push(`--mask=${args.mask}`);
+    simctlArgs.push('-');
+    const { stdout: pngBuffer } = await execSimctlBuffer(simctlArgs, 'tool:screenshot');
+    let outputBuffer;
+    let mimeType;
+    let format;
+    if (requestedFormat === 'jpeg') {
+        outputBuffer = await compressToJpeg(pngBuffer);
+        mimeType = 'image/jpeg';
+        format = 'jpeg';
+    }
+    else {
+        outputBuffer = pngBuffer;
+        mimeType = 'image/png';
+        format = 'png';
+    }
+    // Only save to disk if explicitly requested
+    let savedPath = '';
+    if (args.savePath) {
+        try {
+            const dir = args.savePath.substring(0, args.savePath.lastIndexOf('/'));
+            if (dir)
+                await mkdir(dir, { recursive: true });
+            await writeFile(args.savePath, outputBuffer);
+            savedPath = args.savePath;
+        }
+        catch (err) {
+            logger.debug('tool:screenshot', `Failed to save to ${args.savePath}: ${err.message}`);
+        }
+    }
+    const base64Data = outputBuffer.toString('base64');
+    return {
+        content: [
+            { type: 'image', data: base64Data, mimeType },
+            {
+                type: 'text',
+                text: `Screenshot captured (${format}, ${Math.round(outputBuffer.length / 1024)}KB)${savedPath ? `\nSaved to: ${savedPath}` : ''}`,
+            },
+        ],
+    };
+}

package/dist/tools/system.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+export declare const setLocationParams: {
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleSetLocation(args: {
+    latitude: number;
+    longitude: number;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const sendPushParams: {
+    bundleId: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodAny>;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleSendPush(args: {
+    bundleId: string;
+    payload: Record<string, unknown>;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const setClipboardParams: {
+    text: z.ZodString;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleSetClipboard(args: {
+    text: string;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const getClipboardParams: {
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleGetClipboard(args: {
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const addMediaParams: {
+    filePaths: z.ZodArray<z.ZodString, "many">;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleAddMedia(args: {
+    filePaths: string[];
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const grantPermissionParams: {
+    bundleId: z.ZodString;
+    service: z.ZodString;
+    action: z.ZodEnum<["grant", "revoke", "reset"]>;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleGrantPermission(args: {
+    bundleId: string;
+    service: string;
+    action: 'grant' | 'revoke' | 'reset';
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/system.js

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+import { execSimctl, resolveDevice } from '../helpers/simctl.js';
+import { spawn } from 'node:child_process';
+// --- set_location ---
+export const setLocationParams = {
+    latitude: z.number().min(-90).max(90).describe('Latitude (-90 to 90)'),
+    longitude: z.number().min(-180).max(180).describe('Longitude (-180 to 180)'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleSetLocation(args) {
+    const device = await resolveDevice(args.deviceId);
+    await execSimctl(['location', device, 'set', `${args.latitude},${args.longitude}`], 'tool:setLocation');
+    return { content: [{ type: 'text', text: `Location set to ${args.latitude}, ${args.longitude}` }] };
+}
+// --- send_push ---
+export const sendPushParams = {
+    bundleId: z.string().describe('App bundle ID to receive the push'),
+    payload: z.record(z.any()).describe('Push notification JSON payload (e.g., {"aps": {"alert": "Hello"}})'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleSendPush(args) {
+    const device = await resolveDevice(args.deviceId);
+    const payloadJson = JSON.stringify(args.payload);
+    // Write payload to stdin of simctl push
+    const child = spawn('xcrun', [
+        'simctl', 'push', device, args.bundleId, '-',
+    ]);
+    return new Promise((resolve, reject) => {
+        let stderr = '';
+        child.stderr.on('data', (data) => { stderr += data.toString(); });
+        child.on('error', (err) => reject(new Error(`Push spawn failed: ${err.message}`)));
+        child.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`Push failed: ${stderr}`));
+            }
+            else {
+                resolve({ content: [{ type: 'text', text: `Push notification sent to ${args.bundleId}` }] });
+            }
+        });
+        child.stdin.on('error', () => { }); // prevent EPIPE crash
+        child.stdin.write(payloadJson);
+        child.stdin.end();
+    });
+}
+// --- set_clipboard ---
+export const setClipboardParams = {
+    text: z.string().describe('Text to copy to simulator clipboard'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleSetClipboard(args) {
+    const device = await resolveDevice(args.deviceId);
+    const child = spawn('xcrun', [
+        'simctl', 'pbcopy', device,
+    ]);
+    return new Promise((resolve, reject) => {
+        let stderr = '';
+        child.stderr.on('data', (data) => { stderr += data.toString(); });
+        child.on('error', (err) => reject(new Error(`pbcopy spawn failed: ${err.message}`)));
+        child.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`pbcopy failed: ${stderr}`));
+            }
+            else {
+                resolve({ content: [{ type: 'text', text: `Clipboard set (${args.text.length} chars)` }] });
+            }
+        });
+        child.stdin.on('error', () => { }); // prevent EPIPE crash
+        child.stdin.write(args.text);
+        child.stdin.end();
+    });
+}
+// --- get_clipboard ---
+export const getClipboardParams = {
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleGetClipboard(args) {
+    const device = await resolveDevice(args.deviceId);
+    const { stdout } = await execSimctl(['pbpaste', device], 'tool:getClipboard');
+    return { content: [{ type: 'text', text: stdout || '(clipboard is empty)' }] };
+}
+// --- add_media ---
+export const addMediaParams = {
+    filePaths: z.array(z.string()).describe('Paths to photo/video files to add to camera roll'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleAddMedia(args) {
+    const device = await resolveDevice(args.deviceId);
+    await execSimctl(['addmedia', device, ...args.filePaths], 'tool:addMedia');
+    return { content: [{ type: 'text', text: `Added ${args.filePaths.length} media file(s) to camera roll.` }] };
+}
+// --- grant_permission ---
+export const grantPermissionParams = {
+    bundleId: z.string().describe('App bundle ID'),
+    service: z.string().describe('Permission service: all, calendar, contacts-limited, contacts, location, location-always, photos-add, photos, media-library, microphone, motion, reminders, siri'),
+    action: z.enum(['grant', 'revoke', 'reset']).describe('Permission action'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleGrantPermission(args) {
+    const device = await resolveDevice(args.deviceId);
+    await execSimctl(['privacy', device, args.action, args.service, args.bundleId], 'tool:grantPermission');
+    return {
+        content: [{
+                type: 'text',
+                text: `${args.action === 'grant' ? 'Granted' : args.action === 'revoke' ? 'Revoked' : 'Reset'} ${args.service} permission for ${args.bundleId}`,
+            }],
+    };
+}

package/dist/tools/ui.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+export declare const setAppearanceParams: {
+    mode: z.ZodEnum<["light", "dark"]>;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleSetAppearance(args: {
+    mode: 'light' | 'dark';
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const overrideStatusBarParams: {
+    time: z.ZodOptional<z.ZodString>;
+    batteryLevel: z.ZodOptional<z.ZodNumber>;
+    batteryState: z.ZodOptional<z.ZodEnum<["charging", "charged", "discharging"]>>;
+    cellularBars: z.ZodOptional<z.ZodNumber>;
+    wifiBars: z.ZodOptional<z.ZodNumber>;
+    networkType: z.ZodOptional<z.ZodString>;
+    operatorName: z.ZodOptional<z.ZodString>;
+    clear: z.ZodOptional<z.ZodBoolean>;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleOverrideStatusBar(args: {
+    time?: string;
+    batteryLevel?: number;
+    batteryState?: string;
+    cellularBars?: number;
+    wifiBars?: number;
+    networkType?: string;
+    operatorName?: string;
+    clear?: boolean;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const recordVideoParams: {
+    codec: z.ZodOptional<z.ZodEnum<["h264", "hevc"]>>;
+    display: z.ZodOptional<z.ZodEnum<["internal", "external"]>>;
+    mask: z.ZodOptional<z.ZodEnum<["ignored", "alpha", "black"]>>;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleRecordVideo(args: {
+    codec?: string;
+    display?: string;
+    mask?: string;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const stopRecordingParams: {
+    savePath: z.ZodOptional<z.ZodString>;
+    maxFrames: z.ZodOptional<z.ZodNumber>;
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleStopRecording(args: {
+    savePath?: string;
+    maxFrames?: number;
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text" | "image";
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }[];
+}>;
+export declare const navigateBackParams: {
+    deviceId: z.ZodOptional<z.ZodString>;
+};
+export declare function handleNavigateBack(args: {
+    deviceId?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/ui.js

@@ -0,0 +1,245 @@
+import { z } from 'zod';
+import { execSimctl, execSimctlBuffer, resolveDevice } from '../helpers/simctl.js';
+import * as logger from '../helpers/logger.js';
+import { spawn, execFile } from 'node:child_process';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { mkdir, writeFile, unlink, readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+// Active video recording state
+const activeRecordings = new Map();
+// --- set_appearance ---
+export const setAppearanceParams = {
+    mode: z.enum(['light', 'dark']).describe('Appearance mode'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleSetAppearance(args) {
+    const device = await resolveDevice(args.deviceId);
+    await execSimctl(['ui', device, 'appearance', args.mode], 'tool:setAppearance');
+    return { content: [{ type: 'text', text: `Appearance set to ${args.mode} mode.` }] };
+}
+// --- override_status_bar ---
+export const overrideStatusBarParams = {
+    time: z.string().optional().describe('Status bar time string (e.g., "9:41")'),
+    batteryLevel: z.number().optional().describe('Battery level 0-100'),
+    batteryState: z.enum(['charging', 'charged', 'discharging']).optional().describe('Battery state'),
+    cellularBars: z.number().optional().describe('Cellular signal bars 0-4'),
+    wifiBars: z.number().optional().describe('WiFi signal bars 0-3'),
+    networkType: z.string().optional().describe('Data network type: wifi, 3g, 4g, lte, lte-a, lte+, 5g, 5g+, 5g-uwb, 5g-uc'),
+    operatorName: z.string().optional().describe('Carrier/operator name'),
+    clear: z.boolean().optional().describe('Set to true to clear all overrides'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleOverrideStatusBar(args) {
+    const device = await resolveDevice(args.deviceId);
+    if (args.clear) {
+        await execSimctl(['status_bar', device, 'clear'], 'tool:statusBar');
+        return { content: [{ type: 'text', text: 'Status bar overrides cleared.' }] };
+    }
+    const flags = [];
+    if (args.time)
+        flags.push('--time', args.time);
+    if (args.batteryLevel !== undefined)
+        flags.push('--batteryLevel', String(args.batteryLevel));
+    if (args.batteryState)
+        flags.push('--batteryState', args.batteryState);
+    if (args.cellularBars !== undefined)
+        flags.push('--cellularBars', String(args.cellularBars));
+    if (args.wifiBars !== undefined)
+        flags.push('--wifiBars', String(args.wifiBars));
+    if (args.networkType)
+        flags.push('--dataNetwork', args.networkType);
+    if (args.operatorName)
+        flags.push('--operatorName', args.operatorName);
+    if (flags.length === 0) {
+        return { content: [{ type: 'text', text: 'No overrides specified. Provide at least one parameter or set clear=true.' }] };
+    }
+    await execSimctl(['status_bar', device, 'override', ...flags], 'tool:statusBar');
+    return {
+        content: [{
+                type: 'text',
+                text: `Status bar overrides applied: ${flags.filter((_, i) => i % 2 === 0).map(f => f.replace('--', '')).join(', ')}`,
+            }],
+    };
+}
+// --- record_video ---
+// Records to a temp file. On stop, extracts key frames and returns them as images
+// directly in chat. No permanent disk clutter. Most AI models can't view video files
+// so key frames are much more useful.
+export const recordVideoParams = {
+    codec: z.enum(['h264', 'hevc']).optional().describe('Video codec (default: h264)'),
+    display: z.enum(['internal', 'external']).optional().describe('Display to capture (default: internal)'),
+    mask: z.enum(['ignored', 'alpha', 'black']).optional().describe('For non-rectangular displays, handle mask by policy'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleRecordVideo(args) {
+    const device = await resolveDevice(args.deviceId);
+    const codec = args.codec || 'h264';
+    if (activeRecordings.has(device)) {
+        return { content: [{ type: 'text', text: 'A recording is already in progress. Use simulator_stop_recording to stop it first.' }] };
+    }
+    // Record to temp file — will be cleaned up after frame extraction
+    const tmpPath = join(tmpdir(), `preflight-rec-${Date.now()}.mp4`);
+    const cmdArgs = ['simctl', 'io', device, 'recordVideo', '--codec', codec];
+    if (args.display)
+        cmdArgs.push(`--display=${args.display}`);
+    if (args.mask)
+        cmdArgs.push(`--mask=${args.mask}`);
+    cmdArgs.push('--force', tmpPath);
+    const child = spawn('xcrun', cmdArgs, { stdio: ['pipe', 'pipe', 'pipe'] });
+    activeRecordings.set(device, { process: child, tmpPath, startTime: Date.now() });
+    child.on('exit', () => { activeRecordings.delete(device); });
+    child.on('error', (err) => {
+        logger.error('tool:recordVideo', `Recording process error: ${err.message}`);
+        activeRecordings.delete(device);
+    });
+    return {
+        content: [{
+                type: 'text',
+                text: `Video recording started (${codec}). Use simulator_stop_recording to stop and get key frames.`,
+            }],
+    };
+}
+// --- stop_recording ---
+// Stops recording, extracts key frames as JPEG images, returns them inline.
+// Cleans up the temp video file. No disk clutter.
+export const stopRecordingParams = {
+    savePath: z.string().optional().describe('Optional: save the video file to this path instead of discarding it'),
+    maxFrames: z.number().optional().describe('Max number of key frames to extract (default: 3, max: 6)'),
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleStopRecording(args) {
+    const device = await resolveDevice(args.deviceId);
+    const recording = activeRecordings.get(device);
+    if (!recording) {
+        return { content: [{ type: 'text', text: 'No active recording to stop.' }] };
+    }
+    // Gracefully stop recording
+    recording.process.kill('SIGINT');
+    const duration = Math.round((Date.now() - recording.startTime) / 1000);
+    activeRecordings.delete(device);
+    // Wait for file to finalize
+    await new Promise(resolve => setTimeout(resolve, 1500));
+    const maxFrames = Math.min(args.maxFrames || 3, 6);
+    const content = [];
+    // Extract key frames using ffmpeg if available, otherwise use sips on a single frame
+    try {
+        // Check if ffmpeg is available for frame extraction
+        let hasFFmpeg = false;
+        try {
+            await execFileAsync('which', ['ffmpeg'], { timeout: 3000 });
+            hasFFmpeg = true;
+        }
+        catch { /* no ffmpeg */ }
+        if (hasFFmpeg && duration > 0) {
+            // Extract evenly spaced frames
+            const interval = Math.max(1, Math.floor(duration / maxFrames));
+            const frameDir = join(tmpdir(), `preflight-frames-${Date.now()}`);
+            await mkdir(frameDir, { recursive: true });
+            await execFileAsync('ffmpeg', [
+                '-i', recording.tmpPath,
+                '-vf', `fps=1/${interval}`,
+                '-frames:v', String(maxFrames),
+                '-q:v', '8',
+                join(frameDir, 'frame-%02d.jpg'),
+            ], { timeout: 15000 }).catch(() => { });
+            // Read extracted frames
+            const { readdir } = await import('node:fs/promises');
+            const frames = (await readdir(frameDir).catch(() => []))
+                .filter(f => f.endsWith('.jpg'))
+                .sort()
+                .slice(0, maxFrames);
+            for (const frame of frames) {
+                try {
+                    const buf = await readFile(join(frameDir, frame));
+                    content.push({ type: 'image', data: buf.toString('base64'), mimeType: 'image/jpeg' });
+                }
+                catch { /* skip unreadable frame */ }
+            }
+            // Cleanup frame dir
+            for (const frame of frames) {
+                await unlink(join(frameDir, frame)).catch(() => { });
+            }
+            await unlink(frameDir).catch(() => { });
+        }
+    }
+    catch (err) {
+        logger.debug('tool:stopRecording', `Frame extraction failed: ${err.message}`);
+    }
+    // If no frames extracted, take a final screenshot as fallback
+    if (content.length === 0) {
+        try {
+            const { stdout: pngBuffer } = await execSimctlBuffer(['io', device, 'screenshot', '--type=png', '-'], 'tool:stopRecording');
+            // Compress to JPEG
+            const tmpPng = join(tmpdir(), `stoprec-${Date.now()}.png`);
+            const tmpJpg = join(tmpdir(), `stoprec-${Date.now()}.jpg`);
+            await writeFile(tmpPng, pngBuffer);
+            await execFileAsync('sips', ['-s', 'format', 'jpeg', '-s', 'formatOptions', '60', tmpPng, '--out', tmpJpg], { timeout: 10000 });
+            const jpgBuf = await readFile(tmpJpg);
+            content.push({ type: 'image', data: jpgBuf.toString('base64'), mimeType: 'image/jpeg' });
+            await unlink(tmpPng).catch(() => { });
+            await unlink(tmpJpg).catch(() => { });
+        }
+        catch {
+            content.push({ type: 'text', text: '(Could not capture final frame)' });
+        }
+    }
+    // Handle the video file
+    let videoNote = '';
+    if (args.savePath) {
+        try {
+            const { copyFile } = await import('node:fs/promises');
+            const dir = args.savePath.substring(0, args.savePath.lastIndexOf('/'));
+            if (dir)
+                await mkdir(dir, { recursive: true });
+            await copyFile(recording.tmpPath, args.savePath);
+            videoNote = `\nVideo saved to: ${args.savePath}`;
+        }
+        catch (err) {
+            videoNote = `\nFailed to save video: ${err.message}`;
+        }
+    }
+    // Clean up temp video
+    await unlink(recording.tmpPath).catch(() => { });
+    content.push({
+        type: 'text',
+        text: `Recording stopped (${duration}s). ${content.filter(c => c.type === 'image').length} key frame(s) extracted.${videoNote}`,
+    });
+    return { content };
+}
+// --- navigate_back ---
+export const navigateBackParams = {
+    deviceId: z.string().optional().describe('Device (default: booted)'),
+};
+export async function handleNavigateBack(args) {
+    const device = await resolveDevice(args.deviceId);
+    const { pressKey } = await import('../helpers/applescript.js');
+    try {
+        await pressKey('[', ['command']);
+        return {
+            content: [{
+                    type: 'text',
+                    text: 'Sent back navigation command (Cmd+[). Works in Safari and apps with standard navigation.',
+                }],
+        };
+    }
+    catch {
+        const { checkIdbAvailable, idbTap } = await import('../helpers/idb.js');
+        if (await checkIdbAvailable()) {
+            await idbTap(30, 55, device);
+            return {
+                content: [{
+                        type: 'text',
+                        text: 'Tapped back button area (30, 55) via idb. Use simulator_accessibility_audit to find exact back button coordinates if this didn\'t work.',
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: 'Back navigation failed. Use simulator_tap on the visible back button, or simulator_accessibility_audit to find its coordinates.',
+                }],
+        };
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "preflight-ios-mcp",
+  "version": "1.0.0",
+  "description": "The most comprehensive MCP server for iOS Simulator automation — 57 tools for AI-powered iOS development. Works with Claude Code, Cursor, Windsurf, VS Code, and any MCP client.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "preflight-ios-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EthanAckerman-git/Preflight.git"
+  },
+  "homepage": "https://github.com/EthanAckerman-git/Preflight",
+  "bugs": {
+    "url": "https://github.com/EthanAckerman-git/Preflight/issues"
+  },
+  "author": "Ethan Ackerman",
+  "scripts": {
+    "build": "tsc && swiftc src/helpers/mouse-events.swift -o dist/mouse-events",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "postinstall": "which idb > /dev/null 2>&1 || echo '\\n[Preflight MCP] Optional: Install idb for cursor-free touch injection:\\n  brew tap facebook/fb && brew install idb-companion\\n  pip3 install fb-idb\\n'"
+  },
+  "keywords": ["mcp", "model-context-protocol", "ios", "simulator", "xcode", "testing", "automation", "claude", "cursor", "windsurf", "ai", "accessibility", "debugging", "playwright"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}