mobile-debug-mcp 0.21.0 → 0.21.2

package/dist/interact/android.js

@@ -3,33 +3,6 @@ import { AndroidObserve } from "../observe/index.js";
 import { scrollToElementShared } from "../utils/ui/index.js";
 export class AndroidInteract {
     observe = new AndroidObserve();
-    async waitForElement(text, timeout, deviceId) {
-        const metadata = await getAndroidDeviceMetadata("", deviceId);
-        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
-        const startTime = Date.now();
-        while (Date.now() - startTime < timeout) {
-            try {
-                const tree = await this.observe.getUITree(deviceId);
-                if (tree.error) {
-                    return { device: deviceInfo, found: false, error: tree.error };
-                }
-                const element = tree.elements.find(e => e.text === text);
-                if (element) {
-                    return { device: deviceInfo, found: true, element };
-                }
-            }
-            catch (e) {
-                // Ignore errors during polling and retry
-                console.error("Error polling UI tree:", e);
-            }
-            const elapsed = Date.now() - startTime;
-            const remaining = timeout - elapsed;
-            if (remaining <= 0)
-                break;
-            await new Promise(resolve => setTimeout(resolve, Math.min(500, remaining)));
-        }
-        return { device: deviceInfo, found: false };
-    }
     async tap(x, y, deviceId) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);

package/dist/interact/index.js

@@ -10,11 +10,6 @@ export class ToolsInteract {
         const interact = effectivePlatform === 'android' ? new AndroidInteract() : new iOSInteract();
         return { interact: interact, resolved, platform: effectivePlatform };
     }
-    static async waitForElementHandler({ platform, text, timeout, deviceId }) {
-        const effectiveTimeout = timeout ?? 10000;
-        const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
-        return await interact.waitForElement(text, effectiveTimeout, resolved.id);
-    }
     static async tapHandler({ platform, x, y, deviceId }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
         return await interact.tap(x, y, resolved.id);
@@ -220,6 +215,10 @@ export class ToolsInteract {
         const scoreVal = Math.min(1, Number(bestScore.toFixed(3)));
         return { found: true, element: outEl, score: scoreVal, confidence: scoreVal };
     }
+    static async waitForUIHandler({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }) {
+        // Backwards-compatible wrapper that delegates to the core waitForUICore implementation
+        return await ToolsInteract.waitForUICore({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId });
+    }
     static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }) {
         const start = Date.now();
         let lastFingerprint = null;
@@ -258,7 +257,7 @@ export class ToolsInteract {
         }
         return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start };
     }
