mobile-debug-mcp 0.32.0 → 0.32.2

package/README.md

@@ -1,4 +1,5 @@
 # Mobile Debug Tools
+[![npm version](https://img.shields.io/npm/v/mobile-debug-mcp.svg)](https://www.npmjs.com/package/mobile-debug-mcp)
 
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, interact and inspect Android/iOS apps from an MCP-compatible client.
 

package/dist/observe/android-tree-bridge.js

@@ -0,0 +1,202 @@
+import { execFile, spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { connect } from 'node:net';
+import path from 'node:path';
+import { execAdb, getAdbCmd } from '../utils/android/utils.js';
+import { remainingBudget } from '../utils/operation-budget.js';
+const packageName = 'dev.mobiledebugmcp.treebridge';
+const component = `${packageName}/.TreeInstrumentation`;
+const devicePort = 39019;
+const active = new Map();
+const starting = new Map();
+const stopping = new Map();
+const bridgeSupport = new Map();
+export function androidTreeBridgeEnabled() {
+    return Boolean(process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK);
+}
+function configuredApk() {
+    const configured = process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK;
+    if (!configured)
+        return null;
+    const apk = path.resolve(configured);
+    if (!existsSync(apk))
+        throw new Error(`Android UI tree bridge APK does not exist: ${apk}`);
+    return apk;
+}
+function unbudgetedAdb(deviceId, args) {
+    return new Promise((resolve, reject) => {
+        execFile(getAdbCmd(), ['-s', deviceId, ...args], { timeout: 5000 }, (error) => error ? reject(error) : resolve());
+    });
+}
+function request(bridge, command, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let output = '';
+        const socket = connect(bridge.hostPort, '127.0.0.1', () => socket.write(`${command}\n`));
+        socket.setTimeout(timeoutMs, () => socket.destroy(new Error(`Android UI tree bridge ${command} timed out`)));
+        socket.on('data', (chunk) => {
+            output += chunk.toString();
+            if (command === 'STOP' && output.startsWith('OK\n')) {
+                resolve(output);
+                socket.destroy();
+            }
+        });
+        socket.on('error', reject);
+        socket.on('end', () => resolve(output));
+    });
+}
+function waitForChildClose(bridge, timeoutMs) {
+    if (bridge.childClosed)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const onClose = () => { clearTimeout(timer); resolve(); };
+        const timer = setTimeout(() => {
+            bridge.child.off('close', onClose);
+            reject(new Error('Android UI tree bridge child did not exit'));
+        }, timeoutMs);
+        bridge.child.once('close', onClose);
+    });
+}
+async function stop(bridge) {
+    const pending = stopping.get(bridge.deviceId);
+    if (pending)
+        return pending;
+    bridge.closed = true;
+    const cleanup = (async () => {
+        await request(bridge, 'STOP', 1000).catch(() => '');
+        let forceStopError;
+        try {
+            await unbudgetedAdb(bridge.deviceId, ['shell', 'am', 'force-stop', packageName]);
+        }
+        catch (error) {
+            forceStopError = error;
+        }
+        try {
+            await waitForChildClose(bridge, 1000);
+        }
+        catch {
+            bridge.child.kill('SIGTERM');
+            try {
+                await waitForChildClose(bridge, 1000);
+            }
+            catch {
+                bridge.child.kill('SIGKILL');
+                await waitForChildClose(bridge, 2000).catch(() => { });
+            }
+        }
+        let forwardError;
+        try {
+            await unbudgetedAdb(bridge.deviceId, ['forward', '--remove', `tcp:${bridge.hostPort}`]);
+        }
+        catch (error) {
+            forwardError = error;
+        }
+        if (forceStopError || !bridge.childClosed || forwardError) {
+            const reason = forceStopError ?? (!bridge.childClosed ? 'instrumentation child did not close' : forwardError);
+            throw new Error(`BRIDGE_CLEANUP_UNCONFIRMED: ${reason instanceof Error ? reason.message : String(reason)}`);
+        }
+        if (active.get(bridge.deviceId) === bridge)
+            active.delete(bridge.deviceId);
+    })();
+    stopping.set(bridge.deviceId, cleanup);
+    try {
+        await cleanup;
+    }
+    finally {
+        stopping.delete(bridge.deviceId);
+    }
+}
+async function launch(deviceId, apk) {
+    await unbudgetedAdb(deviceId, ['shell', 'am', 'force-stop', packageName]);
+    try {
+        await execAdb(['install', '-r', apk], deviceId);
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !error.message.includes('INSTALL_FAILED_UPDATE_INCOMPATIBLE'))
+            throw error;
+        await execAdb(['uninstall', packageName], deviceId);
+        await execAdb(['install', '-r', apk], deviceId);
+    }
+    const hostPort = Number(await execAdb(['forward', 'tcp:0', `tcp:${devicePort}`], deviceId));
+    if (!Number.isInteger(hostPort) || hostPort <= 0)
+        throw new Error('Android UI tree bridge could not obtain a host port');
+    const child = spawn(getAdbCmd(), ['-s', deviceId, 'shell', 'am', 'instrument', '-w', component], { stdio: 'ignore' });
+    const bridge = { deviceId, hostPort, child, closed: false, childClosed: false };
+    child.once('close', () => { bridge.childClosed = true; });
+    child.once('error', () => { });
+    active.set(deviceId, bridge);
+    try {
+        const deadline = Date.now() + Math.min(remainingBudget(3000), 3000);
+        while (Date.now() < deadline) {
+            if (bridge.childClosed || child.exitCode !== null || child.signalCode !== null)
+                throw new Error('Android UI tree bridge exited during startup');
+            try {
+                if ((await request(bridge, 'PING', 250)).startsWith('OK\n')) {
+                    return bridge;
+                }
+            }
+            catch { /* The instrumentation process may still be starting. */ }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        throw new Error('Android UI tree bridge did not become ready');
+    }
+    catch (error) {
+        await stop(bridge);
+        throw error;
+    }
+}
+async function ensure(deviceId, apk) {
+    const pending = starting.get(deviceId);
+    if (pending)
+        return pending;
+    const ready = active.get(deviceId);
+    if (ready && !ready.closed && !ready.childClosed && ready.child.exitCode === null && ready.child.signalCode === null)
+        return ready;
+    if (ready)
+        await stop(ready);
+    const promise = launch(deviceId, apk);
+    starting.set(deviceId, promise);
+    try {
+        return await promise;
+    }
+    finally {
+        starting.delete(deviceId);
+    }
+}
+/** Returns null only after the bridge has been stopped, so legacy acquisition is safe. */
+export async function readAndroidTreeFromBridge(deviceId) {
+    const apk = configuredApk();
+    if (!apk)
+        return null;
+    let bridge;
+    try {
+        let supported = bridgeSupport.get(deviceId);
+        if (supported === undefined) {
+            const sdkLevel = Number(await execAdb(['shell', 'getprop', 'ro.build.version.sdk'], deviceId));
+            supported = Number.isInteger(sdkLevel) && sdkLevel >= 34;
+            if (supported)
+                bridgeSupport.set(deviceId, true);
+        }
+        if (!supported)
+            return null;
+        bridge = await ensure(deviceId, apk);
+        const output = await request(bridge, 'TREE', remainingBudget(10000));
+        if (!output.startsWith('OK\n') || !output.includes('<hierarchy'))
+            throw new Error('Android UI tree bridge returned invalid hierarchy output');
+        return output.slice(3);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('BRIDGE_CLEANUP_UNCONFIRMED'))
+            throw error;
+        if (bridge)
+            await stop(bridge);
+        if (error instanceof Error && error.message === 'ACTION_TIMEOUT')
+            throw error;
+        return null;
+    }
+}
+process.once('exit', () => {
+    for (const bridge of active.values()) {
+        spawnSync(getAdbCmd(), ['-s', bridge.deviceId, 'shell', 'am', 'force-stop', packageName], { timeout: 2000, stdio: 'ignore' });
+        spawnSync(getAdbCmd(), ['-s', bridge.deviceId, 'forward', '--remove', `tcp:${bridge.hostPort}`], { timeout: 2000, stdio: 'ignore' });
+    }
+});

