mobile-debug-mcp 0.13.0 → 0.14.0

package/README.md

@@ -1,4 +1,4 @@
-# Mobile Dev Tools
+# Mobile Debug Tools
 
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, and inspect Android/iOS apps from an MCP-compatible client.
 
@@ -33,7 +33,7 @@ I have a crash on the app, can you diagnose it, fix and validate using the mcp t
 
 ## Docs
 
-- Tools: [Tools](docs/TOOLS.md) — full input/response examples
+- Tools: [Tools](docs/tools/TOOLS.md) — full input/response examples
 - Changelog: [Changelog](docs/CHANGELOG.md)
 
 ## License

package/dist/android/interact.js

@@ -1,5 +1,6 @@
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js";
 import { AndroidObserve } from "./observe.js";
+import { scrollToElementShared } from "../tools/scroll_to_element.js";
 export class AndroidInteract {
     observe = new AndroidObserve();
     async waitForElement(text, timeout, deviceId) {
@@ -76,4 +77,15 @@ export class AndroidInteract {
             return { device: deviceInfo, success: false, error: e instanceof Error ? e.message : String(e) };
         }
     }
+    async scrollToElement(selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId) {
+        return await scrollToElementShared({
+            selector,
+            direction,
+            maxScrolls,
+            scrollAmount,
+            deviceId,
+            fetchTree: async () => await this.observe.getUITree(deviceId),
+            swipe: async (x1, y1, x2, y2, duration, devId) => await this.swipe(x1, y1, x2, y2, duration, devId)
+        });
+    }
 }

package/dist/ios/interact.js

@@ -1,6 +1,7 @@
 import { spawn } from "child_process";
 import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "./utils.js";
 import { iOSObserve } from "./observe.js";
