mobile-debug-mcp 0.15.0 → 0.17.0

package/dist/utils/ui/index.js

@@ -0,0 +1,169 @@
+import crypto from 'crypto';
+const ANDROID_STRUCTURAL_TYPES = ['Window', 'Application', 'View', 'ViewGroup', 'LinearLayout', 'FrameLayout', 'RelativeLayout', 'ScrollView', 'RecyclerView', 'TextView', 'ImageView'];
+const IOS_STRUCTURAL_TYPES = ['Window', 'Application', 'View', 'ViewController', 'UITableView', 'UICollectionView', 'UILabel', 'UIImageView', 'UIView', 'UIWindow', 'UIStackView', 'UITextView', 'UITableViewCell'];
+function isDynamicText(t) {
+    if (!t)
+        return false;
+    const txt = t.trim();
+    if (!txt)
+        return false;
+    if (/\b\d{1,2}:\d{2}\b/.test(txt))
+        return true;
+    if (/\b\d{4}-\d{2}-\d{2}\b/.test(txt))
+        return true;
+    if (/^\d+(?:\.\d+)?%$/.test(txt))
+        return true;
+    if (/^\d+$/.test(txt))
+        return true;
+    if (/^[\d,]{1,10}$/.test(txt))
+        return true;
+    return false;
+}
+function normalizeElement(e) {
+    return {
+        type: (e.type || '').toString(),
+        resourceId: (e.resourceId || '').toString(),
+        text: typeof e.text === 'string' ? (isDynamicText(e.text) ? '' : e.text.trim().toLowerCase()) : '',
+        contentDesc: (e.contentDescription || '').toString(),
+        bounds: Array.isArray(e.bounds) ? e.bounds.slice(0, 4).map((n) => Number(n) || 0) : [0, 0, 0, 0]
+    };
+}
+export function computeScreenFingerprint(tree, current, platform, limit = 50) {
+    try {
+        if (!tree || tree.error)
+            return { fingerprint: null, error: tree.error };
+        const activity = current && (current.activity || current.shortActivity) ? (current.activity || current.shortActivity) : '';
+        const candidates = (tree.elements || []).filter(e => {
+            if (!e)
+                return false;
+            if (!e.visible)
+                return false;
+            const hasStableText = typeof e.text === 'string' && e.text.trim().length > 0;
+            const hasResource = !!e.resourceId;
+            const interactable = !!e.clickable || !!e.enabled;
+            const structuralList = platform === 'android' ? ANDROID_STRUCTURAL_TYPES : IOS_STRUCTURAL_TYPES;
+            const structurallySignificant = hasStableText || hasResource || structuralList.includes(e.type || '');
+            return interactable || structurallySignificant;
+        });
+        const normalized = candidates.map(normalizeElement);
+        const filteredNormalized = normalized.filter(e => (e.text && e.text.length > 0) || (e.resourceId && e.resourceId.length > 0) || (e.contentDesc && e.contentDesc.length > 0));
+        filteredNormalized.sort((a, b) => {
+            const ay = (a.bounds && a.bounds[1]) || 0;
+            const by = (b.bounds && b.bounds[1]) || 0;
+            if (ay !== by)
+                return ay - by;
+            const ax = (a.bounds && a.bounds[0]) || 0;
+            const bx = (b.bounds && b.bounds[0]) || 0;
+            return ax - bx;
+        });
+        const limited = filteredNormalized.slice(0, Math.max(0, limit));
+        const payload = {
+            activity: platform === 'android' ? (activity || '') : '',
+            resolution: tree.resolution || { width: 0, height: 0 },
+            elements: limited.map(e => ({ type: e.type, resourceId: e.resourceId, text: e.text, contentDesc: e.contentDesc }))
+        };
+        const combined = JSON.stringify(payload);
+        const hash = crypto.createHash('sha256').update(combined).digest('hex');
+        return { fingerprint: hash, activity: activity };
+    }
+    catch (e) {
+        return { fingerprint: null, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+export async function scrollToElementShared(opts) {
+    const { selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId, fetchTree, swipe, stabilizationDelayMs = 350 } = opts;
+    const matchElement = (el) => {
+        if (!el)
+            return false;
+        if (selector.text !== undefined && selector.text !== el.text)
+            return false;
+        if (selector.resourceId !== undefined && selector.resourceId !== el.resourceId)
+            return false;
+        if (selector.contentDesc !== undefined && selector.contentDesc !== el.contentDescription)
+            return false;
+        if (selector.className !== undefined && selector.className !== el.type)
+            return false;
+        return true;
+    };
+    const isVisible = (el, resolution) => {
+        if (!el)
+            return false;
+        if (el.visible === false)
+            return false;
+        if (!el.bounds || !resolution || !resolution.width || !resolution.height)
+            return (el.visible === undefined ? true : !!el.visible);
+        const [left, top, right, bottom] = el.bounds;
+        const withinY = bottom > 0 && top < resolution.height;
+        const withinX = right > 0 && left < resolution.width;
+        return withinX && withinY;
+    };
+    const findVisibleMatch = (elements, resolution) => {
+        if (!Array.isArray(elements))
+            return null;
+        for (const e of elements) {
+            if (matchElement(e) && isVisible(e, resolution))
+                return e;
+        }
+        return null;
+    };
+    // Initial check
+    let tree = await fetchTree();
+    if (tree.error)
+        return { success: false, reason: tree.error, scrollsPerformed: 0 };
+    let found = findVisibleMatch(tree.elements, tree.resolution);
+    if (found) {
+        return { success: true, element: { text: found.text, resourceId: found.resourceId, bounds: found.bounds }, scrollsPerformed: 0 };
+    }
+    const fingerprintOf = (t) => {
+        try {
+            return JSON.stringify((t.elements || []).map((e) => ({ text: e.text, resourceId: e.resourceId, bounds: e.bounds })));
+        }
+        catch {
+            return '';
+        }
+    };
+    let prevFingerprint = fingerprintOf(tree);
+    const width = (tree.resolution && tree.resolution.width) ? tree.resolution.width : 0;
+    const height = (tree.resolution && tree.resolution.height) ? tree.resolution.height : 0;
+    const centerX = Math.round(width / 2) || 50;
+    const clampPct = (v) => Math.max(0.05, Math.min(0.95, v));
+    const computeCoords = () => {
+        const defaultStart = direction === 'down' ? 0.8 : 0.2;
+        const startPct = clampPct(defaultStart);
+        const endPct = clampPct(defaultStart + (direction === 'down' ? -scrollAmount : scrollAmount));
+        const x1 = centerX;
+        const x2 = centerX;
+        const y1 = Math.round((height || 100) * startPct);
+        const y2 = Math.round((height || 100) * endPct);
+        return { x1, y1, x2, y2 };
+    };
+    const duration = 300;
+    let scrollsPerformed = 0;
+    for (let i = 0; i < maxScrolls; i++) {
+        const { x1, y1, x2, y2 } = computeCoords();
+        try {
+            await swipe(x1, y1, x2, y2, duration, deviceId);
+        }
+        catch (e) {
+            try {
+                console.warn(`scrollToElement swipe failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            catch { }
+        }
+        scrollsPerformed++;
+        await new Promise(resolve => setTimeout(resolve, stabilizationDelayMs));
+        tree = await fetchTree();
+        if (tree.error)
+            return { success: false, reason: tree.error, scrollsPerformed: scrollsPerformed };
+        found = findVisibleMatch(tree.elements, tree.resolution);
+        if (found) {
+            return { success: true, element: { text: found.text, resourceId: found.resourceId, bounds: found.bounds }, scrollsPerformed };
+        }
+        const fp = fingerprintOf(tree);
+        if (fp === prevFingerprint) {
+            return { success: false, reason: 'UI unchanged after scroll; likely end of list', scrollsPerformed: scrollsPerformed };
+        }
+        prevFingerprint = fp;
+    }
+    return { success: false, reason: 'Element not found after scrolling', scrollsPerformed: scrollsPerformed };
+}

package/docs/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.17.0]
+- Added `capture_debug_snapshot` observe tool: captures a full debugging snapshot including screenshot (base64), UI tree, current activity (Android), screen fingerprint, and recent logs (prefers active log stream, falls back to snapshot logs). Returns a single structured JSON object and includes per-part error fields for partial failures. Implemented as `ToolsObserve.captureDebugSnapshotHandler` and registered in the server.
+
+## [0.16.0]
+- Added `wait_for_screen_change` interact tool: polls the platform-specific `get_screen_fingerprint` until it differs from a provided `previousFingerprint`, with configurable `timeoutMs` and `pollIntervalMs` and an optional stability confirmation poll to avoid reacting to transient UI flickers. Implemented at the interact layer and delegates fingerprinting to the observe implementations (Android/iOS).
+- Added unit tests covering immediate change, transient null fingerprints, stability confirmation and timeout behavior: `test/interact/unit/wait_for_screen_change.test.ts`.
+
 ## [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).

package/docs/tools/interact.md

@@ -72,3 +72,32 @@ Notes:
 - Android swipe uses `adb shell input swipe` with screen percentage coordinates. iOS swipe uses `idb ui swipe` command; note `idb` swipe does not accept a duration argument.
 - Unit tests are located at `test/unit/observe/scroll_to_element.test.ts` and device runners at `test/device/observe/`.
 
+---
+
+## wait_for_screen_change
+
+Description:
+- Waits until the current screen fingerprint differs from the provided `previousFingerprint`. Useful after taps, navigation, or other interactions that should change the visible UI.
+
+Input example:
+```
+{ "platform": "android", "previousFingerprint": "<hex-fingerprint>", "timeoutMs": 5000, "pollIntervalMs": 300, "deviceId": "emulator-5554" }
+```
+
+Success response example:
+```
+{ "success": true, "newFingerprint": "<hex-fingerprint>", "elapsedMs": 420 }
+```
+
+Failure (timeout) example:
+```
+{ "success": false, "reason": "timeout", "lastFingerprint": "<hex-fingerprint>", "elapsedMs": 5000 }
+```
+
+Notes:
+- Always compares to the original `previousFingerprint` (baseline is not updated during polling).
+- Treats `null` fingerprints as transient; continues polling rather than returning success.
+- Includes a stability confirmation: after detecting a different fingerprint it waits one additional poll interval and confirms the fingerprint is stable before returning success to avoid reacting to transient flickers or animation frames.
+- Default `timeoutMs` is 5000ms and default `pollIntervalMs` is 300ms; callers may override these.
+- Implemented as an interact-level tool and delegates platform-specific fingerprint calculation to the observe layer (`get_screen_fingerprint`).
+

package/docs/tools/observe.md

@@ -76,6 +76,50 @@ Response:
 
 ---
 
+## capture_debug_snapshot
+Capture a complete debug snapshot of the app state for diagnostics and post-mortem analysis.
+
+Input:
+
+```json
+{
+  "reason": "optional string describing why snapshot is taken",
+  "includeLogs": true,
+  "logLines": 200,
+  "platform": "android | ios",
+  "appId": "optional package/bundle id to scope logs",
+  "deviceId": "optional device serial/udid",
+  "sessionId": "optional log stream session id to prefer"
+}
+```
+
+Behavior:
+- Captures screenshot (base64), current activity (Android), screen fingerprint, full UI tree, and recent logs.
+- Prefers active log stream entries (read_log_stream) and falls back to get_logs when no active stream is available.
+- Returns partial data when components fail and includes per-part error fields (e.g. `screenshot_error`, `ui_tree_error`).
+- Caps logs to `logLines` entries and prefers recent entries.
+- Fast by default: does not wait for new logs and avoids long blocking operations.
+
+Response (example):
+
+```json
+{
+  "timestamp": 1710000000,
+  "reason": "Crash after tapping checkout",
+  "activity": "CheckoutActivity",
+  "fingerprint": "abc123",
+  "screenshot": "<base64 PNG string>",
+  "ui_tree": { ... },
+  "logs": [ { "timestamp": 1710000000, "level": "ERROR", "message": "NullPointerException at CheckoutViewModel" } ]
+}
+```
+
+Notes:
+- Useful immediately after detecting crashes or unexpected UI behaviour.
+- Do not expect perfect data during a crash; tool is designed to return best-effort context and include errors for failed parts.
+
+---
+
 ## get_screen_fingerprint
 Generate a stable fingerprint representing the visible screen. Useful for detecting navigation changes, preventing loops, and synchronisation.
 

package/package.json

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

package/src/interact/android.ts

@@ -1,7 +1,7 @@
 import { WaitForElementResponse, TapResponse, SwipeResponse, TypeTextResponse, PressBackResponse } from "../types.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"
+import { scrollToElementShared } from "../utils/ui/index.js"
 
 
 export class AndroidInteract {

package/src/interact/index.ts

@@ -3,6 +3,9 @@ import { iOSInteract } from './ios.js';
 export { AndroidInteract, iOSInteract };
 
 import { resolveTargetDevice } from '../utils/resolve-device.js'
+import { ToolsObserve } from '../observe/index.js'
+
+interface ScreenFingerprintResponse { fingerprint: string | null }
 
 export class ToolsInteract {
 
@@ -44,4 +47,46 @@ export class ToolsInteract {
     return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id)
   }
 
+  static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }: { platform?: 'android' | 'ios', previousFingerprint: string, timeoutMs?: number, pollIntervalMs?: number, deviceId?: string }) {
+    const start = Date.now()
+    let lastFingerprint: string | null = null
+
+    while (Date.now() - start < timeoutMs) {
+      try {
+        const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
+        const fp = res?.fingerprint ?? null
+        if (fp === null || fp === undefined) {
+          lastFingerprint = null
+          await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+          continue
+        }
+
+        lastFingerprint = fp
+
+        if (fp !== previousFingerprint) {
+          // Stability confirmation
+          await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+              try {
+            const confirmRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
+            const confirmFp = confirmRes?.fingerprint ?? null
+            if (confirmFp === fp) {
+              return { success: true, newFingerprint: fp, elapsedMs: Date.now() - start }
+            }
+            lastFingerprint = confirmFp
+            continue
+          } catch {
+            // ignore and continue polling
+            continue
+          }
+        }
+      } catch {
+        // ignore transient errors
+      }
+
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+    }
+
+    return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start }
+  }
+
 }

package/src/interact/ios.ts

@@ -2,7 +2,7 @@ import { spawn } from "child_process"
 import { WaitForElementResponse, TapResponse, SwipeResponse } from "../types.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"
+import { scrollToElementShared } from "../utils/ui/index.js"
 
 export class iOSInteract {
   private observe = new iOSObserve();

package/src/observe/android.ts

@@ -5,7 +5,7 @@ import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, get
 import { createWriteStream } from "fs"
 import { promises as fsPromises } from "fs"
 import path from "path"
-import { computeScreenFingerprint } from "../interact/shared/fingerprint.js"
+import { computeScreenFingerprint } from "../utils/ui/index.js"
 
 const activeLogStreams: Map<string, { proc: any, file: string }> = new Map()
 

package/src/observe/index.ts

@@ -89,4 +89,92 @@ export class ToolsObserve {
     // Both observes implement getScreenFingerprint
     return await (observe as any).getScreenFingerprint(resolved.id)
   }
+
+  static async captureDebugSnapshotHandler({ reason, includeLogs = true, logLines = 200, platform, appId, deviceId, sessionId }: { reason?: string; includeLogs?: boolean; logLines?: number; platform?: 'android' | 'ios'; appId?: string; deviceId?: string; sessionId?: string } = {}) {
+    const timestamp = Date.now()
+    const out: any = { timestamp, reason: reason || '', activity: null, fingerprint: null, screenshot: null, ui_tree: null, logs: [] }
+
+    // Parallel fetches for performance: screenshot, current screen, fingerprint, ui tree, and log stream/get logs
+    const sid = sessionId || 'default'
+    const tasks = {
+      screenshot: ToolsObserve.captureScreenshotHandler({ platform, deviceId }),
+      currentScreen: (!platform || platform === 'android') ? ToolsObserve.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
+      fingerprint: ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }),
+      uiTree: ToolsObserve.getUITreeHandler({ platform, deviceId }),
+      readLogStream: includeLogs ? ToolsObserve.readLogStreamHandler({ platform, sessionId: sid, limit: logLines }) : Promise.resolve({ entries: [] }),
+    }
+
+    const results = await Promise.allSettled(Object.values(tasks))
+    const keys = Object.keys(tasks)
+
+    // Map results back to keys
+    for (let i = 0; i < results.length; i++) {
+      const key = keys[i]
+      const res = results[i] as PromiseSettledResult<any>
+      if (res.status === 'fulfilled') {
+        const val = res.value
+        if (key === 'screenshot') {
+          out.screenshot = val && val.screenshot ? val.screenshot : null
+        } else if (key === 'currentScreen') {
+          out.activity = val && ((val.activity || val.shortActivity)) ? (val.activity || val.shortActivity) : out.activity || ''
+        } else if (key === 'fingerprint') {
+          if (val && val.fingerprint) out.fingerprint = val.fingerprint
+          if (val && val.activity) out.activity = out.activity || val.activity
+          if (val && val.error) out.fingerprint_error = val.error
+        } else if (key === 'uiTree') {
+          out.ui_tree = val
+          if (val && val.error) out.ui_tree_error = val.error
+        } else if (key === 'readLogStream') {
+          // handle below after evaluating fallback
+          // temporarily attach to out._streamEntries
+          out._streamEntries = val && val.entries ? val.entries : []
+        }
+      } else {
+        const errMsg = res.reason instanceof Error ? res.reason.message : String(res.reason)
+        if (key === 'screenshot') out.screenshot_error = errMsg
+        if (key === 'currentScreen') out.activity_error = errMsg
+        if (key === 'fingerprint') { out.fingerprint = null; out.fingerprint_error = errMsg }
+        if (key === 'uiTree') { out.ui_tree = null; out.ui_tree_error = errMsg }
+        if (key === 'readLogStream') { out._streamEntries = [] ; out.logs_error = errMsg }
+      }
+    }
+
+    // Logs: prefer stream entries, fallback to snapshot logs when empty
+    if (includeLogs) {
+      try {
+        let entries: any[] = Array.isArray(out._streamEntries) ? out._streamEntries : []
+        if (!entries || entries.length === 0) {
+          const gl = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, lines: logLines })
+          const raw: string[] = (gl && (gl as any).logs) ? (gl as any).logs : []
+          entries = raw.slice(-Math.max(0, logLines)).map(line => {
+            const level = /\b(FATAL EXCEPTION|ERROR| E )\b/i.test(line) ? 'ERROR' : /\b(WARN| W )\b/i.test(line) ? 'WARN' : 'INFO'
+            return { timestamp: null, level, message: line }
+          })
+        } else {
+          entries = entries.map(ent => {
+            const msg = (ent && (ent.message || ent.msg)) ? (ent.message || ent.msg) : (typeof ent === 'string' ? ent : JSON.stringify(ent))
+            const levelRaw = (ent && (ent.level || ent.levelName || ent._level)) ? (ent.level || ent.levelName || ent._level) : ''
+            const level = (levelRaw && String(levelRaw)).toString().toUpperCase() || (/\bERROR\b/i.test(msg) ? 'ERROR' : /\bWARN\b/i.test(msg) ? 'WARN' : 'INFO')
+            let tsNum: number | null = null
+            const maybeIso = ent && ((ent._iso || ent.timestamp) as any)
+            if (maybeIso && typeof maybeIso === 'string') {
+              const d = new Date(maybeIso)
+              if (!isNaN(d.getTime())) tsNum = d.getTime()
+            }
+            return { timestamp: tsNum, level, message: msg }
+          })
+        }
+
+        out.logs = entries
+      } catch (e) {
+        out.logs = []
+        out.logs_error = e instanceof Error ? e.message : String(e)
+      }
+    }
+
+    // Clean up internal temporary field
+    delete out._streamEntries
+
+    return out
+  }
 }

package/src/observe/ios.ts

@@ -5,7 +5,7 @@ import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcru
 import { createWriteStream, promises as fsPromises } from 'fs'
 import path from 'path'
 import { parseLogLine } from '../utils/android/utils.js'
-import { computeScreenFingerprint } from '../interact/shared/fingerprint.js'
+import { computeScreenFingerprint } from '../utils/ui/index.js'
 
 const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 

package/src/server.ts

@@ -215,6 +215,23 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["platform"]
       }
     },
+    {
+      name: "capture_debug_snapshot",
+      description: "Capture a complete debug snapshot (screenshot, ui tree, activity, fingerprint, logs). Returns structured JSON."
+      ,
+      inputSchema: {
+        type: "object",
+        properties: {
+          reason: { type: "string", description: "Optional reason for snapshot" },
+          includeLogs: { type: "boolean", description: "Whether to include logs", default: true },
+          logLines: { type: "number", description: "Maximum number of log lines to include", default: 200 },
+          platform: { type: "string", enum: ["android","ios"], description: "Optional platform override" },
+          appId: { type: "string", description: "Optional appId to scope logs (package/bundle id)" },
+          deviceId: { type: "string", description: "Optional device serial/udid" },
+          sessionId: { type: "string", description: "Optional log stream session id to prefer" }
+        }
+      }
+    },
     {
       name: "start_log_stream",
       description: "Start streaming logs for a target application on Android or iOS. For Android this uses adb logcat --pid=<pid>; for iOS it streams `xcrun simctl spawn <device> log stream` with a predicate.",
@@ -294,6 +311,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         }
       }
     },
+    {
+      name: "wait_for_screen_change",
+      description: "Wait until the current screen fingerprint differs from a provided previousFingerprint. Useful to wait for navigation/animation completion.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          platform: { type: "string", enum: ["android", "ios"], description: "Optional platform override (android|ios)" },
+          previousFingerprint: { type: "string", description: "The fingerprint to compare against (required)" },
+          timeoutMs: { type: "number", description: "Timeout in ms to wait for change (default 5000)", default: 5000 },
+          pollIntervalMs: { type: "number", description: "Polling interval in ms (default 300)", default: 300 },
+          deviceId: { type: "string", description: "Optional device id/udid to target" }
+        },
+        required: ["previousFingerprint"]
+      }
+    },
     {
       name: "wait_for_element",
       description: "Wait until a UI element with matching text appears on screen or timeout is reached.",
@@ -322,6 +354,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["platform", "text"]
       }
     },
+
     {
       name: "tap",
       description: "Simulate a finger tap on the device screen at specific coordinates.",
@@ -578,6 +611,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
     }
 
+    if (name === "capture_debug_snapshot") {
+      const { reason, includeLogs, logLines, platform, appId, deviceId, sessionId } = args as any
+      const res = await ToolsObserve.captureDebugSnapshotHandler({ reason, includeLogs, logLines, platform, appId, deviceId, sessionId })
+      return wrapResponse(res)
+    }
+
     if (name === "get_ui_tree") {
       const { platform, deviceId } = args as any
       const res = await ToolsObserve.getUITreeHandler({ platform, deviceId })
@@ -596,6 +635,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return wrapResponse(res)
     }
 
+    if (name === "wait_for_screen_change") {
+      const { platform, previousFingerprint, timeoutMs, pollIntervalMs, deviceId } = (args || {}) as any
+      const res = await ToolsInteract.waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs, pollIntervalMs, deviceId })
+      return wrapResponse(res)
+    }
+
     if (name === "wait_for_element") {
       const { platform, text, timeout, deviceId } = (args || {}) as any
       const res = await ToolsInteract.waitForElementHandler({ platform, text, timeout, deviceId })

package/src/types.ts

@@ -143,3 +143,4 @@ export interface InstallAppResponse {
   error?: string;
   diagnostics?: any;
 }
+

package/src/utils/android/utils.ts

@@ -1,8 +1,8 @@
-import { spawn } from 'child_process'
 import { DeviceInfo, UIElement } from "../../types.js"
 import { promises as fsPromises, existsSync } from 'fs'
 import path from 'path'
 import { detectJavaHome } from '../java.js'
+import { execCmd } from '../exec.js'
 
 export function getAdbCmd() { return process.env.ADB_PATH || 'adb' }
 
@@ -83,87 +83,20 @@ import type { SpawnOptions } from 'child_process'
 
 export type SpawnOptionsWithTimeout = SpawnOptions & { timeout?: number }
 
-export function execAdb(args: string[], deviceId?: string, options: SpawnOptionsWithTimeout = {}): Promise<string> {
+export async function execAdb(args: string[], deviceId?: string, options: SpawnOptionsWithTimeout = {}): Promise<string> {
   const adbArgs = getAdbArgs(args, deviceId)
-  return new Promise((resolve, reject) => {
-    // Extract timeout from options if present, otherwise pass options to spawn
-    const { timeout: customTimeout, ...spawnOptions } = options;
-    
-    // Use spawn instead of execFile for better stream control and to avoid potential buffering hangs
-    const child = spawn(getAdbCmd(), adbArgs, spawnOptions)
-    
-    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 timeoutMs = getAdbTimeout(args, customTimeout)
-
-
-    const timeout = setTimeout(() => {
-      child.kill()
-      reject(new Error(`ADB command timed out after ${timeoutMs}ms: ${args.join(' ')}`))
-    }, timeoutMs)
-
-    child.on('close', (code) => {
-      clearTimeout(timeout)
-      if (code !== 0) {
-        // If there's an actual error (non-zero exit code), reject
-        reject(new Error(stderr.trim() || `Command failed with code ${code}`))
-      } else {
-        // If exit code is 0, resolve with stdout
-        resolve(stdout.trim())
-      }
-    })
-
-    child.on('error', (err) => {
-      clearTimeout(timeout)
-      reject(err)
-    })
-  })
+  const timeoutMs = getAdbTimeout(args, options.timeout)
+  const res = await execCmd(getAdbCmd(), adbArgs, { timeout: timeoutMs, env: options.env as any, cwd: typeof options.cwd === 'string' ? options.cwd : undefined, shell: !!options.shell })
+  if (res.exitCode !== 0) throw new Error(res.stderr || `Command failed with code ${res.exitCode}`)
+  return res.stdout
 }
 
 // Spawn adb but return full streams and exit code so callers can implement fallbacks or stream output
-export function spawnAdb(args: string[], deviceId?: string, options: SpawnOptionsWithTimeout = {}): Promise<{ stdout: string, stderr: string, code: number | null }> {
+export async function spawnAdb(args: string[], deviceId?: string, options: SpawnOptionsWithTimeout = {}): Promise<{ stdout: string, stderr: string, code: number | null }> {
   const adbArgs = getAdbArgs(args, deviceId)
-  return new Promise((resolve, reject) => {
-    const { timeout: customTimeout, ...spawnOptions } = options
-    const child = spawn(getAdbCmd(), adbArgs, spawnOptions)
-
-    let stdout = ''
-    let stderr = ''
-
-    if (child.stdout) child.stdout.on('data', d => { stdout += d.toString() })
-    if (child.stderr) child.stderr.on('data', d => { stderr += d.toString() })
-
-    const timeoutMs = getAdbTimeout(args, customTimeout)
-
-
-    const timeout = setTimeout(() => {
-      try { child.kill() } catch {}
-      reject(new Error(`ADB command timed out after ${timeoutMs}ms: ${args.join(' ')}`))
-    }, timeoutMs)
-
-    child.on('close', (code) => {
-      clearTimeout(timeout)
-      resolve({ stdout: stdout.trim(), stderr: stderr.trim(), code })
-    })
-
-    child.on('error', (err) => {
-      clearTimeout(timeout)
-      reject(err)
-    })
-  })
+  const timeoutMs = getAdbTimeout(args, options.timeout)
+  const res = await execCmd(getAdbCmd(), adbArgs, { timeout: timeoutMs, env: options.env as any, cwd: typeof options.cwd === 'string' ? options.cwd : undefined, shell: !!options.shell })
+  return { stdout: res.stdout, stderr: res.stderr, code: res.exitCode }
 }
 
 export function getDeviceInfo(deviceId: string, metadata: Partial<DeviceInfo> = {}): DeviceInfo {