mobile-debug-mcp 0.14.0 → 0.15.0

package/dist/observe/test/unit/logstream.test.js

@@ -0,0 +1,41 @@
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+import { AndroidObserve } from '../../../../../index.js';
+async function run() {
+    const tmp = os.tmpdir();
+    const sessionId = 'unit-test-logstream';
+    const file = path.join(tmp, `mobile-debug-log-${sessionId}.ndjson`);
+    // Prepare NDJSON with one crash entry and one info entry
+    const crashEntry = { timestamp: '2026-03-13T14:00:00.000Z', level: 'E', tag: 'AndroidRuntime', message: 'FATAL EXCEPTION: main\njava.lang.NullPointerException' };
+    const infoEntry = { timestamp: '2026-03-13T14:01:00.000Z', level: 'I', tag: 'MyTag', message: 'Info message' };
+    await fs.writeFile(file, JSON.stringify(crashEntry) + '\n' + JSON.stringify(infoEntry) + '\n');
+    try {
+        // Read all via AndroidObserve (falls back to session NDJSON file)
+        const obs = new AndroidObserve();
+        const { entries, crash_summary } = await obs.readLogStream(sessionId, 10);
+        if (!Array.isArray(entries) || entries.length !== 2)
+            throw new Error('Expected 2 entries');
+        if (!crash_summary || crash_summary.crash_detected !== true)
+            throw new Error('Expected crash_detected true');
+        if (!crash_summary.exception || !/NullPointerException/.test(crash_summary.exception))
+            throw new Error('Expected NullPointerException detected');
+        console.log('Test 1 PASS: basic parsing & crash detection');
+        // Test since filter (after first entry)
+        const since = new Date('2026-03-13T14:00:30.000Z').toISOString();
+        const r2 = await obs.readLogStream(sessionId, 10, since);
+        if (r2.entries.length !== 1)
+            throw new Error('Expected 1 entry after since filter');
+        console.log('Test 2 PASS: since filter');
+        // Test limit
+        const r3 = await obs.readLogStream(sessionId, 1);
+        if (r3.entries.length !== 1)
+            throw new Error('Expected 1 entry with limit=1');
+        console.log('Test 3 PASS: limit works');
+        console.log('ALL logstream tests passed');
+    }
+    finally {
+        await fs.unlink(file).catch(() => { });
+    }
+}
+run().catch(err => { console.error('Logstream tests failed:', err); process.exit(1); });

package/dist/observe/test/unit/scroll_to_element.test.js