+import { scrollToElementShared } from "../tools/scroll_to_element.js";
 export class iOSInteract {
     observe = new iOSObserve();
     async waitForElement(text, timeout, deviceId = "booted") {
@@ -66,4 +67,54 @@ export class iOSInteract {
             return { device, success: false, x, y, error: e instanceof Error ? e.message : String(e) };
         }
     }
+    async swipe(x1, y1, x2, y2, duration, deviceId = "booted") {
+        const device = await getIOSDeviceMetadata(deviceId);
+        // Use shared helper to detect idb
+        const idbExists = await isIDBInstalled();
+        if (!idbExists) {
+            return {
+                device,
+                success: false,
+                start: [x1, y1],
+                end: [x2, y2],
+                duration,
+                error: "iOS swipe requires 'idb' (iOS Device Bridge)."
+            };
+        }
+        try {
+            const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
+            // idb 'ui swipe' does not accept a duration parameter; use coordinates only
+            const args = ['ui', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString()];
+            if (targetUdid) {
+                args.push('--udid', targetUdid);
+            }
+            await new Promise((resolve, reject) => {
+                const proc = spawn(getIdbCmd(), args);
+                let stderr = '';
+                proc.stderr.on('data', d => stderr += d.toString());
+                proc.on('close', code => {
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(`idb ui swipe failed: ${stderr}`));
+                });
+                proc.on('error', err => reject(err));
+            });
+            return { device, success: true, start: [x1, y1], end: [x2, y2], duration };
+        }
+        catch (e) {
+            return { device, success: false, start: [x1, y1], end: [x2, y2], duration, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async scrollToElement(selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId = 'booted') {
+        return await scrollToElementShared({
+            selector,
+            direction,
+            maxScrolls,
+            scrollAmount,
+            deviceId,
+            fetchTree: async () => await this.observe.getUITree(deviceId),
+            swipe: async (x1, y1, x2, y2, duration, devId) => await this.swipe(x1, y1, x2, y2, duration, devId)
+        });
+    }
 }

package/dist/server.js

@@ -325,8 +325,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 properties: {
                     platform: {
                         type: "string",
-                        enum: ["android"],
-                        description: "Platform to swipe on (currently only android supported)"
+                        enum: ["android", "ios"],
+                        description: "Platform to swipe on (android or ios)"
                     },
                     x1: { type: "number", description: "Start X coordinate" },
                     y1: { type: "number", description: "Start Y coordinate" },
@@ -341,6 +341,30 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["x1", "y1", "x2", "y2", "duration"]
             }
         },
+        {
+            name: "scroll_to_element",
+            description: "Scroll the current screen until a target UI element becomes visible, then return its details.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: { type: "string", enum: ["android", "ios"], description: "Platform to operate on (required)" },
+                    selector: {
+                        type: "object",
+                        properties: {
+                            text: { type: "string" },
+                            resourceId: { type: "string" },
+                            contentDesc: { type: "string" },
+                            className: { type: "string" }
+                        }
+                    },
+                    direction: { type: "string", enum: ["down", "up"], default: "down" },
+                    maxScrolls: { type: "number", default: 10 },
+                    scrollAmount: { type: "number", default: 0.7 },
+                    deviceId: { type: "string", description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected." }
+                },
+                required: ["platform", "selector"]
+            }
+        },
         {
             name: "type_text",
             description: "Type text into the currently focused input field on an Android device.",
@@ -527,8 +551,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return wrapResponse(res);
         }
         if (name === "swipe") {
-            const { x1, y1, x2, y2, duration, deviceId } = (args || {});
-            const res = await ToolsInteract.swipeHandler({ x1, y1, x2, y2, duration, deviceId });
+            const { platform = 'android', x1, y1, x2, y2, duration, deviceId } = (args || {});
+            const res = await ToolsInteract.swipeHandler({ platform, x1, y1, x2, y2, duration, deviceId });
+            return wrapResponse(res);
+        }
+        if (name === "scroll_to_element") {
+            const { platform, selector, direction, maxScrolls, scrollAmount, deviceId } = (args || {});
+            const res = await ToolsInteract.scrollToElementHandler({ platform, selector, direction, maxScrolls, scrollAmount, deviceId });
             return wrapResponse(res);
         }
         if (name === "type_text") {

package/dist/tools/interact.js

@@ -2,31 +2,24 @@ import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { AndroidInteract } from '../android/interact.js';
 import { iOSInteract } from '../ios/interact.js';
 export class ToolsInteract {
+    static async getInteractionService(platform, deviceId) {
+        const effectivePlatform = platform || 'android';
+        const resolved = await resolveTargetDevice({ platform: effectivePlatform, deviceId });
+        const interact = effectivePlatform === 'android' ? new AndroidInteract() : new iOSInteract();
+        return { interact: interact, resolved, platform: effectivePlatform };
+    }
     static async waitForElementHandler({ platform, text, timeout, deviceId }) {
         const effectiveTimeout = timeout ?? 10000;
-        if (platform === 'android') {
-            const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
-            return await new AndroidInteract().waitForElement(text, effectiveTimeout, resolved.id);
-        }
-        else {
-            const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
-            return await new iOSInteract().waitForElement(text, effectiveTimeout, resolved.id);
-        }
+        const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
+        return await interact.waitForElement(text, effectiveTimeout, resolved.id);
     }
     static async tapHandler({ platform, x, y, deviceId }) {
-        const effectivePlatform = platform || 'android';
-        if (effectivePlatform === 'android') {
-            const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
-            return await new AndroidInteract().tap(x, y, resolved.id);
-        }
-        else {
-            const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
-            return await new iOSInteract().tap(x, y, resolved.id);
-        }
+        const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
+        return await interact.tap(x, y, resolved.id);
     }
-    static async swipeHandler({ x1, y1, x2, y2, duration, deviceId }) {
-        const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
-        return await new AndroidInteract().swipe(x1, y1, x2, y2, duration, resolved.id);
+    static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }) {
+        const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
+        return await interact.swipe(x1, y1, x2, y2, duration, resolved.id);
     }
     static async typeTextHandler({ text, deviceId }) {
         const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
@@ -36,4 +29,8 @@ export class ToolsInteract {
         const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
         return await new AndroidInteract().pressBack(resolved.id);
     }
+    static async scrollToElementHandler({ platform, selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId }) {
+        const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
+        return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id);
+    }
 }

package/dist/tools/scroll_to_element.js

