mobile-debug-mcp 0.12.8 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.12.8",
+  "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/ios/manage.ts

@@ -298,102 +298,15 @@ export class iOSManage {
 
   async startApp(bundleId: string, deviceId: string = "booted"): Promise<StartAppResponse> {
     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: any = null
     try {
-      launchResult = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId)
-    } catch (launchErr:any) {
-      // 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 } as any
-    }
-
-    // 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 } as any
-    }
-
-    return { device, appStarted: !!(launchResult && launchResult.output), launchTimeMs: 1000, instrumentation }
-  }
-
-  appExecutableName(bundleId: string) {
-    // 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: string, deviceId: string = "booted", appinfo?: string) {
-    const diagnostics: any = { 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: string | null = 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) } }
-      }
+      return { device, appStarted: !!result.output, launchTimeMs: 1000 }
+    } catch (e:any) {
+      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 } as any
     }
-
-    // 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 }
-    } catch (e) { diagnostics.screenshotError = String(e) }
-
-    return diagnostics
   }
 
   async terminateApp(bundleId: string, deviceId: string = "booted"): Promise<TerminateAppResponse> {

package/src/ios/utils.ts

@@ -88,41 +88,7 @@ export function validateBundleId(bundleId: string) {
 
 export function execCommand(args: string[], deviceId: string = "booted"): Promise<IOSResult> {
   return new Promise((resolve, reject) => {
-    // Instrumentation: append a JSON line with timestamp, command, args, cwd and selected env vars
-    try {
-      const mcpEnv: Record<string,string|undefined> = {}
-      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 = ''
@@ -140,14 +106,6 @@ export function execCommand(args: string[], deviceId: string = "booted"): Promis
       })
     }
 
-    // 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
@@ -173,11 +131,6 @@ export function execCommand(args: string[], deviceId: string = "booted"): Promis
 }
 
 export function execCommandWithDiagnostics(args: string[], deviceId: string = "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/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.",
@@ -412,31 +436,54 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     if (name === "start_app") {
       const { platform, appId, deviceId } = args as any
-      // Defensive validation: ensure required args are present and log malformed requests
+      // Defensive validation: ensure caller provided platform and appId.
       if (!platform || !appId) {
-        try { require('fs').appendFileSync('/tmp/mcp_bad_requests.log', JSON.stringify({ ts: new Date().toISOString(), tool: 'start_app', args }) + '\n') } catch (e) {}
-        const deviceFallback: any = { platform: platform || 'ios', id: deviceId || 'unknown', osVersion: '', model: '', simulator: true }
-        const response: StartAppResponse = { device: deviceFallback, appStarted: false, launchTimeMs: 0, error: 'Missing required argument: platform and/or appId', diagnostics: { receivedArgs: args } }
-        return wrapResponse(response)
-      }
+        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 {
+          const diag = require('./utils/diagnostics.js')
+          if (diag && diag.appendDiagnosticFile) {
+            diag.appendDiagnosticFile('bad_requests.log', payload)
+            logged = true
+          }
+        } catch (err) {
+          console.error('Diagnostics append failed:', String(err))
+        }
 
-      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: StartAppResponse = {
-          device: res.device,
-          appStarted: res.appStarted,
-          launchTimeMs: res.launchTimeMs,
-          error: (res as any).error,
-          diagnostics: (res as any).diagnostics,
-          instrumentation: (res as any).instrumentation
+        // 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))
+          }
         }
-        return wrapResponse(response)
-      } catch (err:any) {
-        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 (e) {}
-        const deviceFallback: any = { 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 } })
+
+        // 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))
+          }
+        }
+
+        return wrapResponse({ error: msg })
       }
+
+      const res = await (platform === 'android' ? new AndroidManage().startApp(appId, deviceId) : new iOSManage().startApp(appId, deviceId))
+      const response: StartAppResponse = {
+        device: res.device,
+        appStarted: res.appStarted,
+        launchTimeMs: res.launchTimeMs
+      }
+      return wrapResponse(response)
     }
 
     if (name === "terminate_app") {
@@ -545,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/src/types.ts

@@ -12,7 +12,6 @@ export interface StartAppResponse {
   launchTimeMs: number;
   error?: string;
   diagnostics?: any;
-  instrumentation?: any;
 }
 
 export interface TerminateAppResponse {

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)