package/dist/observe/android.js

@@ -8,17 +8,28 @@ import { computeScreenFingerprint } from "../utils/ui/index.js";
 import { parsePngSize } from "../utils/image.js";
 import { deriveSnapshotMetadata } from "./snapshot-metadata.js";
 import { remainingBudget } from '../utils/operation-budget.js';
+import { createObservationMeasurement } from './performance-metrics.js';
+import { androidTreeBridgeEnabled, readAndroidTreeFromBridge } from './android-tree-bridge.js';
 const activeLogStreams = new Map();
 export class AndroidObserve {
     async getDeviceMetadata(appId, deviceId) {
         return getAndroidDeviceMetadata(appId, deviceId);
     }
     async getUITree(deviceId) {
-        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const measurement = createObservationMeasurement('android');
+        let metadata;
+        try {
+            metadata = await measurement.timed('metadata_ms', () => getAndroidDeviceMetadata("", deviceId));
+        }
+        catch (error) {
+            measurement.setOutcome('unavailable');
+            measurement.finish();
+            throw error;
+        }
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
             // Get screen resolution first
-            const resolution = await getScreenResolution(deviceId);
+            const resolution = await measurement.timed('resolution_ms', () => getScreenResolution(deviceId));
             if (resolution.width === 0 && resolution.height === 0) {
                 throw new Error("Failed to get screen resolution. Is the device connected and authorized?");
             }
@@ -30,20 +41,38 @@ export class AndroidObserve {
                 remainingBudget();
                 attempts++;
                 try {
-                    // Stabilization delay
-                    await delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100))); // 300ms, 400ms, 500ms...
+                    // The first read starts immediately so it remains fresh for in-place UI changes.
+                    // Delay only a retry after a failed or invalid acquisition.
+                    if (attempts > 1) {
+                        await measurement.timed('observation_wait_ms', () => delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100))));
+                    }
                     remainingBudget();