@@ -0,0 +1,98 @@
+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) {
+            // Log swipe failures to aid debugging but don't fail the overall flow
+            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.14.0]
+- Added `scroll_to_element` tool: platform-aware helper that scrolls until a UI element matching a selector is visible. Supports Android and iOS with configurable options: direction, maxScrolls, and scrollAmount. Includes unit tests and device runners under `test/device/` for manual E2E validation.
+- Moved scroll logic into platform-specific implementations (`src/android/interact.ts`, `src/ios/interact.ts`) and delegated from `src/tools/interact.ts` to centralise platform behaviour.
+- Fixed iOS `idb` swipe arguments and improved visibility detection by using element bounds and device resolution to avoid treating off-screen elements as visible.
+- Consolidated unit tests for `scroll_to_element` into `test/unit/observe/scroll_to_element.test.ts`, and removed older duplicate test files.
+
+
 ## [0.13.0]
 - Fixed a crash in the `start_app` tool by adding validation to ensure `appId` and `platform` are provided.
 

package/docs/tools/TOOLS.md

@@ -4,8 +4,8 @@ This repository groups tool docs into three areas aligned with the codebase: man
 
 See:
 
-- docs/manage.md — build, install and device management tools
-- docs/observe.md — logs, screenshots and UI inspection tools
-- docs/interact.md — UI interaction tools (tap, swipe, type, wait)
+- [mange](manage.md) — build, install and device management tools
+- [observe](observe.md) — logs, screenshots and UI inspection tools
+- [interact](interact.md) — UI interaction tools (tap, swipe, type, wait)
 
 For per-tool deep dives, open the linked files above.

package/docs/tools/interact.md

@@ -41,3 +41,34 @@ Notes:
 - swipe: `adb shell input swipe x1 y1 x2 y2 duration`.
 - type_text: `adb shell input text` (spaces encoded as %s) — may fail for special characters.
 - press_back: `adb shell input keyevent 4`.
