mobile-debug-mcp 0.16.0 → 0.18.0

package/README.md

@@ -24,6 +24,8 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
   }
 }
 ```
+You will need to add ADB_PATH for Android and XCRUN_PATH and IDB_PATH for iOS.
+
 ## Usage
 
 Example: 

package/dist/interact/index.js

@@ -35,6 +35,191 @@ export class ToolsInteract {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
         return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id);
     }
+    static async findElementHandler({ query, exact = false, timeoutMs = 3000, platform, deviceId }) {
+        // Try to use observe layer to fetch the current UI tree and perform a fast semantic search
+        const start = Date.now();
+        const deadline = start + timeoutMs;
+        const normalize = (s) => (s === null || s === undefined) ? '' : String(s).toLowerCase().trim();
+        const q = normalize(query);
+        if (!q)
+            return { found: false, error: 'Empty query' };
+        let best = null;
+        let bestScore = 0;
+        const scoreElement = (el) => {
+            if (!el || !el.visible)
+                return 0;
+            const bounds = el.bounds || [0, 0, 0, 0];
+            if (!Array.isArray(bounds) || bounds.length < 4)
+                return 0;
+            const [l, t, r, b] = bounds;
+            if (r <= l || b <= t)
+                return 0;
+            // Do not early-return on non-interactable elements — score them so we can locate their clickable ancestor later
+            const interactable = !!(el.clickable || el.enabled || el.focusable);
+            const text = normalize(el.text ?? el.label ?? el.value ?? '');
+            const content = normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? '');
+            const resourceId = normalize(el.resourceId ?? el.resourceID ?? el.id ?? '');
+            const className = normalize(el.type ?? el.class ?? '');
+            let score = 0;
+            if (exact) {
+                if (text && text === q)
+                    score = 1.0;
+                else if (content && content === q)
+                    score = 0.95;
+            }
+            else {
+                if (text && text === q)
+                    score = 1.0;
+                else if (content && content === q)
+                    score = 0.95;
+                else if (text && text.includes(q))
+                    score = 0.6;
+                else if (content && content.includes(q))
+                    score = 0.55;
+                else if (resourceId && resourceId.includes(q))
+                    score = 0.7;
+                else if (className && className.includes(q))
+                    score = 0.3;
+            }
+            if (score > 0 && interactable)
+                score += 0.05;
+            return score;
+        };
+        while (Date.now() <= deadline) {
+            try {
+                const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+                if (tree && Array.isArray(tree.elements)) {
+                    const elements = tree.elements;
+                    for (let i = 0; i < elements.length; i++) {
+                        const el = elements[i];
+                        try {
+                            const s = scoreElement(el);
+                            const interactable = !!(el.clickable || el.enabled || el.focusable);
+                            if (s > bestScore) {
+                                bestScore = s;
+                                best = el;
+                                if (best) {
+                                    best._index = i;
+                                    best._interactable = interactable;
+                                }
+                            }
+                            if (bestScore >= 0.95)
+                                break;
+                        }
+                        catch (e) {
+                            console.error('Error scoring element:', e);
+                        }
+                    }
+                    if (bestScore >= 0.95)
+                        break;
+                }
+            }
+            catch (e) {
+                console.error('Error fetching UI tree:', e);
+            }
+            if (Date.now() > deadline)
+                break;
+            await new Promise(r => setTimeout(r, 100));
+        }
+        if (!best)
+            return { found: false, error: 'Element not found' };
+        // If the best match is not interactable, try to resolve an actionable ancestor.
+        try {
+            const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+            const elements = (tree && Array.isArray(tree.elements)) ? tree.elements : [];
+            let chosen = best;
+            const childBounds = Array.isArray(chosen?.bounds) ? chosen.bounds : null;
+            // Strategy 1: if parentId references an index, climb that chain
+            let resolvedAncestor = null;
+            if (childBounds && (chosen.parentId !== undefined && chosen.parentId !== null)) {
+                let cur = chosen;
+                let safety = 0;
+                while (cur && safety < 20 && !(cur.clickable || cur.focusable) && (cur.parentId !== undefined && cur.parentId !== null)) {
+                    let pid = cur.parentId;
+                    let idx = null;
+                    if (typeof pid === 'number')
+                        idx = pid;
+                    else if (typeof pid === 'string' && /^\d+$/.test(pid))
+                        idx = Number(pid);
+                    // If parentId is not an index, try to find by matching resourceId or id field
+                    if (idx !== null && elements[idx]) {
+                        cur = elements[idx];
+                        if (cur && (cur.clickable || cur.enabled || cur.focusable)) {
+                            resolvedAncestor = cur;
+                            break;
+                        }
+                    }
+                    else if (typeof pid === 'string') {
+                        // fallback: search elements for matching resourceId or id
+                        const found = elements.find((el) => (el.resourceId === pid || el.id === pid));
+                        if (found) {
+                            cur = found;
+                            if (cur && (cur.clickable || cur.enabled || cur.focusable)) {
+                                resolvedAncestor = cur;
+                                break;
+                            }
+                            // otherwise continue climbing if this found element has its own parentId
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                    else {
+                        break;
+                    }
+                    safety++;
+                }
+            }
+            // Strategy 2: fallback - find a clickable element whose bounds fully contain the child's bounds
+            if (!resolvedAncestor && childBounds) {
+                const [cl, ct, cr, cb] = childBounds;
+                // find candidates that are clickable and contain the child bounds
+                const candidates = elements.filter((el) => el && (el.clickable || el.focusable) && Array.isArray(el.bounds) && el.bounds.length >= 4).map((el) => ({ el, bounds: el.bounds }));
+                let bestCandidate = null;
+                let bestCandidateArea = Infinity;
+                for (const c of candidates) {
+                    const [pl, pt, pr, pb] = c.bounds;
+                    if (pl <= cl && pt <= ct && pr >= cr && pb >= cb) {
+                        const area = (pr - pl) * (pb - pt);
+                        if (area < bestCandidateArea) {
+                            bestCandidateArea = area;
+                            bestCandidate = c.el;
+                        }
+                    }
+                }
+                if (bestCandidate)
+                    resolvedAncestor = bestCandidate;
+            }
+            if (resolvedAncestor) {
+                best = resolvedAncestor;
+                // small score bump to reflect actionability
+                bestScore = Math.min(1, bestScore + 0.02);
+            }
+        }
+        catch (e) {
+            console.error('Error resolving ancestor:', e);
+        }
+        if (!best)
+            return { found: false, error: 'Element not found' };
+        const boundsObj = Array.isArray(best.bounds) ? { left: best.bounds[0], top: best.bounds[1], right: best.bounds[2], bottom: best.bounds[3] } : null;
+        const tapCoordinates = boundsObj ? { x: Math.floor((boundsObj.left + boundsObj.right) / 2), y: Math.floor((boundsObj.top + boundsObj.bottom) / 2) } : null;
+        const outEl = {
+            text: best.text ?? null,
+            resourceId: best.resourceId ?? null,
+            contentDesc: best.contentDescription ?? best.contentDesc ?? null,
+            class: best.type ?? best.class ?? null,
+            bounds: boundsObj,
+            clickable: !!best.clickable,
+            enabled: !!best.enabled,
+            tapCoordinates,
+            telemetry: {
+                matchedIndex: best?._index ?? null,
+                matchedInteractable: !!best?._interactable
+            }
+        };
+        const scoreVal = Math.min(1, Number(bestScore.toFixed(3)));
+        return { found: true, element: outEl, score: scoreVal, confidence: scoreVal };
+    }
     static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }) {
         const start = Date.now();
         let lastFingerprint = null;
@@ -60,14 +245,14 @@ export class ToolsInteract {
                         lastFingerprint = confirmFp;
                         continue;
                     }
-                    catch {
-                        // ignore and continue polling
+                    catch (e) {
+                        console.error('Error confirming fingerprint:', e);
                         continue;
                     }
                 }
             }
-            catch {
-                // ignore transient errors
+            catch (e) {
+                console.error('Error getting screen fingerprint:', e);
             }
             await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
         }

package/dist/observe/index.js

@@ -82,4 +82,107 @@ export class ToolsObserve {
         // Both observes implement getScreenFingerprint
         return await observe.getScreenFingerprint(resolved.id);
     }
+    static async captureDebugSnapshotHandler({ reason, includeLogs = true, logLines = 200, platform, appId, deviceId, sessionId } = {}) {
+        const timestamp = Date.now();
+        const out = { 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];
+            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 = Array.isArray(out._streamEntries) ? out._streamEntries : [];
+                if (!entries || entries.length === 0) {
+                    const gl = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, lines: logLines });
+                    const raw = (gl && gl.logs) ? gl.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 = null;
+                        const maybeIso = ent && (ent._iso || ent.timestamp);
+                        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/dist/server.js

@@ -195,6 +195,22 @@ 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.",
@@ -316,6 +332,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["platform", "text"]
             }
         },
+        {
+            name: "find_element",
+            description: "Find a UI element by semantic query (text, content-desc, resource-id, class). Returns best match.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Search query (text or label)" },
+                    exact: { type: "boolean", description: "Require exact match (true/false)", default: false },
+                    timeoutMs: { type: "number", description: "Timeout in ms to keep searching", default: 3000 },
+                    platform: { type: "string", enum: ["android", "ios"], description: "Optional platform override" },
+                    deviceId: { type: "string", description: "Optional device serial/udid" }
+                },
+                required: ["query"]
+            }
+        },
         {
             name: "tap",
             description: "Simulate a finger tap on the device screen at specific coordinates.",
@@ -556,6 +587,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ]
             };
         }
+        if (name === "capture_debug_snapshot") {
+            const { reason, includeLogs, logLines, platform, appId, deviceId, sessionId } = args;
+            const res = await ToolsObserve.captureDebugSnapshotHandler({ reason, includeLogs, logLines, platform, appId, deviceId, sessionId });
+            return wrapResponse(res);
+        }
         if (name === "get_ui_tree") {
             const { platform, deviceId } = args;
             const res = await ToolsObserve.getUITreeHandler({ platform, deviceId });
@@ -581,6 +617,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const res = await ToolsInteract.waitForElementHandler({ platform, text, timeout, deviceId });
             return wrapResponse(res);
         }
+        if (name === "find_element") {
+            const { query, exact = false, timeoutMs = 3000, platform, deviceId } = (args || {});
+            const res = await ToolsInteract.findElementHandler({ query, exact, timeoutMs, platform, deviceId });
+            return wrapResponse(res);
+        }
         if (name === "tap") {
             const { platform, x, y, deviceId } = (args || {});
             const res = await ToolsInteract.tapHandler({ platform, x, y, deviceId });

package/docs/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.18.0]
+- Added `find_element` interact tool: semantic UI element search with actionable tap coordinates and lightweight telemetry. The tool searches the UI tree for the best match by text, content description, resource-id, and class, scores candidates (exact, partial, resource-id), and returns the most relevant visible element. When a matching node is non-interactable (e.g., Compose Text child), the tool locates a clickable ancestor (parent or containing element) and returns actionable tapCoordinates (x,y). The handler also returns a `confidence` value and `telemetry` metadata (matchedIndex, matchedInteractable) to aid agent decision-making and logging. Implemented as `ToolsInteract.findElementHandler` and covered by unit tests.
+
+
+## [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`.