-                    // Dump UI hierarchy
-                    await execAdb(['shell', 'uiautomator', 'dump', '/sdcard/ui.xml'], deviceId);
-                    // Read the file
-                    xmlContent = await execAdb(['shell', 'cat', '/sdcard/ui.xml'], deviceId);
-                    // Check validity
-                    if (xmlContent && xmlContent.trim().length > 0 && !xmlContent.includes("ERROR:")) {
-                        break; // Success
+                    let bridgeContent = null;
+                    if (androidTreeBridgeEnabled()) {
+                        try {
+                            bridgeContent = await measurement.physicalRead(async () => {
+                                const content = await readAndroidTreeFromBridge(deviceInfo.id);
+                                if (!content)
+                                    throw new Error('Android UI tree bridge unavailable');
+                                return content;
+                            });
+                        }
+                        catch (error) {
+                            if (error instanceof Error && (error.message === 'ACTION_TIMEOUT' || error.message.startsWith('BRIDGE_CLEANUP_UNCONFIRMED')))
+                                throw error;
+                        }
                     }
+                    xmlContent = bridgeContent ?? await measurement.physicalRead(async () => {
+                        await execAdb(['shell', 'uiautomator', 'dump', '/sdcard/ui.xml'], deviceId);
+                        const content = await execAdb(['shell', 'cat', '/sdcard/ui.xml'], deviceId);
+                        if (!content || !content.trim() || content.includes('ERROR:'))
+                            throw new Error('Empty or invalid UI dump');
+                        return content;
+                    });
+                    break;
                 }
                 catch (e) {
-                    if (e instanceof Error && e.message === 'ACTION_TIMEOUT')
+                    if (e instanceof Error && (e.message === 'ACTION_TIMEOUT' || e.message.startsWith('BRIDGE_CLEANUP_UNCONFIRMED')))
                         throw e;
                     console.error(`Attempt ${attempts} failed: ${e}`);
                 }
@@ -55,7 +84,7 @@ export class AndroidObserve {
                 ignoreAttributes: false,
                 attributeNamePrefix: "@_"
             });
-            const result = parser.parse(xmlContent);
+            const result = await measurement.timed('parse_ms', async () => parser.parse(xmlContent));
             const elements = [];
             // The root is usually hierarchy -> node
             if (result.hierarchy && result.hierarchy.node) {
@@ -72,18 +101,23 @@ export class AndroidObserve {
                 resolution,
                 elements
             }, 'ui_tree');