+
+---
+
+## scroll_to_element
+
+Description:
+- Scrolls the UI until an element matching the provided selector becomes visible, or until a maximum number of scroll attempts is reached.
+- Delegates platform behaviour to Android and iOS implementations for reliable swipes and UI-tree checks.
+
+Input example:
+```
+{ "platform": "android", "selector": { "text": "Offscreen Test Element" }, "direction": "down", "maxScrolls": 10, "scrollAmount": 0.7, "deviceId": "emulator-5554" }
+```
+
+Response example (found):
+```
+{ "success": true, "reason": "element_found", "element": { /* element metadata */ }, "scrollsPerformed": 2 }
+```
+
+Response example (failure - unchanged UI):
+```
+{ "success": false, "reason": "ui_unchanged_after_scroll", "scrollsPerformed": 3 }
+```
+
+Notes:
+- Matching is exact on provided selector fields (text, resourceId, contentDesc, className).
+- Visibility check uses element.bounds intersecting the device resolution when available; falls back to the element.visible flag if bounds/resolution are missing.
+- The tool fingerprints the visible UI between scrolls; if the fingerprint doesn't change after a swipe the tool stops early assuming end-of-list.
+- 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/`.
+

package/package.json

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

package/src/android/interact.ts

@@ -1,6 +1,7 @@
 import { WaitForElementResponse, TapResponse, SwipeResponse, TypeTextResponse, PressBackResponse } from "../types.js"
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js"
 import { AndroidObserve } from "./observe.js"
+import { scrollToElementShared } from "../tools/scroll_to_element.js"
 
 
 export class AndroidInteract {
@@ -88,4 +89,16 @@ export class AndroidInteract {
     }
   }
 
+  async scrollToElement(selector: { text?: string, resourceId?: string, contentDesc?: string, className?: string }, direction: 'down' | 'up' = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId?: string) {
+    return await scrollToElementShared({
+      selector,
+      direction,
+      maxScrolls,
+      scrollAmount,
+      deviceId,
+      fetchTree: async () => await this.observe.getUITree(deviceId),
+      swipe: async (x1: number, y1: number, x2: number, y2: number, duration: number, devId?: string) => await this.swipe(x1, y1, x2, y2, duration, devId)
+    })
+  }
+
 }

package/src/ios/interact.ts

@@ -1,7 +1,8 @@
 import { spawn } from "child_process"
-import { WaitForElementResponse, TapResponse } from "../types.js"
+import { WaitForElementResponse, TapResponse, SwipeResponse } from "../types.js"
 import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "./utils.js"
 import { iOSObserve } from "./observe.js"
+import { scrollToElementShared } from "../tools/scroll_to_element.js"
 
 export class iOSInteract {
   private observe = new iOSObserve();
@@ -75,4 +76,58 @@ export class iOSInteract {
       return { device, success: false, x, y, error: e instanceof Error ? e.message : String(e) };
     }
   }
+
+  async swipe(x1: number, y1: number, x2: number, y2: number, duration: number, deviceId: string = "booted"): Promise<SwipeResponse> {
+    const device = await getIOSDeviceMetadata(deviceId);
+    // Use shared helper to detect idb
+    const idbExists = await isIDBInstalled();
+
+    if (!idbExists) {
+      return {
+        device,
+        success: false,
+        start: [x1, y1],
+        end: [x2, y2],
+        duration,
+        error: "iOS swipe requires 'idb' (iOS Device Bridge)."
+      }
+    }
+
+    try {
+      const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
+      // idb 'ui swipe' does not accept a duration parameter; use coordinates only
+      const args: string[] = ['ui', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString()];
+      if (targetUdid) {
+        args.push('--udid', targetUdid);
+      }
+
+      await new Promise<void>((resolve, reject) => {
+        const proc = spawn(getIdbCmd(), args);
+        let stderr = '';
+        proc.stderr.on('data', d => stderr += d.toString());
+        proc.on('close', code => {
+          if (code === 0) resolve();
+          else reject(new Error(`idb ui swipe failed: ${stderr}`));
+        });
+        proc.on('error', err => reject(err));
+      });
+
+      return { device, success: true, start: [x1, y1], end: [x2, y2], duration };
+    } catch (e) {
+      return { device, success: false, start: [x1, y1], end: [x2, y2], duration, error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  async scrollToElement(selector: { text?: string, resourceId?: string, contentDesc?: string, className?: string }, direction: 'down' | 'up' = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId: string = 'booted') {
+    return await scrollToElementShared({
+      selector,
+      direction,
+      maxScrolls,
+      scrollAmount,
+      deviceId,
+      fetchTree: async () => await this.observe.getUITree(deviceId),
+      swipe: async (x1: number, y1: number, x2: number, y2: number, duration: number, devId?: string) => await this.swipe(x1, y1, x2, y2, duration, devId)
+    })
+  }
 }
+

package/src/server.ts

@@ -346,8 +346,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         properties: {
           platform: {
             type: "string",
-            enum: ["android"],
-            description: "Platform to swipe on (currently only android supported)"
+            enum: ["android","ios"],
+            description: "Platform to swipe on (android or ios)"
           },
           x1: { type: "number", description: "Start X coordinate" },
           y1: { type: "number", description: "Start Y coordinate" },
@@ -362,6 +362,30 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["x1", "y1", "x2", "y2", "duration"]
       }
     },
+    {
+      name: "scroll_to_element",
+      description: "Scroll the current screen until a target UI element becomes visible, then return its details.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          platform: { type: "string", enum: ["android", "ios"], description: "Platform to operate on (required)" },
+          selector: {
+            type: "object",
+            properties: {
+              text: { type: "string" },
+              resourceId: { type: "string" },
+              contentDesc: { type: "string" },
+              className: { type: "string" }
+            }
+          },
+          direction: { type: "string", enum: ["down", "up"], default: "down" },
+          maxScrolls: { type: "number", default: 10 },
+          scrollAmount: { type: "number", default: 0.7 },
+          deviceId: { type: "string", description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected." }
+        },
+        required: ["platform", "selector"]
+      }
+    },
     {
       name: "type_text",
       description: "Type text into the currently focused input field on an Android device.",
@@ -568,8 +592,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
 
     if (name === "swipe") {
-      const { x1, y1, x2, y2, duration, deviceId } = (args || {}) as any
-      const res = await ToolsInteract.swipeHandler({ x1, y1, x2, y2, duration, deviceId })
+      const { platform = 'android', x1, y1, x2, y2, duration, deviceId } = (args || {}) as any
+      const res = await ToolsInteract.swipeHandler({ platform, x1, y1, x2, y2, duration, deviceId })
+      return wrapResponse(res)
+    }
+
+    if (name === "scroll_to_element") {
+      const { platform, selector, direction, maxScrolls, scrollAmount, deviceId } = (args || {}) as any
+      const res = await ToolsInteract.scrollToElementHandler({ platform, selector, direction, maxScrolls, scrollAmount, deviceId })
       return wrapResponse(res)
     }
 

package/src/tools/interact.ts

@@ -4,31 +4,27 @@ import { iOSInteract } from '../ios/interact.js'
 
 export class ToolsInteract {
 
+  private static async getInteractionService(platform?: 'android' | 'ios', deviceId?: string) {
+    const effectivePlatform = platform || 'android'
+    const resolved = await resolveTargetDevice({ platform: effectivePlatform as 'android' | 'ios', deviceId })
+    const interact = effectivePlatform === 'android' ? new AndroidInteract() : new iOSInteract()
+    return { interact: interact as any, resolved, platform: effectivePlatform }
+  }
+
   static async waitForElementHandler({ platform, text, timeout, deviceId }: { platform: 'android' | 'ios', text: string, timeout?: number, deviceId?: string }) {
     const effectiveTimeout = timeout ?? 10000
-    if (platform === 'android') {
-      const resolved = await resolveTargetDevice({ platform: 'android', deviceId })
-      return await new AndroidInteract().waitForElement(text, effectiveTimeout, resolved.id)
-    } else {
-      const resolved = await resolveTargetDevice({ platform: 'ios', deviceId })
-      return await new iOSInteract().waitForElement(text, effectiveTimeout, resolved.id)
-    }
+    const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId)
+    return await interact.waitForElement(text, effectiveTimeout, resolved.id)
   }
 
   static async tapHandler({ platform, x, y, deviceId }: { platform?: 'android' | 'ios', x: number, y: number, deviceId?: string }) {
-    const effectivePlatform = platform || 'android'
-    if (effectivePlatform === 'android') {
-      const resolved = await resolveTargetDevice({ platform: 'android', deviceId })
-      return await new AndroidInteract().tap(x, y, resolved.id)
-    } else {
-      const resolved = await resolveTargetDevice({ platform: 'ios', deviceId })
-      return await new iOSInteract().tap(x, y, resolved.id)
-    }
+    const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId)
+    return await interact.tap(x, y, resolved.id)
   }
 
-  static async swipeHandler({ x1, y1, x2, y2, duration, deviceId }: { x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string }) {
-    const resolved = await resolveTargetDevice({ platform: 'android', deviceId })
-    return await new AndroidInteract().swipe(x1, y1, x2, y2, duration, resolved.id)
+  static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }: { platform?: 'android' | 'ios', x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string }) {
+    const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId)
+    return await interact.swipe(x1, y1, x2, y2, duration, resolved.id)
   }
 
   static async typeTextHandler({ text, deviceId }: { text: string, deviceId?: string }) {
@@ -41,5 +37,10 @@ export class ToolsInteract {
     return await new AndroidInteract().pressBack(resolved.id)
   }
 
+  static async scrollToElementHandler({ platform, selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId }: { platform: 'android' | 'ios', selector: { text?: string, resourceId?: string, contentDesc?: string, className?: string }, direction?: 'down' | 'up', maxScrolls?: number, scrollAmount?: number, deviceId?: string }) {
+    const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId)
+    return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id)
+  }
+
 }
 

package/src/tools/scroll_to_element.ts

@@ -0,0 +1,110 @@
+import { UIElement, GetUITreeResponse, SwipeResponse } from '../types.js'
+
+export interface ScrollSelector { text?: string; resourceId?: string; contentDesc?: string; className?: string }
+
+export async function scrollToElementShared(opts: {
+  selector: ScrollSelector,
+  direction?: 'down' | 'up',
+  maxScrolls?: number,
+  scrollAmount?: number,
+  deviceId?: string,
+  fetchTree: () => Promise<GetUITreeResponse>,
+  swipe: (x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string) => Promise<SwipeResponse>,
+  stabilizationDelayMs?: number
+}): Promise<{ success: boolean; reason?: string; element?: Partial<UIElement>; scrollsPerformed: number }> {
+  const { selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId, fetchTree, swipe, stabilizationDelayMs = 350 } = opts
+
+  const matchElement = (el?: UIElement) => {
+    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?: UIElement, resolution?: GetUITreeResponse['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?: UIElement[], resolution?: GetUITreeResponse['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: GetUITreeResponse) => {
+    try {
+      return JSON.stringify((t.elements || []).map((e: UIElement) => ({ 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: number) => 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) {
+      // Log swipe failures to aid debugging but don't fail the overall flow
+      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/test/device/observe/run-scroll-test-android.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { AndroidInteract } from '../../../dist/android/interact.js'
+
+
+// Usage: tsx test/device/observe/run-scroll-test-android.ts <deviceId> <appId> <selectorText>
+const args = process.argv.slice(2)
+const DEVICE_ID = args[0] || process.env.DEVICE_ID || 'emulator-5554'
+const SELECTOR = args[2] || process.env.SELECTOR || 'Generate Session'
+
+async function main() {
+  console.log('Starting app if not running...')
+  // Best-effort tap to wake device/emulator
+  try { const tmp = new AndroidInteract(); await tmp.tap(10,10, DEVICE_ID).catch(()=>{}) } catch {}
+  await new Promise(r => setTimeout(r, 1000))
+
+  console.log('Running scroll_to_element for selector:', SELECTOR)
+  // Use ToolsInteract from dist to call the handler
+  const ToolsInteract = (await import('../../../dist/tools/interact.js')).ToolsInteract
+
+  const res = await (ToolsInteract as any).scrollToElementHandler({ platform: 'android', selector: { text: SELECTOR }, direction: 'down', maxScrolls: 10, scrollAmount: 0.7, deviceId: DEVICE_ID })
+  console.log('Result:', JSON.stringify(res, null, 2))
+}
+
+main().catch(console.error)

package/test/unit/observe/scroll_to_element.test.ts

@@ -0,0 +1,129 @@
+import { ToolsInteract } from '../../../src/tools/interact.js'
+import { ToolsObserve } from '../../../src/tools/observe.js'
+
+const origGet = (ToolsObserve as any).getUITreeHandler
+const origSwipe = (ToolsInteract as any).swipeHandler
+
+async function runTests() {
+  // Use a stable logger to avoid test harness replacing console.log between calls
+  console.log = (...args: any[]) => { try { process.stdout.write(args.map(a => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ') + '\n') } catch {} }
+  console.log('Starting tests for scroll_to_element...')
+
+  // Test 1: Element found immediately
+  console.log('\nTest 1: Element found immediately')
+  (ToolsObserve as any).getUITreeHandler = async () => ({
+    device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+    screen: '',
+    resolution: { width: 1080, height: 1920 },
+    elements: [{
+      text: 'Target',
+      type: 'Button',
+      contentDescription: null,
+      clickable: true,
+      enabled: true,
+      visible: true,
+      bounds: [0, 0, 100, 100],
+      resourceId: null
+    }]
+  })
+
+  const res1 = await ToolsInteract.scrollToElementHandler({ platform: 'android', selector: { text: 'Target' }, direction: 'down', maxScrolls: 5, scrollAmount: 0.7 })
+  console.log('Result:', res1.success === true ? 'PASS' : 'FAIL')
+  console.log('scrollsPerformed:', (res1 as any).scrollsPerformed)
+
+  // Test 2: Element found after scrolling
+  console.log('\nTest 2: Element found after scrolling')
+  let calls = 0
+  (ToolsObserve as any).getUITreeHandler = async () => {
+    calls++
+    if (calls < 3) {
+      return {
+        device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+        screen: '',
+        resolution: { width: 1080, height: 1920 },
+        elements: []
+      }
+    }
+    return {
+      device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: [{
+        text: 'Target',
+        type: 'Button',
+        contentDescription: null,
+        clickable: true,
+        enabled: true,
+        visible: true,
+        bounds: [0, 0, 100, 100],
+        resourceId: null
+      }]
+    }
+  }
+
+  // Stub swipe so it doesn't try to call adb/idb
+  (ToolsInteract as any).swipeHandler = async () => ({ success: true })
+
+  const res2 = await ToolsInteract.scrollToElementHandler({ platform: 'android', selector: { text: 'Target' }, direction: 'down', maxScrolls: 5, scrollAmount: 0.7 })
+  console.log('Result:', res2.success === true ? 'PASS' : 'FAIL')
+  console.log('calls:', calls, calls >= 3 ? 'PASS' : 'FAIL')
+
+  // Test 3: UI unchanged stops early
+  console.log('\nTest 3: UI unchanged stops early')
+  (ToolsObserve as any).getUITreeHandler = async () => ({
+    device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+    screen: '',
+    resolution: { width: 1080, height: 1920 },
+    elements: []
+  })
+
+  (ToolsInteract as any).swipeHandler = async () => ({ success: true })
+
+  const res3 = await ToolsInteract.scrollToElementHandler({ platform: 'android', selector: { text: 'Missing' }, direction: 'down', maxScrolls: 5, scrollAmount: 0.7 })
+  console.log('Result:', res3.success === false && (res3 as any).attempts === 1 ? 'PASS' : 'FAIL')
+  console.log('Reason:', (res3 as any).reason || JSON.stringify(res3))
+
+  // Test 4: Offscreen element scrolls into view
+  console.log('\nTest 4: Offscreen element scrolls into view')
+  const ai = new (await import('../../../src/android/interact.js')).AndroidInteract()
+  const origObserveGet = ai['observe'].getUITree
+  const origAiSwipe = ai.swipe
+  let swiped = false
+  let swipeCalled = 0
+  ;(ai['observe'] as any).getUITree = async () => {
+    if (!swiped) {
+      return {
+        device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+        screen: '',
+        resolution: { width: 1080, height: 1920 },
+        elements: [ { text: null, type: 'android.view.View', resourceId: null, contentDescription: null, bounds: [0,0,1080,200], visible: true } ]
+      }
+    }
+    return {
+      device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: [{ text: 'OffscreenTarget', type: 'android.widget.Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [100,400,300,460], resourceId: null }]
+    }
+  }
+  ;(ai as any).swipe = async () => { swipeCalled++; swiped = true; return { success: true } }
+
+  const r4 = await ai.scrollToElement({ text: 'OffscreenTarget' }, 'down', 3, 0.7, 'mock')
+  const ok4 = r4 && (r4 as any).success === true && (r4 as any).scrollsPerformed === 1 && swipeCalled === 1
+  console.log('Result:', ok4 ? 'PASS' : 'FAIL')
+  console.log('  success:', (r4 as any).success, 'scrollsPerformed:', (r4 as any).scrollsPerformed, 'swipeCalled:', swipeCalled)
+
+  ;(ai['observe'] as any).getUITree = origObserveGet
+  ;(ai as any).swipe = origAiSwipe
+
+  // Restore
+  (ToolsObserve as any).getUITreeHandler = origGet
+  ;(ToolsInteract as any).swipeHandler = origSwipe
+}
+
+// Ensure console.log is a function (some test runners replace it)
+if (typeof console.log !== 'function') {
+  console.log = (...args: any[]) => { try { process.stdout.write(args.map(a => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ') + '\n') } catch { /* swallow */ } }
+}
+
+runTests().catch(console.error)

package/test/unit/observe/wait_for_element_mock.ts

@@ -95,7 +95,7 @@ async function runTests() {
   const elapsed4 = Date.now() - start4;
   console.log("Result:", result4.found === false && result4.error === "ADB Connection Failed" ? "PASS" : "FAIL");
   console.log("Error Message:", result4.error);
-  console.log("Elapsed time (should be < 500ms):", elapsed4, elapsed4 < 500 ? "PASS" : "FAIL");
+  console.log("Elapsed time (should be < 1000ms):", elapsed4, elapsed4 < 1000 ? "PASS" : "FAIL");
 
   // Restore
   (AndroidObserve as any).prototype.getUITree = originalGetUITree;