package/docs/tools/interact.md

@@ -101,3 +101,53 @@ Notes:
 - 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`).
 
+---
+
+## find_element
+
+Purpose:
+
+Locate a UI element on the current screen using semantic matching and return an actionable element descriptor (including tap coordinates) and confidence telemetry.
+
+Input:
+
+```json
+{ "query": "string", "exact": false, "timeoutMs": 3000, "platform": "android|ios", "deviceId": "optional device id" }
+```
+
+Behaviour:
+
+- Fetches the current UI tree (get_ui_tree) and scores visible elements using: text, content description, resource-id, and class name.
+- Normalises strings (lowercase, trimmed). If exact=true require exact match; otherwise allow partial matches (contains) and resource-id/class matches.
+- Considers element bounds and visibility; scores non-interactable children as matches and attempts to resolve a clickable ancestor (parent index or containing clickable element) to produce an actionable element.
+- Retries until timeoutMs; stops early for high-confidence matches.
+- Does not block on long operations and returns partial results where appropriate.
+
+Output:
+
+```json
+{
+  "found": true,
+  "element": {
+    "text": "Login",
+    "resourceId": "com.example:id/login",
+    "contentDesc": null,
+    "class": "android.widget.Button",
+    "bounds": { "left":0, "top":0, "right":100, "bottom":50 },
+    "clickable": true,
+    "enabled": true,
+    "tapCoordinates": { "x":50, "y":25 },
+    "telemetry": { "matchedIndex": 3, "matchedInteractable": true }
+  },
+  "score": 1.0,
+  "confidence": 1.0
+}
+```
+
+Notes:
+
+- `tapCoordinates` are the recommended center point to use for `tap` calls.
+- `confidence` mirrors the internal scoring (0..1) and is suitable for telemetry or logging to decide whether to proceed with an automated action.
+- The tool favours actionable (clickable/focusable) targets; when a matching node is not directly actionable, it finds the smallest containing clickable ancestor.
+- Unit tests for edge cases (parent-clickable child-text, resource-id matches, fuzzy matching) are under `test/observe/unit/find_element.test.ts`.
+

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.16.0",
+  "version": "0.18.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/src/interact/index.ts

@@ -5,6 +5,30 @@ export { AndroidInteract, iOSInteract };
 import { resolveTargetDevice } from '../utils/resolve-device.js'
 import { ToolsObserve } from '../observe/index.js'
 
+interface ScreenFingerprintResponse { fingerprint: string | null }
+
+interface UiElement {
+  text?: string | null
+  label?: string | null
+  value?: string | null
+  contentDescription?: string | null
+  contentDesc?: string | null
+  accessibilityLabel?: string | null
+  resourceId?: string | null
+  resourceID?: string | null
+  id?: string | null
+  type?: string | null
+  class?: string | null
+  bounds?: number[] | null
+  clickable?: boolean
+  enabled?: boolean
+  focusable?: boolean
+  visible?: boolean
+  parentId?: number | string | null
+  _index?: number
+  _interactable?: boolean
+}
+
 export class ToolsInteract {
 
   private static async getInteractionService(platform?: 'android' | 'ios', deviceId?: string) {
@@ -45,14 +69,168 @@ export class ToolsInteract {
     return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id)
   }
 
+  static async findElementHandler({ query, exact = false, timeoutMs = 3000, platform, deviceId }: { query: string, exact?: boolean, timeoutMs?: number, platform?: 'android' | 'ios', deviceId?: string }) {
+    // Try to use observe layer to fetch the current UI tree and perform a fast semantic search
+    const start = Date.now()
+    const deadline = start + timeoutMs
+    const normalize = (s: any) => (s === null || s === undefined) ? '' : String(s).toLowerCase().trim()
+
+    const q = normalize(query)
+    if (!q) return { found: false, error: 'Empty query' }
+
+    let best: UiElement | null = null
+    let bestScore = 0
+
+    const scoreElement = (el: UiElement | null) => {
+      if (!el || !el.visible) return 0
+      const bounds = el.bounds || [0,0,0,0]
+      if (!Array.isArray(bounds) || bounds.length < 4) return 0
+      const [l,t,r,b] = bounds
+      if (r <= l || b <= t) return 0
+      // Do not early-return on non-interactable elements — score them so we can locate their clickable ancestor later
+      const interactable = !!(el.clickable || el.enabled || el.focusable)
+
+      const text = normalize(el.text ?? el.label ?? el.value ?? '')
+      const content = normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? '')
+      const resourceId = normalize(el.resourceId ?? el.resourceID ?? el.id ?? '')
+      const className = normalize(el.type ?? el.class ?? '')
+
+      let score = 0
+      if (exact) {
+        if (text && text === q) score = 1.0
+        else if (content && content === q) score = 0.95
+      } else {
+        if (text && text === q) score = 1.0
+        else if (content && content === q) score = 0.95
+        else if (text && text.includes(q)) score = 0.6
+        else if (content && content.includes(q)) score = 0.55
+        else if (resourceId && resourceId.includes(q)) score = 0.7
+        else if (className && className.includes(q)) score = 0.3
+      }
+      if (score > 0 && interactable) score += 0.05
+      return score
+    }
+
+    while (Date.now() <= deadline) {
+      try {
+        const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId })
+        if (tree && Array.isArray((tree as any).elements)) {
+          const elements = ((tree as any).elements as UiElement[])
+          for (let i = 0; i < elements.length; i++) {
+            const el = elements[i]
+            try {
+              const s = scoreElement(el)
+              const interactable = !!(el.clickable || el.enabled || (el as any).focusable)
+              if (s > bestScore) {
+                bestScore = s
+                best = el as UiElement
+                if (best) { best._index = i; best._interactable = interactable }
+              }
+              if (bestScore >= 0.95) break
+            } catch (e) { console.error('Error scoring element:', e) }
+          }
+          if (bestScore >= 0.95) break
+        }
+      } catch (e) { console.error('Error fetching UI tree:', e) }
+      if (Date.now() > deadline) break
+      await new Promise(r => setTimeout(r, 100))
+    }
+
+    if (!best) return { found: false, error: 'Element not found' }
+
+    // If the best match is not interactable, try to resolve an actionable ancestor.
+    try {
+      const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
+      const elements = (tree && Array.isArray(tree.elements)) ? (tree.elements as UiElement[]) : []
+      let chosen = best as any
+      const childBounds = Array.isArray(chosen?.bounds) ? chosen.bounds : null
+
+      // Strategy 1: if parentId references an index, climb that chain
+      let resolvedAncestor: any = null
+      if (childBounds && (chosen.parentId !== undefined && chosen.parentId !== null)) {
+        let cur = chosen
+        let safety = 0
+        while (cur && safety < 20 && !(cur.clickable || cur.focusable) && (cur.parentId !== undefined && cur.parentId !== null)) {
+          let pid = cur.parentId
+          let idx: number | null = null
+          if (typeof pid === 'number') idx = pid
+          else if (typeof pid === 'string' && /^\d+$/.test(pid)) idx = Number(pid)
+          // If parentId is not an index, try to find by matching resourceId or id field
+          if (idx !== null && elements[idx]) {
+            cur = elements[idx]
+            if (cur && (cur.clickable || cur.enabled || cur.focusable)) { resolvedAncestor = cur; break }
+          } else if (typeof pid === 'string') {
+            // fallback: search elements for matching resourceId or id
+            const found = elements.find((el: UiElement)=> (el.resourceId === pid || el.id === pid))
+            if (found) {
+              cur = found
+              if (cur && (cur.clickable || cur.enabled || cur.focusable)) { resolvedAncestor = cur; break }
+              // otherwise continue climbing if this found element has its own parentId
+            } else {
+              break
+            }
+          } else {
+            break
+          }
+          safety++
+        }
+      }
+
+      // Strategy 2: fallback - find a clickable element whose bounds fully contain the child's bounds
+      if (!resolvedAncestor && childBounds) {
+        const [cl,ct,cr,cb] = childBounds
+        // find candidates that are clickable and contain the child bounds
+        const candidates = elements.filter((el: UiElement)=> el && (el.clickable || el.focusable) && Array.isArray(el.bounds) && el.bounds!.length>=4).map((el: UiElement)=>({el, bounds: el.bounds! as number[]}))
+        let bestCandidate: any = null
+        let bestCandidateArea = Infinity
+        for (const c of candidates) {
+          const [pl,pt,pr,pb] = c.bounds
+          if (pl <= cl && pt <= ct && pr >= cr && pb >= cb) {
+            const area = (pr-pl) * (pb-pt)
+            if (area < bestCandidateArea) { bestCandidateArea = area; bestCandidate = c.el }
+          }
+        }
+        if (bestCandidate) resolvedAncestor = bestCandidate
+      }
+
+      if (resolvedAncestor) {
+        best = resolvedAncestor
+        // small score bump to reflect actionability
+        bestScore = Math.min(1, bestScore + 0.02)
+      }
+    } catch (e) { console.error('Error resolving ancestor:', e) }
+
+    if (!best) return { found: false, error: 'Element not found' }
+
+    const boundsObj = Array.isArray(best.bounds) ? { left: best.bounds[0], top: best.bounds[1], right: best.bounds[2], bottom: best.bounds[3] } : null
+    const tapCoordinates = boundsObj ? { x: Math.floor((boundsObj.left + boundsObj.right) / 2), y: Math.floor((boundsObj.top + boundsObj.bottom) / 2) } : null
+
+    const outEl = {
+      text: best.text ?? null,
+      resourceId: best.resourceId ?? null,
+      contentDesc: best.contentDescription ?? best.contentDesc ?? null,
+      class: best.type ?? best.class ?? null,
+      bounds: boundsObj,
+      clickable: !!best.clickable,
+      enabled: !!best.enabled,
+      tapCoordinates,
+      telemetry: {
+        matchedIndex: best?._index ?? null,
+        matchedInteractable: !!best?._interactable
+      }
+    }
+    const scoreVal = Math.min(1, Number(bestScore.toFixed(3)))
+    return { found: true, element: outEl, score: scoreVal, confidence: scoreVal }
+  }
+
   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 })
-        const fp = (res as any)?.fingerprint ?? null
+        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))
@@ -64,22 +242,17 @@ export class ToolsInteract {
         if (fp !== previousFingerprint) {
           // Stability confirmation
           await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
-          try {
-            const confirmRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId })
-            const confirmFp = (confirmRes as any)?.fingerprint ?? null
+              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 (e) { console.error('Error confirming fingerprint:', e); continue }
         }
-      } catch {
-        // ignore transient errors
-      }
+      } catch (e) { console.error('Error getting screen fingerprint:', e) }
 
       await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
     }

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/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.",
@@ -337,6 +354,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["platform", "text"]
       }
     },
+    {
+      name: "find_element",
+      description: "Find a UI element by semantic query (text, content-desc, resource-id, class). Returns best match.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search query (text or label)" },
+          exact: { type: "boolean", description: "Require exact match (true/false)", default: false },
+          timeoutMs: { type: "number", description: "Timeout in ms to keep searching", default: 3000 },
+          platform: { type: "string", enum: ["android","ios"], description: "Optional platform override" },
+          deviceId: { type: "string", description: "Optional device serial/udid" }
+        },
+        required: ["query"]
+      }
+    },
 
     {
       name: "tap",
@@ -594,6 +626,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 })
@@ -624,6 +662,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return wrapResponse(res)
     }
 
+    if (name === "find_element") {
+      const { query, exact = false, timeoutMs = 3000, platform, deviceId } = (args || {}) as any
+      const res = await ToolsInteract.findElementHandler({ query, exact, timeoutMs, platform, deviceId })
+      return wrapResponse(res)
+    }
+
     if (name === "tap") {
       const { platform, x, y, deviceId } = (args || {}) as any
       const res = await ToolsInteract.tapHandler({ platform, x, y, deviceId })

package/test/observe/unit/capture_debug_snapshot.test.ts

@@ -0,0 +1,89 @@
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+async function run() {
+  console.log('Starting capture_debug_snapshot unit tests...')
+
+  // Save original ToolsObserve handlers
+  const origCaptureHandler = (ToolsObserve as any).captureScreenshotHandler
+  const origGetCurrentHandler = (ToolsObserve as any).getCurrentScreenHandler
+  const origGetFpHandler = (ToolsObserve as any).getScreenFingerprintHandler
+  const origGetTreeHandler = (ToolsObserve as any).getUITreeHandler
+  const origReadLogStreamHandler = (ToolsObserve as any).readLogStreamHandler
+  const origGetLogsHandler = (ToolsObserve as any).getLogsHandler
+
+  try {
+    // --- Test 1: all components succeed and logs come from stream ---
+    ;(ToolsObserve as any).captureScreenshotHandler = async function() {
+      return { device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }, screenshot: 'BASE64PNG', resolution: { width: 1080, height: 1920 } }
+    }
+    ;(ToolsObserve as any).getCurrentScreenHandler = async function() {
+      return { device: { platform: 'android', id: 'mock' }, package: 'com.example', activity: 'com.example.Main', shortActivity: 'Main' }
+    }
+    ;(ToolsObserve as any).getScreenFingerprintHandler = async function() {
+      return { fingerprint: 'abc123', activity: 'Main' }
+    }
+    ;(ToolsObserve as any).getUITreeHandler = async function() {
+      return { device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }, screen: '', resolution: { width: 1080, height: 1920 }, elements: [] }
+    }
+    ;(ToolsObserve as any).readLogStreamHandler = async function() {
+      return { entries: [ { timestamp: '2026-03-23T20:00:00.000Z', level: 'ERROR', message: 'Boom' } ], crash_summary: { crash_detected: true } }
+    }
+    ;(ToolsObserve as any).getLogsHandler = async function() {
+      return { device: { platform: 'android', id: 'mock' }, logs: [], logCount: 0 }
+    }
+
+    const res1: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: true, logLines: 50, sessionId: 's1' })
+    console.log('res1:', JSON.stringify(res1, null, 2))
+    const pass1 = res1 && res1.screenshot === 'BASE64PNG' && res1.activity && res1.fingerprint === 'abc123' && Array.isArray(res1.logs) && res1.logs.length === 1
+    console.log('Test 1:', pass1 ? 'PASS' : 'FAIL')
+
+    // Restore handlers before next test
+    ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
+    ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler
+    ;(ToolsObserve as any).getScreenFingerprintHandler = origGetFpHandler
+    ;(ToolsObserve as any).getUITreeHandler = origGetTreeHandler
+    ;(ToolsObserve as any).readLogStreamHandler = origReadLogStreamHandler
+    ;(ToolsObserve as any).getLogsHandler = origGetLogsHandler
+
+    // --- Test 2: screenshot and ui tree fail; logs fallback to getLogs ---
+    ;(ToolsObserve as any).captureScreenshotHandler = async function() { throw new Error('screencap failed') }
+    ;(ToolsObserve as any).getUITreeHandler = async function() { throw new Error('uie_error') }
+    ;(ToolsObserve as any).readLogStreamHandler = async function() { return { entries: [] } }
+    ;(ToolsObserve as any).getLogsHandler = async function() { return { device: { platform: 'android', id: 'mock' }, logs: ['INFO starting','ERROR crash here'], logCount: 2 } }
+
+    const res2: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: true, logLines: 10, appId: 'com.example' })
+    console.log('res2:', JSON.stringify(res2, null, 2))
+    const pass2 = res2 && res2.screenshot_error && res2.ui_tree_error && Array.isArray(res2.logs) && res2.logs.length === 2
+    console.log('Test 2:', pass2 ? 'PASS' : 'FAIL')
+
+    // Restore handlers before next test
+    ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
+    ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler
+    ;(ToolsObserve as any).getScreenFingerprintHandler = origGetFpHandler
+    ;(ToolsObserve as any).getUITreeHandler = origGetTreeHandler
+    ;(ToolsObserve as any).readLogStreamHandler = origReadLogStreamHandler
+    ;(ToolsObserve as any).getLogsHandler = origGetLogsHandler
+
+    // --- Test 3: includeLogs=false should omit logs ---
+    ;(ToolsObserve as any).captureScreenshotHandler = async function() { return { device: { platform: 'android', id: 'mock' }, screenshot: null } }
+    ;(ToolsObserve as any).getCurrentScreenHandler = async function() { return { device: { platform: 'android', id: 'mock' }, package: '', activity: '', shortActivity: '' } }
+    ;(ToolsObserve as any).getScreenFingerprintHandler = async function() { return { fingerprint: null } }
+    ;(ToolsObserve as any).getUITreeHandler = async function() { return { device: { platform: 'android', id: 'mock' }, screen: '', resolution: { width: 0, height: 0 }, elements: [] } }
+    ;(ToolsObserve as any).readLogStreamHandler = async function() { return { entries: [] } }
+
+    const res3: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: false })
+    console.log('res3:', JSON.stringify(res3, null, 2))
+    const pass3 = res3 && typeof res3.logs !== 'undefined' && res3.logs.length === 0
+    console.log('Test 3:', pass3 ? 'PASS' : 'FAIL')
+
+  } finally {
+    ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
+    ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler
+    ;(ToolsObserve as any).getScreenFingerprintHandler = origGetFpHandler
+    ;(ToolsObserve as any).getUITreeHandler = origGetTreeHandler
+    ;(ToolsObserve as any).readLogStreamHandler = origReadLogStreamHandler
+    ;(ToolsObserve as any).getLogsHandler = origGetLogsHandler
+  }
+}
+
+run().catch(console.error)

package/test/observe/unit/find_element.test.ts

@@ -0,0 +1,85 @@
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+async function run() {
+  process.stdout.write('Starting find_element unit tests...\n')
+
+  const origGetTree = (ToolsObserve as any).getUITreeHandler
+
+  try {
+    // Test 1: exact text match
+    (ToolsObserve as any).getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock' },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: [
+        { text: 'Login', type: 'android.widget.Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [10,10,100,60], resourceId: 'btn_login' },
+        { text: 'Cancel', type: 'android.widget.Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [110,10,200,60], resourceId: 'btn_cancel' }
+      ]
+    })
+
+    const res1: any = await ToolsInteract.findElementHandler({ query: 'login', exact: true, platform: 'android' })
+    process.stdout.write('res1 ' + JSON.stringify(res1, null, 2) + '\n');
+    const pass1 = res1.found === true && res1.element && res1.element.resourceId === 'btn_login' && res1.element.tapCoordinates && typeof res1.element.tapCoordinates.x === 'number' && typeof res1.element.tapCoordinates.y === 'number' && typeof res1.confidence === 'number'
+    process.stdout.write('Test 1: ' + (pass1 ? 'PASS' : 'FAIL') + '\n');
+
+    // Test 2: partial match & scoring
+    (ToolsObserve as any).getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock' },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: [
+        { text: 'Sign in', type: 'android.widget.Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [10,10,100,60], resourceId: 'btn_signin' },
+        { text: 'Login with Email', type: 'android.widget.Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [110,10,300,60], resourceId: 'btn_login_email' }
+      ]
+    })
+
+    const res2: any = await ToolsInteract.findElementHandler({ query: 'login', exact: false, platform: 'android' })
+    process.stdout.write('res2 ' + JSON.stringify(res2, null, 2) + '\n');
+    const pass2 = res2.found === true && res2.element && res2.element.resourceId === 'btn_login_email' && res2.element.tapCoordinates && typeof res2.element.tapCoordinates.x === 'number' && typeof res2.element.tapCoordinates.y === 'number' && typeof res2.confidence === 'number'
+    process.stdout.write('Test 2: ' + (pass2 ? 'PASS' : 'FAIL') + '\n');
+
+    // Test 3: resourceId match
+    (ToolsObserve as any).getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock' },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: [
+        { text: null, type: 'android.widget.ImageView', contentDescription: null, clickable: false, enabled: true, visible: true, bounds: [0,0,50,50], resourceId: 'icon_login' }
+      ]
+    })
+
+    const res3: any = await ToolsInteract.findElementHandler({ query: 'icon_login', exact: false, platform: 'android' })
+    process.stdout.write('res3 ' + JSON.stringify(res3, null, 2) + '\n');
+    const pass3 = res3.found === true && res3.element && res3.element.resourceId === 'icon_login' && res3.element.tapCoordinates && typeof res3.element.tapCoordinates.x === 'number' && typeof res3.element.tapCoordinates.y === 'number' && typeof res3.confidence === 'number'
+    process.stdout.write('Test 3: ' + (pass3 ? 'PASS' : 'FAIL') + '\n');
+
+    // Test 4: parent-clickable child-text scenario
+    (ToolsObserve as any).getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock' },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: [
+        { text: null, type: 'android.view.View', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [0,0,400,100], resourceId: 'btn_generate', children: [1] },
+        { text: 'Generate Session', type: 'android.widget.TextView', contentDescription: null, clickable: false, enabled: true, visible: true, bounds: [10,10,390,90], resourceId: null, parentId: 0 }
+      ]
+    })
+
+    const res4: any = await ToolsInteract.findElementHandler({ query: 'generate', exact: false, platform: 'android', timeoutMs: 300 })
+    process.stdout.write('res4 ' + JSON.stringify(res4, null, 2) + '\n');
+    const pass4 = res4.found === true && res4.element && res4.element.clickable === true && res4.element.resourceId === 'btn_generate' && res4.element.tapCoordinates && typeof res4.element.tapCoordinates.x === 'number' && typeof res4.element.tapCoordinates.y === 'number' && typeof res4.confidence === 'number'
+    process.stdout.write('Test 4: ' + (pass4 ? 'PASS' : 'FAIL') + '\n');
+
+    // Test 5: not found
+    (ToolsObserve as any).getUITreeHandler = async () => ({ device: { platform: 'android', id: 'mock' }, screen: '', resolution: { width: 1080, height: 1920 }, elements: [] })
+    const res5: any = await ToolsInteract.findElementHandler({ query: 'nope', exact: false, platform: 'android', timeoutMs: 300 })
+    process.stdout.write('res5 ' + JSON.stringify(res5, null, 2) + '\n');
+    const pass5 = res5.found === false
+    process.stdout.write('Test 5: ' + (pass5 ? 'PASS' : 'FAIL') + '\n');
+
+  } finally {
+    ;(ToolsObserve as any).getUITreeHandler = origGetTree
+  }
+}
+
+run().catch(console.error)

package/test/unit/index.ts

@@ -11,5 +11,7 @@ import '../manage/unit/diagnostics.test.ts'
 import '../manage/unit/detection.test.ts'
 import '../manage/unit/mcp_disable_autodetect.test.ts'
 import '../interact/unit/wait_for_screen_change.test.ts'
+import '../observe/unit/capture_debug_snapshot.test.ts'
+import '../observe/unit/find_element.test.ts'
 
 console.log('Unit tests loaded.')