mobile-debug-mcp 0.11.0 → 0.12.0

package/README.md

@@ -1,15 +1,15 @@
-# Mobile Debug MCP
+# Mobile Dev Agent Tools
 
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, and inspect Android/iOS apps from an MCP-compatible client.
 
-> **Note:** iOS support is currently an untested Work In Progress (WIP). Please use with caution and report any issues.
+> **Note:** iOS support is currently only tested on simulator. Please use with caution and report any issues.
 
 ## Requirements
 
 - Node.js >= 18
-- Android SDK (adb) for Android support
+- [Android SDK](https://developer.android.com/studio) (adb) for Android support
 - Xcode command-line tools for iOS support
-- Optional: idb for enhanced iOS device support
+- [idb](https://github.com/facebook/idb) for iOS device support
 
 ## Configuration example
 
@@ -19,12 +19,16 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
     "mobile-debug": {
       "command": "npx",
       "args": ["--yes","mobile-debug-mcp","server"],
-      "env": { "ADB_PATH": "/path/to/adb", "XCRUN_PATH": "/usr/bin/xcrun" }
+      "env": { "ADB_PATH": "/path/to/adb", "XCRUN_PATH": "/usr/bin/xcrun", "IDB_PATH": "/path/to/idb" }
     }
   }
 }
 ```
 ## Usage
+
+Example: 
+After a crash tell the agent the following:
+
 I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available
 
 ## Docs
@@ -35,3 +39,12 @@ I have a crash on the app, can you diagnose it, fix and validate using the mcp t
 ## License
 
 MIT
+
+## IDB/ADB healthcheck and diagnostics
+
+The agent provides healthcheck and optional auto-install scripts for iOS (idb) and Android (adb).
+
+- Run `npm run healthcheck` to verify idb is available. Set `MCP_AUTO_INSTALL_IDB=true` to allow the installer to run in CI or non-interactive environments.
+- Override detection with `IDB_PATH` or `ADB_PATH` environment variables.
+- Tools now return structured diagnostics on failures: { exitCode, stdout, stderr, command, args, envSnapshot, suggestedFixes } which helps agents decide corrective actions.
+

package/dist/android/diagnostics.js

@@ -0,0 +1,24 @@
+import { spawnSync } from 'child_process';
+import { getAdbCmd } from './utils.js';
+import { makeEnvSnapshot } from '../utils/diagnostics.js';
+export function execAdbWithDiagnostics(args, deviceId) {
+    const adbArgs = deviceId ? ['-s', deviceId, ...args] : args;
+    const timeout = 120000;
+    const res = spawnSync(getAdbCmd(), adbArgs, { encoding: 'utf8', timeout });
+    const runResult = {
+        exitCode: typeof res.status === 'number' ? res.status : null,
+        stdout: res.stdout || '',
+        stderr: res.stderr || '',
+        envSnapshot: makeEnvSnapshot(['PATH', 'ADB_PATH', 'HOME', 'JAVA_HOME']),
+        command: getAdbCmd(),
+        args: adbArgs,
+        suggestedFixes: []
+    };
+    if (res.status !== 0) {
+        if ((runResult.stderr || '').includes('device not found'))
+            runResult.suggestedFixes.push('Ensure device is connected and adb is authorized (adb devices)');
+        if ((runResult.stderr || '').includes('No such file or directory'))
+            runResult.suggestedFixes.push('Verify ADB_PATH or that adb is installed');
+    }
+    return { runResult };
+}

package/dist/android/manage.js

@@ -3,6 +3,7 @@ import { spawn } from 'child_process';
 import path from 'path';
 import { existsSync } from 'fs';
 import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from './utils.js';
+import { execAdbWithDiagnostics } from './diagnostics.js';
 import { detectJavaHome } from '../utils/java.js';
 export class AndroidManage {
     async build(projectPath, _variant) {
@@ -34,8 +35,8 @@ export class AndroidManage {
     async installApp(apkPath, deviceId) {
         const metadata = await getAndroidDeviceMetadata('', deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        let apkToInstall = apkPath;
         try {
-            let apkToInstall = apkPath;
             const stat = await fs.stat(apkPath).catch(() => null);
             if (stat && stat.isDirectory()) {
                 const detectedJavaHome = await detectJavaHome().catch(() => undefined);
@@ -104,20 +105,38 @@ export class AndroidManage {
             return { device: deviceInfo, installed: true, output: pmOut };
         }
         catch (e) {
-            return { device: deviceInfo, installed: false, error: e instanceof Error ? e.message : String(e) };
+            // gather diagnostics for attempted adb operations
+            const basename = path.basename(apkToInstall);
+            const remotePath = `/data/local/tmp/${basename}`;
+            const installDiag = execAdbWithDiagnostics(['install', '-r', apkToInstall], deviceId);
+            const pushDiag = execAdbWithDiagnostics(['push', apkToInstall, remotePath], deviceId);
+            const pmDiag = execAdbWithDiagnostics(['shell', 'pm', 'install', '-r', remotePath], deviceId);
+            return { device: deviceInfo, installed: false, error: e instanceof Error ? e.message : String(e), diagnostics: { installDiag, pushDiag, pmDiag } };
         }
     }
     async startApp(appId, deviceId) {
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
-        await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
-        return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 };
+        try {
+            await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
+            return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 };
+        }
+        catch (e) {
+            const diag = execAdbWithDiagnostics(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
+            return { device: deviceInfo, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+        }
     }
     async terminateApp(appId, deviceId) {
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
-        await execAdb(['shell', 'am', 'force-stop', appId], deviceId);
-        return { device: deviceInfo, appTerminated: true };
+        try {
+            await execAdb(['shell', 'am', 'force-stop', appId], deviceId);
+            return { device: deviceInfo, appTerminated: true };
+        }
+        catch (e) {
+            const diag = execAdbWithDiagnostics(['shell', 'am', 'force-stop', appId], deviceId);
+            return { device: deviceInfo, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+        }
     }
     async restartApp(appId, deviceId) {
         await this.terminateApp(appId, deviceId);
@@ -131,7 +150,13 @@ export class AndroidManage {
     async resetAppData(appId, deviceId) {
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
-        const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId);
-        return { device: deviceInfo, dataCleared: output === 'Success' };
+        try {
+            const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId);
+            return { device: deviceInfo, dataCleared: output === 'Success' };
+        }
+        catch (e) {
+            const diag = execAdbWithDiagnostics(['shell', 'pm', 'clear', appId], deviceId);
+            return { device: deviceInfo, dataCleared: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+        }
     }
 }

package/dist/android/observe.js

@@ -1,6 +1,6 @@
 import { spawn } from "child_process";
 import { XMLParser } from "fast-xml-parser";
-import { ADB, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, getScreenResolution, traverseNode, parseLogLine } from "./utils.js";
+import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, getScreenResolution, traverseNode, parseLogLine } from "./utils.js";
 import { createWriteStream } from "fs";
 import { promises as fsPromises } from "fs";
 import path from "path";
@@ -67,7 +67,7 @@ export class AndroidObserve {
             };
         }
         catch (e) {
-            const errorMessage = `Failed to get UI tree. ADB Path: '${ADB}'. Error: ${e instanceof Error ? e.message : String(e)}`;
+            const errorMessage = `Failed to get UI tree. ADB Path: '${getAdbCmd()}'. Error: ${e instanceof Error ? e.message : String(e)}`;
             console.error(errorMessage);
             return {
                 device: deviceInfo,
@@ -115,7 +115,7 @@ export class AndroidObserve {
             // Need to construct ADB args manually since spawn handles it
             const args = deviceId ? ['-s', deviceId, 'exec-out', 'screencap', '-p'] : ['exec-out', 'screencap', '-p'];
             // Using spawn for screencap as well to ensure consistent process handling
-            const child = spawn(ADB, args);
+            const child = spawn(getAdbCmd(), args);
             const chunks = [];
             let stderr = '';
             child.stdout.on('data', (chunk) => {
@@ -245,7 +245,7 @@ export class AndroidObserve {
                 activeLogStreams.delete(sessionId);
             }
             const args = ['logcat', `--pid=${pid}`, filter];
-            const proc = spawn(ADB, args);
+            const proc = spawn(getAdbCmd(), args);
             const tmpDir = process.env.TMPDIR || '/tmp';
             const file = path.join(tmpDir, `mobile-debug-log-${sessionId}.ndjson`);
             const stream = createWriteStream(file, { flags: 'a' });

package/dist/android/utils.js

@@ -2,7 +2,7 @@ import { spawn } from 'child_process';
 import { promises as fsPromises, existsSync } from 'fs';
 import path from 'path';
 import { detectJavaHome } from '../utils/java.js';
-export const ADB = process.env.ADB_PATH || 'adb';
+export function getAdbCmd() { return process.env.ADB_PATH || 'adb'; }
 /**
  * Prepare Gradle execution options for building an Android project.
  * Returns execCmd (wrapper or gradle), base gradleArgs array, and spawn options including env.
@@ -72,7 +72,7 @@ export function execAdb(args, deviceId, options = {}) {
         // Extract timeout from options if present, otherwise pass options to spawn
         const { timeout: customTimeout, ...spawnOptions } = options;
         // Use spawn instead of execFile for better stream control and to avoid potential buffering hangs
-        const child = spawn(ADB, adbArgs, spawnOptions);
+        const child = spawn(getAdbCmd(), adbArgs, spawnOptions);
         let stdout = '';
         let stderr = '';
         if (child.stdout) {
@@ -112,7 +112,7 @@ export function spawnAdb(args, deviceId, options = {}) {
     const adbArgs = getAdbArgs(args, deviceId);
     return new Promise((resolve, reject) => {
         const { timeout: customTimeout, ...spawnOptions } = options;
-        const child = spawn(ADB, adbArgs, spawnOptions);
+        const child = spawn(getAdbCmd(), adbArgs, spawnOptions);
         let stdout = '';
         let stderr = '';
         if (child.stdout)

package/dist/ios/interact.js

@@ -1,5 +1,5 @@
 import { spawn } from "child_process";
-import { getIOSDeviceMetadata, IDB } from "./utils.js";
+import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "./utils.js";
 import { iOSObserve } from "./observe.js";
 export class iOSInteract {
     observe = new iOSObserve();
@@ -31,12 +31,8 @@ export class iOSInteract {
     }
     async tap(x, y, deviceId = "booted") {
         const device = await getIOSDeviceMetadata(deviceId);
-        // Check for idb
-        const child = spawn(IDB, ['--version']);
-        const idbExists = await new Promise((resolve) => {
-            child.on('error', () => resolve(false));
-            child.on('close', (code) => resolve(code === 0));
-        });
+        // Use shared helper to detect idb
+        const idbExists = await isIDBInstalled();
         if (!idbExists) {
             return {
                 device,
@@ -53,7 +49,7 @@ export class iOSInteract {
                 args.push('--udid', targetUdid);
             }
             await new Promise((resolve, reject) => {
-                const proc = spawn(IDB, args);
+                const proc = spawn(getIdbCmd(), args);
                 let stderr = '';
                 proc.stderr.on('data', d => stderr += d.toString());
                 proc.on('close', code => {

package/dist/ios/manage.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "fs";
 import { spawn } from "child_process";
-import { execCommand, getIOSDeviceMetadata, validateBundleId, IDB, findAppBundle } from "./utils.js";
+import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "./utils.js";
 import path from "path";
 export class iOSManage {
     async build(projectPath, _variant) {
@@ -23,7 +23,8 @@ export class iOSManage {
                 buildArgs = ['-project', projectPathFull, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build'];
             }
             await new Promise((resolve, reject) => {
-                const proc = spawn('xcodebuild', buildArgs, { cwd: projectPath });
+                const xcodeCmd = process.env.XCODEBUILD_PATH || 'xcodebuild';
+                const proc = spawn(xcodeCmd, buildArgs, { cwd: projectPath });
                 let stderr = '';
                 proc.stderr?.on('data', d => stderr += d.toString());
                 proc.on('close', code => {
@@ -71,15 +72,18 @@ export class iOSManage {
                 return { device, installed: true, output: res.output };
             }
             catch (e) {
+                // Gather diagnostics for simctl failure
+                const diag = execCommandWithDiagnostics(['simctl', 'install', deviceId, toInstall], deviceId);
                 try {
-                    const child = spawn(IDB, ['--version']);
+                    const child = spawn(getIdbCmd(), ['--version']);
                     const idbExists = await new Promise((resolve) => {
                         child.on('error', () => resolve(false));
                         child.on('close', (code) => resolve(code === 0));
                     });
                     if (idbExists) {
+                        // attempt idb install via spawn but include diagnostics
                         await new Promise((resolve, reject) => {
-                            const proc = spawn(IDB, ['install', toInstall, '--udid', device.id]);
+                            const proc = spawn(getIdbCmd(), ['install', toInstall, '--udid', device.id]);
                             let stderr = '';
                             proc.stderr.on('data', d => stderr += d.toString());
                             proc.on('close', code => {
@@ -94,7 +98,7 @@ export class iOSManage {
                     }
                 }
                 catch { }
-                return { device, installed: false, error: e instanceof Error ? e.message : String(e) };
+                return { device, installed: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
             }
         }
         catch (e) {
@@ -103,15 +107,29 @@ export class iOSManage {
     }
     async startApp(bundleId, deviceId = "booted") {
         validateBundleId(bundleId);
-        const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId);
-        const device = await getIOSDeviceMetadata(deviceId);
-        return { device, appStarted: !!result.output, launchTimeMs: 1000 };
+        try {
+            const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId);
+            const device = await getIOSDeviceMetadata(deviceId);
+            return { device, appStarted: !!result.output, launchTimeMs: 1000 };
+        }
+        catch (e) {
+            const diag = execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId);
+            const device = await getIOSDeviceMetadata(deviceId);
+            return { device, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+        }
     }
     async terminateApp(bundleId, deviceId = "booted") {
         validateBundleId(bundleId);
-        await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId);
-        const device = await getIOSDeviceMetadata(deviceId);
-        return { device, appTerminated: true };
+        try {
+            await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId);
+            const device = await getIOSDeviceMetadata(deviceId);
+            return { device, appTerminated: true };
+        }
+        catch (e) {
+            const diag = execCommandWithDiagnostics(['simctl', 'terminate', deviceId, bundleId], deviceId);
+            const device = await getIOSDeviceMetadata(deviceId);
+            return { device, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+        }
     }
     async restartApp(bundleId, deviceId = "booted") {
         await this.terminateApp(bundleId, deviceId);
@@ -122,24 +140,30 @@ export class iOSManage {
         validateBundleId(bundleId);
         await this.terminateApp(bundleId, deviceId);
         const device = await getIOSDeviceMetadata(deviceId);
-        const containerResult = await execCommand(['simctl', 'get_app_container', deviceId, bundleId, 'data'], deviceId);
-        const dataPath = containerResult.output.trim();
-        if (!dataPath)
-            throw new Error(`Could not find data container for ${bundleId}`);
         try {
-            const libraryPath = `${dataPath}/Library`;
-            const documentsPath = `${dataPath}/Documents`;
-            const tmpPath = `${dataPath}/tmp`;
-            await fs.rm(libraryPath, { recursive: true, force: true }).catch(() => { });
-            await fs.rm(documentsPath, { recursive: true, force: true }).catch(() => { });
-            await fs.rm(tmpPath, { recursive: true, force: true }).catch(() => { });
-            await fs.mkdir(libraryPath, { recursive: true }).catch(() => { });
-            await fs.mkdir(documentsPath, { recursive: true }).catch(() => { });
-            await fs.mkdir(tmpPath, { recursive: true }).catch(() => { });
-            return { device, dataCleared: true };
+            const containerResult = await execCommand(['simctl', 'get_app_container', deviceId, bundleId, 'data'], deviceId);
+            const dataPath = containerResult.output.trim();
+            if (!dataPath)
+                throw new Error(`Could not find data container for ${bundleId}`);
+            try {
+                const libraryPath = `${dataPath}/Library`;
+                const documentsPath = `${dataPath}/Documents`;
+                const tmpPath = `${dataPath}/tmp`;
+                await fs.rm(libraryPath, { recursive: true, force: true }).catch(() => { });
+                await fs.rm(documentsPath, { recursive: true, force: true }).catch(() => { });
+                await fs.rm(tmpPath, { recursive: true, force: true }).catch(() => { });
+                await fs.mkdir(libraryPath, { recursive: true }).catch(() => { });
+                await fs.mkdir(documentsPath, { recursive: true }).catch(() => { });
+                await fs.mkdir(tmpPath, { recursive: true }).catch(() => { });
+                return { device, dataCleared: true };
+            }
+            catch (e) {
+                throw new Error(`Failed to clear data for ${bundleId}: ${e instanceof Error ? e.message : String(e)}`);
+            }
         }
         catch (e) {
-            throw new Error(`Failed to clear data for ${bundleId}: ${e instanceof Error ? e.message : String(e)}`);
+            const diag = execCommandWithDiagnostics(['simctl', 'get_app_container', deviceId, bundleId, 'data'], deviceId);
+            return { device, dataCleared: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
         }
     }
 }

package/dist/ios/observe.js

@@ -1,6 +1,6 @@
 import { spawn } from "child_process";
 import { promises as fs } from "fs";
-import { execCommand, getIOSDeviceMetadata, validateBundleId, IDB, XCRUN } from "./utils.js";
+import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcrunCmd, isIDBInstalled } from "./utils.js";
 import { createWriteStream, promises as fsPromises } from 'fs';
 import path from 'path';
 import { parseLogLine } from '../android/utils.js';
@@ -9,6 +9,17 @@ const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 function parseIDBFrame(frame) {
     if (!frame)
         return [0, 0, 0, 0];
+    // Handle string frames like "{{0, 0}, {402, 874}}"
+    if (typeof frame === 'string') {
+        const nums = frame.match(/-?\d+(?:\.\d+)?/g);
+        if (!nums || nums.length < 4)
+            return [0, 0, 0, 0];
+        const x = Number(nums[0]);
+        const y = Number(nums[1]);
+        const w = Number(nums[2]);
+        const h = Number(nums[3]);
+        return [Math.round(x), Math.round(y), Math.round(x + w), Math.round(y + h)];
+    }
     const x = Number(frame.x || 0);
     const y = Number(frame.y || 0);
     const w = Number(frame.width || frame.w || 0);
@@ -72,15 +83,6 @@ function traverseIDBNode(node, elements, parentIndex = -1, depth = 0) {
     }
     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));
-    });
-}
 // iOS live log stream support (moved from ios/utils to observe)
 const iosActiveLogStreams = new Map();
 // Test helpers
@@ -161,12 +163,12 @@ export class iOSObserve {
             try {
                 // Stabilization delay
                 await delay(300 + (attempts * 100));
-                const args = ['ui', 'describe', '--json'];
+                const args = ['ui', 'describe-all', '--json'];
                 if (targetUdid) {
                     args.push('--udid', targetUdid);
                 }
                 const output = await new Promise((resolve, reject) => {
-                    const child = spawn(IDB, args);
+                    const child = spawn(getIdbCmd(), args);
                     let stdout = '';
                     let stderr = '';
                     child.stdout.on('data', (data) => stdout += data.toString());
@@ -201,8 +203,15 @@ export class iOSObserve {
         }
         try {
             const elements = [];
-            const root = jsonContent;
-            traverseIDBNode(root, elements);
+            // idb describe-all returns either a root object or an array of root nodes
+            if (Array.isArray(jsonContent)) {
+                for (const node of jsonContent) {
+                    traverseIDBNode(node, elements);
+                }
+            }
+            else {
+                traverseIDBNode(jsonContent, elements);
+            }
             // Infer resolution from root element if possible (usually the Window/Application frame)
             let width = 0;
             let height = 0;
@@ -240,7 +249,7 @@ export class iOSObserve {
                 iosActiveLogStreams.delete(sessionId);
             }
             const args = ['simctl', 'spawn', deviceId, 'log', 'stream', '--style', 'syslog', '--predicate', predicate];
-            const proc = spawn(XCRUN, args);
+            const proc = spawn(getXcrunCmd(), args);
             // Prepare output file
             const tmpDir = process.env.TMPDIR || '/tmp';
             const file = path.join(tmpDir, `mobile-debug-ios-log-${sessionId}.ndjson`);

package/dist/ios/utils.js

@@ -1,8 +1,90 @@
-import { execFile, spawn } from "child_process";
+import { execFile, spawn, execSync, spawnSync } from "child_process";
 import { promises as fsPromises } from 'fs';
 import path from 'path';
-export const XCRUN = process.env.XCRUN_PATH || "xcrun";
-export const IDB = "idb";
+import { makeEnvSnapshot } from '../utils/diagnostics.js';
+export function getXcrunCmd() { return process.env.XCRUN_PATH || 'xcrun'; }
+export function getConfiguredIdbPath() {
+    if (process.env.MCP_IDB_PATH)
+        return process.env.MCP_IDB_PATH;
+    if (process.env.IDB_PATH)
+        return process.env.IDB_PATH;
+    const cfgPaths = [
+        process.env.MCP_CONFIG_PATH || (process.env.HOME ? `${process.env.HOME}/.mcp/config.json` : ''),
+        `${process.cwd()}/mcp.config.json`
+    ];
+    try {
+        const fs = require('fs');
+        for (const p of cfgPaths) {
+            if (!p)
+                continue;
+            try {
+                if (fs.existsSync(p)) {
+                    const raw = fs.readFileSync(p, 'utf8');
+                    const json = JSON.parse(raw);
+                    if (json) {
+                        if (json.idbPath)
+                            return json.idbPath;
+                        if (json.IDB_PATH)
+                            return json.IDB_PATH;
+                    }
+                }
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return undefined;
+}
+export function getIdbCmd() {
+    const cfg = getConfiguredIdbPath();
+    if (cfg)
+        return cfg;
+    if (process.env.IDB_PATH)
+        return process.env.IDB_PATH;
+    try {
+        const p = execSync('which idb', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+        if (p)
+            return p;
+    }
+    catch { }
+    try {
+        const p2 = execSync('command -v idb', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+        if (p2)
+            return p2;
+    }
+    catch { }
+    // check common user locations
+    const common = [
+        `${process.env.HOME}/Library/Python/3.9/bin/idb`,
+        `${process.env.HOME}/Library/Python/3.10/bin/idb`,
+        '/opt/homebrew/bin/idb',
+        '/usr/local/bin/idb',
+    ];
+    for (const c of common) {
+        try {
+            execSync(`test -x ${c}`, { stdio: ['ignore', 'pipe', 'ignore'] });
+            return c;
+        }
+        catch { }
+    }
+    return 'idb';
+}
+export async function isIDBInstalled() {
+    const cmd = getIdbCmd();
+    try {
+        execSync(`command -v ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] });
+        return true;
+    }
+    catch {
+        try {
+            execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
 // Validate bundle ID to prevent any potential injection or invalid characters
 export function validateBundleId(bundleId) {
     if (!bundleId)
@@ -15,7 +97,7 @@ export function validateBundleId(bundleId) {
 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);
+        const child = spawn(getXcrunCmd(), args);
         let stdout = '';
         let stderr = '';
         if (child.stdout) {
@@ -28,10 +110,12 @@ export function execCommand(args, deviceId = "booted") {
                 stderr += data.toString();
             });
         }
-        const timeoutMs = args.includes('log') ? 10000 : 5000; // 10s for logs, 5s for others
+        const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000; // env (ms) or default 30s
+        const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000; // env (ms) or default 60s
+        const timeoutMs = args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT; // choose appropriate timeout
         const timeout = setTimeout(() => {
             child.kill();
-            reject(new Error(`Command timed out after ${timeoutMs}ms: ${XCRUN} ${args.join(' ')}`));
+            reject(new Error(`Command timed out after ${timeoutMs}ms: ${getXcrunCmd()} ${args.join(' ')}`));
         }, timeoutMs);
         child.on('close', (code) => {
             clearTimeout(timeout);
@@ -48,6 +132,35 @@ export function execCommand(args, deviceId = "booted") {
         });
     });
 }