-            return {
+            measurement.setOutcome('observed');
+            const response = measurement.bindObservation({
                 device: deviceInfo,
                 screen: "",
                 resolution,
                 elements,
                 ...snapshotMetadata
-            };
+            });
+            measurement.finish();
+            return response;
         }
         catch (e) {
             const errorMessage = `Failed to get UI tree. ADB Path: '${getAdbCmd()}'. Error: ${e instanceof Error ? e.message : String(e)}`;
             console.error(errorMessage);
             const snapshotMetadata = deriveSnapshotMetadata(`android:${deviceInfo.id}`, null, 'ui_tree');
+            measurement.setOutcome('unavailable');
+            measurement.finish();
             return {
                 device: deviceInfo,
                 screen: "",

package/dist/observe/ios.js

@@ -1,5 +1,7 @@
 import { spawn } from "child_process";
 import { remainingBudget } from '../utils/operation-budget.js';
+import { execCmd } from '../utils/exec.js';
+import { createObservationMeasurement } from './performance-metrics.js';
 import { promises as fs } from "fs";
 import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcrunCmd, isIDBInstalled } from "../utils/ios/utils.js";
 import { createWriteStream, promises as fsPromises } from 'fs';
@@ -483,11 +485,22 @@ export class iOSObserve {
         }
     }
     async getUITree(deviceId = "booted") {
-        const device = await getIOSDeviceMetadata(deviceId);
+        const measurement = createObservationMeasurement('ios');
+        let device;
+        try {
+            device = await measurement.timed('metadata_ms', () => getIOSDeviceMetadata(deviceId));
+        }
+        catch (error) {
+            measurement.setOutcome('unavailable');
+            measurement.finish();
+            throw error;
+        }
         const deviceKey = `ios:${device.id}`;
-        const idbExists = await isIDBInstalled();
+        const idbExists = await measurement.timed('capability_check_ms', () => isIDBInstalled());
         if (!idbExists) {
             const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree');
+            measurement.setOutcome('unavailable');
+            measurement.finish();
             return {
                 device,
                 screen: "",
@@ -505,30 +518,24 @@ export class iOSObserve {
             remainingBudget();
             attempts++;
             try {
-                await delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100)));
+                await measurement.timed('observation_wait_ms', () => delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100))));
                 remainingBudget();
                 const args = ['ui', 'describe-all', '--json'];
                 if (targetUdid) {
                     args.push('--udid', targetUdid);
                 }
