mobile-debug-mcp 0.11.0 → 0.12.1

package/dist/cli/ios/run-ios-ui-tree-tap.js

@@ -0,0 +1,29 @@
+import { iOSObserve } from '../../ios/observe.js';
+import { iOSInteract } from '../../ios/interact.js';
+async function main() {
+    const deviceId = 'booted';
+    const obs = new iOSObserve();
+    const interact = new iOSInteract();
+    console.log('Fetching UI tree...');
+    const tree = await obs.getUITree(deviceId);
+    if (tree.error) {
+        console.error('getUITree error:', tree.error);
+        process.exit(2);
+    }
+    console.log('Elements found:', tree.elements.length);
+    if (!tree.elements || tree.elements.length === 0) {
+        console.error('No elements found; aborting');
+        process.exit(3);
+    }
+    const clickable = tree.elements.find(e => e.clickable) || tree.elements[0];
+    console.log('Using element:', clickable.text || '(no text)', 'clickable=', clickable.clickable, 'center=', clickable.center);
+    const [x, y] = clickable.center || [0, 0];
+    console.log(`Tapping at ${x},${y}...`);
+    const res = await interact.tap(x, y, deviceId);
+    console.log('Tap result:', res);
+    if (res.success)
+        process.exit(0);
+    else
+        process.exit(4);
+}
+main();

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,43 +1,152 @@
 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) {
         void _variant;
         try {
-            const files = await fs.readdir(projectPath).catch(() => []);
-            const workspace = files.find(f => f.endsWith('.xcworkspace'));
-            const proj = files.find(f => f.endsWith('.xcodeproj'));
-            if (!workspace && !proj)
+            // Look for an Xcode workspace or project at the provided path. If not present, scan subdirectories (limited depth)
+            async function findProject(root, maxDepth = 3) {
+                try {
+                    const ents = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+                    for (const e of ents) {
+                        // .xcworkspace and .xcodeproj are directories on disk (bundles), not regular files
+                        if (e.name.endsWith('.xcworkspace'))
+                            return { dir: root, workspace: e.name };
+                        if (e.name.endsWith('.xcodeproj'))
+                            return { dir: root, proj: e.name };
+                    }
+                }
+                catch { }
+                if (maxDepth <= 0)
+                    return null;
+                try {
+                    const ents = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+                    for (const e of ents) {
+                        if (e.isDirectory()) {
+                            const candidate = await findProject(path.join(root, e.name), maxDepth - 1);
+                            if (candidate)
+                                return candidate;
+                        }
+                    }
+                }
+                catch { }
+                return null;
+            }
+            const projectInfo = await findProject(projectPath, 3);
+            if (!projectInfo)
                 return { error: 'No Xcode project or workspace found' };
+            const projectRootDir = projectInfo.dir || projectPath;
+            const workspace = projectInfo.workspace;
+            const proj = projectInfo.proj;
+            // Determine destination: prefer explicit env var, otherwise use booted simulator UDID
+            let destinationUDID = process.env.MCP_XCODE_DESTINATION_UDID || process.env.MCP_XCODE_DESTINATION || '';
+            if (!destinationUDID) {
+                try {
+                    const meta = await getIOSDeviceMetadata('booted');
+                    if (meta && meta.id)
+                        destinationUDID = meta.id;
+                }
+                catch { }
+            }
             let buildArgs;
             if (workspace) {
-                const workspacePath = path.join(projectPath, workspace);
+                const workspacePath = path.join(projectRootDir, workspace);
                 const scheme = workspace.replace(/\.xcworkspace$/, '');
                 buildArgs = ['-workspace', workspacePath, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build'];
             }
             else {
-                const projectPathFull = path.join(projectPath, proj);
+                const projectPathFull = path.join(projectRootDir, proj);
                 const scheme = proj.replace(/\.xcodeproj$/, '');
                 buildArgs = ['-project', projectPathFull, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build'];
             }
-            await new Promise((resolve, reject) => {
-                const proc = spawn('xcodebuild', buildArgs, { cwd: projectPath });
-                let stderr = '';
-                proc.stderr?.on('data', d => stderr += d.toString());
-                proc.on('close', code => {
-                    if (code === 0)
-                        resolve();
-                    else
-                        reject(new Error(stderr || `xcodebuild failed with code ${code}`));
+            // If we have a destination UDID, add an explicit destination to avoid xcodebuild picking an ambiguous target
+            if (destinationUDID) {
+                buildArgs.push('-destination', `platform=iOS Simulator,id=${destinationUDID}`);
+            }
+            // Add result bundle path for diagnostics
+            const resultsDir = path.join(projectPath, 'build-results');
+            // Remove any stale results to avoid xcodebuild complaining about existing result bundles
+            await fs.rm(resultsDir, { recursive: true, force: true }).catch(() => { });
+            await fs.mkdir(resultsDir, { recursive: true }).catch(() => { });
+            // Skip specifying -resultBundlePath to avoid platform-specific collisions; rely on stdout/stderr logs
+            const xcodeCmd = process.env.XCODEBUILD_PATH || 'xcodebuild';
+            const XCODEBUILD_TIMEOUT = parseInt(process.env.MCP_XCODEBUILD_TIMEOUT || '', 10) || 180000; // default 3 minutes
+            const MAX_RETRIES = parseInt(process.env.MCP_XCODEBUILD_RETRIES || '', 10) || 1;
+            const tries = MAX_RETRIES + 1;
+            let lastStdout = '';
+            let lastStderr = '';
+            let lastErr = null;
+            for (let attempt = 1; attempt <= tries; attempt++) {
+                // Run xcodebuild with a watchdog
+                const res = await new Promise((resolve) => {
+                    const proc = spawn(xcodeCmd, buildArgs, { cwd: projectPath });
+                    let stdout = '';
+                    let stderr = '';
+                    proc.stdout?.on('data', d => stdout += d.toString());
+                    proc.stderr?.on('data', d => stderr += d.toString());
+                    let killed = false;
+                    const to = setTimeout(() => {
+                        killed = true;
+                        try {
+                            proc.kill('SIGKILL');
+                        }
+                        catch { }
+                    }, XCODEBUILD_TIMEOUT);
+                    proc.on('close', (code) => {
+                        clearTimeout(to);
+                        resolve({ code, stdout, stderr, killedByWatchdog: killed });
+                    });
+                    proc.on('error', (err) => {
+                        clearTimeout(to);
+                        resolve({ code: null, stdout, stderr: String(err), killedByWatchdog: killed });
+                    });
                 });
-                proc.on('error', err => reject(err));
-            });
+                lastStdout = res.stdout;
+                lastStderr = res.stderr;
+                if (res.code === 0) {
+                    // success — clear any previous error and stop retrying
+                    lastErr = null;
+                    break;
+                }
+                // record the failure for reporting
+                lastErr = new Error(res.stderr || `xcodebuild failed with code ${res.code}`);
+                // write logs for diagnostics (helpful whether killed or not)
+                try {
+                    await fs.writeFile(path.join(resultsDir, `xcodebuild-${attempt}.stdout.log`), res.stdout).catch(() => { });
+                    await fs.writeFile(path.join(resultsDir, `xcodebuild-${attempt}.stderr.log`), res.stderr).catch(() => { });
+                }
+                catch { }
+                // If killed by watchdog and there are remaining attempts, continue to retry
+                if (res.killedByWatchdog && attempt < tries) {
+                    continue;
+                }
+                // no more retries or not a watchdog kill — break to report lastErr
+                if (attempt >= tries)
+                    break;
+            }
+            if (lastErr) {
+                // Include diagnostics and result bundle path when available
+                return { error: `xcodebuild failed: ${lastErr.message}. See build-results for logs.`, output: `stdout:\n${lastStdout}\nstderr:\n${lastStderr}` };
+            }
+            // Try to locate built .app. First search project tree, then DerivedData if necessary
             const built = await findAppBundle(projectPath);
-            if (!built)
-                return { error: 'Could not find .app after build' };
-            return { artifactPath: built };
+            if (built)
+                return { artifactPath: built };
+            // Fallback: search DerivedData for matching product
+            const dd = path.join(process.env.HOME || '', 'Library', 'Developer', 'Xcode', 'DerivedData');
+            try {
+                const entries = await fs.readdir(dd).catch(() => []);
+                for (const e of entries) {
+                    const candidate = path.join(dd, e);
+                    const found = await findAppBundle(candidate).catch(() => undefined);
+                    if (found)
+                        return { artifactPath: found };
+                }
+            }
+            catch { }
+            return { error: 'Could not find .app after build' };
         }
         catch (e) {
             return { error: e instanceof Error ? e.message : String(e) };
@@ -71,15 +180,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 +206,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 +215,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 +248,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 {

package/dist/server.js

@@ -126,6 +126,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["appPath"]
             }
         },
+        {
+            name: "build_app",
+            description: "Build a project for Android or iOS and return the built artifact path. Does not install.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: { type: "string", enum: ["android", "ios"], description: "Optional. If omitted the server will attempt to detect platform from projectPath files." },
+                    projectPath: { type: "string", description: "Path to project directory (contains gradlew or xcodeproj/xcworkspace)" },
+                    variant: { type: "string", description: "Optional build variant (e.g., Debug/Release)" }
+                },
+                required: ["projectPath"]
+            }
+        },
         {
             name: "get_logs",
             description: "Get recent logs from Android or iOS simulator. Returns device metadata and the log output.",
@@ -411,6 +424,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
             return wrapResponse(response);
         }
+        if (name === "build_app") {
+            const { platform, projectPath, variant } = args;
+            const res = await ToolsManage.buildAppHandler({ platform, projectPath, variant });
+            return wrapResponse(res);
+        }
         if (name === 'build_and_install') {
             const { platform, projectPath, deviceId, timeout } = args;
             const res = await ToolsManage.buildAndInstallHandler({ platform, projectPath, deviceId, timeout });

package/dist/utils/diagnostics.js

@@ -0,0 +1,25 @@
+export function makeEnvSnapshot(keys) {
+    const snap = {};
+    for (const k of keys)
+        snap[k] = process.env[k];
+    return snap;
+}
+export function wrapExecResult(command, args, res) {
+    return {
+        exitCode: res.status,
+        stdout: res.stdout ? (typeof res.stdout === 'string' ? res.stdout : res.stdout.toString()) : '',
+        stderr: res.stderr ? (typeof res.stderr === 'string' ? res.stderr : res.stderr.toString()) : '',
+        envSnapshot: makeEnvSnapshot(['PATH', 'IDB_PATH', 'JAVA_HOME', 'HOME']),
+        command,
+        args,
+        suggestedFixes: []
+    };
+}
+export class DiagnosticError extends Error {
+    runResult;
+    constructor(message, runResult) {
+        super(message);
+        this.name = 'DiagnosticError';
+        this.runResult = runResult;
+    }
+}