mobile-debug-mcp 0.14.0 → 0.15.0

package/dist/utils/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/utils/cli/ios/run-ios-smoke.js

@@ -0,0 +1,28 @@
+import { iOSObserve } from '../../../observe/index.js';
+import { iOSManage } from '../../../manage/index.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/utils/cli/ios/run-ios-ui-tree-tap.js

@@ -0,0 +1,29 @@
+import { iOSObserve } from '../../../observe/index.js';
+import { iOSInteract } from '../../../interact/index.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/utils/diagnostics.js

@@ -25,7 +25,7 @@ export class DiagnosticError extends Error {
 }
 // Exec ADB with diagnostics — moved from src/android/diagnostics.ts
 import { spawnSync } from 'child_process';
-import { getAdbCmd } from '../android/utils.js';
+import { getAdbCmd } from './android/utils.js';
 export function execAdbWithDiagnostics(args, deviceId) {
     const adbArgs = deviceId ? ['-s', deviceId, ...args] : args;
     const timeout = 120000;

package/dist/utils/ios/utils.js

@@ -0,0 +1,301 @@
+import { execFile, spawn, execSync, spawnSync } from "child_process";
+import { promises as fsPromises } from 'fs';
+import path from 'path';
+import { makeEnvSnapshot } from '../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)
+        return;
+    // Allow alphanumeric, dots, hyphens, and underscores.
+    if (!/^[a-zA-Z0-9.\-_]+$/.test(bundleId)) {
+        throw new Error(`Invalid Bundle ID: ${bundleId}. Must contain only alphanumeric characters, dots, hyphens, or underscores.`);
+    }
+}
+export function execCommand(args, deviceId = "booted") {
+    return new Promise((resolve, reject) => {
+        // Use spawn for better stream control and consistency with Android implementation
+        const child = spawn(getXcrunCmd(), args);
+        let stdout = '';
+        let stderr = '';
+        if (child.stdout) {
+            child.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+        }
+        if (child.stderr) {
+            child.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+        }
+        const 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: ${getXcrunCmd()} ${args.join(' ')}`));
+        }, timeoutMs);
+        child.on('close', (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                reject(new Error(stderr.trim() || `Command failed with code ${code}`));
+            }
+            else {
+                resolve({ output: stdout.trim(), device: { platform: "ios", id: deviceId } });
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+    });
+}
+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 {
+        const parts = runtime.split('.');
+        const lastPart = parts[parts.length - 1]; // e.g. "iOS-17-0"
+        // Split by hyphen to separate OS from version numbers
+        // e.g. "iOS-17-0" -> ["iOS", "17", "0"]
+        const segments = lastPart.split('-');
+        if (segments.length > 1) {
+            const os = segments[0]; // "iOS"
+            const version = segments.slice(1).join('.'); // "17.0"
+            return `${os} ${version}`;
+        }
+        return lastPart;
+    }
+    catch {
+        return runtime;
+    }
+}
+export async function findAppBundle(dir) {
+    const entries = await fsPromises.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            if (full.endsWith('.app'))
+                return full;
+            const found = await findAppBundle(full);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+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(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
+            const fallback = {
+                platform: "ios",
+                id: deviceId,
+                osVersion: "Unknown",
+                model: "Simulator",
+                simulator: true,
+            };
+            if (err || !stdout) {
+                resolve(fallback);
+                return;
+            }
+            try {
+                const data = JSON.parse(stdout);
+                const devicesMap = data.devices || {};
+                for (const runtime in devicesMap) {
+                    const devices = devicesMap[runtime];
+                    if (Array.isArray(devices)) {
+                        for (const device of devices) {
+                            if (deviceId === "booted" || device.udid === deviceId) {
+                                resolve({
+                                    platform: "ios",
+                                    id: device.udid,
+                                    osVersion: parseRuntimeName(runtime),
+                                    model: device.name,
+                                    simulator: true,
+                                });
+                                return;
+                            }
+                        }
+                    }
+                }
+                resolve(fallback);
+            }
+            catch {
+                resolve(fallback);
+            }
+        });
+    });
+}
+export async function listIOSDevices(appId) {
+    return new Promise((resolve) => {
+        // Query all devices and separately query booted devices to mark them
+        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], (err, stdout) => {
+            if (err || !stdout)
+                return resolve([]);
+            try {
+                const data = JSON.parse(stdout);
+                const devicesMap = data.devices || {};
+                const out = [];
+                const checks = [];
+                // Get booted devices set
+                execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err2, stdout2) => {
+                    const bootedSet = new Set();
+                    if (!err2 && stdout2) {
+                        try {
+                            const bdata = JSON.parse(stdout2);
+                            const bmap = bdata.devices || {};
+                            for (const rt in bmap) {
+                                const devs = bmap[rt];
+                                if (Array.isArray(devs))
+                                    for (const d of devs)
+                                        bootedSet.add(d.udid);
+                            }
+                        }
+                        catch { }
+                    }
+                    for (const runtime in devicesMap) {
+                        const devices = devicesMap[runtime];
+                        if (Array.isArray(devices)) {
+                            for (const device of devices) {
+                                const info = {
+                                    platform: 'ios',
+                                    id: device.udid,
+                                    osVersion: parseRuntimeName(runtime),
+                                    model: device.name,
+                                    simulator: true,
+                                    booted: bootedSet.has(device.udid)
+                                };
+                                if (appId) {
+                                    // check if installed
+                                    const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
+                                        .then(() => { info.appInstalled = true; })
+                                        .catch(() => { info.appInstalled = false; })
+                                        .then(() => { out.push(info); });
+                                    checks.push(p);
+                                }
+                                else {
+                                    out.push(info);
+                                }
+                            }
+                        }
+                    }
+                    Promise.all(checks).then(() => resolve(out)).catch(() => resolve(out));
+                });
+            }
+            catch {
+                resolve([]);
+            }
+        });
+    });
+}

package/dist/utils/resolve-device.js

@@ -1,5 +1,5 @@
-import { listAndroidDevices } from "../android/utils.js";
-import { listIOSDevices } from "../ios/utils.js";
+import { listAndroidDevices } from "./android/utils.js";
+import { listIOSDevices } from "./ios/utils.js";
 function parseNumericVersion(v) {
     if (!v)
         return 0;

package/docs/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.15.0]
+- Reorganised repository for cohesion: merged tool handlers into feature entrypoints (src/observe, src/interact, src/manage) and moved platform helpers and CLI tooling into src/utils/{android,ios,cli}.
+- Added computeScreenFingerprint utility used by observe/interact to normalise UI element significance across platforms (fingerprint shared between Android and iOS implementations).
+
 ## [0.14.0]
 - Added `scroll_to_element` tool: platform-aware helper that scrolls until a UI element matching a selector is visible. Supports Android and iOS with configurable options: direction, maxScrolls, and scrollAmount. Includes unit tests and device runners under `test/device/` for manual E2E validation.
 - Moved scroll logic into platform-specific implementations (`src/android/interact.ts`, `src/ios/interact.ts`) and delegated from `src/tools/interact.ts` to centralise platform behaviour.

package/docs/tools/observe.md

@@ -76,6 +76,30 @@ Response:
 
 ---
 
+## get_screen_fingerprint
+Generate a stable fingerprint representing the visible screen. Useful for detecting navigation changes, preventing loops, and synchronisation.
+
+Input (optional):
+
+```
+{ "platform": "android", "deviceId": "emulator-5554" }
+```
+
+Response:
+
+```json
+{ "fingerprint": "<sha256_hex>", "activity": "com.example.app.MainActivity" }
+```
+
+Notes:
+- Uses get_ui_tree and (on Android) get_current_screen as inputs.
+- Normalises visible, interactable or structurally significant elements (class/type, resourceId, text, contentDesc).
+- Trims and lowercases text, filters out likely dynamic values (timestamps, counters).
+- Sorts deterministically (top-to-bottom, left-to-right) and limits elements to 50.
+- Returns fingerprint: null and an error message if the UI tree or activity cannot be retrieved.
+
+---
+
 ## start_log_stream / read_log_stream / stop_log_stream
 Start a background adb logcat stream and retrieve parsed NDJSON entries.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/src/{android/interact.ts → interact/android.ts}

@@ -1,7 +1,7 @@
 import { WaitForElementResponse, TapResponse, SwipeResponse, TypeTextResponse, PressBackResponse } from "../types.js"
-import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js"
-import { AndroidObserve } from "./observe.js"
-import { scrollToElementShared } from "../tools/scroll_to_element.js"
+import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../utils/android/utils.js"
+import { AndroidObserve } from "../observe/index.js"
+import { scrollToElementShared } from "../interact/shared/scroll_to_element.js"
 
 
 export class AndroidInteract {

package/src/{tools/interact.ts → interact/index.ts}

@@ -1,6 +1,8 @@
+import { AndroidInteract } from './android.js';
+import { iOSInteract } from './ios.js';
+export { AndroidInteract, iOSInteract };
+
 import { resolveTargetDevice } from '../utils/resolve-device.js'
-import { AndroidInteract } from '../android/interact.js'
-import { iOSInteract } from '../ios/interact.js'
 
 export class ToolsInteract {
 
@@ -43,4 +45,3 @@ export class ToolsInteract {
   }
 
 }
-

package/src/{ios/interact.ts → interact/ios.ts}

@@ -1,8 +1,8 @@
 import { spawn } from "child_process"
 import { WaitForElementResponse, TapResponse, SwipeResponse } from "../types.js"
-import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "./utils.js"
-import { iOSObserve } from "./observe.js"
-import { scrollToElementShared } from "../tools/scroll_to_element.js"
+import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../utils/ios/utils.js"
+import { iOSObserve } from "../observe/index.js"
+import { scrollToElementShared } from "../interact/shared/scroll_to_element.js"
 
 export class iOSInteract {
   private observe = new iOSObserve();