mobile-debug-mcp 0.5.0 → 0.7.0

package/dist/server.js

@@ -2,11 +2,17 @@
 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 { startAndroidApp, getAndroidLogs, captureAndroidScreen, getAndroidDeviceMetadata, terminateAndroidApp, restartAndroidApp, resetAndroidAppData } from "./android.js";
-import { startIOSApp, getIOSLogs, captureIOSScreenshot, getIOSDeviceMetadata, terminateIOSApp, restartIOSApp, resetIOSAppData } from "./ios.js";
+import { AndroidObserve } from "./android/observe.js";
+import { AndroidInteract } from "./android/interact.js";
+import { iOSObserve } from "./ios/observe.js";
+import { iOSInteract } from "./ios/interact.js";
+const androidObserve = new AndroidObserve();
+const androidInteract = new AndroidInteract();
+const iosObserve = new iOSObserve();
+const iosInteract = new iOSInteract();
 const server = new Server({
     name: "mobile-debug-mcp",
-    version: "0.4.0"
+    version: "0.7.0"
 }, {
     capabilities: {
         tools: {}
@@ -153,6 +159,158 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ["platform"]
             }
+        },
+        {
+            name: "get_ui_tree",
+            description: "Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: {
+                        type: "string",
+                        enum: ["android", "ios"],
+                        description: "Platform to get UI tree for"
+                    },
+                    deviceId: {
+                        type: "string",
+                        description: "Device Serial (Android) or UDID (iOS). Defaults to connected/booted device."
+                    }
+                },
+                required: ["platform"]
+            }
+        },
+        {
+            name: "get_current_screen",
+            description: "Get the currently visible activity on an Android device. Returns package and activity name.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    deviceId: {
+                        type: "string",
+                        description: "Device Serial (Android). Defaults to connected/booted device."
+                    }
+                }
+            }
+        },
+        {
+            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."
+                    }
+                }
+            }
         }
     ]
 }));
