mobile-debug-mcp 0.12.8 → 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/ios/manage.js

@@ -291,117 +291,16 @@ export class iOSManage {
     }
     async startApp(bundleId, deviceId = "booted") {
         validateBundleId(bundleId);
-        // Prepare instrumentation object upfront so it can be returned to callers
-        const instrumentation = { ts: new Date().toISOString(), action: 'startApp', cmd: 'xcrun', args: ['simctl', 'launch', deviceId, bundleId], cwd: process.cwd(), env: { PATH: process.env.PATH, XCRUN_PATH: process.env.XCRUN_PATH } };
         try {
-            // Instrumentation: persist and emit to stderr for server logs
-            try {
-                await fs.appendFile('/tmp/mcp_startapp_instrument.log', JSON.stringify(instrumentation) + '\n');
-            }
-            catch (e) { }
-            try {
-                console.error('MCP-STARTAPP-EXEC', JSON.stringify(instrumentation));
-            }
-            catch (e) { }
-        }
-        catch { }
-        // Attempt to launch
-        let launchResult = null;
-        try {
-            launchResult = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId);
-        }
-        catch (launchErr) {
-            // Collect diagnostics when simctl launch fails
-            const launchDiag = execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId);
+            const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId);
             const device = await getIOSDeviceMetadata(deviceId);
