mobile-debug-mcp 0.17.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/server.js

@@ -332,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.",
@@ -602,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,10 @@
 
 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.
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.17.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

@@ -7,6 +7,28 @@ 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) {
@@ -47,6 +69,160 @@ 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
@@ -74,14 +250,9 @@ export class ToolsInteract {
             }
             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/server.ts

@@ -354,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",
@@ -647,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/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

@@ -12,5 +12,6 @@ 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.')