@@ -165,16 +323,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let launchTimeMs;
             let deviceInfo;
             if (platform === "android") {
-                const result = await startAndroidApp(appId, deviceId);
+                const result = await androidInteract.startApp(appId, deviceId);
                 appStarted = result.appStarted;
                 launchTimeMs = result.launchTimeMs;
-                deviceInfo = await getAndroidDeviceMetadata(appId, deviceId);
+                deviceInfo = result.device;
             }
             else {
-                const result = await startIOSApp(appId, deviceId);
+                const result = await iosInteract.startApp(appId, deviceId);
                 appStarted = result.appStarted;
                 launchTimeMs = result.launchTimeMs;
-                deviceInfo = await getIOSDeviceMetadata(deviceId);
+                deviceInfo = result.device;
             }
             const response = {
                 device: deviceInfo,
@@ -188,14 +346,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let appTerminated;
             let deviceInfo;
             if (platform === "android") {
-                const result = await terminateAndroidApp(appId, deviceId);
+                const result = await androidInteract.terminateApp(appId, deviceId);
                 appTerminated = result.appTerminated;
-                deviceInfo = await getAndroidDeviceMetadata(appId, deviceId);
+                deviceInfo = result.device;
             }
             else {
-                const result = await terminateIOSApp(appId, deviceId);
+                const result = await iosInteract.terminateApp(appId, deviceId);
                 appTerminated = result.appTerminated;
-                deviceInfo = await getIOSDeviceMetadata(deviceId);
+                deviceInfo = result.device;
             }
             const response = {
                 device: deviceInfo,
@@ -209,16 +367,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let launchTimeMs;
             let deviceInfo;
             if (platform === "android") {
-                const result = await restartAndroidApp(appId, deviceId);
+                const result = await androidInteract.restartApp(appId, deviceId);
                 appRestarted = result.appRestarted;
                 launchTimeMs = result.launchTimeMs;
-                deviceInfo = await getAndroidDeviceMetadata(appId, deviceId);
+                deviceInfo = result.device;
             }
             else {
-                const result = await restartIOSApp(appId, deviceId);
+                const result = await iosInteract.restartApp(appId, deviceId);
                 appRestarted = result.appRestarted;
                 launchTimeMs = result.launchTimeMs;
-                deviceInfo = await getIOSDeviceMetadata(deviceId);
+                deviceInfo = result.device;
             }
             const response = {
                 device: deviceInfo,
@@ -232,14 +390,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let dataCleared;
             let deviceInfo;
             if (platform === "android") {
-                const result = await resetAndroidAppData(appId, deviceId);
+                const result = await androidInteract.resetAppData(appId, deviceId);
                 dataCleared = result.dataCleared;
-                deviceInfo = await getAndroidDeviceMetadata(appId, deviceId);
+                deviceInfo = result.device;
             }
             else {
-                const result = await resetIOSAppData(appId, deviceId);
+                const result = await iosInteract.resetAppData(appId, deviceId);
                 dataCleared = result.dataCleared;
-                deviceInfo = await getIOSDeviceMetadata(deviceId);
+                deviceInfo = result.device;
             }
             const response = {
                 device: deviceInfo,
@@ -252,13 +410,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let logs;
             let deviceInfo;
             if (platform === "android") {
-                deviceInfo = await getAndroidDeviceMetadata(appId || "", deviceId);
-                const response = await getAndroidLogs(appId, lines ?? 200, deviceId);
+                deviceInfo = await androidObserve.getDeviceMetadata(appId || "", deviceId);
+                const response = await androidObserve.getLogs(appId, lines ?? 200, deviceId);
                 logs = Array.isArray(response.logs) ? response.logs : [];
             }
             else {
-                deviceInfo = await getIOSDeviceMetadata(deviceId);
-                const response = await getIOSLogs(appId, deviceId);
+                deviceInfo = await iosObserve.getDeviceMetadata(deviceId);
+                const response = await iosObserve.getLogs(appId, deviceId);
                 logs = Array.isArray(response.logs) ? response.logs : [];
             }
             // Filter crash lines (e.g. lines containing 'FATAL EXCEPTION') for internal or AI use
@@ -289,14 +447,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let resolution;
             let deviceInfo;
             if (platform === "android") {
-                deviceInfo = await getAndroidDeviceMetadata("", deviceId);
-                const result = await captureAndroidScreen(deviceId);
+                deviceInfo = await androidObserve.getDeviceMetadata("", deviceId);
+                const result = await androidObserve.captureScreen(deviceId);
                 screenshot = result.screenshot;
                 resolution = result.resolution;
             }
             else {
-                deviceInfo = await getIOSDeviceMetadata(deviceId);
-                const result = await captureIOSScreenshot(deviceId);
+                deviceInfo = await iosObserve.getDeviceMetadata(deviceId);
+                const result = await iosObserve.captureScreenshot(deviceId);
                 screenshot = result.screenshot;
                 resolution = result.resolution;
             }
@@ -319,6 +477,92 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ]
             };
         }
+        if (name === "get_ui_tree") {
+            const { platform, deviceId } = args;
+            let result;
+            if (platform === "android") {
+                result = await androidObserve.getUITree(deviceId);
+            }
+            else if (platform === "ios") {
+                result = await iosObserve.getUITree(deviceId);
+            }
+            else {
+                throw new Error(`Platform ${platform} not supported for get_ui_tree`);
+            }
+            return wrapResponse(result);
+        }
+        if (name === "get_current_screen") {
+            const { deviceId } = (args || {});
+            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,7 +2,17 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
-## [0.4.0] - 2026-03-09
+## [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]
 
 ### 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.5.0",
+  "version": "0.7.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "fast-xml-parser": "^5.5.1",
     "zod": "^3.22.4"
   },
   "devDependencies": {

package/smoke-test.ts

@@ -1,8 +1,15 @@
-import { startAndroidApp, terminateAndroidApp, captureAndroidScreen, getAndroidLogs } from "./src/android.js";
-import { startIOSApp, terminateIOSApp, captureIOSScreenshot, getIOSLogs } from "./src/ios.js";
+import { AndroidObserve } from "./src/android/observe.js";
+import { AndroidInteract } from "./src/android/interact.js";
+import { iOSObserve } from "./src/ios/observe.js";
+import { iOSInteract } from "./src/ios/interact.js";
 import fs from "fs/promises";
 import path from "path";
 
+const androidObserve = new AndroidObserve();
+const androidInteract = new AndroidInteract();
+const iosObserve = new iOSObserve();
+const iosInteract = new iOSInteract();
+
 async function main() {
   const args = process.argv.slice(2);
   const platform = args[0] as string; // Cast to string first
@@ -22,11 +29,11 @@ async function main() {
     let launchTimeMs: number;
 
     if (platform === "android") {
-      const result = await startAndroidApp(appId);
+      const result = await androidInteract.startApp(appId);
       startResult = result.appStarted;
       launchTimeMs = result.launchTimeMs;
     } else {
-      const result = await startIOSApp(appId);
+      const result = await iosInteract.startApp(appId);
       startResult = result.appStarted;
       launchTimeMs = result.launchTimeMs;
     }
@@ -47,11 +54,11 @@ async function main() {
     let resolution: { width: number; height: number };
 
     if (platform === "android") {
-      const result = await captureAndroidScreen();
+      const result = await androidObserve.captureScreen();
       screenshotBase64 = result.screenshot;
       resolution = result.resolution;
     } else {
-      const result = await captureIOSScreenshot();
+      const result = await iosObserve.captureScreenshot();
       screenshotBase64 = result.screenshot;
       resolution = result.resolution;
     }
@@ -70,11 +77,11 @@ async function main() {
     let logs: string[] = [];
 
     if (platform === "android") {
-       const result = await getAndroidLogs(appId, 50);
+       const result = await androidObserve.getLogs(appId, 50);
        logsCount = result.logCount;
        logs = result.logs;
     } else {
-       const result = await getIOSLogs();
+       const result = await iosObserve.getLogs(appId);
        logsCount = result.logCount;
        logs = result.logs;
     }
@@ -90,10 +97,10 @@ async function main() {
     let termResult: boolean;
     
     if (platform === "android") {
-      const result = await terminateAndroidApp(appId);
+      const result = await androidInteract.terminateApp(appId);
       termResult = result.appTerminated;
     } else {
-      const result = await terminateIOSApp(appId);
+      const result = await iosInteract.terminateApp(appId);
       termResult = result.appTerminated;
     }
 

package/src/android/interact.ts

@@ -0,0 +1,126 @@
+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)
+    
+    await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId)
+    
+    return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 }
+  }
+
+  async terminateApp(appId: string, deviceId?: string): Promise<TerminateAppResponse> {
+    const metadata = await getAndroidDeviceMetadata(appId, deviceId)
+    const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
+
+    await execAdb(['shell', 'am', 'force-stop', appId], deviceId)
+    
+    return { device: deviceInfo, appTerminated: true }
+  }
+
+  async restartApp(appId: string, deviceId?: string): Promise<RestartAppResponse> {
+    await this.terminateApp(appId, deviceId)
+    const startResult = await this.startApp(appId, deviceId)
+    return {
+      device: startResult.device,
+      appRestarted: startResult.appStarted,
+      launchTimeMs: startResult.launchTimeMs
+    }
+  }
+
+  async resetAppData(appId: string, deviceId?: string): Promise<ResetAppDataResponse> {
+    const metadata = await getAndroidDeviceMetadata(appId, deviceId)
+    const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
+
+    const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId)
+    
+    return { device: deviceInfo, dataCleared: output === 'Success' }
+  }
+}