mobile-debug-mcp 0.6.0 → 0.7.0

package/README.md

@@ -282,6 +282,150 @@ Get the currently visible activity on an Android device.
 }
 ```
 
+### wait_for_element
+Wait until a UI element with matching text appears on screen or timeout is reached. Useful for handling loading states or transitions.
+
+**Input:**
+```jsonc
+{
+  "platform": "android" | "ios",
+  "text": "Home", // Text to wait for
+  "timeout": 5000, // Max wait time in ms (default 10000)
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "found": true,
+  "element": { /* UIElement object if found */ }
+}
+```
+
+If the element is not found within the timeout, `found` will be `false`. If a system error occurs (e.g., ADB failure), an `error` field will be present.
+
+```json
+{
+  "device": { /* device info */ },
+  "found": false,
+  "error": "Optional error message"
+}
+```
+
+### tap
+Simulate a finger tap on the device screen at specific coordinates.
+
+Platform support and constraints:
+- Android: Implemented via `adb shell input tap` and works when `adb` is available in PATH or configured via `ADB_PATH`.
+- iOS: Requires Facebook's `idb` tooling. The iOS implementation uses `idb` to deliver UI events and is simulator-oriented (works reliably on a booted simulator). Physical device support depends on `idb` capabilities and a running `idb_companion` on the target device; it may not work in all environments.
+
+Prerequisites for iOS (if you intend to use tap on iOS):
+```bash
+brew tap facebook/fb
+brew install idb-companion
+pip3 install fb-idb
+```
+Ensure `idb` and `idb_companion` are in your PATH. If you use non-standard tool locations, set `XCRUN_PATH` and/or `ADB_PATH` environment variables as appropriate.
+
+Behavior notes:
+- The tool is a primitive input: it only sends a tap at the provided coordinates. It does not inspect or interpret the UI.
+- If `idb` is missing or the simulator/device is not available, the tool will return an error explaining the failure.
+
+**Input:**
+```jsonc
+{
+  "platform": "android" | "ios", // Optional, defaults to "android"
+  "x": 200, // X coordinate (Required)
+  "y": 400, // Y coordinate (Required)
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "success": true,
+  "x": 200,
+  "y": 400
+}
+```
+
+If the tap fails (e.g., missing `adb`/`idb`, device not found), `success` will be `false` and an `error` field will be present.
+
+### swipe
+Simulate a swipe gesture on an Android device.
+
+**Input:**
+```jsonc
+{
+  "platform": "android", // Optional, defaults to "android"
+  "x1": 500, // Start X (Required)
+  "y1": 1500, // Start Y (Required)
+  "x2": 500, // End X (Required)
+  "y2": 500, // End Y (Required)
+  "duration": 300, // Duration in ms (Required)
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "success": true,
+  "start": [500, 1500],
+  "end": [500, 500],
+  "duration": 300
+}
+```
+
+If the swipe fails, `success` will be `false` and an `error` field will be present.
+
+### type_text
+Type text into the currently focused input field on an Android device.
+
+**Input:**
+```jsonc
+{
+  "platform": "android", // Optional, defaults to "android"
+  "text": "hello world", // Text to type (Required)
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "success": true,
+  "text": "hello world"
+}
+```
+
+If the command fails, `success` will be `false` and an `error` field will be present.
+
+### press_back
+Simulate pressing the Android Back button.
+
+**Input:**
+```jsonc
+{
+  "platform": "android", // Optional
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "success": true
+}
+```
+
 ---
 
 ## Recommended Workflow
@@ -290,8 +434,9 @@ Get the currently visible activity on an Android device.
 2. Use `start_app` to launch the app.
 3. Use `get_logs` to read the latest logs.
 4. Use `capture_screenshot` to visually inspect the app if needed.
-5. Use `reset_app_data` to clear state if debugging fresh install scenarios.
-6. Use `restart_app` to quickly reboot the app during development cycles.
+5. Use `wait_for_element` to ensure the app is in the expected state before proceeding (e.g., after login).
+6. Use `reset_app_data` to clear state if debugging fresh install scenarios.
+7. Use `restart_app` to quickly reboot the app during development cycles.
 
 ---
 

package/dist/android/interact.js

@@ -1,5 +1,81 @@
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js";
+import { AndroidObserve } from "./observe.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);
+        try {
+            await execAdb(['shell', 'input', 'tap', x.toString(), y.toString()], deviceId);
+            return { device: deviceInfo, success: true, x, y };
+        }
+        catch (e) {
+            return { device: deviceInfo, success: false, x, y, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async swipe(x1, y1, x2, y2, duration, deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            await execAdb(['shell', 'input', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString(), duration.toString()], deviceId);
+            return { device: deviceInfo, success: true, start: [x1, y1], end: [x2, y2], duration };
+        }
+        catch (e) {
+            return { device: deviceInfo, success: false, start: [x1, y1], end: [x2, y2], duration, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async typeText(text, deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            // Encode spaces as %s to ensure proper input handling by adb shell input text
+            const encodedText = text.replace(/\s/g, '%s');
+            // Note: 'input text' might fail with some characters or if keyboard isn't ready, but it's the standard ADB way.
+            await execAdb(['shell', 'input', 'text', encodedText], deviceId);
+            return { device: deviceInfo, success: true, text };
+        }
+        catch (e) {
+            return { device: deviceInfo, success: false, text, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async pressBack(deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            await execAdb(['shell', 'input', 'keyevent', '4'], deviceId);
+            return { device: deviceInfo, success: true };
+        }
+        catch (e) {
+            return { device: deviceInfo, success: false, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
     async startApp(appId, deviceId) {
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);

package/dist/ios/interact.js

@@ -1,6 +1,76 @@
 import { promises as fs } from "fs";
-import { execCommand, getIOSDeviceMetadata, validateBundleId } from "./utils.js";
+import { spawn } from "child_process";
+import { execCommand, getIOSDeviceMetadata, validateBundleId, IDB } from "./utils.js";
+import { iOSObserve } from "./observe.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);
+        // Check for idb
+        const child = spawn(IDB, ['--version']);
+        const idbExists = await new Promise((resolve) => {
+            child.on('error', () => resolve(false));
+            child.on('close', (code) => resolve(code === 0));
+        });
+        if (!idbExists) {
+            return {
+                device,
+                success: false,
+                x,
+                y,
+                error: "iOS tap requires 'idb' (iOS Device Bridge)."
+            };
+        }
+        try {
+            const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
+            const args = ['ui', 'tap', x.toString(), y.toString()];
+            if (targetUdid) {
+                args.push('--udid', targetUdid);
+            }
+            await new Promise((resolve, reject) => {
+                const proc = spawn(IDB, args);
+                let stderr = '';
+                proc.stderr.on('data', d => stderr += d.toString());
+                proc.on('close', code => {
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(`idb ui tap failed: ${stderr}`));
+                });
+                proc.on('error', err => reject(err));
+            });
+            return { device, success: true, x, y };
+        }
+        catch (e) {
+            return { device, success: false, x, y, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
     async startApp(bundleId, deviceId = "booted") {
         validateBundleId(bundleId);
         const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId);

package/dist/server.js

@@ -12,7 +12,7 @@ const iosObserve = new iOSObserve();
 const iosInteract = new iOSInteract();
 const server = new Server({
     name: "mobile-debug-mcp",
-    version: "0.6.0"
+    version: "0.7.0"
 }, {
     capabilities: {
         tools: {}
@@ -191,6 +191,126 @@ 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: "tap",
+            description: "Simulate a finger tap on the device screen at specific coordinates.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: {
+                        type: "string",
+                        enum: ["android", "ios"],
+                        description: "Platform to tap on"
+                    },
+                    x: {
+                        type: "number",
+                        description: "X coordinate"
+                    },
+                    y: {
+                        type: "number",
+                        description: "Y coordinate"
+                    },
+                    deviceId: {
+                        type: "string",
+                        description: "Device Serial/UDID. Defaults to connected/booted device."
+                    }
+                },
+                required: ["x", "y"]
+            }
+        },
+        {
+            name: "swipe",
+            description: "Simulate a swipe gesture on an Android device.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: {
+                        type: "string",
+                        enum: ["android"],
+                        description: "Platform to swipe on (currently only android supported)"
+                    },
+                    x1: { type: "number", description: "Start X coordinate" },
+                    y1: { type: "number", description: "Start Y coordinate" },
+                    x2: { type: "number", description: "End X coordinate" },
+                    y2: { type: "number", description: "End Y coordinate" },
+                    duration: { type: "number", description: "Duration in ms" },
+                    deviceId: {
+                        type: "string",
+                        description: "Device Serial/UDID. Defaults to connected/booted device."
+                    }
+                },
+                required: ["x1", "y1", "x2", "y2", "duration"]
+            }
+        },
+        {
+            name: "type_text",
+            description: "Type text into the currently focused input field on an Android device.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: {
+                        type: "string",
+                        enum: ["android"],
+                        description: "Platform to type on (currently only android supported)"
+                    },
+                    text: {
+                        type: "string",
+                        description: "The text to type"
+                    },
+                    deviceId: {
+                        type: "string",
+                        description: "Device Serial/UDID. Defaults to connected/booted device."
+                    }
+                },
+                required: ["text"]
+            }
+        },
+        {
+            name: "press_back",
+            description: "Simulate pressing the Android Back button.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: {
+                        type: "string",
+                        enum: ["android"],
+                        description: "Platform (currently only android supported)"
+                    },
+                    deviceId: {
+                        type: "string",
+                        description: "Device Serial/UDID. Defaults to connected/booted device."
+                    }
+                }
+            }
         }
     ]
 }));
@@ -376,6 +496,73 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const result = await androidObserve.getCurrentScreen(deviceId);
             return wrapResponse(result);
         }
+        if (name === "wait_for_element") {
+            const { platform, text, timeout, deviceId } = (args || {});
+            const effectiveTimeout = timeout ?? 10000;
+            let result;
+            if (platform === "android") {
+                result = await androidInteract.waitForElement(text, effectiveTimeout, deviceId);
+            }
+            else {
+                result = await iosInteract.waitForElement(text, effectiveTimeout, deviceId);
+            }
+            return wrapResponse(result);
+        }
+        if (name === "tap") {
+            const { platform, x, y, deviceId } = (args || {});
+            const effectivePlatform = platform || "android";
+            // Basic validation
+            if (typeof x !== 'number' || typeof y !== 'number') {
+                throw new Error("x and y coordinates are required and must be numbers");
+            }
+            let result;
+            if (effectivePlatform === "android") {
+                result = await androidInteract.tap(x, y, deviceId);
+            }
+            else {
+                result = await iosInteract.tap(x, y, deviceId);
+            }
+            return wrapResponse(result);
+        }
+        if (name === "swipe") {
+            const { platform, x1, y1, x2, y2, duration, deviceId } = (args || {});
+            const effectivePlatform = platform || "android";
+            if (typeof x1 !== 'number' || typeof y1 !== 'number' || typeof x2 !== 'number' || typeof y2 !== 'number' || typeof duration !== 'number') {
+                throw new Error("x1, y1, x2, y2, and duration are required and must be numbers");
+            }
+            let result;
+            if (effectivePlatform === "android") {
+                result = await androidInteract.swipe(x1, y1, x2, y2, duration, deviceId);
+            }
+            else {
+                throw new Error(`Platform ${effectivePlatform} not supported for swipe`);
+            }
+            return wrapResponse(result);
+        }
+        if (name === "type_text") {
+            const { platform, text, deviceId } = (args || {});
+            const effectivePlatform = platform || "android";
+            if (typeof text !== 'string') {
+                throw new Error("text is required and must be a string");
+            }
+            let result;
+            if (effectivePlatform === "android") {
+                result = await androidInteract.typeText(text, deviceId);
+            }
+            else {
+                throw new Error(`Platform ${effectivePlatform} not supported for type_text`);
+            }
+            return wrapResponse(result);
+        }
+        if (name === "press_back") {
+            const { platform, deviceId } = (args || {});
+            const effectivePlatform = platform || "android";
+            if (effectivePlatform !== "android") {
+                throw new Error(`Platform ${effectivePlatform} not supported for press_back`);
+            }
+            const result = await androidInteract.pressBack(deviceId);
+            return wrapResponse(result);
+        }
     }
     catch (error) {
         return {

package/docs/CHANGELOG.md

@@ -2,12 +2,17 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
-## [0.6.0] - 2026-03-11
+## [0.7.0]
 
 ### Added
+- **`wait_for_element` tool**: Added ability to wait for a specific UI element to appear on screen. Polls `get_ui_tree` until timeout. Useful for waiting on app transitions or loading states.
 - **`get_current_screen` tool**: Added ability to determine the currently visible activity on an Android device using `dumpsys activity activities`. Includes robust regex parsing to handle various Android versions.
+- **`tap` tool**: Added ability to tap at specific screen coordinates on Android and iOS devices.
+- **`swipe` tool**: Added ability to simulate swipe gestures (scroll, drag) on Android devices.
+- **`type_text` tool**: Added ability to type text into focused input fields on Android devices.
+- **`press_back` tool**: Added ability to simulate the Android Back button.
 
-## [0.4.0] - 2026-03-09
+## [0.4.0]
 
 ### Added
 - **`terminate_app` tool**: Added ability to terminate apps on Android and iOS.

package/package.json

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

package/src/android/interact.ts

@@ -1,7 +1,92 @@
-import { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from "../types.js"
+import { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse, WaitForElementResponse, TapResponse, SwipeResponse, TypeTextResponse, PressBackResponse } from "../types.js"
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js"
+import { AndroidObserve } from "./observe.js"
 
 export class AndroidInteract {
+  private observe = new AndroidObserve();
+
+  async waitForElement(text: string, timeout: number, deviceId?: string): Promise<WaitForElementResponse> {
+    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: number, y: number, deviceId?: string): Promise<TapResponse> {
+    const metadata = await getAndroidDeviceMetadata("", deviceId)
+    const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
+
+    try {
+      await execAdb(['shell', 'input', 'tap', x.toString(), y.toString()], deviceId)
+      return { device: deviceInfo, success: true, x, y }
+    } catch (e) {
+      return { device: deviceInfo, success: false, x, y, error: e instanceof Error ? e.message : String(e) }
+    }
+  }
+
+  async swipe(x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string): Promise<SwipeResponse> {
+    const metadata = await getAndroidDeviceMetadata("", deviceId)
+    const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
+
+    try {
+      await execAdb(['shell', 'input', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString(), duration.toString()], deviceId)
+      return { device: deviceInfo, success: true, start: [x1, y1], end: [x2, y2], duration }
+    } catch (e) {
+      return { device: deviceInfo, success: false, start: [x1, y1], end: [x2, y2], duration, error: e instanceof Error ? e.message : String(e) }
+    }
+  }
+
+  async typeText(text: string, deviceId?: string): Promise<TypeTextResponse> {
+    const metadata = await getAndroidDeviceMetadata("", deviceId)
+    const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
+
+    try {
+      // Encode spaces as %s to ensure proper input handling by adb shell input text
+      const encodedText = text.replace(/\s/g, '%s')
+      // Note: 'input text' might fail with some characters or if keyboard isn't ready, but it's the standard ADB way.
+      await execAdb(['shell', 'input', 'text', encodedText], deviceId)
+      return { device: deviceInfo, success: true, text }
+    } catch (e) {
+      return { device: deviceInfo, success: false, text, error: e instanceof Error ? e.message : String(e) }
+    }
+  }
+
+  async pressBack(deviceId?: string): Promise<PressBackResponse> {
+    const metadata = await getAndroidDeviceMetadata("", deviceId)
+    const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
+
+    try {
+      await execAdb(['shell', 'input', 'keyevent', '4'], deviceId)
+      return { device: deviceInfo, success: true }
+    } catch (e) {
+      return { device: deviceInfo, success: false, error: e instanceof Error ? e.message : String(e) }
+    }
+  }
+
   async startApp(appId: string, deviceId?: string): Promise<StartAppResponse> {
     const metadata = await getAndroidDeviceMetadata(appId, deviceId)
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)

package/src/ios/interact.ts

@@ -1,8 +1,86 @@
 import { promises as fs } from "fs"
-import { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from "../types.js"
-import { execCommand, getIOSDeviceMetadata, validateBundleId } from "./utils.js"
+import { spawn } from "child_process"
+import { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse, WaitForElementResponse, TapResponse } from "../types.js"
+import { execCommand, getIOSDeviceMetadata, validateBundleId, IDB } from "./utils.js"
+import { iOSObserve } from "./observe.js"
 
 export class iOSInteract {
+  private observe = new iOSObserve();
+
+  async waitForElement(text: string, timeout: number, deviceId: string = "booted"): Promise<WaitForElementResponse> {
+    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: number, y: number, deviceId: string = "booted"): Promise<TapResponse> {
+    const device = await getIOSDeviceMetadata(deviceId)
+    
+    // Check for idb
+    const child = spawn(IDB, ['--version']);
+    const idbExists = await new Promise<boolean>((resolve) => {
+      child.on('error', () => resolve(false));
+      child.on('close', (code) => resolve(code === 0));
+    });
+
+    if (!idbExists) {
+        return {
+            device,
+            success: false,
+            x,
+            y,
+            error: "iOS tap requires 'idb' (iOS Device Bridge)."
+        }
+    }
+
+    try {
+      const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
+      const args = ['ui', 'tap', x.toString(), y.toString()];
+      if (targetUdid) {
+        args.push('--udid', targetUdid);
+      }
+
+      await new Promise<void>((resolve, reject) => {
+        const proc = spawn(IDB, args);
+        let stderr = '';
+        proc.stderr.on('data', d => stderr += d.toString());
+        proc.on('close', code => {
+            if (code === 0) resolve();
+            else reject(new Error(`idb ui tap failed: ${stderr}`));
+        });
+        proc.on('error', err => reject(err));
+      });
+
+      return { device, success: true, x, y };
+    } catch (e) {
+      return { device, success: false, x, y, error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
   async startApp(bundleId: string, deviceId: string = "booted"): Promise<StartAppResponse> {
     validateBundleId(bundleId)
     const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId)

package/src/server.ts

@@ -13,7 +13,12 @@ import {
   RestartAppResponse,
   ResetAppDataResponse,
   GetUITreeResponse,
-  GetCurrentScreenResponse
+  GetCurrentScreenResponse,
+  WaitForElementResponse,
+  TapResponse,
+  SwipeResponse,
+  TypeTextResponse,
+  PressBackResponse
 } from "./types.js"
 
 import { AndroidObserve } from "./android/observe.js"
@@ -29,7 +34,7 @@ const iosInteract = new iOSInteract()
 const server = new Server(
   {
     name: "mobile-debug-mcp",
-    version: "0.6.0"
+    version: "0.7.0"
   },
   {
     capabilities: {
@@ -212,6 +217,126 @@ 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: "tap",
+      description: "Simulate a finger tap on the device screen at specific coordinates.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          platform: {
+            type: "string",
+            enum: ["android", "ios"],
+            description: "Platform to tap on"
+          },
+          x: {
+            type: "number",
+            description: "X coordinate"
+          },
+          y: {
+            type: "number",
+            description: "Y coordinate"
+          },
+          deviceId: {
+            type: "string",
+            description: "Device Serial/UDID. Defaults to connected/booted device."
+          }
+        },
+        required: ["x", "y"]
+      }
+    },
+    {
+      name: "swipe",
+      description: "Simulate a swipe gesture on an Android device.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          platform: {
+            type: "string",
+            enum: ["android"],
+            description: "Platform to swipe on (currently only android supported)"
+          },
+          x1: { type: "number", description: "Start X coordinate" },
+          y1: { type: "number", description: "Start Y coordinate" },
+          x2: { type: "number", description: "End X coordinate" },
+          y2: { type: "number", description: "End Y coordinate" },
+          duration: { type: "number", description: "Duration in ms" },
+          deviceId: {
+            type: "string",
+            description: "Device Serial/UDID. Defaults to connected/booted device."
+          }
+        },
+        required: ["x1", "y1", "x2", "y2", "duration"]
+      }
+    },
+    {
+      name: "type_text",
+      description: "Type text into the currently focused input field on an Android device.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          platform: {
+            type: "string",
+            enum: ["android"],
+            description: "Platform to type on (currently only android supported)"
+          },
+          text: {
+            type: "string",
+            description: "The text to type"
+          },
+          deviceId: {
+            type: "string",
+            description: "Device Serial/UDID. Defaults to connected/booted device."
+          }
+        },
+        required: ["text"]
+      }
+    },
+    {
+      name: "press_back",
+      description: "Simulate pressing the Android Back button.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          platform: {
+            type: "string",
+            enum: ["android"],
+            description: "Platform (currently only android supported)"
+          },
+          deviceId: {
+            type: "string",
+            description: "Device Serial/UDID. Defaults to connected/booted device."
+          }
+        }
+      }
     }
   ]
 }))
@@ -444,6 +569,113 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const result = await androidObserve.getCurrentScreen(deviceId)
       return wrapResponse(result)
     }
+
+    if (name === "wait_for_element") {
+      const { platform, text, timeout, deviceId } = (args || {}) as {
+        platform: "android" | "ios"
+        text: string
+        timeout?: number
+        deviceId?: string
+      }
+      
+      const effectiveTimeout = timeout ?? 10000;
+      
+      let result: WaitForElementResponse;
+      if (platform === "android") {
+        result = await androidInteract.waitForElement(text, effectiveTimeout, deviceId)
+      } else {
+        result = await iosInteract.waitForElement(text, effectiveTimeout, deviceId)
+      }
+      return wrapResponse(result)
+    }
+
+    if (name === "tap") {
+      const { platform, x, y, deviceId } = (args || {}) as {
+        platform?: "android" | "ios"
+        x: number
+        y: number
+        deviceId?: string
+      }
+
+      const effectivePlatform = platform || "android";
+      
+      // Basic validation
+      if (typeof x !== 'number' || typeof y !== 'number') {
+        throw new Error("x and y coordinates are required and must be numbers");
+      }
+
+      let result: TapResponse;
+      if (effectivePlatform === "android") {
+        result = await androidInteract.tap(x, y, deviceId)
+      } else {
+        result = await iosInteract.tap(x, y, deviceId)
+      }
+      return wrapResponse(result)
+    }
+
+    if (name === "swipe") {
+      const { platform, x1, y1, x2, y2, duration, deviceId } = (args || {}) as {
+        platform?: "android"
+        x1: number
+        y1: number
+        x2: number
+        y2: number
+        duration: number
+        deviceId?: string
+      }
+
+      const effectivePlatform = platform || "android";
+      
+      if (typeof x1 !== 'number' || typeof y1 !== 'number' || typeof x2 !== 'number' || typeof y2 !== 'number' || typeof duration !== 'number') {
+        throw new Error("x1, y1, x2, y2, and duration are required and must be numbers");
+      }
+
+      let result: SwipeResponse;
+      if (effectivePlatform === "android") {
+        result = await androidInteract.swipe(x1, y1, x2, y2, duration, deviceId)
+      } else {
+        throw new Error(`Platform ${effectivePlatform} not supported for swipe`)
+      }
+      return wrapResponse(result)
+    }
+
+    if (name === "type_text") {
+      const { platform, text, deviceId } = (args || {}) as {
+        platform?: "android"
+        text: string
+        deviceId?: string
+      }
+
+      const effectivePlatform = platform || "android";
+      
+      if (typeof text !== 'string') {
+        throw new Error("text is required and must be a string");
+      }
+
+      let result: TypeTextResponse;
+      if (effectivePlatform === "android") {
+        result = await androidInteract.typeText(text, deviceId)
+      } else {
+        throw new Error(`Platform ${effectivePlatform} not supported for type_text`)
+      }
+      return wrapResponse(result)
+    }
+
+    if (name === "press_back") {
+      const { platform, deviceId } = (args || {}) as {
+        platform?: "android"
+        deviceId?: string
+      }
+      
+      const effectivePlatform = platform || "android";
+      
+      if (effectivePlatform !== "android") {
+        throw new Error(`Platform ${effectivePlatform} not supported for press_back`)
+      }
+
+      const result = await androidInteract.pressBack(deviceId)
+      return wrapResponse(result)
+    }
   } catch (error) {
     return {
       content: [{ type: "text", text: `Error executing tool ${name}: ${error instanceof Error ? error.message : String(error)}` }]

package/src/types.ts

@@ -90,3 +90,40 @@ export interface GetCurrentScreenResponse {
   shortActivity: string;
   error?: string;
 }
+
+export interface WaitForElementResponse {
+  device: DeviceInfo;
+  found: boolean;
+  element?: UIElement;
+  error?: string;
+}
+
+export interface TapResponse {
+  device: DeviceInfo;
+  success: boolean;
+  x: number;
+  y: number;
+  error?: string;
+}
+
+export interface SwipeResponse {
+  device: DeviceInfo;
+  success: boolean;
+  start: [number, number];
+  end: [number, number];
+  duration: number;
+  error?: string;
+}
+
+export interface TypeTextResponse {
+  device: DeviceInfo;
+  success: boolean;
+  text: string;
+  error?: string;
+}
+
+export interface PressBackResponse {
+  device: DeviceInfo;
+  success: boolean;
+  error?: string;
+}

package/test/run-real-test.js

@@ -0,0 +1,24 @@
+// This script wraps the real test execution for ease of use
+// It sets ADB_PATH and invokes the test file
+import { spawn } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ADB_PATH = process.env.ADB_PATH || process.env.ADB || 'adb';
+const TEST_FILE = path.join(__dirname, 'wait_for_element_real.js');
+
+// Merge ADB_PATH into the child environment if provided
+const childEnv = { ...process.env, ADB_PATH };
+
+// Use NODE to execute the JS test by default, or respect RUNNER env if set (e.g., 'npx tsx')
+const runner = process.env.RUNNER || 'node';
+const runnerArgs = [TEST_FILE];
+
+const child = spawn(runner, runnerArgs, {
+    env: childEnv,
+    stdio: 'inherit'
+});
+child.on('exit', (code) => {
+    process.exit(code || 0);
+});

package/test/wait_for_element_mock.js

@@ -0,0 +1,113 @@
+import { AndroidInteract } from "../src/android/interact.js";
+import { AndroidObserve } from "../src/android/observe.js";
+// Mock the observe method
+// We need to override the prototype method directly
+// Since we are using ES modules, we need to handle the import correctly or just override the instance method if possible.
+// But getUITree is an instance method on AndroidObserve, which AndroidInteract instantiates internally.
+// We can override the prototype of AndroidObserve to affect all instances.
+const originalGetUITree = AndroidObserve.prototype.getUITree;
+async function runTests() {
+    console.log("Starting tests for wait_for_element...");
+    const interact = new AndroidInteract();
+    // ---------------------------------------------------------
+    // Test 1: Element found immediately
+    // ---------------------------------------------------------
+    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");
+    // ---------------------------------------------------------
+    // Test 2: Element not found (timeout)
+    // ---------------------------------------------------------
+    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();
+    // Use a short timeout for test speed, but long enough to sleep at least once
+    const result2 = await interact.waitForElement("Target", 1200);
+    const elapsed2 = Date.now() - start2;
+    console.log("Result:", result2.found === false ? "PASS" : "FAIL");
+    // Should wait at least 1200ms
+    console.log("Elapsed time (should be >= 1200ms):", elapsed2, elapsed2 >= 1200 ? "PASS" : "FAIL");
+    // ---------------------------------------------------------
+    // Test 3: Element found after polling
+    // ---------------------------------------------------------
+    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");
+    // Expected calls: 0ms (fail), 500ms (fail), 1000ms (success). Elapsed should be >= 1000ms.
+    console.log("Elapsed time (should be >= 1000ms):", elapsed3, elapsed3 >= 1000 ? "PASS" : "FAIL");
+    // ---------------------------------------------------------
+    // Test 4: Error handling (fast failure)
+    // ---------------------------------------------------------
+    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);
+    // Should fail fast, not wait for timeout
+    console.log("Elapsed time (should be < 500ms):", elapsed4, elapsed4 < 500 ? "PASS" : "FAIL");
+    // Restore original
+    AndroidObserve.prototype.getUITree = originalGetUITree;
+}
+runTests().catch(console.error);

package/test/wait_for_element_real.js

@@ -0,0 +1,67 @@
+import { AndroidInteract } from "../src/android/interact.js";
+import { AndroidObserve } from "../src/android/observe.js";
+// Configure ADB path and target via env vars or CLI args.
+// Usage: node test/wait_for_element_real.js [deviceId] [appId]
+// Priority: CLI args > environment variables
+const args = process.argv.slice(2);
+const DEVICE_ID = args[0] || process.env.DEVICE_ID;
+const APP_ID = args[1] || process.env.APP_ID;
+
+// Do not hard-code ADB_PATH here. If the user supplied ADB_PATH in the environment, leave it as-is.
+// (process.env.ADB_PATH may be set externally before running this script.)
+
+if (!DEVICE_ID || !APP_ID) {
+  console.error("Usage: node test/wait_for_element_real.js <deviceId> <appId> or set DEVICE_ID and APP_ID env vars");
+  process.exit(1);
+}
+async function runRealTest() {
+    console.log(`Connecting to device ${DEVICE_ID}...`);
+    const interact = new AndroidInteract();
+    const observe = new AndroidObserve();
+    try {
+        // 1. Start App
+        console.log(`\nStarting app ${APP_ID}...`);
+        await interact.startApp(APP_ID, DEVICE_ID);
+        // Give it a moment to render
+        console.log("Waiting 3s for app to render...");
+        await new Promise(r => setTimeout(r, 3000));
+        // 2. Get UI Tree to find a valid text target
+        console.log("\nFetching UI Tree to find a target text...");
+        const tree = await observe.getUITree(DEVICE_ID);
+        if (tree.error) {
+            console.error("Failed to get UI Tree:", tree.error);
+            return;
+        }
+        // Find first visible element with text
+        const targetElement = tree.elements.find(e => e.text && e.text.length > 0 && e.visible);
+        if (!targetElement || !targetElement.text) {
+            console.warn("No visible text elements found on screen to test with.");
+            console.log("Elements found:", tree.elements.length);
+            return;
+        }
+        const targetText = targetElement.text;
+        console.log(`Found target element: "${targetText}"`);
+        // 3. Test waitForElement (Success Case)
+        console.log(`\nTest 1: Waiting for existing element "${targetText}" (should succeed)...`);
+        const start1 = Date.now();
+        const result1 = await interact.waitForElement(targetText, 5000, DEVICE_ID);
+        const elapsed1 = Date.now() - start1;
+        console.log(`Result: ${result1.found ? "PASS" : "FAIL"}`);
+        console.log(`Found Element: ${result1.element?.text}`);
+        console.log(`Time taken: ${elapsed1}ms`);
+        // 4. Test waitForElement (Timeout Case)
+        const missingText = "THIS_TEXT_SHOULD_NOT_EXIST_XYZ_123";
+        console.log(`\nTest 2: Waiting for missing element "${missingText}" (should timeout)...`);
+        const start2 = Date.now();
+        // Use short timeout 2s
+        const result2 = await interact.waitForElement(missingText, 2000, DEVICE_ID);
+        const elapsed2 = Date.now() - start2;
+        console.log(`Result: ${!result2.found ? "PASS" : "FAIL"}`);
+        console.log(`Found: ${result2.found}`);
+        console.log(`Time taken: ${elapsed2}ms (expected ~2000ms)`);
+    }
+    catch (error) {
+        console.error("Test failed with error:", error);
+    }
+}
+runRealTest();