mobile-debug-mcp 0.14.0 → 0.16.0

package/dist/utils/ui/index.js

@@ -0,0 +1,169 @@
+import crypto from 'crypto';
+const ANDROID_STRUCTURAL_TYPES = ['Window', 'Application', 'View', 'ViewGroup', 'LinearLayout', 'FrameLayout', 'RelativeLayout', 'ScrollView', 'RecyclerView', 'TextView', 'ImageView'];
+const IOS_STRUCTURAL_TYPES = ['Window', 'Application', 'View', 'ViewController', 'UITableView', 'UICollectionView', 'UILabel', 'UIImageView', 'UIView', 'UIWindow', 'UIStackView', 'UITextView', 'UITableViewCell'];
+function isDynamicText(t) {
+    if (!t)
+        return false;
+    const txt = t.trim();
+    if (!txt)
+        return false;
+    if (/\b\d{1,2}:\d{2}\b/.test(txt))
+        return true;
+    if (/\b\d{4}-\d{2}-\d{2}\b/.test(txt))
+        return true;
+    if (/^\d+(?:\.\d+)?%$/.test(txt))
+        return true;
+    if (/^\d+$/.test(txt))
+        return true;
+    if (/^[\d,]{1,10}$/.test(txt))
+        return true;
+    return false;
+}
+function normalizeElement(e) {
+    return {
+        type: (e.type || '').toString(),
+        resourceId: (e.resourceId || '').toString(),
+        text: typeof e.text === 'string' ? (isDynamicText(e.text) ? '' : e.text.trim().toLowerCase()) : '',
+        contentDesc: (e.contentDescription || '').toString(),
+        bounds: Array.isArray(e.bounds) ? e.bounds.slice(0, 4).map((n) => Number(n) || 0) : [0, 0, 0, 0]
+    };
+}
+export function computeScreenFingerprint(tree, current, platform, limit = 50) {
+    try {
+        if (!tree || tree.error)
+            return { fingerprint: null, error: tree.error };
+        const activity = current && (current.activity || current.shortActivity) ? (current.activity || current.shortActivity) : '';
+        const candidates = (tree.elements || []).filter(e => {
+            if (!e)
+                return false;
+            if (!e.visible)
+                return false;
+            const hasStableText = typeof e.text === 'string' && e.text.trim().length > 0;
+            const hasResource = !!e.resourceId;
+            const interactable = !!e.clickable || !!e.enabled;
+            const structuralList = platform === 'android' ? ANDROID_STRUCTURAL_TYPES : IOS_STRUCTURAL_TYPES;
+            const structurallySignificant = hasStableText || hasResource || structuralList.includes(e.type || '');
+            return interactable || structurallySignificant;
+        });
+        const normalized = candidates.map(normalizeElement);
+        const filteredNormalized = normalized.filter(e => (e.text && e.text.length > 0) || (e.resourceId && e.resourceId.length > 0) || (e.contentDesc && e.contentDesc.length > 0));
+        filteredNormalized.sort((a, b) => {
+            const ay = (a.bounds && a.bounds[1]) || 0;
+            const by = (b.bounds && b.bounds[1]) || 0;
+            if (ay !== by)
+                return ay - by;
+            const ax = (a.bounds && a.bounds[0]) || 0;
+            const bx = (b.bounds && b.bounds[0]) || 0;
+            return ax - bx;
+        });
+        const limited = filteredNormalized.slice(0, Math.max(0, limit));
+        const payload = {
+            activity: platform === 'android' ? (activity || '') : '',
+            resolution: tree.resolution || { width: 0, height: 0 },
+            elements: limited.map(e => ({ type: e.type, resourceId: e.resourceId, text: e.text, contentDesc: e.contentDesc }))
+        };
+        const combined = JSON.stringify(payload);
+        const hash = crypto.createHash('sha256').update(combined).digest('hex');
+        return { fingerprint: hash, activity: activity };
+    }
+    catch (e) {
+        return { fingerprint: null, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+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) {
+            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,14 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.16.0]
+- Added `wait_for_screen_change` interact tool: polls the platform-specific `get_screen_fingerprint` until it differs from a provided `previousFingerprint`, with configurable `timeoutMs` and `pollIntervalMs` and an optional stability confirmation poll to avoid reacting to transient UI flickers. Implemented at the interact layer and delegates fingerprinting to the observe implementations (Android/iOS).
+- Added unit tests covering immediate change, transient null fingerprints, stability confirmation and timeout behavior: `test/interact/unit/wait_for_screen_change.test.ts`.
+
+## [0.15.0]
+- Reorganised repository for cohesion: merged tool handlers into feature entrypoints (src/observe, src/interact, src/manage) and moved platform helpers and CLI tooling into src/utils/{android,ios,cli}.
+- Added computeScreenFingerprint utility used by observe/interact to normalise UI element significance across platforms (fingerprint shared between Android and iOS implementations).
+
 ## [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.

package/docs/tools/interact.md

@@ -72,3 +72,32 @@ Notes:
 - 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/`.
 
+---
+
+## wait_for_screen_change
+
+Description:
+- Waits until the current screen fingerprint differs from the provided `previousFingerprint`. Useful after taps, navigation, or other interactions that should change the visible UI.
+
+Input example:
+```
+{ "platform": "android", "previousFingerprint": "<hex-fingerprint>", "timeoutMs": 5000, "pollIntervalMs": 300, "deviceId": "emulator-5554" }
+```
+
+Success response example:
+```
+{ "success": true, "newFingerprint": "<hex-fingerprint>", "elapsedMs": 420 }
+```
+
+Failure (timeout) example:
+```
+{ "success": false, "reason": "timeout", "lastFingerprint": "<hex-fingerprint>", "elapsedMs": 5000 }
+```
+
+Notes:
+- Always compares to the original `previousFingerprint` (baseline is not updated during polling).
+- Treats `null` fingerprints as transient; continues polling rather than returning success.
+- Includes a stability confirmation: after detecting a different fingerprint it waits one additional poll interval and confirms the fingerprint is stable before returning success to avoid reacting to transient flickers or animation frames.
+- Default `timeoutMs` is 5000ms and default `pollIntervalMs` is 300ms; callers may override these.
+- Implemented as an interact-level tool and delegates platform-specific fingerprint calculation to the observe layer (`get_screen_fingerprint`).
+

package/docs/tools/observe.md

@@ -76,6 +76,30 @@ Response:
 
 ---
 
+## get_screen_fingerprint
+Generate a stable fingerprint representing the visible screen. Useful for detecting navigation changes, preventing loops, and synchronisation.
+
+Input (optional):
+
+```
+{ "platform": "android", "deviceId": "emulator-5554" }
+```
+
+Response:
+
+```json
+{ "fingerprint": "<sha256_hex>", "activity": "com.example.app.MainActivity" }
+```
+
+Notes:
+- Uses get_ui_tree and (on Android) get_current_screen as inputs.
+- Normalises visible, interactable or structurally significant elements (class/type, resourceId, text, contentDesc).
+- Trims and lowercases text, filters out likely dynamic values (timestamps, counters).
+- Sorts deterministically (top-to-bottom, left-to-right) and limits elements to 50.
+- Returns fingerprint: null and an error message if the UI tree or activity cannot be retrieved.
+
+---
+
 ## start_log_stream / read_log_stream / stop_log_stream
 Start a background adb logcat stream and retrieve parsed NDJSON entries.
 

package/package.json

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

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

@@ -1,7 +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"
+import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../utils/android/utils.js"
+import { AndroidObserve } from "../observe/index.js"
+import { scrollToElementShared } from "../utils/ui/index.js"
 
 
 export class AndroidInteract {

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

@@ -1,6 +1,9 @@
+import { AndroidInteract } from './android.js';
+import { iOSInteract } from './ios.js';
+export { AndroidInteract, iOSInteract };
+
 import { resolveTargetDevice } from '../utils/resolve-device.js'
-import { AndroidInteract } from '../android/interact.js'
-import { iOSInteract } from '../ios/interact.js'
+import { ToolsObserve } from '../observe/index.js'
 
 export class ToolsInteract {
 
@@ -42,5 +45,46 @@ export class ToolsInteract {
     return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id)
   }
 
-}
+  static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }: { platform?: 'android' | 'ios', previousFingerprint: string, timeoutMs?: number, pollIntervalMs?: number, deviceId?: string }) {
+    const start = Date.now()
+    let lastFingerprint: string | null = null
+
+    while (Date.now() - start < timeoutMs) {
+      try {
+        const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId })
+        const fp = (res as any)?.fingerprint ?? null
+        if (fp === null || fp === undefined) {
+          lastFingerprint = null
+          await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+          continue
+        }
+
+        lastFingerprint = fp
+
+        if (fp !== previousFingerprint) {
+          // Stability confirmation
+          await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+          try {
+            const confirmRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId })
+            const confirmFp = (confirmRes as any)?.fingerprint ?? null
+            if (confirmFp === fp) {
+              return { success: true, newFingerprint: fp, elapsedMs: Date.now() - start }
+            }
+            lastFingerprint = confirmFp
+            continue
+          } catch {
+            // ignore and continue polling
+            continue
+          }
+        }
+      } catch {
+        // ignore transient errors
+      }
 
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+    }
+
+    return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start }
+  }
+
+}

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

@@ -1,8 +1,8 @@
 import { spawn } from "child_process"
 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"
+import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../utils/ios/utils.js"
+import { iOSObserve } from "../observe/index.js"
+import { scrollToElementShared } from "../utils/ui/index.js"
 
 export class iOSInteract {
   private observe = new iOSObserve();

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 "../utils/ui/index.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)
+  }
+}