mobile-debug-mcp 0.13.0 → 0.15.0

package/src/interact/shared/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/{android/manage.ts → manage/android.ts}

@@ -2,7 +2,7 @@ import { promises as fs } from 'fs'
 import { spawn } from 'child_process'
 import path from 'path'
 import { existsSync } from 'fs'
-import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from './utils.js'
+import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from '../utils/android/utils.js'
 import { execAdbWithDiagnostics } from '../utils/diagnostics.js'
 import { detectJavaHome } from '../utils/java.js'
 import { InstallAppResponse, StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from '../types.js'
@@ -12,7 +12,7 @@ export class AndroidManage {
     void _variant
     try {
       // Always use the shared prepareGradle utility for consistent env/setup
-      const { execCmd, gradleArgs, spawnOpts } = await (await import('./utils.js')).prepareGradle(projectPath)
+      const { execCmd, gradleArgs, spawnOpts } = await (await import('../utils/android/utils.js')).prepareGradle(projectPath)
       await new Promise<void>((resolve, reject) => {
         const proc = spawn(execCmd, gradleArgs, spawnOpts)
         let stderr = ''

package/src/{tools/manage.ts → manage/index.ts}

@@ -1,13 +1,16 @@
 import { promises as fs } from 'fs'
 import path from 'path'
 import { resolveTargetDevice, listDevices } from '../utils/resolve-device.js'
-import { AndroidManage } from '../android/manage.js'
-import { iOSManage } from '../ios/manage.js'
-import { findApk } from '../android/utils.js'
-import { findAppBundle } from '../ios/utils.js'
+import { AndroidManage } from './android.js'
+import { iOSManage } from './ios.js'
+import { findApk } from '../utils/android/utils.js'
+import { findAppBundle } from '../utils/ios/utils.js'
 import { execSync } from 'child_process'
 import type { InstallAppResponse, StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from '../types.js'
 
+export { AndroidManage } from './android.js';
+export { iOSManage } from './ios.js';
+
 export async function detectProjectPlatform(projectPath: string): Promise<'ios'|'android'|'ambiguous'|'unknown'> {
   // Recursively scan up to a limited depth for platform markers to avoid mis-detection
   async function scan(dir: string, depth = 3): Promise<{ ios: boolean, android: boolean }>{

package/src/{ios/manage.ts → manage/ios.ts}

@@ -1,7 +1,7 @@
 import { promises as fs } from "fs"
 import { spawn, spawnSync } from "child_process"
 import { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse, InstallAppResponse } from "../types.js"
-import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "./utils.js"
+import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "../utils/ios/utils.js"
 import path from "path"
 
 export class iOSManage {

package/src/{android/observe.ts → observe/android.ts}

@@ -1,15 +1,14 @@
 import { spawn } from "child_process"
 import { XMLParser } from "fast-xml-parser"
 import { GetLogsResponse, CaptureAndroidScreenResponse, GetUITreeResponse, GetCurrentScreenResponse, UIElement, DeviceInfo } from "../types.js"
-import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, getScreenResolution, traverseNode, parseLogLine } from "./utils.js"
+import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, getScreenResolution, traverseNode, parseLogLine } from "../utils/android/utils.js"
 import { createWriteStream } from "fs"
 import { promises as fsPromises } from "fs"
 import path from "path"
+import { computeScreenFingerprint } from "../interact/shared/fingerprint.js"
 
 const activeLogStreams: Map<string, { proc: any, file: string }> = new Map()
 
-
-
 export class AndroidObserve {
   async getDeviceMetadata(appId: string, deviceId?: string): Promise<DeviceInfo> {
     return getAndroidDeviceMetadata(appId, deviceId);
@@ -98,24 +97,16 @@ export class AndroidObserve {
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
     try {
-      // We'll skip PID lookup for now to avoid potential hangs with 'pidof' on some emulators
-      // and rely on robust string matching against the log line.
-      
-      // Get logs
       const stdout = await execAdb(['logcat', '-d', '-t', lines.toString(), '-v', 'threadtime'], deviceId)
       const allLogs = stdout.split('\n')
       
       let filteredLogs = allLogs
       if (appId) {
-         // Filter by checking if the line contains the appId string.
          const matchingLogs = allLogs.filter(line => line.includes(appId))
          
          if (matchingLogs.length > 0) {
            filteredLogs = matchingLogs
          } else {
-           // Fallback: if no logs match the appId, return the raw logs (last N lines)
-           // This matches the behavior of the "working" version provided by the user,
-           // ensuring they at least see system activity if the app is silent or crashing early.
            filteredLogs = allLogs
          }
       }
@@ -132,10 +123,7 @@ export class AndroidObserve {
     const deviceInfo: DeviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
     return new Promise((resolve, reject) => {
-      // Need to construct ADB args manually since spawn handles it
       const args = deviceId ? ['-s', deviceId, 'exec-out', 'screencap', '-p'] : ['exec-out', 'screencap', '-p'];
-      
-      // Using spawn for screencap as well to ensure consistent process handling
       const child = spawn(getAdbCmd(), args)
       
       const chunks: Buffer[] = []
@@ -164,7 +152,6 @@ export class AndroidObserve {
         const screenshotBuffer = Buffer.concat(chunks)
         const screenshotBase64 = screenshotBuffer.toString('base64')
 
-        // Get resolution
         execAdb(['shell', 'wm', 'size'], deviceId)
           .then(sizeStdout => {
             let width = 0
@@ -201,13 +188,8 @@ export class AndroidObserve {
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
     try {
-      // Dumpsys activity can be slow on some devices, so we increase timeout to 10s
       const output = await execAdb(['shell', 'dumpsys', 'activity', 'activities'], deviceId, { timeout: 10000 })
-      
-      // Find the line with mResumedActivity or ResumedActivity (some versions might differ)
       const lines = output.split('\n');
-      // Prioritize mResumedActivity, then ResumedActivity. 
-      // Use strict regex match to ensure it starts with the key, avoiding false positives like 'mLastResumedActivity'.
       let resumedLine = lines.find(line => /^\s*mResumedActivity:/.test(line));
       
       if (!resumedLine) {
@@ -224,17 +206,12 @@ export class AndroidObserve {
          }
       }
 
-      // Regex to parse the line: ActivityRecord{... package/activity ...}
-      // Matches: ActivityRecord{<hex> <user> <package>/<activity> ...}
-      // We want to capture the component "package/activity" which is separated by space from other tokens.
-      // We use greedy match ([^ \{}]+) for activity to ensure we get the full name until a space or closing brace.
       const match = resumedLine.match(/ActivityRecord\{[^ ]*(?:\s+[^ ]+)*\s+([^\/ ]+)\/([^ \{}]+)[^}]*\}/);
 
       if (match) {
         const packageName = match[1];
         let activityName = match[2];
         
-        // Handle relative activity names (e.g. .LoginActivity)
         if (activityName.startsWith('.')) {
           activityName = packageName + activityName;
         }
@@ -268,6 +245,18 @@ export class AndroidObserve {
     }
   }
 
+  async getScreenFingerprint(deviceId?: string): Promise<{ fingerprint: string | null; activity?: string; error?: string }> {
+    try {
+      const tree = await this.getUITree(deviceId)
+      if (!tree || (tree as any).error) return { fingerprint: null, error: (tree as any).error }
+
+      const current = await this.getCurrentScreen(deviceId).catch(() => null)
+      return computeScreenFingerprint(tree, current, 'android', 50)
+    } catch (e) {
+      return { fingerprint: null, error: e instanceof Error ? e.message : String(e) }
+    }
+  }
+
   async startLogStream(packageName: string, level: 'error' | 'warn' | 'info' | 'debug' = 'error', deviceId?: string, sessionId: string = 'default') {
     try {
       const pidOutput = await execAdb(['shell', 'pidof', packageName], deviceId).catch(() => '')
@@ -328,7 +317,6 @@ export class AndroidObserve {
   }
 
   async readLogStream(sessionId: string = 'default', limit: number = 100, since?: string) {
-    // Prefer active stream if present, otherwise fall back to a well-known NDJSON file for the session
     const entry = activeLogStreams.get(sessionId)
     let file: string | undefined
     if (entry && entry.file) file = entry.file

package/src/observe/index.ts

@@ -0,0 +1,92 @@
+import { resolveTargetDevice } from '../utils/resolve-device.js'
+import { AndroidObserve } from './android.js'
+import { iOSObserve } from './ios.js'
+
+export { AndroidObserve } from './android.js'
+export { iOSObserve } from './ios.js'
+
+export class ToolsObserve {
+  // Resolve a target device and return the appropriate observe instance and resolved info.
+  private static async resolveObserve(platform?: 'android' | 'ios', deviceId?: string, appId?: string) {
+    if (platform === 'android') {
+      const resolved = await resolveTargetDevice({ platform: 'android', deviceId, appId })
+      return { observe: new AndroidObserve(), resolved }
+    }
+    if (platform === 'ios') {
+      const resolved = await resolveTargetDevice({ platform: 'ios', deviceId, appId })
+      return { observe: new iOSObserve(), resolved }
+    }
+
+    // No platform specified: try android then ios
+    try {
+      const resolved = await resolveTargetDevice({ platform: 'android', deviceId, appId })
+      return { observe: new AndroidObserve(), resolved }
+    } catch {
+      const resolved = await resolveTargetDevice({ platform: 'ios', deviceId, appId })
+      return { observe: new iOSObserve(), resolved }
+    }
+  }
+
+  static async getUITreeHandler({ platform, deviceId }: { platform?: 'android' | 'ios', deviceId?: string }) {
+    const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId)
+    return await observe.getUITree(resolved.id)
+  }
+
+  static async getCurrentScreenHandler({ deviceId }: { deviceId?: string }) {
+    const { observe, resolved } = await ToolsObserve.resolveObserve('android', deviceId)
+    // getCurrentScreen is Android-specific
+    return await (observe as AndroidObserve).getCurrentScreen(resolved.id)
+  }
+
+  static async getLogsHandler({ platform, appId, deviceId, lines }: { platform?: 'android' | 'ios', appId?: string, deviceId?: string, lines?: number }) {
+    const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId, appId)
+    if (observe instanceof AndroidObserve) {
+      const response = await observe.getLogs(appId, lines ?? 200, resolved.id)
+      const logs = Array.isArray(response.logs) ? response.logs : []
+      const crashLines = logs.filter(line => line.includes('FATAL EXCEPTION'))
+      return { device: response.device, logs, crashLines }
+    } else {
+      const resp = await (observe as iOSObserve).getLogs(appId, resolved.id)
+      const logs = Array.isArray(resp.logs) ? resp.logs : []
+      const crashLines = logs.filter(l => l.includes('FATAL EXCEPTION'))
+      return { device: resp.device, logs, crashLines }
+    }
+  }
+
+  static async startLogStreamHandler({ platform, packageName, level, sessionId, deviceId }: { platform?: 'android' | 'ios', packageName: string, level?: 'error' | 'warn' | 'info' | 'debug', sessionId?: string, deviceId?: string }) {
+    const sid = sessionId || 'default'
+    const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId, packageName)
+    if (observe instanceof AndroidObserve) {
+      return await observe.startLogStream(packageName, level || 'error', resolved.id, sid)
+    } else {
+      return await (observe as iOSObserve).startLogStream(packageName, resolved.id, sid)
+    }
+  }
+
+  static async readLogStreamHandler({ platform, sessionId, limit, since }: { platform?: 'android' | 'ios', sessionId?: string, limit?: number, since?: string }) {
+    const sid = sessionId || 'default'
+    const { observe } = await ToolsObserve.resolveObserve(platform)
+    return await (observe as any).readLogStream(sid, limit ?? 100, since)
+  }
+
+  static async stopLogStreamHandler({ platform, sessionId }: { platform?: 'android' | 'ios', sessionId?: string }) {
+    const sid = sessionId || 'default'
+    const { observe } = await ToolsObserve.resolveObserve(platform)
+    return await (observe as any).stopLogStream(sid)
+  }
+
+  static async captureScreenshotHandler({ platform, deviceId }: { platform?: 'android' | 'ios', deviceId?: string }) {
+    const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId)
+    if (observe instanceof AndroidObserve) {
+      return await observe.captureScreen(resolved.id)
+    } else {
+      return await (observe as iOSObserve).captureScreenshot(resolved.id)
+    }
+  }
+
+  static async getScreenFingerprintHandler({ platform, deviceId }: { platform?: 'android' | 'ios', deviceId?: string } = {}) {
+    const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId)
+    // Both observes implement getScreenFingerprint
+    return await (observe as any).getScreenFingerprint(resolved.id)
+  }
+}

package/src/{ios/observe.ts → observe/ios.ts}

@@ -1,12 +1,11 @@
 import { spawn } from "child_process"
 import { promises as fs } from "fs"
 import { GetLogsResponse, CaptureIOSScreenshotResponse, GetUITreeResponse, UIElement, DeviceInfo } from "../types.js"
-import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcrunCmd, isIDBInstalled } from "./utils.js"
+import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcrunCmd, isIDBInstalled } from "../utils/ios/utils.js"
 import { createWriteStream, promises as fsPromises } from 'fs'
 import path from 'path'
-import { parseLogLine } from '../android/utils.js'
-
-// --- Helper Functions Specific to Observe ---
+import { parseLogLine } from '../utils/android/utils.js'
+import { computeScreenFingerprint } from '../interact/shared/fingerprint.js'
 
 const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 
@@ -25,7 +24,6 @@ interface IDBElement {
 
 function parseIDBFrame(frame: any): [number, number, number, number] {
   if (!frame) return [0, 0, 0, 0];
-  // Handle string frames like "{{0, 0}, {402, 874}}"
   if (typeof frame === 'string') {
     const nums = frame.match(/-?\d+(?:\.\d+)?/g);
     if (!nums || nums.length < 4) return [0, 0, 0, 0];
@@ -53,29 +51,25 @@ function traverseIDBNode(node: IDBElement, elements: UIElement[], parentIndex: n
 
   let currentIndex = -1;
 
-  // Prefer standard keys, fallback to alternatives
   const type = node.AXElementType || node.type || "unknown";
   const label = node.AXLabel || node.label || null;
   const value = node.AXValue || null;
   const frame = node.AXFrame || node.frame;
   const traits = node.AXTraits || [];
   
-  const clickable = traits.includes("UIAccessibilityTraitButton") || type === "Button" || type === "Cell"; // Cells are often clickable
+  const clickable = traits.includes("UIAccessibilityTraitButton") || type === "Button" || type === "Cell";
   
-  // Filtering Logic:
-  // Keep if clickable OR has visible text/label OR has value
-  // Also keep 'Window' or 'Application' types as they define the root structure often, though usually depth 0
   const isUseful = clickable || (label && label.length > 0) || (value && value.length > 0) || type === "Application" || type === "Window";
 
   if (isUseful) {
     const bounds = parseIDBFrame(frame);
     const element: UIElement = {
       text: label,
-      contentDescription: value, 
+      contentDescription: value,
       type: type,
       resourceId: node.AXUniqueId || null,
       clickable: clickable,
-      enabled: true, // idb usually returns enabled elements
+      enabled: true,
       visible: true,
       bounds: bounds,
       center: getCenter(bounds),
@@ -90,8 +84,6 @@ function traverseIDBNode(node: IDBElement, elements: UIElement[], parentIndex: n
     currentIndex = elements.length - 1;
   }
   
-  // If current node was skipped, children inherit parentIndex and depth (flattening)
-  // If current node was added, children use currentIndex and depth + 1
   const nextParentIndex = currentIndex !== -1 ? currentIndex : parentIndex;
   const nextDepth = currentIndex !== -1 ? depth + 1 : depth;
 
@@ -113,12 +105,8 @@ function traverseIDBNode(node: IDBElement, elements: UIElement[], parentIndex: n
   return currentIndex;
 }
 
-
-
-// iOS live log stream support (moved from ios/utils to observe)
 const iosActiveLogStreams: Map<string, { proc: ReturnType<typeof import('child_process').spawn>, file: string }> = new Map()
 
-// Test helpers
 export function _setIOSActiveLogStream(sessionId: string, file: string) {
   iosActiveLogStreams.set(sessionId, { proc: {} as any, file })
 }
@@ -133,9 +121,6 @@ export class iOSObserve {
   }
 
   async getLogs(appId?: string, deviceId: string = "booted"): Promise<GetLogsResponse> {
-    // If appId is provided, use predicate filtering
-    // Note: execFile passes args directly, so we don't need shell escaping for the predicate string itself,
-    // but we do need to construct the predicate correctly for log show.
     const args = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog', '--last', '1m']
     if (appId) {
       validateBundleId(appId)
@@ -157,25 +142,19 @@ export class iOSObserve {
     const tmpFile = `/tmp/mcp-ios-screenshot-${Date.now()}.png`
 
     try {
-      // 1. Capture screenshot to temp file
       await execCommand(['simctl', 'io', deviceId, 'screenshot', tmpFile], deviceId)
       
-      // 2. Read file as base64
       const buffer = await fs.readFile(tmpFile)
       const base64 = buffer.toString('base64')
       
-      // 3. Clean up
       await fs.rm(tmpFile).catch(() => {})
 
       return {
         device,
         screenshot: base64,
-        // Default resolution since we can't easily parse it without extra libs
-        // Clients will read the real dimensions from the PNG header anyway
         resolution: { width: 0, height: 0 },
       }
     } catch (e) {
-      // Ensure cleanup happens even on error
       await fs.rm(tmpFile).catch(() => {})
       throw new Error(`Failed to capture screenshot: ${e instanceof Error ? e.message : String(e)}`)
     }
@@ -184,7 +163,6 @@ export class iOSObserve {
   async getUITree(deviceId: string = "booted"): Promise<GetUITreeResponse> {
     const device = await getIOSDeviceMetadata(deviceId);
     
-    // idb is required
     const idbExists = await isIDBInstalled();
     if (!idbExists) {
        return {
@@ -196,10 +174,8 @@ export class iOSObserve {
        };
     }
 
-    // Resolve UDID if needed
     const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
 
-    // Retry Logic
     let jsonContent: any = null;
     let attempts = 0;
     const maxAttempts = 3;
@@ -207,7 +183,6 @@ export class iOSObserve {
     while (attempts < maxAttempts) {
       attempts++;
       try {
-         // Stabilization delay
          await delay(300 + (attempts * 100));
 
          const args = ['ui', 'describe-all', '--json'];
@@ -255,7 +230,6 @@ export class iOSObserve {
 
     try {
         const elements: UIElement[] = [];
-        // idb describe-all returns either a root object or an array of root nodes
         if (Array.isArray(jsonContent)) {
           for (const node of jsonContent) {
             traverseIDBNode(node, elements);
@@ -264,7 +238,6 @@ export class iOSObserve {
           traverseIDBNode(jsonContent, elements);
         }
 
-        // Infer resolution from root element if possible (usually the Window/Application frame)
         let width = 0;
         let height = 0;
         if (elements.length > 0) {
@@ -290,7 +263,17 @@ export class iOSObserve {
     }
   }
 
-  // --- Log stream methods ---
+  async getScreenFingerprint(deviceId: string = 'booted'): Promise<{ fingerprint: string | null; activity?: string; error?: string }> {
+    try {
+      const tree = await this.getUITree(deviceId)
+      if (!tree || tree.error) return { fingerprint: null, error: tree && (tree as any).error }
+
+      return computeScreenFingerprint(tree, null, 'ios', 50)
+    } catch (e) {
+      return { fingerprint: null, error: e instanceof Error ? e.message : String(e) }
+    }
+  }
+
   async startLogStream(bundleId: string, deviceId: string = 'booted', sessionId: string = 'default') : Promise<{ success: boolean; stream_started?: boolean; error?: string }> {
     try {
       const predicate = `process == "${bundleId}" or subsystem contains "${bundleId}"`
@@ -303,7 +286,6 @@ export class iOSObserve {
       const args = ['simctl', 'spawn', deviceId, 'log', 'stream', '--style', 'syslog', '--predicate', predicate]
       const proc = spawn(getXcrunCmd(), args)
 
-      // Prepare output file
       const tmpDir = process.env.TMPDIR || '/tmp'
       const file = path.join(tmpDir, `mobile-debug-ios-log-${sessionId}.ndjson`)
       const stream = createWriteStream(file, { flags: 'a' })

package/src/server.ts

@@ -14,11 +14,11 @@ import {
   InstallAppResponse
 } from "./types.js"
 
-import { ToolsManage } from './tools/manage.js'
-import { ToolsInteract } from './tools/interact.js'
-import { ToolsObserve } from './tools/observe.js'
-import { AndroidManage } from './android/manage.js'
-import { iOSManage } from './ios/manage.js'
+import { ToolsManage } from './manage/index.js'
+import { ToolsInteract } from './interact/index.js'
+import { ToolsObserve } from './observe/index.js'
+import { AndroidManage } from './manage/index.js'
+import { iOSManage } from './manage/index.js'
 
 
 const server = new Server(
@@ -283,6 +283,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         }
       }
     },
+    {
+      name: "get_screen_fingerprint",
+      description: "Generate a stable fingerprint representing the current visible screen (activity + visible UI elements).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          platform: { type: "string", enum: ["android", "ios"], description: "Optional platform override (android|ios)" },
+          deviceId: { type: "string", description: "Optional device id/udid to target" }
+        }
+      }
+    },
     {
       name: "wait_for_element",
       description: "Wait until a UI element with matching text appears on screen or timeout is reached.",
@@ -346,8 +357,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 +373,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.",
@@ -555,6 +590,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return wrapResponse(res)
     }
 
+    if (name === "get_screen_fingerprint") {
+      const { platform, deviceId } = (args || {}) as any
+      const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId })
+      return wrapResponse(res)
+    }
+
     if (name === "wait_for_element") {
       const { platform, text, timeout, deviceId } = (args || {}) as any
       const res = await ToolsInteract.waitForElementHandler({ platform, text, timeout, deviceId })
@@ -568,8 +609,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)
     }
 
@@ -614,7 +661,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 const transport = new StdioServerTransport()
 
 async function main() {
-  await server.connect(transport)
+  await (server as any).connect(transport)
 }
 
 main().catch((error) => {