mobile-debug-mcp 0.12.0 → 0.12.1

package/README.md

@@ -1,8 +1,8 @@
-# Mobile Dev Agent Tools
+# Mobile Dev MCP
 
 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 only tested on simulator. Please use with caution and report any issues.
+> **Note:** iOS support is limited currently, Please use with caution and report any issues.
 
 ## Requirements
 
@@ -40,11 +40,3 @@ I have a crash on the app, can you diagnose it, fix and validate using the mcp t
 
 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/cli/idb/check-idb.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { execSync, spawnSync } from 'child_process';
+import { main as installMain } from './install-idb.js';
+import { getIdbCmd, isIDBInstalled } from './idb-helper.js';
+function which(cmd) {
+    try {
+        const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] });
+        if (r && r.status === 0 && r.stdout)
+            return r.stdout.toString().trim();
+    }
+    catch { }
+    try {
+        return execSync(`which ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    }
+    catch {
+        return null;
+    }
+}
+function print(...args) {
+    console.log(...args);
+}
+async function runInstaller() {
+    try {
+        // prefer invoking the TS script via npx/tsx to ensure environment
+        const runner = which('npx') ? 'npx' : which('tsx') ? 'tsx' : null;
+        if (runner) {
+            const args = runner === 'npx' ? ['tsx', './src/cli/idb/install-idb.ts'] : ['./src/cli/idb/install-idb.ts'];
+            const res = spawnSync(runner, args, { stdio: 'inherit' });
+            return typeof res.status === 'number' ? res.status === 0 : false;
+        }
+        // fallback: attempt to import and run the installer directly (may rely on ts-node/tsx)
+        try {
+            // call the exported main; it returns a promise
+            await installMain();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    catch (e) {
+        console.error('Failed to run installer:', e instanceof Error ? e.message : String(e));
+        return false;
+    }
+}
+try {
+    print('PATH=', process.env.PATH);
+    const idb = process.env.IDB_PATH || getIdbCmd();
+    print('idb:', idb);
+    if (idb && isIDBInstalled()) {
+        try {
+            print('idb --version:', execSync(`${idb} --version`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim());
+        }
+        catch (e) {
+            print('idb --version: (failed)', e instanceof Error ? e.message : String(e));
+        }
+        const companion = which('idb_companion');
+        print('which idb_companion:', companion);
+        if (companion)
+            try {
+                print('idb_companion --version:', execSync('idb_companion --version', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim());
+            }
+            catch (e) {
+                print('idb_companion --version: (failed)', e instanceof Error ? e.message : String(e));
+            }
+        process.exit(0);
+    }
+    print('idb not found or not responding');
+    const auto = process.env.MCP_AUTO_INSTALL_IDB === 'true';
+    if (auto) {
+        print('MCP_AUTO_INSTALL_IDB=true, attempting installer...');
+        const ok = await runInstaller();
+        if (ok)
+            process.exit(0);
+        print('Installer failed or did not produce idb');
+        process.exit(2);
+    }
+    print('Set MCP_AUTO_INSTALL_IDB=true to attempt automatic installation (CI-friendly).');
+    process.exit(2);
+}
+catch (e) {
+    console.error('idb healthcheck failed:', e instanceof Error ? e.message : String(e));
+    process.exit(2);
+}

package/dist/cli/idb/idb-helper.js

@@ -0,0 +1,91 @@
+import { execSync, spawnSync } from 'child_process';
+import fs from 'fs';
+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`
+    ];
+    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 { }
+    }
+    return undefined;
+}
+export function commandWhich(cmd) {
+    try {
+        const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] });
+        if (r && r.status === 0 && r.stdout)
+            return r.stdout.toString().trim();
+    }
+    catch { }
+    try {
+        const p = execSync(`which ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+        if (p)
+            return p;
+    }
+    catch { }
+    return null;
+}
+export function getIdbCmd() {
+    const cfg = getConfiguredIdbPath();
+    if (cfg)
+        return cfg;
+    if (process.env.IDB_PATH)
+        return process.env.IDB_PATH;
+    // Prefer command -v/which
+    const found = commandWhich('idb');
+    if (found)
+        return found;
+    // Common locations
+    const common = [
+        process.env.HOME ? `${process.env.HOME}/Library/Python/3.9/bin/idb` : '',
+        process.env.HOME ? `${process.env.HOME}/Library/Python/3.10/bin/idb` : '',
+        '/opt/homebrew/bin/idb',
+        '/usr/local/bin/idb'
+    ];
+    for (const c of common) {
+        if (!c)
+            continue;
+        try {
+            execSync(`test -x ${c}`, { stdio: ['ignore', 'pipe', 'ignore'] });
+            return c;
+        }
+        catch { }
+    }
+    return null;
+}
+export function isIDBInstalled() {
+    const cmd = getIdbCmd();
+    if (!cmd)
+        return false;
+    try {
+        // command -v <cmd>
+        const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] });
+        if (r && r.status === 0)
+            return true;
+    }
+    catch { }
+    try {
+        execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 });
+        return true;
+    }
+    catch { }
+    return false;
+}

package/{scripts → dist/cli/idb}/install-idb.js

@@ -1,15 +1,8 @@
 #!/usr/bin/env node
-import { execSync, spawnSync } from 'child_process';
+import { spawnSync } from 'child_process';
 import readline from 'readline';
+import { getIdbCmd, isIDBInstalled, commandWhich } from './idb-helper.js';
 const IDB_PKG = 'fb-idb';
-function which(cmd) {
-    try {
-        return execSync(`which ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
-    }
-    catch {
-        return null;
-    }
-}
 function runCommand(cmd, args) {
     const res = spawnSync(cmd, args, { stdio: 'inherit' });
     return typeof res.status === 'number' ? res.status : 1;
@@ -28,8 +21,8 @@ async function confirm(prompt) {
 async function main() {
     try {
         const idbFromEnv = process.env.IDB_PATH;
-        const existing = idbFromEnv || which('idb') || which('command -v idb');
-        if (existing) {
+        const existing = idbFromEnv || getIdbCmd();
+        if (existing && isIDBInstalled()) {
             console.log('idb already available at:', existing);
             process.exit(0);
         }
@@ -45,12 +38,12 @@ async function main() {
             console.log('Auto-install enabled (MCP_AUTO_INSTALL_IDB=true or CI=true)');
         }
         const attempts = [];
-        if (which('pipx'))
+        if (commandWhich('pipx'))
             attempts.push({ name: 'pipx', cmd: 'pipx', args: ['install', IDB_PKG] });
-        if (which('pip') || which('python3'))
-            attempts.push({ name: 'pip', cmd: which('pip') ? 'pip' : 'python3', args: which('pip') ? ['install', '--user', IDB_PKG] : ['-m', 'pip', 'install', '--user', IDB_PKG] });
+        if (commandWhich('pip') || commandWhich('python3'))
+            attempts.push({ name: 'pip', cmd: commandWhich('pip') ? 'pip' : 'python3', args: commandWhich('pip') ? ['install', '--user', IDB_PKG] : ['-m', 'pip', 'install', '--user', IDB_PKG] });
         // Add brew as a fallback on macOS if present (best-effort)
-        if (process.platform === 'darwin' && which('brew')) {
+        if (process.platform === 'darwin' && commandWhich('brew')) {
             attempts.push({ name: 'brew', cmd: 'brew', args: ['install', 'idb'] });
         }
         if (attempts.length === 0) {
@@ -68,7 +61,7 @@ async function main() {
             catch (e) {
                 console.warn(`${a.name} install failed: ${e instanceof Error ? e.message : String(e)}`);
             }
-            const found = which('idb') || which('command -v idb');
+            const found = commandWhich('idb') || commandWhich('command -v idb');
             if (found) {
                 console.log('idb installed at:', found);
                 process.exit(0);
@@ -82,7 +75,8 @@ async function main() {
         process.exit(2);
     }
 }
-if (require.main === module) {
-    main();
+const scriptPath = new URL(import.meta.url).pathname;
+if (scriptPath === process.argv[1]) {
+    main().catch(e => { console.error('Installer failed:', e instanceof Error ? e.message : String(e)); process.exit(2); });
 }
 export { main };

package/dist/cli/ios/preflight-ios.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import { getIdbCmd, isIDBInstalled, commandWhich } from '../idb/idb-helper.js';
+async function exists(p) {
+    try {
+        await fs.promises.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function findFirst(root, patterns, maxDepth = 4) {
+    const queue = [{ dir: root, depth: 0 }];
+    while (queue.length) {
+        const { dir, depth } = queue.shift();
+        try {
+            console.error('DEBUG findFirst: reading dir', dir, 'depth', depth);
+            const ents = await fs.promises.readdir(dir, { withFileTypes: true });
+            console.error('DEBUG findFirst: entries', ents.map(e => e.name));
+            for (const e of ents) {
+                const full = path.join(dir, e.name);
+                for (const p of patterns) {
+                    if (e.name.endsWith(p)) {
+                        console.error('DEBUG findFirst: matched', full);
+                        return full;
+                    }
+                }
+                if (e.isDirectory() && depth < maxDepth)
+                    queue.push({ dir: full, depth: depth + 1 });
+            }
+        }
+        catch (err) {
+            console.error('DEBUG findFirst: read failed for', dir, err);
+            // ignore
+        }
+    }
+    return null;
+}
+function startCompanionIfNeeded(companionPath, udid) {
+    if (!companionPath || !udid)
+        return { started: false, error: 'missing companion or udid' };
+    try {
+        const child = spawn(companionPath, ['--udid', udid], { detached: true, stdio: 'ignore' });
+        child.unref();
+        return { started: true };
+    }
+    catch (e) {
+        return { started: false, error: e.message };
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    let projectArg;
+    let udid;
+    let startCompanion = false;
+    let kmpBuild = null;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--project' && args[i + 1]) {
+            projectArg = args[i + 1];
+            i++;
+        }
+        else if (a === '--udid' && args[i + 1]) {
+            udid = args[i + 1];
+            i++;
+        }
+        else if (a === '--start-companion')
+            startCompanion = true;
+        else if (!projectArg)
+            projectArg = a;
+    }
+    const cwd = process.cwd();
+    const projectRoot = projectArg ? path.resolve(projectArg) : cwd;
+    // If user passed a direct .xcodeproj or .xcworkspace path, accept it as the projectFile
+    let projectFile = null;
+    try {
+        const stat = await fs.promises.stat(projectRoot);
+        if (stat.isFile() && (projectRoot.endsWith('.xcodeproj') || projectRoot.endsWith('.xcworkspace'))) {
+            projectFile = projectRoot;
+        }
+    }
+    catch {
+        // ignore
+    }
+    // detect project if not a direct file
+    if (!projectFile) {
+        const projectFound = await exists(projectRoot);
+        if (projectFound) {
+            projectFile = await findFirst(projectRoot, ['.xcworkspace', '.xcodeproj'], 2);
+        }
+        else {
+            // attempt to find under cwd
+            projectFile = await findFirst(cwd, ['.xcworkspace', '.xcodeproj'], 3);
+        }
+    }
+    // 2) KMP Shared.framework detection (search for *.framework named Shared.framework)
+    let kmpFramework = null;
+    const projectSearchRoot = projectFile ? (fs.existsSync(projectFile) && fs.lstatSync(projectFile).isDirectory() ? projectFile : path.dirname(projectFile)) : cwd;
+    kmpFramework = await findFirst(projectSearchRoot, ['Shared.framework'], 5);
+    if (!kmpFramework)
+        kmpFramework = await findFirst(cwd, ['Shared.framework'], 6);
+    // 3) idb detection
+    const idbPath = getIdbCmd();
+    const idbAvailable = idbPath ? isIDBInstalled() : false;
+    // 4) idb_companion
+    const companionPath = commandWhich('idb_companion');
+    const companionAvailable = !!companionPath;
+    const suggestions = [];
+    if (!projectFile)
+        suggestions.push('Provide correct project path or ensure .xcodeproj/.xcworkspace exists in project dir');
+    if (!kmpFramework)
+        suggestions.push('Run KMP Gradle task to produce Shared.framework before xcodebuild (e.g., :shared:embedAndSignAppleFrameworkForXcode)');
+    if (!idbAvailable)
+        suggestions.push('Ensure idb is in PATH or set MCP_IDB_PATH / IDB_PATH');
+    if (!companionAvailable)
+        suggestions.push('Install idb_companion and ensure it is in PATH');
+    const result = {
+        ok: !!projectFile && !!idbAvailable,
+        project: {
+            root: projectRoot,
+            found: !!projectFile,
+            projectFile: projectFile
+        },
+        kmp: {
+            found: !!kmpFramework,
+            path: kmpFramework,
+            build: kmpBuild
+        },
+        idb: {
+            cmd: idbPath,
+            installed: idbAvailable
+        },
+        idb_companion: {
+            cmd: companionPath,
+            installed: companionAvailable
+        },
+        suggestions
+    };
+    if (startCompanion && udid) {
+        const started = startCompanionIfNeeded(companionPath, udid);
+        result.idb_companion.start = started;
+        if (started.started)
+            result.ok = result.ok && true;
+    }
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.ok ? 0 : 2);
+}
+main().catch(e => {
+    // Report structured error on stdout (avoid noisy stderr in normal runs)
+    console.log(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }, null, 2));
+    process.exit(2);
+});

package/dist/cli/ios/run-ios-smoke.js

@@ -0,0 +1,28 @@
+import { iOSObserve } from '../../ios/observe.js';
+import { iOSManage } from '../../ios/manage.js';
+async function main() {
+    const appId = process.argv[2] || 'com.apple.springboard';
+    const deviceId = 'booted';
+    const obs = new iOSObserve();
+    const manage = new iOSManage();
+    try {
+        console.log('[1] startApp ->', appId);
+        const start = await manage.startApp(appId, deviceId);
+        console.log('start result:', start);
+        console.log('[2] captureScreenshot');
+        const shot = await obs.captureScreenshot(deviceId);
+        console.log('screenshot OK? size:', shot && shot.screenshot ? shot.screenshot.length : 0);
+        console.log('[3] getLogs');
+        const logs = await obs.getLogs(appId, undefined);
+        console.log('logs count:', logs.logCount);
+        console.log('[4] terminateApp');
+        const term = await manage.terminateApp(appId, deviceId);
+        console.log('terminate:', term);
+        console.log('SMOKE OK');
+    }
+    catch (err) {
+        console.error('SMOKE ERROR:', err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+main();

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/manage.js

@@ -6,39 +6,147 @@ 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 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 => {
-                    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) };

package/docs/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.12.1]
+- Improve iOS build/install reliability: project auto-scan, explicit simulator destination, configurable watchdog timeout (MCP_XCODEBUILD_TIMEOUT) and retries (MCP_XCODEBUILD_RETRIES), and DerivedData fallback for locating .app artifacts.
+- Make install_app capable of building iOS projects before installing so agents can autonomously fix, build, install and validate apps.
+- Migrate CLI scripts into typed src/cli/* modules and update npm scripts; fix ESM import paths and lint issues.
+- Add preflight checks and idb resolution helpers (getIdbCmd, isIDBInstalled) and add idb_companion health checks.
+- Capture build stdout/stderr into build-results/ for easier diagnostics and surfaced suggestions when KMP frameworks are missing.
+- Add device test runner under test/device and gate device-dependent tests behind RUN_DEVICE_TESTS.
+
+
 ## [0.12.0]
 - Add iOS idb integration: config-driven idb path resolution (MCP_IDB_PATH / MCP config / IDB_PATH), robust idb detection and parsing of `ui describe-all` output.
 - Add reusable helpers: `isIDBInstalled()` and `getIdbCmd()` to centralise idb resolution and diagnostics.

package/eslint.config.js

@@ -12,7 +12,6 @@ export default [
       '.vscode/',
       'coverage/',
       '.env',
-      'scripts/'
     ]
   },
   // Apply rules to JS/TS source
@@ -58,9 +57,9 @@ export default [
       '@typescript-eslint/no-unused-vars': 'off'
     }
   },
-  // Apply rules to scripts and tooling (support TS syntax in scripts)
+  // Apply rules to CLI tooling
   {
-    files: ['scripts/**/*.ts', 'scripts/**/*.js'],
+    files: ['src/cli/**/*.ts', 'src/cli/**/*.js'],
     languageOptions: {
       parser: tsParser,
       parserOptions: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
@@ -10,8 +10,9 @@
     "build": "tsc",
     "start": "node ./dist/server.js",
     "prepare": "npm run build",
-    "healthcheck": "tsx ./scripts/check-idb.ts",
-    "install-idb": "tsx ./scripts/install-idb.ts",
+    "healthcheck": "tsx ./src/cli/idb/check-idb.ts",
+    "install-idb": "tsx ./src/cli/idb/install-idb.ts",
+    "preflight-ios": "tsx ./src/cli/ios/preflight-ios.ts",
     "test:unit": "tsx test/unit/index.ts",
     "test:integration": "npm run build && tsx test/device/index.ts",
     "test:device": "npm run build && tsx test/device/index.ts",
@@ -19,6 +20,7 @@
     "lint": "eslint --ext .ts,.js src test --quiet",
     "lint:fix": "eslint --ext .ts,.js src test --fix"
   },
+
   "engines": {
     "node": ">=18"
   },

package/{scripts → src/cli/idb}/check-idb.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { execSync, spawnSync } from 'child_process'
-import { main as installMain } from './install-idb'
-import { getIdbCmd, isIDBInstalled } from './idb-helper'
+import { main as installMain } from './install-idb.js'
+import { getIdbCmd, isIDBInstalled } from './idb-helper.js'
 
 function which(cmd: string): string | null {
   try {
@@ -24,7 +24,7 @@ async function runInstaller() {
     // prefer invoking the TS script via npx/tsx to ensure environment
     const runner = which('npx') ? 'npx' : which('tsx') ? 'tsx' : null
     if (runner) {
-      const args = runner === 'npx' ? ['tsx', './scripts/install-idb.ts'] : ['./scripts/install-idb.ts']
+      const args = runner === 'npx' ? ['tsx', './src/cli/idb/install-idb.ts'] : ['./src/cli/idb/install-idb.ts']
       const res = spawnSync(runner, args, { stdio: 'inherit' as any })
       return typeof res.status === 'number' ? res.status === 0 : false
     }
@@ -59,7 +59,7 @@ try {
   const auto = process.env.MCP_AUTO_INSTALL_IDB === 'true'
   if (auto) {
     print('MCP_AUTO_INSTALL_IDB=true, attempting installer...')
-    const ok = runInstaller()
+    const ok = await runInstaller()
     if (ok) process.exit(0)
     print('Installer failed or did not produce idb')
     process.exit(2)

package/{scripts → src/cli/idb}/idb-helper.ts

@@ -1,6 +1,5 @@
 import { execSync, spawnSync } from 'child_process'
 import fs from 'fs'
-import path from 'path'
 
 export function getConfiguredIdbPath(): string | undefined {
   if (process.env.MCP_IDB_PATH) return process.env.MCP_IDB_PATH

package/{scripts → src/cli/idb}/install-idb.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { execSync, spawnSync } from 'child_process'
+import { spawnSync } from 'child_process'
 import readline from 'readline'
-import { getIdbCmd, isIDBInstalled, commandWhich } from './idb-helper'
+import { getIdbCmd, isIDBInstalled, commandWhich } from './idb-helper.js'
 
 const IDB_PKG = 'fb-idb'
 
@@ -67,7 +67,7 @@ async function main() {
         console.warn(`${a.name} install failed: ${e instanceof Error ? e.message : String(e)}`)
       }
 
-      const found = which('idb') || which('command -v idb')
+      const found = commandWhich('idb') || commandWhich('command -v idb')
       if (found) {
         console.log('idb installed at:', found)
         process.exit(0)

package/src/cli/ios/preflight-ios.ts

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import fs from 'fs'
+import path from 'path'
+import { spawn } from 'child_process'
+import { getIdbCmd, isIDBInstalled, commandWhich } from '../idb/idb-helper.js'
+
+async function exists(p: string) {
+  try { await fs.promises.access(p); return true } catch { return false }
+}
+
+async function findFirst(root: string, patterns: string[], maxDepth = 4): Promise<string | null> {
+  const queue: Array<{dir:string, depth:number}> = [{dir: root, depth:0}]
+  while (queue.length) {
+    const {dir, depth} = queue.shift()!
+    try {
+      console.error('DEBUG findFirst: reading dir', dir, 'depth', depth)
+      const ents: fs.Dirent[] = await fs.promises.readdir(dir, { withFileTypes: true })
+      console.error('DEBUG findFirst: entries', ents.map(e=>e.name))
+      for (const e of ents) {
+        const full = path.join(dir, e.name)
+        for (const p of patterns) {
+          if (e.name.endsWith(p)) {
+            console.error('DEBUG findFirst: matched', full)
+            return full
+          }
+        }
+        if (e.isDirectory() && depth < maxDepth) queue.push({dir: full, depth: depth+1})
+      }
+    } catch (err) {
+      console.error('DEBUG findFirst: read failed for', dir, err)
+      // ignore
+    }
+  }
+  return null
+}
+
+function startCompanionIfNeeded(companionPath: string | null, udid: string | null) {
+  if (!companionPath || !udid) return { started: false, error: 'missing companion or udid' }
+  try {
+    const child = spawn(companionPath, ['--udid', udid], { detached: true, stdio: 'ignore' })
+    child.unref()
+    return { started: true }
+  } catch (e:any) {
+    return { started: false, error: e.message }
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  let projectArg: string | undefined
+  let udid: string | undefined
+  let startCompanion = false
+  let kmpBuild: any = null
+  for (let i=0;i<args.length;i++) {
+    const a = args[i]
+    if (a === '--project' && args[i+1]) { projectArg = args[i+1]; i++ }
+    else if (a === '--udid' && args[i+1]) { udid = args[i+1]; i++ }
+    else if (a === '--start-companion') startCompanion = true
+    else if (!projectArg) projectArg = a
+  }
+
+  const cwd = process.cwd()
+  const projectRoot = projectArg ? path.resolve(projectArg) : cwd
+
+  // If user passed a direct .xcodeproj or .xcworkspace path, accept it as the projectFile
+  let projectFile: string | null = null
+  try {
+    const stat = await fs.promises.stat(projectRoot)
+    if (stat.isFile() && (projectRoot.endsWith('.xcodeproj') || projectRoot.endsWith('.xcworkspace'))) {
+      projectFile = projectRoot
+    }
+  } catch {
+    // ignore
+  }
+
+  // detect project if not a direct file
+  if (!projectFile) {
+    const projectFound = await exists(projectRoot)
+    if (projectFound) {
+      projectFile = await findFirst(projectRoot, ['.xcworkspace', '.xcodeproj'], 2)
+    } else {
+      // attempt to find under cwd
+      projectFile = await findFirst(cwd, ['.xcworkspace', '.xcodeproj'], 3)
+    }
+  }
+
+  // 2) KMP Shared.framework detection (search for *.framework named Shared.framework)
+  let kmpFramework: string | null = null
+  const projectSearchRoot = projectFile ? (fs.existsSync(projectFile) && fs.lstatSync(projectFile).isDirectory() ? projectFile : path.dirname(projectFile)) : cwd
+  kmpFramework = await findFirst(projectSearchRoot, ['Shared.framework'], 5)
+  if (!kmpFramework) kmpFramework = await findFirst(cwd, ['Shared.framework'], 6)
+
+  // 3) idb detection
+  const idbPath = getIdbCmd()
+  const idbAvailable = idbPath ? isIDBInstalled() : false
+
+  // 4) idb_companion
+  const companionPath = commandWhich('idb_companion')
+  const companionAvailable = !!companionPath
+
+  const suggestions: string[] = []
+  if (!projectFile) suggestions.push('Provide correct project path or ensure .xcodeproj/.xcworkspace exists in project dir')
+  if (!kmpFramework) suggestions.push('Run KMP Gradle task to produce Shared.framework before xcodebuild (e.g., :shared:embedAndSignAppleFrameworkForXcode)')
+  if (!idbAvailable) suggestions.push('Ensure idb is in PATH or set MCP_IDB_PATH / IDB_PATH')
+  if (!companionAvailable) suggestions.push('Install idb_companion and ensure it is in PATH')
+
+  const result: any = {
+    ok: !!projectFile && !!idbAvailable,
+    project: {
+      root: projectRoot,
+      found: !!projectFile,
+      projectFile: projectFile
+    },
+    kmp: {
+      found: !!kmpFramework,
+      path: kmpFramework,
+      build: kmpBuild
+    },
+    idb: {
+      cmd: idbPath,
+      installed: idbAvailable
+    },
+    idb_companion: {
+      cmd: companionPath,
+      installed: companionAvailable
+    },
+    suggestions
+  }
+
+  if (startCompanion && udid) {
+    const started = startCompanionIfNeeded(companionPath, udid)
+    result.idb_companion.start = started
+    if (started.started) result.ok = result.ok && true
+  }
+
+  console.log(JSON.stringify(result, null, 2))
+  process.exit(result.ok ? 0 : 2)
+}
+
+main().catch(e => {
+  // Report structured error on stdout (avoid noisy stderr in normal runs)
+  console.log(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }, null, 2))
+  process.exit(2)
+})

package/{scripts → src/cli/ios}/run-ios-smoke.ts

@@ -1,5 +1,5 @@
-import { iOSObserve } from '../src/ios/observe.js';
-import { iOSManage } from '../src/ios/manage.js';
+import { iOSObserve } from '../../ios/observe.js';
+import { iOSManage } from '../../ios/manage.js';
 
 async function main() {
   const appId = process.argv[2] || 'com.apple.springboard';

package/{scripts → src/cli/ios}/run-ios-ui-tree-tap.ts

@@ -1,5 +1,5 @@
-import { iOSObserve } from '../src/ios/observe.js';
-import { iOSInteract } from '../src/ios/interact.js';
+import { iOSObserve } from '../../ios/observe.js';
+import { iOSInteract } from '../../ios/interact.js';
 
 async function main() {
   const deviceId = 'booted';

package/src/ios/manage.ts

@@ -8,37 +8,154 @@ export class iOSManage {
   async build(projectPath: string, _variant?: string): Promise<{ artifactPath: string, output?: string } | { error: string }> {
     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) return { error: 'No Xcode project or workspace found' }
+      // Look for an Xcode workspace or project at the provided path. If not present, scan subdirectories (limited depth)
+      async function findProject(root: string, maxDepth = 3): Promise<{ dir: string, workspace?: string, proj?: string } | null> {
+        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: string[]
       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<void>((resolve, reject) => {
-        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 => {
-          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: any = null
+
+      for (let attempt = 1; attempt <= tries; attempt++) {
+        // Run xcodebuild with a watchdog
+        const res = await new Promise<{ code: number | null, stdout: string, stderr: string, killedByWatchdog?: boolean }>((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) }
     }

package/scripts/check-idb.js

@@ -1,83 +0,0 @@
-#!/usr/bin/env node
-import { execSync, spawnSync } from 'child_process';
-import { main as installMain } from './install-idb';
-function which(cmd) {
-    try {
-        // Prefer POSIX `command -v` which can resolve shell builtins. Use spawnSync
-        // to avoid shell interpolation and injection risks. Fall back to `which`.
-        const res = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] });
-        if (res && res.status === 0 && res.stdout) return res.stdout.toString().trim();
-        return execSync(`which ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
-    }
-    catch {
-        return null;
-    }
-}
-function print(...args) {
-    console.log(...args);
-}
-async function runInstaller() {
-    try {
-        // prefer invoking the TS script via npx/tsx to ensure environment
-        const runner = which('npx') ? 'npx' : which('tsx') ? 'tsx' : null;
-        if (runner) {
-            const args = runner === 'npx' ? ['tsx', './scripts/install-idb.ts'] : ['./scripts/install-idb.ts'];
-            const res = spawnSync(runner, args, { stdio: 'inherit' });
-            return typeof res.status === 'number' ? res.status === 0 : false;
-        }
-        // fallback: attempt to import and run the installer directly (may rely on ts-node/tsx)
-        try {
-            // call the exported main; it returns a promise
-            await installMain();
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    catch (e) {
-        console.error('Failed to run installer:', e instanceof Error ? e.message : String(e));
-        return false;
-    }
-}
-(async () => {
-    try {
-        print('PATH=', process.env.PATH);
-        const idb = process.env.IDB_PATH || which('idb');
-        print('which idb:', idb);
-        if (idb) {
-            try {
-                print('idb --version:', execSync('idb --version', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim());
-            }
-            catch (e) {
-                print('idb --version: (failed)', e instanceof Error ? e.message : String(e));
-            }
-            const companion = which('idb_companion');
-            print('which idb_companion:', companion);
-            if (companion)
-                try {
-                    print('idb_companion --version:', execSync('idb_companion --version', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim());
-                }
-                catch (e) {
-                    print('idb_companion --version: (failed)', e instanceof Error ? e.message : String(e));
-                }
-            process.exit(0);
-        }
-        print('idb not found');
-        const auto = process.env.MCP_AUTO_INSTALL_IDB === 'true';
-        if (auto) {
-            print('MCP_AUTO_INSTALL_IDB=true, attempting installer...');
-            const ok = await runInstaller();
-            if (ok)
-                process.exit(0);
-            print('Installer failed or did not produce idb');
-            process.exit(2);
-        }
-        print('Set MCP_AUTO_INSTALL_IDB=true to attempt automatic installation (CI-friendly).');
-        process.exit(2);
-    }
-    catch (e) {
-        console.error('idb healthcheck failed:', e instanceof Error ? e.message : String(e));
-        process.exit(2);
-    }
-})();