@@ -0,0 +1,113 @@
+import { ToolsInteract } from '../../../src/tools/interact.js';
+import { ToolsObserve } from '../../../src/tools/observe.js';
+const origGet = ToolsObserve.getUITreeHandler;
+const origSwipe = ToolsInteract.swipeHandler;
+async function runTests() {
+    // Use a stable logger to avoid test harness replacing console.log between calls
+    console.log = (...args) => { try {
+        process.stdout.write(args.map(a => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ') + '\n');
+    }
+    catch { } };
+    console.log('Starting tests for scroll_to_element...');
+    // Test 1: Element found immediately
+    console.log('\nTest 1: Element found immediately')(ToolsObserve).getUITreeHandler = async () => ({
+        device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+        screen: '',
+        resolution: { width: 1080, height: 1920 },
+        elements: [{
+                text: 'Target',
+                type: 'Button',
+                contentDescription: null,
+                clickable: true,
+                enabled: true,
+                visible: true,
+                bounds: [0, 0, 100, 100],
+                resourceId: null
+            }]
+    });
+    const res1 = await ToolsInteract.scrollToElementHandler({ platform: 'android', selector: { text: 'Target' }, direction: 'down', maxScrolls: 5, scrollAmount: 0.7 });
+    console.log('Result:', res1.success === true ? 'PASS' : 'FAIL');
+    console.log('scrollsPerformed:', res1.scrollsPerformed);
+    // Test 2: Element found after scrolling
+    console.log('\nTest 2: Element found after scrolling');
+    let calls = 0(ToolsObserve).getUITreeHandler = async () => {
+        calls++;
+        if (calls < 3) {
+            return {
+                device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+                screen: '',
+                resolution: { width: 1080, height: 1920 },
+                elements: []
+            };
+        }
+        return {
+            device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+            screen: '',
+            resolution: { width: 1080, height: 1920 },
+            elements: [{
+                    text: 'Target',
+                    type: 'Button',
+                    contentDescription: null,
+                    clickable: true,
+                    enabled: true,
+                    visible: true,
+                    bounds: [0, 0, 100, 100],
+                    resourceId: null
+                }]
+        };
+    };
+    // Stub swipe so it doesn't try to call adb/idb
+    ToolsInteract.swipeHandler = async () => ({ success: true });
+    const res2 = await ToolsInteract.scrollToElementHandler({ platform: 'android', selector: { text: 'Target' }, direction: 'down', maxScrolls: 5, scrollAmount: 0.7 });
+    console.log('Result:', res2.success === true ? 'PASS' : 'FAIL');
+    console.log('calls:', calls, calls >= 3 ? 'PASS' : 'FAIL');
+    // Test 3: UI unchanged stops early
+    console.log('\nTest 3: UI unchanged stops early')(ToolsObserve).getUITreeHandler = async () => ({
+        device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+        screen: '',
+        resolution: { width: 1080, height: 1920 },
+        elements: []
+    })(ToolsInteract).swipeHandler = async () => ({ success: true });
+    const res3 = await ToolsInteract.scrollToElementHandler({ platform: 'android', selector: { text: 'Missing' }, direction: 'down', maxScrolls: 5, scrollAmount: 0.7 });
+    console.log('Result:', res3.success === false && res3.attempts === 1 ? 'PASS' : 'FAIL');
+    console.log('Reason:', res3.reason || JSON.stringify(res3));
+    // Test 4: Offscreen element scrolls into view
+    console.log('\nTest 4: Offscreen element scrolls into view');
+    const ai = new (await import('../../../src/android/interact.js')).AndroidInteract();
+    const origObserveGet = ai['observe'].getUITree;
+    const origAiSwipe = ai.swipe;
+    let swiped = false;
+    let swipeCalled = 0;
+    ai['observe'].getUITree = async () => {
+        if (!swiped) {
+            return {
+                device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+                screen: '',
+                resolution: { width: 1080, height: 1920 },
+                elements: [{ text: null, type: 'android.view.View', resourceId: null, contentDescription: null, bounds: [0, 0, 1080, 200], visible: true }]
+            };
+        }
+        return {
+            device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+            screen: '',
+            resolution: { width: 1080, height: 1920 },
+            elements: [{ text: 'OffscreenTarget', type: 'android.widget.Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [100, 400, 300, 460], resourceId: null }]
+        };
+    };
+    ai.swipe = async () => { swipeCalled++; swiped = true; return { success: true }; };
+    const r4 = await ai.scrollToElement({ text: 'OffscreenTarget' }, 'down', 3, 0.7, 'mock');
+    const ok4 = r4 && r4.success === true && r4.scrollsPerformed === 1 && swipeCalled === 1;
+    console.log('Result:', ok4 ? 'PASS' : 'FAIL');
+    console.log('  success:', r4.success, 'scrollsPerformed:', r4.scrollsPerformed, 'swipeCalled:', swipeCalled);
+    ai['observe'].getUITree = origObserveGet;
+    ai.swipe = origAiSwipe(ToolsObserve).getUITreeHandler = origGet;
+    ToolsInteract.swipeHandler = origSwipe;
+}
+// Ensure console.log is a function (some test runners replace it)
+if (typeof console.log !== 'function') {
+    console.log = (...args) => { try {
+        process.stdout.write(args.map(a => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ') + '\n');
+    }
+    catch { /* swallow */ } };
+}
+runTests().catch(console.error);

package/dist/observe/test/unit/wait_for_element_mock.js

@@ -0,0 +1,92 @@
+import { AndroidInteract } from '../../../src/android/interact.js';
+import { AndroidObserve } from '../../../../../index.js';
+const originalGetUITree = AndroidObserve.prototype.getUITree;
+async function runTests() {
+    console.log("Starting tests for wait_for_element...");
+    const interact = new AndroidInteract();
+    console.log("\nTest 1: Element found immediately");
+    AndroidObserve.prototype.getUITree = async () => ({
+        device: { platform: "android", id: "mock", osVersion: "12", model: "Pixel", simulator: true },
+        screen: "",
+        resolution: { width: 1080, height: 1920 },
+        elements: [{
+                text: "Target",
+                type: "Button",
+                contentDescription: null,
+                clickable: true,
+                enabled: true,
+                visible: true,
+                bounds: [0, 0, 100, 100],
+                resourceId: null
+            }]
+    });
+    const start1 = Date.now();
+    const result1 = await interact.waitForElement("Target", 1000);
+    const elapsed1 = Date.now() - start1;
+    console.log("Result:", result1.found === true ? "PASS" : "FAIL");
+    console.log("Element:", result1.element ? "FOUND" : "MISSING");
+    console.log("Elapsed:", elapsed1, "ms");
+    console.log("\nTest 2: Element not found (timeout)");
+    AndroidObserve.prototype.getUITree = async () => ({
+        device: { platform: "android", id: "mock", osVersion: "12", model: "Pixel", simulator: true },
+        screen: "",
+        resolution: { width: 1080, height: 1920 },
+        elements: []
+    });
+    const start2 = Date.now();
+    const result2 = await interact.waitForElement("Target", 1200);
+    const elapsed2 = Date.now() - start2;
+    console.log("Result:", result2.found === false ? "PASS" : "FAIL");
+    console.log("Elapsed time (should be >= 1200ms):", elapsed2, elapsed2 >= 1200 ? "PASS" : "FAIL");
+    console.log("\nTest 3: Element found after polling");
+    let calls = 0;
+    AndroidObserve.prototype.getUITree = async () => {
+        calls++;
+        if (calls < 3) {
+            return {
+                device: { platform: "android", id: "mock", osVersion: "12", model: "Pixel", simulator: true },
+                screen: "",
+                resolution: { width: 1080, height: 1920 },
+                elements: []
+            };
+        }
+        return {
+            device: { platform: "android", id: "mock", osVersion: "12", model: "Pixel", simulator: true },
+            screen: "",
+            resolution: { width: 1080, height: 1920 },
+            elements: [{
+                    text: "Target",
+                    type: "Button",
+                    contentDescription: null,
+                    clickable: true,
+                    enabled: true,
+                    visible: true,
+                    bounds: [0, 0, 100, 100],
+                    resourceId: null
+                }]
+        };
+    };
+    const start3 = Date.now();
+    const result3 = await interact.waitForElement("Target", 2000);
+    const elapsed3 = Date.now() - start3;
+    console.log("Result:", result3.found === true ? "PASS" : "FAIL");
+    console.log("Calls:", calls, calls >= 3 ? "PASS" : "FAIL");
+    console.log("Elapsed time (should be >= 1000ms):", elapsed3, elapsed3 >= 1000 ? "PASS" : "FAIL");
+    console.log("\nTest 4: Error handling (fast failure)");
+    AndroidObserve.prototype.getUITree = async () => ({
+        device: { platform: "android", id: "mock", osVersion: "12", model: "Pixel", simulator: true },
+        screen: "",
+        resolution: { width: 0, height: 0 },
+        elements: [],
+        error: "ADB Connection Failed"
+    });
+    const start4 = Date.now();
+    const result4 = await interact.waitForElement("Target", 5000);
+    const elapsed4 = Date.now() - start4;
+    console.log("Result:", result4.found === false && result4.error === "ADB Connection Failed" ? "PASS" : "FAIL");
+    console.log("Error Message:", result4.error);
+    console.log("Elapsed time (should be < 1000ms):", elapsed4, elapsed4 < 1000 ? "PASS" : "FAIL");
+    // Restore
+    AndroidObserve.prototype.getUITree = originalGetUITree;
+}
+runTests().catch(console.error);

package/dist/server.js

@@ -2,11 +2,11 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/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({
     name: "mobile-debug-mcp",
     version: "0.7.0"
@@ -262,6 +262,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.",
@@ -540,6 +551,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const res = await ToolsObserve.getCurrentScreenHandler({ deviceId });
             return wrapResponse(res);
         }
+        if (name === "get_screen_fingerprint") {
+            const { platform, deviceId } = (args || {});
+            const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+            return wrapResponse(res);
+        }
         if (name === "wait_for_element") {
             const { platform, text, timeout, deviceId } = (args || {});
             const res = await ToolsInteract.waitForElementHandler({ platform, text, timeout, deviceId });

package/dist/shared/fingerprint.js

@@ -0,0 +1,72 @@
+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) };
+    }
+}

package/dist/shared/scroll_to_element.js

@@ -0,0 +1,98 @@
+export async function scrollToElementShared(opts) {
+    const { selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId, fetchTree, swipe, stabilizationDelayMs = 350 } = opts;
+    const matchElement = (el) => {
+        if (!el)
+            return false;
+        if (selector.text !== undefined && selector.text !== el.text)
+            return false;
+        if (selector.resourceId !== undefined && selector.resourceId !== el.resourceId)
+            return false;
+        if (selector.contentDesc !== undefined && selector.contentDesc !== el.contentDescription)
+            return false;
+        if (selector.className !== undefined && selector.className !== el.type)
+            return false;
+        return true;
+    };
+    const isVisible = (el, resolution) => {
+        if (!el)
+            return false;
+        if (el.visible === false)
+            return false;
+        if (!el.bounds || !resolution || !resolution.width || !resolution.height)
+            return (el.visible === undefined ? true : !!el.visible);
+        const [left, top, right, bottom] = el.bounds;
+        const withinY = bottom > 0 && top < resolution.height;
+        const withinX = right > 0 && left < resolution.width;
+        return withinX && withinY;
+    };
+    const findVisibleMatch = (elements, resolution) => {
+        if (!Array.isArray(elements))
+            return null;
+        for (const e of elements) {
+            if (matchElement(e) && isVisible(e, resolution))
+                return e;
+        }
+        return null;
+    };
+    // Initial check
+    let tree = await fetchTree();
+    if (tree.error)
+        return { success: false, reason: tree.error, scrollsPerformed: 0 };
+    let found = findVisibleMatch(tree.elements, tree.resolution);
+    if (found) {
+        return { success: true, element: { text: found.text, resourceId: found.resourceId, bounds: found.bounds }, scrollsPerformed: 0 };
+    }
+    const fingerprintOf = (t) => {
+        try {
+            return JSON.stringify((t.elements || []).map((e) => ({ text: e.text, resourceId: e.resourceId, bounds: e.bounds })));
+        }
+        catch {
+            return '';
+        }
+    };
+    let prevFingerprint = fingerprintOf(tree);
+    const width = (tree.resolution && tree.resolution.width) ? tree.resolution.width : 0;
+    const height = (tree.resolution && tree.resolution.height) ? tree.resolution.height : 0;
+    const centerX = Math.round(width / 2) || 50;
+    const clampPct = (v) => Math.max(0.05, Math.min(0.95, v));
+    const computeCoords = () => {
+        const defaultStart = direction === 'down' ? 0.8 : 0.2;
+        const startPct = clampPct(defaultStart);
+        const endPct = clampPct(defaultStart + (direction === 'down' ? -scrollAmount : scrollAmount));
+        const x1 = centerX;
+        const x2 = centerX;
+        const y1 = Math.round((height || 100) * startPct);
+        const y2 = Math.round((height || 100) * endPct);
+        return { x1, y1, x2, y2 };
+    };
+    const duration = 300;
+    let scrollsPerformed = 0;
+    for (let i = 0; i < maxScrolls; i++) {
+        const { x1, y1, x2, y2 } = computeCoords();
+        try {
+            await swipe(x1, y1, x2, y2, duration, deviceId);
+        }
+        catch (e) {
+            // Log swipe failures to aid debugging but don't fail the overall flow
+            try {
+                console.warn(`scrollToElement swipe failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            catch { }
+        }
+        scrollsPerformed++;
+        await new Promise(resolve => setTimeout(resolve, stabilizationDelayMs));
+        tree = await fetchTree();
+        if (tree.error)
+            return { success: false, reason: tree.error, scrollsPerformed: scrollsPerformed };
+        found = findVisibleMatch(tree.elements, tree.resolution);
+        if (found) {
+            return { success: true, element: { text: found.text, resourceId: found.resourceId, bounds: found.bounds }, scrollsPerformed };
+        }
+        const fp = fingerprintOf(tree);
+        if (fp === prevFingerprint) {
+            return { success: false, reason: 'UI unchanged after scroll; likely end of list', scrollsPerformed: scrollsPerformed };
+        }
+        prevFingerprint = fp;
+    }
+    return { success: false, reason: 'Element not found after scrolling', scrollsPerformed: scrollsPerformed };
+}

package/dist/tools/interact.js

@@ -1,6 +1,6 @@
 import { resolveTargetDevice } from '../utils/resolve-device.js';
-import { AndroidInteract } from '../android/interact.js';
-import { iOSInteract } from '../ios/interact.js';
+import { AndroidInteract } from '../interact/index.js';
+import { iOSInteract } from '../interact/index.js';
 export class ToolsInteract {
     static async getInteractionService(platform, deviceId) {
         const effectivePlatform = platform || 'android';

package/dist/tools/manage.js

@@ -1,8 +1,8 @@
 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 { AndroidManage } from '../manage/index.js';
+import { iOSManage } from '../manage/index.js';
 import { findApk } from '../android/utils.js';
 import { findAppBundle } from '../ios/utils.js';
 import { execSync } from 'child_process';

package/dist/tools/observe.js

@@ -1,80 +1,82 @@
 import { resolveTargetDevice } from '../utils/resolve-device.js';
-import { AndroidObserve } from '../android/observe.js';
-import { iOSObserve } from '../ios/observe.js';
+import { AndroidObserve, iOSObserve } from '../observe/index.js';
 export class ToolsObserve {
-    static async getUITreeHandler({ platform, deviceId }) {
+    // Resolve a target device and return the appropriate observe instance and resolved info.
+    static async resolveObserve(platform, deviceId, appId) {
         if (platform === 'android') {
-            const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
-            return await new AndroidObserve().getUITree(resolved.id);
+            const resolved = await resolveTargetDevice({ platform: 'android', deviceId, appId });
+            return { observe: new AndroidObserve(), resolved };
         }
-        else {
-            const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
-            return await new iOSObserve().getUITree(resolved.id);
+        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 (e) {
+            const resolved = await resolveTargetDevice({ platform: 'ios', deviceId, appId });
+            return { observe: new iOSObserve(), resolved };
         }
     }
+    static async getUITreeHandler({ platform, deviceId }) {
+        const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId);
+        return await observe.getUITree(resolved.id);
+    }
     static async getCurrentScreenHandler({ deviceId }) {
-        const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
-        return await new AndroidObserve().getCurrentScreen(resolved.id);
+        const { observe, resolved } = await ToolsObserve.resolveObserve('android', deviceId);
+        // getCurrentScreen is Android-specific
+        return await observe.getCurrentScreen(resolved.id);
     }
     static async getLogsHandler({ platform, appId, deviceId, lines }) {
-        if (platform === 'android') {
-            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
-            const response = await new AndroidObserve().getLogs(appId, lines ?? 200, resolved.id);
+        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 resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
-            const resp = await new iOSObserve().getLogs(appId, resolved.id);
+            const resp = await observe.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 }) {
-        const effectivePlatform = platform || 'android';
         const sid = sessionId || 'default';
-        if (effectivePlatform === 'android') {
-            const resolved = await resolveTargetDevice({ platform: 'android', appId: packageName, deviceId });
-            // Delegate to AndroidObserve's log stream methods
-            return await new AndroidObserve().startLogStream(packageName, level || 'error', resolved.id, sid);
+        const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId, packageName);
+        if (observe instanceof AndroidObserve) {
+            return await observe.startLogStream(packageName, level || 'error', resolved.id, sid);
         }
         else {
-            const resolved = await resolveTargetDevice({ platform: 'ios', appId: packageName, deviceId });
-            // Delegate to iOSObserve for starting log streams
-            return await new iOSObserve().startLogStream(packageName, resolved.id, sid);
+            return await observe.startLogStream(packageName, resolved.id, sid);
         }
     }
     static async readLogStreamHandler({ platform, sessionId, limit, since }) {
-        const effectivePlatform = platform || 'android';
         const sid = sessionId || 'default';
-        if (effectivePlatform === 'android') {
-            return await new AndroidObserve().readLogStream(sid, limit ?? 100, since);
-        }
-        else {
-            return await new iOSObserve().readLogStream(sid, limit ?? 100, since);
-        }
+        const { observe } = await ToolsObserve.resolveObserve(platform);
+        return await observe.readLogStream(sid, limit ?? 100, since);
     }
     static async stopLogStreamHandler({ platform, sessionId }) {
-        const effectivePlatform = platform || 'android';
         const sid = sessionId || 'default';
-        if (effectivePlatform === 'android') {
-            return await new AndroidObserve().stopLogStream(sid);
-        }
-        else {
-            return await new iOSObserve().stopLogStream(sid);
-        }
+        const { observe } = await ToolsObserve.resolveObserve(platform);
+        return await observe.stopLogStream(sid);
     }
     static async captureScreenshotHandler({ platform, deviceId }) {
-        const effectivePlatform = platform || 'android';
-        if (effectivePlatform === 'android') {
-            const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
-            return await new AndroidObserve().captureScreen(resolved.id);
+        const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId);
+        if (observe instanceof AndroidObserve) {
+            return await observe.captureScreen(resolved.id);
         }
         else {
-            const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
-            return await new iOSObserve().captureScreenshot(resolved.id);
+            return await observe.captureScreenshot(resolved.id);
         }
     }
+    static async getScreenFingerprintHandler({ platform, deviceId } = {}) {
+        const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId);
+        // Both observes implement getScreenFingerprint
+        return await observe.getScreenFingerprint(resolved.id);
+    }
 }