-                const output = await new Promise((resolve, reject) => {
-                    const child = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
-                    let stdout = '';
-                    let stderr = '';
-                    child.stdout.on('data', (data) => stdout += data.toString());
-                    child.stderr.on('data', (data) => stderr += data.toString());
-                    child.on('error', (err) => reject(new Error(`Failed to execute idb: ${err.message}`)));
-                    child.on('close', (code) => {
-                        if (code !== 0) {
-                            reject(new Error(`idb failed (code ${code}): ${stderr.trim()}`));
-                        }
-                        else {
-                            resolve(stdout);
-                        }
-                    });
+                const output = await measurement.physicalRead(async () => {
+                    const result = await execCmd(getIdbCmd(), args, { timeout: remainingBudget() });
+                    if (result.stderr === 'ACTION_TIMEOUT')
+                        throw new Error('ACTION_TIMEOUT');
+                    if (result.exitCode !== 0)
+                        throw new Error(`idb failed (code ${result.exitCode}): ${result.stderr}`);
+                    if (!result.stdout.trim())
+                        throw new Error('Empty idb UI tree output');
+                    return result.stdout;
                 });
                 if (output && output.trim().length > 0) {
-                    jsonContent = JSON.parse(output);
+                    jsonContent = await measurement.timed('parse_ms', async () => JSON.parse(output));
                     break; // Success
                 }
             }
@@ -539,6 +546,8 @@ export class iOSObserve {
             }
             if (attempts === maxAttempts) {
                 const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree');
+                measurement.setOutcome('unavailable');
+                measurement.finish();
                 return {
                     device,
                     screen: "",
@@ -550,15 +559,17 @@ export class iOSObserve {
             }
         }
         try {
-            const elements = [];
-            if (Array.isArray(jsonContent)) {
-                for (const node of jsonContent) {
-                    traverseIDBNode(node, elements);
+            const elements = await measurement.timed('conversion_ms', async () => {
+                const parsed = [];
+                if (Array.isArray(jsonContent)) {
+                    for (const node of jsonContent)
+                        traverseIDBNode(node, parsed);
                 }
-            }
-            else {
-                traverseIDBNode(jsonContent, elements);
-            }
+                else {
+                    traverseIDBNode(jsonContent, parsed);
+                }
+                return parsed;
+            });
             let width = 0;
             let height = 0;
             if (elements.length > 0) {
@@ -571,16 +582,21 @@ export class iOSObserve {
                 resolution: { width, height },
                 elements
             }, 'ui_tree');
-            return {
+            measurement.setOutcome('observed');
+            const response = measurement.bindObservation({
                 device,
                 screen: "",
                 resolution: { width, height },
                 elements,
                 ...snapshotMetadata
-            };
+            });
+            measurement.finish();
+            return response;
         }
         catch (e) {
             const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree');
+            measurement.setOutcome('unavailable');
+            measurement.finish();
             return {
                 device,
                 screen: "",

package/dist/observe/performance-metrics.js

@@ -0,0 +1,124 @@
+import { randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+const context = new AsyncLocalStorage();
+const observationIds = new WeakMap();
+export function withObservationContext(value, operation) {
+    if (process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS !== '1')
+        return operation();
+    return context.run({ purpose: value.purpose ?? context.getStore()?.purpose ?? 'unspecified', stepId: value.stepId ?? context.getStore()?.stepId }, operation);
+}
+export function recordObservationEvent(event) {
+    if (process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS !== '1')
+        return;
+    const current = context.getStore();
+    process.stderr.write(`${JSON.stringify({
+        event: 'ui_tree_metric',
+        host_monotonic_ns: process.hrtime.bigint().toString(),
+        type: 'action_observation',
+        step_id: current?.stepId,
+        purpose: current?.purpose ?? 'unspecified',
+        ...event
+    })}\n`);
+}
+export function recordObservationConsumer(observation, purpose, stepId) {
+    if (process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS !== '1' || !observation || typeof observation !== 'object')
+        return;
+    const acquisitionId = observationIds.get(observation);
+    if (!acquisitionId)
+        return;
+    const current = context.getStore();
+    process.stderr.write(`${JSON.stringify({
+        event: 'ui_tree_metric',
+        host_monotonic_ns: process.hrtime.bigint().toString(),
+        type: 'observation_consumer',
+        acquisition_id: acquisitionId,
+        consumer_step_id: stepId ?? current?.stepId,
+        consumer_purpose: purpose,
+        reused_observations: 1
+    })}\n`);
+}
+export function createObservationMeasurement(platform) {
+    const enabled = process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS === '1';
+    const startedAt = enabled ? performance.now() : 0;
+    const id = enabled ? randomUUID() : undefined;
+    const current = context.getStore();
+    const durations = {};
+    let successfulOutput = false;
+    let outcome = 'unavailable';
+    let readAttempt = 0;
+    const emit = (event) => {
+        if (!enabled)
+            return;
+        process.stderr.write(`${JSON.stringify({
+            event: 'ui_tree_metric',
+            host_monotonic_ns: process.hrtime.bigint().toString(),
+            acquisition_id: id,
+            platform,
+            step_id: current?.stepId,
+            purpose: current?.purpose ?? 'unspecified',
+            ...event
+        })}\n`);
+    };
+    return {
+        id,
+        bindObservation(observation) {
+            if (enabled && id)
+                observationIds.set(observation, id);
+            return observation;
+        },
+        timed: async (stage, operation) => {
+            if (!enabled)
+                return operation();
+            const start = performance.now();
+            let success = true;
+            try {
+                return await operation();
+            }
+            catch (error) {
+                success = false;
+                throw error;
+            }
+            finally {
+                const elapsed = performance.now() - start;
+                durations[stage] = (durations[stage] ?? 0) + elapsed;
+                emit({ type: 'stage', stage, attempt_index: stage === 'parse_ms' ? readAttempt : undefined, elapsed_ms: elapsed, success });
+            }
+        },
+        physicalRead: async (operation) => {
+            if (!enabled)
+                return operation();
+            const start = performance.now();
+            readAttempt++;
+            emit({ type: 'physical_read_started', attempt_index: readAttempt });
+            try {
+                const result = await operation();
+                successfulOutput = true;
+                emit({ type: 'physical_read_completed', attempt_index: readAttempt, elapsed_ms: performance.now() - start, success: true });
+                return result;
+            }
+            catch (error) {
+                emit({ type: 'physical_read_completed', attempt_index: readAttempt, elapsed_ms: performance.now() - start, success: false });
+                throw error;
+            }
+        },
+        setOutcome(value) { if (enabled)
+            outcome = value; },
+        finish() {
+            if (!enabled)
+                return;
+            emit({
+                type: 'observation_consumer',
+                consumer_step_id: current?.stepId,
+                consumer_purpose: current?.purpose ?? 'unspecified',
+                reused_observations: 0
+            });
+            emit({
+                type: 'acquisition_completed',
+                elapsed_ms: performance.now() - startedAt,
+                successful_output: successfulOutput,
+                outcome,
+                durations_ms: durations
+            });
+        }
+    };
+}