+export function execCommandWithDiagnostics(args, deviceId = "booted") {
+    // Run synchronously to capture stdout/stderr and exitCode reliably for diagnostics
+    const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000;
+    const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000;
+    const timeoutMs = args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT;
+    const res = spawnSync(getXcrunCmd(), args, { encoding: 'utf8', timeout: timeoutMs });
+    const runResult = {
+        exitCode: typeof res.status === 'number' ? res.status : null,
+        stdout: res.stdout || '',
+        stderr: res.stderr || '',
+        envSnapshot: makeEnvSnapshot(['PATH', 'IDB_PATH', 'JAVA_HOME', 'HOME']),
+        command: getXcrunCmd(),
+        args,
+        deviceId
+    };
+    if (res.status !== 0) {
+        // include suggested fixes for common errors
+        const suggested = [];
+        if ((runResult.stderr || '').includes('xcodebuild: error')) {
+            suggested.push('Ensure the project/workspace path is correct and xcodebuild is installed and accessible.');
+        }
+        if ((runResult.stderr || '').includes('No such file or directory') || (runResult.stderr || '').includes('not found')) {
+            suggested.push('Check that Xcode Command Line Tools are installed and XCRUN_PATH is set if using non-standard location.');
+        }
+        // Return diagnostics object
+        return { runResult: { ...runResult, suggestedFixes: suggested } };
+    }
+    return { runResult: { ...runResult, suggestedFixes: [] } };
+}
 function parseRuntimeName(runtime) {
     // Example: com.apple.CoreSimulator.SimRuntime.iOS-17-0 -> iOS 17.0
     try {
@@ -84,7 +197,7 @@ export async function findAppBundle(dir) {
 export async function getIOSDeviceMetadata(deviceId = "booted") {
     return new Promise((resolve) => {
         // If deviceId is provided (and not "booted"), attempt to find that device among booted simulators.
-        execFile(XCRUN, ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
+        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
             const fallback = {
                 platform: "ios",
                 id: deviceId,
@@ -126,7 +239,7 @@ export async function getIOSDeviceMetadata(deviceId = "booted") {
 }
 export async function listIOSDevices(appId) {
     return new Promise((resolve) => {
-        execFile(XCRUN, ['simctl', 'list', 'devices', '--json'], (err, stdout) => {
+        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], (err, stdout) => {
             if (err || !stdout)
                 return resolve([]);
             try {