mobile-debug-mcp 0.14.0 → 0.15.0

package/src/interact/shared/fingerprint.ts

@@ -0,0 +1,73 @@
+import crypto from 'crypto'
+import { GetUITreeResponse, GetCurrentScreenResponse, UIElement } from '../../types.js'
+
+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?: string): boolean {
+  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: UIElement) {
+  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:any)=>Number(n)||0) : [0,0,0,0]
+  }
+}
+
+export function computeScreenFingerprint(tree: GetUITreeResponse, current: GetCurrentScreenResponse | null, platform: 'android' | 'ios', limit: number = 50): { fingerprint: string | null; activity?: string; error?: string } {
+  try {
+    if (!tree || (tree as any).error) return { fingerprint: null, error: (tree as any).error }
+
+    const activity = current && (current.activity || (current as any).shortActivity) ? (current.activity || (current as any).shortActivity) : ''
+
+    const candidates: UIElement[] = (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
+    }) as UIElement[]
+
+    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 as any).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) }
+  }
+}

package/src/{tools → interact/shared}/scroll_to_element.ts

@@ -1,4 +1,4 @@
-import { UIElement, GetUITreeResponse, SwipeResponse } from '../types.js'
+import { UIElement, GetUITreeResponse, SwipeResponse } from '../../types.js'
 
 export interface ScrollSelector { text?: string; resourceId?: string; contentDesc?: string; className?: string }
 

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.",
@@ -579,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 })
@@ -644,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) => {

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

@@ -1,8 +1,8 @@
 import { spawn } from 'child_process'
-import { DeviceInfo, UIElement } from "../types.js"
+import { DeviceInfo, UIElement } from "../../types.js"
 import { promises as fsPromises, existsSync } from 'fs'
 import path from 'path'
-import { detectJavaHome } from '../utils/java.js'
+import { detectJavaHome } from '../java.js'
 
 export function getAdbCmd() { return process.env.ADB_PATH || 'adb' }
 

package/src/{cli → utils/cli}/ios/run-ios-smoke.ts

@@ -1,5 +1,5 @@
-import { iOSObserve } from '../../ios/observe.js';
-import { iOSManage } from '../../ios/manage.js';
+import { iOSObserve } from '../../../observe/index.js';
+import { iOSManage } from '../../../manage/index.js';
 
 async function main() {
   const appId = process.argv[2] || 'com.apple.springboard';

package/src/{cli → utils/cli}/ios/run-ios-ui-tree-tap.ts

@@ -1,5 +1,5 @@
-import { iOSObserve } from '../../ios/observe.js';
-import { iOSInteract } from '../../ios/interact.js';
+import { iOSObserve } from '../../../observe/index.js';
+import { iOSInteract } from '../../../interact/index.js';
 
 async function main() {
   const deviceId = 'booted';
@@ -18,7 +18,7 @@ async function main() {
     process.exit(3);
   }
 
-  const clickable = tree.elements.find(e => e.clickable) || tree.elements[0];
+  const clickable = tree.elements.find((e: any) => e.clickable) || tree.elements[0];
   console.log('Using element:', clickable.text || '(no text)', 'clickable=', clickable.clickable, 'center=', clickable.center);
   const [x,y] = clickable.center || [0,0];
 

package/src/utils/diagnostics.ts

@@ -37,7 +37,7 @@ export class DiagnosticError extends Error {
 
 // Exec ADB with diagnostics — moved from src/android/diagnostics.ts
 import { spawnSync } from 'child_process'
-import { getAdbCmd } from '../android/utils.js'
+import { getAdbCmd } from './android/utils.js'
 
 export function execAdbWithDiagnostics(args: string[], deviceId?: string) {
   const adbArgs = deviceId ? ['-s', deviceId, ...args] : args

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

@@ -1,8 +1,8 @@
 import { execFile, spawn, execSync, spawnSync } from "child_process"
-import { DeviceInfo } from "../types.js"
+import { DeviceInfo } from "../../types.js"
 import { promises as fsPromises } from 'fs'
 import path from 'path'
-import { makeEnvSnapshot } from '../utils/diagnostics.js'
+import { makeEnvSnapshot } from '../diagnostics.js'
 
 export function getXcrunCmd() { return process.env.XCRUN_PATH || 'xcrun' }
 

package/src/utils/resolve-device.ts

@@ -1,6 +1,6 @@
 import { DeviceInfo } from "../types.js"
-import { listAndroidDevices } from "../android/utils.js"
-import { listIOSDevices } from "../ios/utils.js"
+import { listAndroidDevices } from "./android/utils.js"
+import { listIOSDevices } from "./ios/utils.js"
 
 export interface ResolveOptions {
   platform: "android" | "ios"