mobile-debug-mcp 0.5.0 → 0.7.0

package/dist/ios/observe.js

@@ -0,0 +1,219 @@
+import { spawn } from "child_process";
+import { promises as fs } from "fs";
+import { execCommand, getIOSDeviceMetadata, validateBundleId, IDB } from "./utils.js";
+// --- Helper Functions Specific to Observe ---
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+function parseIDBFrame(frame) {
+    if (!frame)
+        return [0, 0, 0, 0];
+    const x = Number(frame.x || 0);
+    const y = Number(frame.y || 0);
+    const w = Number(frame.width || frame.w || 0);
+    const h = Number(frame.height || frame.h || 0);
+    return [Math.round(x), Math.round(y), Math.round(x + w), Math.round(y + h)];
+}
+function getCenter(bounds) {
+    const [x1, y1, x2, y2] = bounds;
+    return [Math.floor((x1 + x2) / 2), Math.floor((y1 + y2) / 2)];
+}
+function traverseIDBNode(node, elements, parentIndex = -1, depth = 0) {
+    if (!node)
+        return -1;
+    let currentIndex = -1;
+    // Prefer standard keys, fallback to alternatives
+    const type = node.AXElementType || node.type || "unknown";
+    const label = node.AXLabel || node.label || null;
+    const value = node.AXValue || null;
+    const frame = node.AXFrame || node.frame;
+    const traits = node.AXTraits || [];
+    const clickable = traits.includes("UIAccessibilityTraitButton") || type === "Button" || type === "Cell"; // Cells are often clickable
+    // Filtering Logic:
+    // Keep if clickable OR has visible text/label OR has value
+    // Also keep 'Window' or 'Application' types as they define the root structure often, though usually depth 0
+    const isUseful = clickable || (label && label.length > 0) || (value && value.length > 0) || type === "Application" || type === "Window";
+    if (isUseful) {
+        const bounds = parseIDBFrame(frame);
+        const element = {
+            text: label,
+            contentDescription: value,
+            type: type,
+            resourceId: node.AXUniqueId || null,
+            clickable: clickable,
+            enabled: true, // idb usually returns enabled elements
+            visible: true,
+            bounds: bounds,
+            center: getCenter(bounds),
+            depth: depth
+        };
+        if (parentIndex !== -1) {
+            element.parentId = parentIndex;
+        }
+        elements.push(element);
+        currentIndex = elements.length - 1;
+    }
+    // If current node was skipped, children inherit parentIndex and depth (flattening)
+    // If current node was added, children use currentIndex and depth + 1
+    const nextParentIndex = currentIndex !== -1 ? currentIndex : parentIndex;
+    const nextDepth = currentIndex !== -1 ? depth + 1 : depth;
+    const childrenIndices = [];
+    if (node.children && Array.isArray(node.children)) {
+        for (const child of node.children) {
+            const childIndex = traverseIDBNode(child, elements, nextParentIndex, nextDepth);
+            if (childIndex !== -1) {
+                childrenIndices.push(childIndex);
+            }
+        }
+    }
+    if (currentIndex !== -1 && childrenIndices.length > 0) {
+        elements[currentIndex].children = childrenIndices;
+    }
+    return currentIndex;
+}
+// Check if IDB is installed
+async function isIDBInstalled() {
+    return new Promise((resolve) => {
+        // Check if 'idb' is in path by trying to run it
+        const child = spawn(IDB, ['--version']);
+        child.on('error', () => resolve(false));
+        child.on('close', (code) => resolve(code === 0));
+    });
+}
+export class iOSObserve {
+    async getDeviceMetadata(deviceId = "booted") {
+        return getIOSDeviceMetadata(deviceId);
+    }
+    async getLogs(appId, deviceId = "booted") {
+        // If appId is provided, use predicate filtering
+        // Note: execFile passes args directly, so we don't need shell escaping for the predicate string itself,
+        // but we do need to construct the predicate correctly for log show.
+        const args = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog', '--last', '1m'];
+        if (appId) {
+            validateBundleId(appId);
+            args.push('--predicate', `subsystem contains "${appId}" or process == "${appId}"`);
+        }
+        const result = await execCommand(args, deviceId);
+        const device = await getIOSDeviceMetadata(deviceId);
+        const logs = result.output ? result.output.split('\n') : [];
+        return {
+            device,
+            logs,
+            logCount: logs.length,
+        };
+    }
+    async captureScreenshot(deviceId = "booted") {
+        const device = await getIOSDeviceMetadata(deviceId);
+        const tmpFile = `/tmp/mcp-ios-screenshot-${Date.now()}.png`;
+        try {
+            // 1. Capture screenshot to temp file
+            await execCommand(['simctl', 'io', deviceId, 'screenshot', tmpFile], deviceId);
+            // 2. Read file as base64
+            const buffer = await fs.readFile(tmpFile);
+            const base64 = buffer.toString('base64');
+            // 3. Clean up
+            await fs.rm(tmpFile).catch(() => { });
+            return {
+                device,
+                screenshot: base64,
+                // Default resolution since we can't easily parse it without extra libs
+                // Clients will read the real dimensions from the PNG header anyway
+                resolution: { width: 0, height: 0 },
+            };
+        }
+        catch (err) {
+            // Ensure cleanup happens even on error
+            await fs.rm(tmpFile).catch(() => { });
+            throw new Error(`Failed to capture screenshot: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    async getUITree(deviceId = "booted") {
+        const device = await getIOSDeviceMetadata(deviceId);
+        // idb is required
+        const idbExists = await isIDBInstalled();
+        if (!idbExists) {
+            return {
+                device,
+                screen: "",
+                resolution: { width: 0, height: 0 },
+                elements: [],
+                error: "iOS UI tree retrieval requires 'idb' (iOS Device Bridge). Please install it via Homebrew: `brew tap facebook/fb && brew install idb-companion` and `pip3 install fb-idb`."
+            };
+        }
+        // Resolve UDID if needed
+        const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
+        // Retry Logic
+        let jsonContent = null;
+        let attempts = 0;
+        const maxAttempts = 3;
+        while (attempts < maxAttempts) {
+            attempts++;
+            try {
+                // Stabilization delay
+                await delay(300 + (attempts * 100));
+                const args = ['ui', 'describe', '--json'];
+                if (targetUdid) {
+                    args.push('--udid', targetUdid);
+                }
+                const output = await new Promise((resolve, reject) => {
+                    const child = spawn(IDB, args);
+                    let stdout = '';
+                    let stderr = '';
+                    child.stdout.on('data', (data) => stdout += data.toString());
+                    child.stderr.on('data', (data) => stderr += data.toString());
+                    child.on('error', (err) => reject(new Error(`Failed to execute idb: ${err.message}`)));
+                    child.on('close', (code) => {
+                        if (code !== 0) {
+                            reject(new Error(`idb failed (code ${code}): ${stderr.trim()}`));
+                        }
+                        else {
+                            resolve(stdout);
+                        }
+                    });
+                });
+                if (output && output.trim().length > 0) {
+                    jsonContent = JSON.parse(output);
+                    break; // Success
+                }
+            }
+            catch (err) {
+                console.error(`Attempt ${attempts} failed: ${err}`);
+            }
+            if (attempts === maxAttempts) {
+                return {
+                    device,
+                    screen: "",
+                    resolution: { width: 0, height: 0 },
+                    elements: [],
+                    error: `Failed to retrieve valid UI dump after ${maxAttempts} attempts.`
+                };
+            }
+        }
+        try {
+            const elements = [];
+            const root = jsonContent;
+            traverseIDBNode(root, elements);
+            // Infer resolution from root element if possible (usually the Window/Application frame)
+            let width = 0;
+            let height = 0;
+            if (elements.length > 0) {
+                const rootBounds = elements[0].bounds;
+                width = rootBounds[2] - rootBounds[0];
+                height = rootBounds[3] - rootBounds[1];
+            }
+            return {
+                device,
+                screen: "",
+                resolution: { width, height },
+                elements
+            };
+        }
+        catch (e) {
+            return {
+                device,
+                screen: "",
+                resolution: { width: 0, height: 0 },
+                elements: [],
+                error: `Failed to parse idb output: ${e instanceof Error ? e.message : String(e)}`
+            };
+        }
+    }
+}

package/dist/ios/utils.js

@@ -0,0 +1,114 @@
+import { execFile, spawn } from "child_process";
+export const XCRUN = process.env.XCRUN_PATH || "xcrun";
+export const IDB = "idb";
+// Validate bundle ID to prevent any potential injection or invalid characters
+export function validateBundleId(bundleId) {
+    if (!bundleId)
+        return;
+    // Allow alphanumeric, dots, hyphens, and underscores.
+    if (!/^[a-zA-Z0-9.\-_]+$/.test(bundleId)) {
+        throw new Error(`Invalid Bundle ID: ${bundleId}. Must contain only alphanumeric characters, dots, hyphens, or underscores.`);
+    }
+}
+export function execCommand(args, deviceId = "booted") {
+    return new Promise((resolve, reject) => {
+        // Use spawn for better stream control and consistency with Android implementation
+        const child = spawn(XCRUN, args);
+        let stdout = '';
+        let stderr = '';
+        if (child.stdout) {
+            child.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+        }
+        if (child.stderr) {
+            child.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+        }
+        const timeoutMs = args.includes('log') ? 10000 : 5000; // 10s for logs, 5s for others
+        const timeout = setTimeout(() => {
+            child.kill();
+            reject(new Error(`Command timed out after ${timeoutMs}ms: ${XCRUN} ${args.join(' ')}`));
+        }, timeoutMs);
+        child.on('close', (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                reject(new Error(stderr.trim() || `Command failed with code ${code}`));
+            }
+            else {
+                resolve({ output: stdout.trim(), device: { platform: "ios", id: deviceId } });
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+    });
+}
+function parseRuntimeName(runtime) {
+    // Example: com.apple.CoreSimulator.SimRuntime.iOS-17-0 -> iOS 17.0
+    try {
+        const parts = runtime.split('.');
+        const lastPart = parts[parts.length - 1]; // e.g. "iOS-17-0"
+        // Split by hyphen to separate OS from version numbers
+        // e.g. "iOS-17-0" -> ["iOS", "17", "0"]
+        const segments = lastPart.split('-');
+        if (segments.length > 1) {
+            const os = segments[0]; // "iOS"
+            const version = segments.slice(1).join('.'); // "17.0"
+            return `${os} ${version}`;
+        }
+        return lastPart;
+    }
+    catch {
+        return runtime;
+    }
+}
+export async function getIOSDeviceMetadata(deviceId = "booted") {
+    return new Promise((resolve) => {
+        // If deviceId is provided (and not "booted"), we could try to list just that device.
+        // But listing all booted devices is usually fine to find the one we want or just one.
+        // Let's stick to listing all and filtering if needed, or just return basic info if we can't find it.
+        execFile(XCRUN, ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
+            // Default fallback
+            const fallback = {
+                platform: "ios",
+                id: deviceId,
+                osVersion: "Unknown",
+                model: "Simulator",
+                simulator: true,
+            };
+            if (err || !stdout) {
+                resolve(fallback);
+                return;
+            }
+            try {
+                const data = JSON.parse(stdout);
+                const devicesMap = data.devices || {};
+                // Find the device
+                for (const runtime in devicesMap) {
+                    const devices = devicesMap[runtime];
+                    if (Array.isArray(devices)) {
+                        for (const device of devices) {
+                            if (deviceId === "booted" || device.udid === deviceId) {
+                                resolve({
+                                    platform: "ios",
+                                    id: device.udid,
+                                    osVersion: parseRuntimeName(runtime),
+                                    model: device.name,
+                                    simulator: true,
+                                });
+                                return;
+                            }
+                        }
+                    }
+                }
+                resolve(fallback);
+            }
+            catch (error) {
+                resolve(fallback);
+            }
+        });
+    });
+}

package/dist/ios.js

@@ -1,6 +1,7 @@
 import { execFile, spawn } from "child_process";
 import { promises as fs } from "fs";
 const XCRUN = process.env.XCRUN_PATH || "xcrun";
+const IDB = "idb";
 // Validate bundle ID to prevent any potential injection or invalid characters
 function validateBundleId(bundleId) {
     if (!bundleId)
@@ -208,3 +209,136 @@ export async function captureIOSScreenshot(deviceId = "booted") {
         throw new Error(`Failed to capture screenshot: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+function parseIDBFrame(frame) {
+    if (!frame)
+        return [0, 0, 0, 0];
+    const x = Number(frame.x || 0);
+    const y = Number(frame.y || 0);
+    const w = Number(frame.width || frame.w || 0);
+    const h = Number(frame.height || frame.h || 0);
+    return [Math.round(x), Math.round(y), Math.round(x + w), Math.round(y + h)];
+}
+function traverseIDBNode(node, elements, parentIndex = -1) {
+    if (!node)
+        return -1;
+    // Prefer standard keys, fallback to alternatives
+    const type = node.AXElementType || node.type || "unknown";
+    const label = node.AXLabel || node.label || null;
+    const value = node.AXValue || null;
+    const frame = node.AXFrame || node.frame;
+    const element = {
+        text: label,
+        contentDescription: value, // iOS uses Value/Label differently than Android but this maps roughly
+        type: type,
+        resourceId: node.AXUniqueId || null,
+        clickable: (node.AXTraits || []).includes("UIAccessibilityTraitButton") || type === "Button",
+        enabled: true, // idb usually returns enabled elements
+        visible: true,
+        bounds: parseIDBFrame(frame),
+    };
+    if (parentIndex !== -1) {
+        element.parentId = parentIndex;
+    }
+    elements.push(element);
+    const currentIndex = elements.length - 1;
+    const childrenIndices = [];
+    if (node.children && Array.isArray(node.children)) {
+        for (const child of node.children) {
+            const childIndex = traverseIDBNode(child, elements, currentIndex);
+            if (childIndex !== -1) {
+                childrenIndices.push(childIndex);
+            }
+        }
+    }
+    if (childrenIndices.length > 0) {
+        elements[currentIndex].children = childrenIndices;
+    }
+    return currentIndex;
+}
+// Check if IDB is installed
+async function isIDBInstalled() {
+    return new Promise((resolve) => {
+        const child = spawn(IDB, ['--version']);
+        child.on('error', () => resolve(false));
+        child.on('close', (code) => resolve(code === 0));
+    });
+}
+export async function getIOSUITree(deviceId = "booted") {
+    const device = await getIOSDeviceMetadata(deviceId);
+    // idb is required
+    const idbExists = await isIDBInstalled();
+    if (!idbExists) {
+        return {
+            device,
+            screen: "",
+            resolution: { width: 0, height: 0 },
+            elements: [],
+            error: "iOS UI tree retrieval requires 'idb' (iOS Device Bridge). Please install it via Homebrew: `brew tap facebook/fb && brew install idb-companion` and `pip3 install fb-idb`."
+        };
+    }
+    return new Promise((resolve) => {
+        // idb ui describe --udid <uuid> --json
+        // If deviceId is 'booted', try to resolve it to a UDID because idb often needs explicit target
+        const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
+        const args = ['ui', 'describe', '--json'];
+        if (targetUdid) {
+            args.push('--udid', targetUdid);
+        }
+        const child = spawn(IDB, args);
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (data) => stdout += data.toString());
+        child.stderr.on('data', (data) => stderr += data.toString());
+        child.on('error', (err) => {
+            resolve({
+                device,
+                screen: "",
+                resolution: { width: 0, height: 0 },
+                elements: [],
+                error: `Failed to execute idb: ${err.message}`
+            });
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                resolve({
+                    device,
+                    screen: "",
+                    resolution: { width: 0, height: 0 },
+                    elements: [],
+                    error: `idb failed (code ${code}): ${stderr.trim()}`
+                });
+                return;
+            }
+            try {
+                const json = JSON.parse(stdout);
+                const elements = [];
+                // idb return object usually has 'children' at root or is the root
+                const root = json;
+                traverseIDBNode(root, elements);
+                // Infer resolution from root element if possible (usually the Window/Application frame)
+                let width = 0;
+                let height = 0;
+                if (elements.length > 0) {
+                    const rootBounds = elements[0].bounds;
+                    width = rootBounds[2] - rootBounds[0];
+                    height = rootBounds[3] - rootBounds[1];
+                }
+                resolve({
+                    device,
+                    screen: "",
+                    resolution: { width, height },
+                    elements
+                });
+            }
+            catch (e) {
+                resolve({
+                    device,
+                    screen: "",
+                    resolution: { width: 0, height: 0 },
+                    elements: [],
+                    error: `Failed to parse idb output: ${e instanceof Error ? e.message : String(e)}`
+                });
+            }
+        });
+    });
+}