mobile-debug-mcp 0.12.0 → 0.12.2

package/README.md

@@ -1,8 +1,8 @@
-# Mobile Dev Agent Tools
+# Mobile Dev 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 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/android/diagnostics.js

@@ -1,24 +1 @@
-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 };
-}
+export { execAdbWithDiagnostics } from '../utils/diagnostics.js';

package/dist/android/manage.js

@@ -3,7 +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 { execAdbWithDiagnostics } from '../utils/diagnostics.js';
 import { detectJavaHome } from '../utils/java.js';
 export class AndroidManage {
     async build(projectPath, _variant) {

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();