-    static async observeUntilHandler({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }) {
+    static async waitForUICore({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }) {
         const start = Date.now();
         const deadline = start + (timeoutMs || 0);
         const q = (query === null || query === undefined) ? '' : String(query);
@@ -281,7 +280,7 @@ export class ToolsInteract {
         }
         catch (err) {
             try {
-                console.warn('observeUntil: failed to get baseline data (non-fatal):', err instanceof Error ? err.message : String(err));
+                console.warn('waitForUI: failed to get baseline data (non-fatal):', err instanceof Error ? err.message : String(err));
             }
             catch { }
         }
@@ -292,7 +291,7 @@ export class ToolsInteract {
         // Optional initial observation delay requested by caller
         if (typeof observationDelayMs === 'number' && observationDelayMs > 0) {
             try {
-                console.log(`observeUntil: delaying observation for ${observationDelayMs}ms`);
+                console.log(`waitForUI: delaying observation for ${observationDelayMs}ms`);
             }
             catch { }
             await sleep(observationDelayMs);
@@ -309,29 +308,11 @@ export class ToolsInteract {
             // Evaluate condition per type
             if (type === 'ui') {
                 try {
-                    // Lightweight UI check: fetch UI tree and perform a normalized substring match to reduce overhead
+                    // Prefer using the public findElementHandler which tests can override. This avoids relying
+                    // on resolveObserve/getUITree for unit tests which may not have devices available.
                     try {
-                        // Bound the UI tree fetch to avoid long blocking calls; prefer quick failure over hanging a poll
-                        const withTimeout = (p, ms) => Promise.race([p, new Promise(resolve => setTimeout(() => resolve(null), ms))]);
-                        const tree = await withTimeout(ToolsObserve.getUITreeHandler({ platform, deviceId }), Math.min(pollInterval, 500));
-                        const elems = Array.isArray(tree && tree.elements) ? tree.elements : [];
-                        const qnorm = q.toLowerCase();
-                        let matched = null;
-                        for (const el of elems) {
-                            try {
-                                const txt = ((el && (el.text || el.label || el.value || el.contentDescription || el.accessibilityLabel)) || '');
-                                if (!txt)
-                                    continue;
-                                if (String(txt).toLowerCase().includes(qnorm)) {
-                                    matched = el;
-                                    break;
-                                }
-                            }
-                            catch {
-                                continue;
-                            }
-                        }
-                        const isPresent = !!matched;
+                        const findRes = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, pollInterval), platform, deviceId });
+                        const isPresent = !!(findRes && findRes.found);
                         const conditionTrue = (match === 'present') ? isPresent : !isPresent;
                         if (conditionTrue) {
                             if (matchedAt === null)
@@ -339,8 +320,8 @@ export class ToolsInteract {
                             stableDuration = Date.now() - matchedAt;
                             lastObservedState = true;
                             if (stableDuration >= stability_ms) {
-                                matchSource = 'ui-tree-' + (match === 'present' ? 'present' : 'absent');
-                                const element = isPresent ? matched : null;
+                                matchSource = 'ui-find';
+                                const element = isPresent ? findRes.element : null;
                                 const now2 = Date.now();
                                 return { success: true, condition: match, query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: stableDuration, matchedElement: element, matchSource, timestamp: now2, type: 'ui', observed_state: lastObservedState ?? null };
                             }
@@ -352,11 +333,11 @@ export class ToolsInteract {
                         }
                     }
                     catch (err) {
-                        console.error('observeUntil(ui) tree error:', err);
+                        console.error('waitForUI(ui) find error:', err);
                     }
                 }
                 catch (err) {
-                    console.error('observeUntil(ui) find error:', err);
+                    console.error('waitForUI(ui) outer error:', err);
                 }
             }
             else if (type === 'log') {
@@ -387,7 +368,7 @@ export class ToolsInteract {
                     }
                 }
                 catch (err) {
-                    console.error('observeUntil(log) error:', err);
+                    console.error('waitForUI(log) error:', err);
                 }
             }
             else if (type === 'screen') {
@@ -415,7 +396,7 @@ export class ToolsInteract {
                     }
                 }
                 catch (err) {
-                    console.error('observeUntil(screen) error:', err);
+                    console.error('waitForUI(screen) error:', err);
                 }
             }
             else if (type === 'idle') {
@@ -439,7 +420,7 @@ export class ToolsInteract {
                     }
                 }
                 catch (err) {
-                    console.error('observeUntil(idle) error:', err);
+                    console.error('waitForUI(idle) error:', err);
                 }
             }
             // Respect poll interval and avoid tight loop
@@ -449,7 +430,11 @@ export class ToolsInteract {
         let snapshot = null;
         if (includeSnapshotOnFailure) {
             try {
-                snapshot = await ToolsObserve.captureDebugSnapshotHandler({ reason: `observe_until timeout for ${type}`, includeLogs: true, platform, deviceId });
+                // Use dynamic import to avoid circular-initialization issues where the ToolsObserve
+                // binding captured earlier may not reflect test-time overrides. Importing at call
+                // time ensures the latest exported ToolsObserve object is used.
+                const Obs = await import('../observe/index.js');
+                snapshot = await Obs.ToolsObserve.captureDebugSnapshotHandler({ reason: `wait_for_ui timeout for ${type}`, includeLogs: true, platform, deviceId });
             }
             catch (err) {
                 snapshot = { error: err instanceof Error ? err.message : String(err) };

package/dist/interact/ios.js

@@ -4,32 +4,6 @@ import { iOSObserve } from "../observe/index.js";
 import { scrollToElementShared } from "../utils/ui/index.js";
 export class iOSInteract {
     observe = new iOSObserve();
-    async waitForElement(text, timeout, deviceId = "booted") {
-        const device = await getIOSDeviceMetadata(deviceId);
-        const startTime = Date.now();
-        while (Date.now() - startTime < timeout) {
-            try {
-                const tree = await this.observe.getUITree(deviceId);
-                if (tree.error) {
-                    return { device, found: false, error: tree.error };
-                }
-                const element = tree.elements.find(e => e.text === text);
-                if (element) {
-                    return { device, found: true, element };
-                }
-            }
-            catch (e) {
-                // Ignore errors during polling and retry
-                console.error("Error polling UI tree:", e);
-            }
-            const elapsed = Date.now() - startTime;
-            const remaining = timeout - elapsed;
-            if (remaining <= 0)
-                break;
-            await new Promise(resolve => setTimeout(resolve, Math.min(500, remaining)));
-        }
-        return { device, found: false };
-    }
     async tap(x, y, deviceId = "booted") {
         const device = await getIOSDeviceMetadata(deviceId);
         // Use shared helper to detect idb

package/dist/observe/android.js

@@ -5,6 +5,7 @@ import { createWriteStream } from "fs";
 import { promises as fsPromises } from "fs";
 import path from "path";
 import { computeScreenFingerprint } from "../utils/ui/index.js";
+import { parsePngSize } from "../utils/image.js";
 const activeLogStreams = new Map();
 export class AndroidObserve {
     async getDeviceMetadata(appId, deviceId) {
@@ -120,7 +121,7 @@ export class AndroidObserve {
                 child.kill();
                 reject(new Error(`ADB screencap timed out after 10s`));
             }, 10000);
-            child.on('close', (code) => {
+            child.on('close', async (code) => {
                 clearTimeout(timeout);
                 if (code !== 0) {
                     reject(new Error(stderr.trim() || `Screencap failed with code ${code}`));
@@ -128,28 +129,91 @@ export class AndroidObserve {
                 }
                 const screenshotBuffer = Buffer.concat(chunks);
                 const screenshotBase64 = screenshotBuffer.toString('base64');
-                execAdb(['shell', 'wm', 'size'], deviceId)
-                    .then(sizeStdout => {
-                    let width = 0;
-                    let height = 0;
-                    const match = sizeStdout.match(/Physical size: (\d+)x(\d+)/);
-                    if (match) {
-                        width = parseInt(match[1], 10);
-                        height = parseInt(match[2], 10);
+                const parsed = parsePngSize(screenshotBuffer);
+                if (parsed.width > 0 && parsed.height > 0) {
+                    // Attempt to convert to WebP (preferred) and provide JPEG fallback (awaited to avoid race)
+                    try {
+                        const sharpModule = await import('sharp');
+                        const sharp = sharpModule && sharpModule.default ? sharpModule.default : sharpModule;
+                        const buf = screenshotBuffer;
+                        const img = sharp(buf);
+                        const meta = await img.metadata().catch((err) => { console.error('sharp.metadata failed (Android):', err); return {}; });
+                        const hasAlpha = !!meta.hasAlpha || (meta.channels && meta.channels > 3);
+                        let webpBuf = null;
+                        let jpegBuf = null;
+                        try {
+                            webpBuf = await img.webp({ quality: 80 }).toBuffer();
+                        }
+                        catch (err) {
+                            console.error('WebP conversion failed (Android):', err instanceof Error ? err.message : String(err));
+                            webpBuf = null;
+                        }
+                        try {
+                            jpegBuf = await img.jpeg({ quality: 80 }).toBuffer();
+                        }
+                        catch (err) {
+                            console.error('JPEG conversion failed (Android):', err instanceof Error ? err.message : String(err));
+                            jpegBuf = null;
+                        }
+                        if (hasAlpha) {
+                            if (webpBuf) {
+                                const webpB64 = webpBuf.toString('base64');
+                                const jpegB64 = jpegBuf ? jpegBuf.toString('base64') : null;
+                                resolve({ device: deviceInfo, screenshot: webpB64, screenshot_mime: 'image/webp', screenshot_fallback: jpegB64, screenshot_fallback_mime: jpegB64 ? 'image/jpeg' : undefined, resolution: { width: parsed.width, height: parsed.height } });
+                                return;
+                            }
+                            const pngB64 = buf.toString('base64');
+                            resolve({ device: deviceInfo, screenshot: pngB64, screenshot_mime: 'image/png', resolution: { width: parsed.width, height: parsed.height } });
+                            return;
+                        }
+                        if (webpBuf) {
+                            const webpB64 = webpBuf.toString('base64');
+                            const jpegB64 = jpegBuf ? jpegBuf.toString('base64') : null;
+                            resolve({ device: deviceInfo, screenshot: webpB64, screenshot_mime: 'image/webp', screenshot_fallback: jpegB64, screenshot_fallback_mime: jpegB64 ? 'image/jpeg' : undefined, resolution: { width: parsed.width, height: parsed.height } });
+                            return;
+                        }
+                        if (jpegBuf) {
+                            resolve({ device: deviceInfo, screenshot: jpegBuf.toString('base64'), screenshot_mime: 'image/jpeg', resolution: { width: parsed.width, height: parsed.height } });
+                            return;
+                        }
+                        // No conversions succeeded; return original PNG
+                        resolve({ device: deviceInfo, screenshot: screenshotBase64, screenshot_mime: 'image/png', resolution: { width: parsed.width, height: parsed.height } });
+                        return;
                     }
-                    resolve({
-                        device: deviceInfo,
-                        screenshot: screenshotBase64,
-                        resolution: { width, height }
-                    });
-                })
-                    .catch(() => {
-                    resolve({
-                        device: deviceInfo,
-                        screenshot: screenshotBase64,
-                        resolution: { width: 0, height: 0 }
+                    catch (err) {
+                        console.error('Screenshot conversion pipeline failed (Android):', err instanceof Error ? err.message : String(err));
+                        // Conversion failed - fall back to original PNG with parsed resolution
+                        resolve({ device: deviceInfo, screenshot: screenshotBase64, screenshot_mime: 'image/png', resolution: { width: parsed.width, height: parsed.height } });
+                        return;
+                    }
+                }
+                else {
+                    // Fallback to querying wm size if parsing failed
+                    execAdb(['shell', 'wm', 'size'], deviceId)
+                        .then(sizeStdout => {
+                        let width = 0;
+                        let height = 0;
+                        const match = sizeStdout.match(/Physical size: (\d+)x(\d+)/);
+                        if (match) {
+                            width = parseInt(match[1], 10);
+                            height = parseInt(match[2], 10);
+                        }
+                        resolve({
+                            device: deviceInfo,
+                            screenshot: screenshotBase64,
+                            screenshot_mime: 'image/png',
+                            resolution: { width, height }
+                        });
+                    })
+                        .catch(() => {
+                        resolve({
+                            device: deviceInfo,
+                            screenshot: screenshotBase64,
+                            screenshot_mime: 'image/png',
+                            resolution: { width: 0, height: 0 }
+                        });
                     });
-                });
+                }
             });
             child.on('error', (err) => {
                 clearTimeout(timeout);

package/dist/observe/ios.js

@@ -5,6 +5,7 @@ import { createWriteStream, promises as fsPromises } from 'fs';
 import path from 'path';
 import { parseLogLine } from '../utils/android/utils.js';
 import { computeScreenFingerprint } from '../utils/ui/index.js';
+import { parsePngSize } from '../utils/image.js';
 const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 function parseIDBFrame(frame) {
     if (!frame)
@@ -109,11 +110,59 @@ export class iOSObserve {
             await execCommand(['simctl', 'io', deviceId, 'screenshot', tmpFile], deviceId);
             const buffer = await fs.readFile(tmpFile);
             const base64 = buffer.toString('base64');
+            const dims = parsePngSize(buffer);
+            // Try to generate WebP (preferred) and JPEG fallback using sharp (in-process, cross-platform)
+            try {
+                const sharpModule = await import('sharp');
+                const sharp = sharpModule && sharpModule.default ? sharpModule.default : sharpModule;
+                const img = sharp(buffer);
+                const meta = await img.metadata().catch((err) => { console.error('sharp.metadata failed:', err); return {}; });
+                // If image has alpha channel, prefer lossless PNG to preserve transparency
+                const hasAlpha = !!meta.hasAlpha || (meta.channels && meta.channels > 3);
+                // Generate WebP and JPEG buffers; log failures
+                let webpBuf = null;
+                let jpegBuf = null;
+                try {
+                    webpBuf = await img.webp({ quality: 80 }).toBuffer();
+                }
+                catch (err) {
+                    console.error('WebP conversion failed (iOS):', err instanceof Error ? err.message : String(err));
+                    webpBuf = null;
+                }
+                try {
+                    jpegBuf = await img.jpeg({ quality: 80 }).toBuffer();
+                }
+                catch (err) {
+                    console.error('JPEG conversion failed (iOS):', err instanceof Error ? err.message : String(err));
+                    jpegBuf = null;
+                }
+                await fs.rm(tmpFile).catch(() => { });
+                if (hasAlpha) {
+                    // preserve alpha: return PNG if WebP not available
+                    if (webpBuf) {
+                        return { device, screenshot: webpBuf.toString('base64'), screenshot_mime: 'image/webp', screenshot_fallback: base64, screenshot_fallback_mime: 'image/png', resolution: { width: dims.width, height: dims.height } };
+                    }
+                    // if webp unavailable, return original PNG
+                    return { device, screenshot: base64, screenshot_mime: 'image/png', resolution: { width: dims.width, height: dims.height } };
+                }
+                // No alpha: prefer webp, fall back to jpeg
+                if (webpBuf) {
+                    return { device, screenshot: webpBuf.toString('base64'), screenshot_mime: 'image/webp', screenshot_fallback: jpegBuf ? jpegBuf.toString('base64') : undefined, screenshot_fallback_mime: jpegBuf ? 'image/jpeg' : undefined, resolution: { width: dims.width, height: dims.height } };
+                }
+                if (jpegBuf) {
+                    return { device, screenshot: jpegBuf.toString('base64'), screenshot_mime: 'image/jpeg', resolution: { width: dims.width, height: dims.height } };
+                }
+            }
+            catch (err) {
+                console.error('Screenshot conversion pipeline failed (iOS):', err instanceof Error ? err.message : String(err));
+                // fall through to png fallback
+            }
             await fs.rm(tmpFile).catch(() => { });
             return {
                 device,
                 screenshot: base64,
-                resolution: { width: 0, height: 0 },
+                screenshot_mime: 'image/png',
+                resolution: { width: dims.width, height: dims.height },
             };
         }
         catch (e) {

package/dist/server.js

@@ -315,8 +315,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             }
         },
         {
-            name: "observe_until",
-            description: "Wait for a UI condition (element present/absent) and require a stability window before returning success. Network-based waiting is not required; UI-only synchronization is the default and primary mode.",
+            name: "wait_for_ui",
+            description: "Wait for a UI/log/screen/idle condition with a stability window before returning success.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -332,34 +332,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 }
             }
         },
-        {
-            name: "wait_for_element",
-            description: "Wait until a UI element with matching text appears on screen or timeout is reached.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    platform: {
-                        type: "string",
-                        enum: ["android", "ios"],
-                        description: "Platform to check"
-                    },
-                    text: {
-                        type: "string",
-                        description: "Text content of the element to wait for"
-                    },
-                    timeout: {
-                        type: "number",
-                        description: "Max wait time in ms (default 10000)",
-                        default: 10000
-                    },
-                    deviceId: {
-                        type: "string",
-                        description: "Device Serial/UDID. Defaults to connected/booted device."
-                    }
-                },
-                required: ["platform", "text"]
-            }
-        },
         {
             name: "find_element",
             description: "Find a UI element by semantic query (text, content-desc, resource-id, class). Returns best match.",
@@ -612,12 +584,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (name === "capture_screenshot") {
             const { platform, deviceId } = args;
             const res = await ToolsObserve.captureScreenshotHandler({ platform, deviceId });
-            return {
-                content: [
-                    { type: 'text', text: JSON.stringify({ device: res.device, result: { resolution: res.resolution } }, null, 2) },
-                    { type: 'image', data: res.screenshot, mimeType: 'image/png' }
-                ]
-            };
+            const mime = res.screenshot_mime || 'image/png';
+            const content = [
+                { type: 'text', text: JSON.stringify({ device: res.device, result: { resolution: res.resolution, mimeType: mime } }, null, 2) },
+                { type: 'image', data: res.screenshot, mimeType: mime }
+            ];
+            // If a jpeg fallback is available, include a small note and the fallback as an additional image block for compatibility
+            if (res.screenshot_fallback) {
+                content.push({ type: 'text', text: JSON.stringify({ note: 'JPEG fallback included for compatibility', mimeType: res.screenshot_fallback_mime || 'image/jpeg' }) });
+                content.push({ type: 'image', data: res.screenshot_fallback, mimeType: res.screenshot_fallback_mime || 'image/jpeg' });
+            }
+            return { content };
         }
         if (name === "capture_debug_snapshot") {
             const { reason, includeLogs, logLines, platform, appId, deviceId, sessionId } = args;
@@ -644,9 +621,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const res = await ToolsInteract.waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs, pollIntervalMs, deviceId });
             return wrapResponse(res);
         }
-        if (name === "wait_for_element") {
-            const { platform, text, timeout, deviceId } = (args || {});
-            const res = await ToolsInteract.waitForElementHandler({ platform, text, timeout, deviceId });
+        if (name === "wait_for_ui") {
+            const { type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId } = (args || {});
+            const res = await ToolsInteract.waitForUIHandler({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId });
             return wrapResponse(res);
         }
         if (name === "find_element") {

package/dist/utils/image.js

@@ -0,0 +1,18 @@
+export function parsePngSize(buf) {
+    try {
+        if (!buf || buf.length < 24)
+            return { width: 0, height: 0 };
+        // PNG signature + IHDR checks
+        if (buf.readUInt32BE(0) !== 0x89504e47 || buf.readUInt32BE(4) !== 0x0d0a1a0a)
+            return { width: 0, height: 0 };
+        const ihdr = buf.toString('ascii', 12, 16);
+        if (ihdr !== 'IHDR')
+            return { width: 0, height: 0 };
+        const width = buf.readUInt32BE(16);
+        const height = buf.readUInt32BE(20);
+        return { width, height };
+    }
+    catch {
+        return { width: 0, height: 0 };
+    }
+}

package/dist/utils/resolve-device.js

@@ -23,6 +23,11 @@ export async function listDevices(platform, appId) {
 export async function resolveTargetDevice(opts) {
     const { platform, appId, prefer, deviceId } = opts;
     const devices = await listDevices(platform, appId);
+    // During unit tests (no adb/xcrun available), provide a lightweight mock device so
+    // the observe/interact unit tests can run without real devices.
+    if ((!devices || devices.length === 0) && (process.env.NODE_ENV === 'test' || process.env.MCP_TEST_MOCK_DEVICES === '1')) {
+        return { id: 'mock', platform: platform || 'android', osVersion: '12', model: 'Pixel', simulator: true };
+    }
     if (deviceId) {
         const found = devices.find(d => d.id === deviceId);
         if (!found)

package/docs/CHANGELOG.md

@@ -2,8 +2,14 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.21.2]
+- Fixed screenshots not working, imnproved tool
+
+## [0.21.1]
+- Removed wait_for_element and renamed observe_until to wait_for_ui (obsolete references removed)
+
 ## [0.21.0]
-- Added `observe_until` as a tool for agents to wait for things like API requests
+- Added `wait_for_ui` as a tool for agents to wait for things like API requests
 
 ## [0.20.1]
 - Fixes gradle home issue for android
@@ -24,7 +30,7 @@ All notable changes to the **Mobile Debug MCP** project will be documented in th
 
 ## [0.19.0]
 
-- Added `observe_until` interaction tool: waits for UI, log, screen fingerprint or idle conditions with configurable polling and timeout. Returns rich details on match (element info, log line, new fingerprint).
+- Added `wait_for_ui` interaction tool: waits for UI, log, screen fingerprint or idle conditions with configurable polling and timeout. Returns rich details on match (element info, log line, new fingerprint).
 
 
 ## [0.18.0]

package/docs/tools/interact.md

@@ -2,26 +2,6 @@
 
 Tools that perform UI interactions: tap, swipe, type_text, press_back, and waiting for elements.
 
-## wait_for_element
-Wait until a UI element with matching text appears on screen or timeout is reached.
-
-Input:
-
-```
-{ "platform": "android", "text": "Home", "timeout": 5000, "deviceId": "emulator-5554" }
-```
-
-Response:
-
-```
-{ "device": { "platform": "android", "id": "emulator-5554" }, "found": true, "element": { "text": "Home", "resourceId": "com.example:id/home" } }
-```
-
-Notes:
-- Polls get_ui_tree until timeout or element found. Returns an `error` field if system failures occur.
-
----
-
 ## tap / swipe / type_text / press_back
 
 Tap input example:
@@ -153,7 +133,7 @@ Notes:
 
 ---
 
-## observe_until
+## wait_for_ui
 
 Purpose:
 - Wait for a condition to occur on the device: UI element appearance, a log line, a screen fingerprint change, or an idle/stable screen state.
@@ -164,7 +144,7 @@ Supported types and behavior:
 - screen: Compares screen fingerprints (visual checks) against an initial baseline and returns when fingerprint changes. If `query` is provided it will attempt a `find_element` on the new screen to validate the expected content.
 - idle: Waits until the screen fingerprint remains stable for a short stability window (default 1000ms).
 
-Input (ToolsInteract.observeUntilHandler):
+Input (ToolsInteract.waitForUIHandler):
 ```
 { "type": "ui|log|screen|idle", "query": "optional string", "timeoutMs": 5000, "pollIntervalMs": 200, "platform": "android|ios", "deviceId": "optional device id" }
 ```
@@ -190,16 +170,16 @@ Notes & tips:
 - For UI-sensitive flows prefer type='ui' rather than relying solely on visual fingerprint changes, as some UI updates don't alter the fingerprint.
 
 Tests:
-- Unit: `test/interact/unit/observe_until.test.ts`
-- Device runner: `test/interact/device/observe_until_device.ts` (requires devices/emulators and adb/xcrun in PATH)
+- Unit: `test/interact/unit/wait_for_ui.test.ts`
+- Device runner: `test/interact/device/wait_for_ui_device.ts` (requires devices/emulators and adb/xcrun in PATH)
 
 Example:
 ```
 // Wait up to 5s for a button labeled "Generate Session" on Android
-ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 5000, platform: 'android' })
+ToolsInteract.waitForUIHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 5000, platform: 'android' })
 ```
 
 Troubleshooting:
-- If observe_until(log) never matches, ensure log streaming is started for the target package and baseline logs captured correctly.
-- If observe_until(screen) times out despite visible UI change, try type='ui' to validate content-level changes.
+- If wait_for_ui(log) never matches, ensure log streaming is started for the target package and baseline logs captured correctly.
+- If wait_for_ui(screen) times out despite visible UI change, try type='ui' to validate content-level changes.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
     "healthcheck": "tsx ./src/cli/idb/check-idb.ts",
     "install-idb": "tsx ./src/cli/idb/install-idb.ts",
     "preflight-ios": "tsx ./src/cli/ios/preflight-ios.ts",
-    "test:unit": "tsx test/unit/index.ts",
+    "test:unit": "SKIP_DEVICE_TESTS=1 tsx test/unit/index.ts",
     "test:integration": "npm run build && tsx test/device/index.ts",
     "test:device": "npm run build && tsx test/device/index.ts",
     "test": "npm run test:unit",
@@ -27,7 +27,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "fast-xml-parser": "^5.5.1",
-    "zod": "^3.22.4"
+    "zod": "^3.22.4",
+    "sharp": "^0.32.1"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",