-            const post = await this.collectPostLaunchDiagnostics(bundleId, deviceId);
-            return { device, appStarted: false, launchTimeMs: 0, error: launchErr instanceof Error ? launchErr.message : String(launchErr), diagnostics: { launchDiag, post }, instrumentation };
-        }
-        // Basic success — but verify RunningBoard/installcoordination didn't mark it as placeholder
-        const device = await getIOSDeviceMetadata(deviceId);
-        // short wait to let system settle
-        await new Promise(r => setTimeout(r, 1000));
-        let appinfo = '';
-        try {
-            const ai = await execCommand(['simctl', 'appinfo', deviceId, bundleId], deviceId);
-            appinfo = ai.output || '';
-        }
-        catch { }
-        // capture recent runningboard/installcoordination logs
-        const logDiag = execCommandWithDiagnostics(['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog', '--predicate', `(process == "${bundleId}" ) OR eventMessage CONTAINS "installcoordinationd" OR eventMessage CONTAINS "runningboard"`, '--last', '1m'], deviceId);
-        const placeholderDetected = (appinfo && /isPlaceholder[:=]?\s*Y/i.test(appinfo)) || (logDiag && ((logDiag.runResult && ((logDiag.runResult.stdout || '').includes('isPlaceholder')) || (logDiag.runResult.stderr || '').includes('isPlaceholder'))));
-        if (placeholderDetected) {
-            const post = await this.collectPostLaunchDiagnostics(bundleId, deviceId, appinfo);
-            return { device, appStarted: false, launchTimeMs: 0, diagnostics: { appinfo, logDiag, post }, instrumentation };
-        }
-        return { device, appStarted: !!(launchResult && launchResult.output), launchTimeMs: 1000, instrumentation };
-    }
-    appExecutableName(bundleId) {
-        // Best-effort executable name: prefer last component of bundleId
-        try {
-            const candidate = bundleId.split('.').pop();
-            return candidate || bundleId;
-        }
-        catch {
-            return bundleId;
-        }
-    }
-    // Collect bundle- and system-level diagnostics after a failed or placeholder launch
-    async collectPostLaunchDiagnostics(bundleId, deviceId = "booted", appinfo) {
-        const diagnostics = { ts: new Date().toISOString(), bundleId, deviceId };
-        // gather simctl appinfo (if not provided)
-        try {
-            diagnostics.appinfo = appinfo || ((await execCommand(['simctl', 'appinfo', deviceId, bundleId], deviceId)).output || '');
-        }
-        catch (e) {
-            diagnostics.appinfoError = String(e);
-        }
-        // attempt to discover bundle path from appinfo
-        let bundlePath = null;
-        if (diagnostics.appinfo) {
-            const m = diagnostics.appinfo.match(/Path\s*=\s*"?([\S]+)"?/) || diagnostics.appinfo.match(/Container: (\/\S+)/);
-            if (m)
-                bundlePath = m[1];
-        }
-        // lipo / file / otool / codesign / xattr
-        if (bundlePath) {
-            diagnostics.bundlePath = bundlePath;
-            const execs = [
-                { name: 'file', cmd: ['file', bundlePath + '/' + this.appExecutableName(bundleId)] },
-                { name: 'lipo', cmd: ['lipo', '-info', bundlePath + '/' + this.appExecutableName(bundleId)] },
-                { name: 'otool-L', cmd: ['otool', '-L', bundlePath + '/' + this.appExecutableName(bundleId)] },
-                { name: 'otool-load', cmd: ['otool', '-l', bundlePath + '/' + this.appExecutableName(bundleId)] },
-                { name: 'plutil', cmd: ['plutil', '-p', bundlePath + '/Info.plist'] },
-                { name: 'codesign', cmd: ['codesign', '-dvvv', bundlePath] },
-                { name: 'xattr', cmd: ['xattr', '-l', bundlePath] },
-                { name: 'ls', cmd: ['ls', '-la', bundlePath] },
-            ];
-            diagnostics.bundle = {};
-            for (const e of execs) {
-                try {
-                    const r = execCommandWithDiagnostics(e.cmd, deviceId);
-                    diagnostics.bundle[e.name] = r && r.runResult ? { stdout: r.runResult.stdout, stderr: r.runResult.stderr, code: r.runResult.exitCode } : { error: 'no-result' };
-                }
-                catch (err) {
-                    diagnostics.bundle[e.name] = { error: String(err) };
-                }
-            }
-        }
-        // collect recent system logs and a screenshot
-        try {
-            diagnostics.recentLogs = execCommandWithDiagnostics(['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog', '--predicate', `eventMessage CONTAINS "installcoordinationd" OR eventMessage CONTAINS "runningboard"`, '--last', '5m'], deviceId);
-        }
-        catch (e) {
-            diagnostics.recentLogsError = String(e);
-        }
-        try {
-            const shot = await execCommandWithDiagnostics(['simctl', 'io', deviceId, 'screenshot', '--type', 'png', '/tmp/mcp_post_launch_screenshot.png'], deviceId);
-            diagnostics.screenshot = { created: true, path: '/tmp/mcp_post_launch_screenshot.png', result: shot && shot.runResult };
+            return { device, appStarted: !!result.output, launchTimeMs: 1000 };
         }
         catch (e) {
-            diagnostics.screenshotError = String(e);
+            const diag = execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId);
+            const device = await getIOSDeviceMetadata(deviceId);
+            return { device, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
         }
-        return diagnostics;
     }
     async terminateApp(bundleId, deviceId = "booted") {
         validateBundleId(bundleId);

package/dist/ios/utils.js

@@ -96,40 +96,7 @@ export function validateBundleId(bundleId) {
 }
 export function execCommand(args, deviceId = "booted") {
     return new Promise((resolve, reject) => {
-        // Instrumentation: append a JSON line with timestamp, command, args, cwd and selected env vars
-        try {
-            const mcpEnv = {};
-            for (const k of Object.keys(process.env || {})) {
-                if (k.startsWith('MCP_'))
-                    mcpEnv[k] = process.env[k];
-            }
-            const instrument = {
-                timestamp: new Date().toISOString(),
-                command: getXcrunCmd(),
-                args,
-                cwd: process.cwd(),
-                env: {
-                    PATH: process.env.PATH,
-                    XCRUN_PATH: process.env.XCRUN_PATH,
-                    ...mcpEnv
-                }
-            };
-            try {
-                require('fs').appendFileSync('/tmp/mcp_exec_instrument.log', JSON.stringify(instrument) + '\n');
-            }
-            catch (e) { }
-        }
-        catch (e) {
-            // swallow instrumentation errors to avoid changing behavior
-        }
         // Use spawn for better stream control and consistency with Android implementation
-        // Instrument: emit a JSON line to stderr so the MCP server stderr/stdout capture can record the exact command and env
-        try {
-            const instLine = JSON.stringify({ ts: new Date().toISOString(), cmd: getXcrunCmd(), args, cwd: process.cwd(), PATH: process.env.PATH });
-            // Use stderr so it appears in server logs reliably
-            console.error('MCP-INSTRUMENT-EXEC', instLine);
-        }
-        catch (e) { }
         const child = spawn(getXcrunCmd(), args);
         let stdout = '';
         let stderr = '';
@@ -143,17 +110,6 @@ export function execCommand(args, deviceId = "booted") {
                 stderr += data.toString();
             });
         }
-        // Additional instrumentation: write pid and env snapshot when child starts
-        try {
-            const pidInfo = { ts: new Date().toISOString(), childPid: (child.pid || null), invoked: getXcrunCmd(), args };
-            try {
-                require('fs').appendFileSync('/tmp/mcp_exec_instrument.log', JSON.stringify(pidInfo) + '\n');
-            }
-            catch (e) { }
-        }
-        catch (e) {
-            // ignore
-        }
         const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000; // env (ms) or default 30s
         const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000; // env (ms) or default 60s
         const timeoutMs = args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT; // choose appropriate timeout
@@ -177,11 +133,6 @@ export function execCommand(args, deviceId = "booted") {
     });
 }
 export function execCommandWithDiagnostics(args, deviceId = "booted") {
-    try {
-        const syncInst = { ts: new Date().toISOString(), cmd: getXcrunCmd(), args, cwd: process.cwd() };
-        require('fs').appendFileSync('/tmp/mcp_exec_instrument_sync.log', JSON.stringify(syncInst) + '\n');
-    }
-    catch (e) { }
     // Run synchronously to capture stdout/stderr and exitCode reliably for diagnostics
     const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000;
     const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000;

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.",
@@ -389,37 +413,52 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         if (name === "start_app") {
             const { platform, appId, deviceId } = args;
-            // Defensive validation: ensure required args are present and log malformed requests
+            // Defensive validation: ensure caller provided platform and appId.
             if (!platform || !appId) {
+                const msg = 'Both platform and appId parameters are required (platform: ios|android, appId: bundle id or package name).';
+                const payload = { ts: new Date().toISOString(), tool: 'start_app', args };
+                let logged = false;
+                // Prefer the diagnostics module when available
                 try {
-                    require('fs').appendFileSync('/tmp/mcp_bad_requests.log', JSON.stringify({ ts: new Date().toISOString(), tool: 'start_app', args }) + '\n');
+                    const diag = require('./utils/diagnostics.js');
+                    if (diag && diag.appendDiagnosticFile) {
+                        diag.appendDiagnosticFile('bad_requests.log', payload);
+                        logged = true;
+                    }
                 }
-                catch (e) { }
-                const deviceFallback = { platform: platform || 'ios', id: deviceId || 'unknown', osVersion: '', model: '', simulator: true };
-                const response = { device: deviceFallback, appStarted: false, launchTimeMs: 0, error: 'Missing required argument: platform and/or appId', diagnostics: { receivedArgs: args } };
-                return wrapResponse(response);
-            }
-            try {
-                const res = await (platform === 'android' ? new AndroidManage().startApp(appId, deviceId) : new iOSManage().startApp(appId, deviceId));
-                // Preserve diagnostics and instrumentation from platform managers so agents receive full context
-                const response = {
-                    device: res.device,
-                    appStarted: res.appStarted,
-                    launchTimeMs: res.launchTimeMs,
-                    error: res.error,
-                    diagnostics: res.diagnostics,
-                    instrumentation: res.instrumentation
-                };
-                return wrapResponse(response);
-            }
-            catch (err) {
-                try {
-                    require('fs').appendFileSync('/tmp/mcp_bad_requests.log', JSON.stringify({ ts: new Date().toISOString(), tool: 'start_app', args, error: err && err.message ? err.message : String(err) }) + '\n');
+                catch (err) {
+                    console.error('Diagnostics append failed:', String(err));
+                }
+                // Fallback to /tmp file (synchronous) and report failures rather than swallowing
+                if (!logged) {
+                    try {
+                        const fs = require('fs');
+                        fs.appendFileSync('/tmp/mcp_bad_requests.log', JSON.stringify(payload) + '\n');
+                        logged = true;
+                    }
+                    catch (err) {
+                        console.error('Failed to write bad request to /tmp/mcp_bad_requests.log:', String(err));
+                    }
+                }
+                // Final fallback: emit payload to stderr so it's visible in server logs
+                if (!logged) {
+                    try {
+                        console.error('Bad request (start_app) payload:', JSON.stringify(payload));
+                    }
+                    catch (err) {
+                        // Last resort: still log the failure
+                        console.error('Failed to emit bad request payload to stderr:', String(err));
+                    }
                 }
-                catch (e) { }
-                const deviceFallback = { platform: platform || 'ios', id: deviceId || 'unknown', osVersion: '', model: '', simulator: true };
-                return wrapResponse({ device: deviceFallback, appStarted: false, launchTimeMs: 0, error: err instanceof Error ? err.message : String(err), diagnostics: { receivedArgs: args } });
+                return wrapResponse({ error: msg });
             }
+            const res = await (platform === 'android' ? new AndroidManage().startApp(appId, deviceId) : new iOSManage().startApp(appId, deviceId));
+            const response = {
+                device: res.device,
+                appStarted: res.appStarted,
+                launchTimeMs: res.launchTimeMs
+            };
+            return wrapResponse(response);
         }
         if (name === "terminate_app") {
             const { platform, appId, deviceId } = args;
@@ -512,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,16 @@
 
 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.
+
 ## [0.12.4]
 - Made projectType and platform mandatory
 

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/`.
+