mobile-debug-mcp 0.6.0 → 0.8.0

package/dist/server.js

@@ -6,13 +6,16 @@ import { AndroidObserve } from "./android/observe.js";
 import { AndroidInteract } from "./android/interact.js";
 import { iOSObserve } from "./ios/observe.js";
 import { iOSInteract } from "./ios/interact.js";
+import { resolveTargetDevice, listDevices } from "./resolve-device.js";
+import { startAndroidLogStream, readLogStreamLines, stopAndroidLogStream } from "./android/utils.js";
+import { startIOSLogStream, readIOSLogStreamLines, stopIOSLogStream } from "./ios/utils.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.6.0"
+    version: "0.7.0"
 }, {
     capabilities: {
         tools: {}
@@ -116,6 +119,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["platform", "appId"]
             }
         },
+        {
+            name: "install_app",
+            description: "Install an app on Android (apk) or iOS simulator/device (ipa/.app).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: { type: "string", enum: ["android", "ios"] },
+                    appPath: { type: "string", description: "Path to APK (Android) or .app/.ipa (iOS) on the host machine" },
+                    deviceId: { type: "string", description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected." }
+                },
+                required: ["platform", "appPath"]
+            }
+        },
         {
             name: "get_logs",
             description: "Get recent logs from Android or iOS simulator. Returns device metadata and the log output.",
@@ -142,6 +158,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["platform"]
             }
         },
+        {
+            name: "list_devices",
+            description: "List connected devices and their metadata (android + ios).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: { type: "string", enum: ["android", "ios"] }
+                }
+            }
+        },
         {
             name: "capture_screenshot",
             description: "Capture a screenshot from an Android device or iOS simulator. Returns device metadata and the screenshot image.",
@@ -160,6 +186,41 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["platform"]
             }
         },
+        {
+            name: "start_log_stream",
+            description: "Start streaming logs for a target application on Android or iOS. For Android this uses adb logcat --pid=<pid>; for iOS it streams `xcrun simctl spawn <device> log stream` with a predicate.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: { type: "string", enum: ["android", "ios"], default: "android" },
+                    packageName: { type: "string", description: "Android package name or iOS bundle id" },
+                    level: { type: "string", enum: ["error", "warn", "info", "debug"], default: "error" },
+                    deviceId: { type: "string", description: "Device Serial (Android) or UDID (iOS). Defaults to connected/booted device." },
+                    sessionId: { type: "string", description: "Session identifier for the log stream" }
+                },
+                required: ["packageName"]
+            }
+        },
+        {
+            name: "read_log_stream",
+            description: "Read accumulated log stream entries for the active session.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    sessionId: { type: "string" }
+                }
+            }
+        },
+        {
+            name: "stop_log_stream",
+            description: "Stop an active log stream for the session.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    sessionId: { type: "string" }
+                }
+            }
+        },
         {
             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.",
@@ -191,6 +252,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."
+                    }
+                }
+            }
         }
     ]
 }));
@@ -203,13 +384,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let launchTimeMs;
             let deviceInfo;
             if (platform === "android") {
-                const result = await androidInteract.startApp(appId, deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+                const result = await androidInteract.startApp(appId, resolved.id);
                 appStarted = result.appStarted;
                 launchTimeMs = result.launchTimeMs;
                 deviceInfo = result.device;
             }
             else {
-                const result = await iosInteract.startApp(appId, deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+                const result = await iosInteract.startApp(appId, resolved.id);
                 appStarted = result.appStarted;
                 launchTimeMs = result.launchTimeMs;
                 deviceInfo = result.device;
@@ -226,12 +409,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let appTerminated;
             let deviceInfo;
             if (platform === "android") {
-                const result = await androidInteract.terminateApp(appId, deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+                const result = await androidInteract.terminateApp(appId, resolved.id);
                 appTerminated = result.appTerminated;
                 deviceInfo = result.device;
             }
             else {
-                const result = await iosInteract.terminateApp(appId, deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+                const result = await iosInteract.terminateApp(appId, resolved.id);
                 appTerminated = result.appTerminated;
                 deviceInfo = result.device;
             }
@@ -247,13 +432,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let launchTimeMs;
             let deviceInfo;
             if (platform === "android") {
-                const result = await androidInteract.restartApp(appId, deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+                const result = await androidInteract.restartApp(appId, resolved.id);
                 appRestarted = result.appRestarted;
                 launchTimeMs = result.launchTimeMs;
                 deviceInfo = result.device;
             }
             else {
-                const result = await iosInteract.restartApp(appId, deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+                const result = await iosInteract.restartApp(appId, resolved.id);
                 appRestarted = result.appRestarted;
                 launchTimeMs = result.launchTimeMs;
                 deviceInfo = result.device;
@@ -270,12 +457,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let dataCleared;
             let deviceInfo;
             if (platform === "android") {
-                const result = await androidInteract.resetAppData(appId, deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+                const result = await androidInteract.resetAppData(appId, resolved.id);
                 dataCleared = result.dataCleared;
                 deviceInfo = result.device;
             }
             else {
-                const result = await iosInteract.resetAppData(appId, deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+                const result = await iosInteract.resetAppData(appId, resolved.id);
                 dataCleared = result.dataCleared;
                 deviceInfo = result.device;
             }
@@ -285,18 +474,51 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
             return wrapResponse(response);
         }
+        if (name === "install_app") {
+            const { platform, appPath, deviceId } = args;
+            let installed;
+            let output;
+            let deviceInfo;
+            let errorMsg;
+            if (platform === "android") {
+                const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+                const result = await androidInteract.installApp(appPath, resolved.id);
+                installed = result.installed;
+                output = result.output;
+                deviceInfo = result.device;
+                errorMsg = result.error;
+            }
+            else {
+                const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
+                const result = await iosInteract.installApp(appPath, resolved.id);
+                installed = result.installed;
+                output = result.output;
+                deviceInfo = result.device;
+                errorMsg = result.error;
+            }
+            const response = {
+                device: deviceInfo,
+                installed,
+                output,
+                error: errorMsg
+            };
+            return wrapResponse(response);
+        }
         if (name === "get_logs") {
             const { platform, appId, deviceId, lines } = args;
             let logs;
             let deviceInfo;
             if (platform === "android") {
-                deviceInfo = await androidObserve.getDeviceMetadata(appId || "", deviceId);
-                const response = await androidObserve.getLogs(appId, lines ?? 200, deviceId);
+                // Resolve an explicit target device when multiple are attached
+                const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+                deviceInfo = resolved;
+                const response = await androidObserve.getLogs(appId, lines ?? 200, resolved.id);
                 logs = Array.isArray(response.logs) ? response.logs : [];
             }
             else {
-                deviceInfo = await iosObserve.getDeviceMetadata(deviceId);
-                const response = await iosObserve.getLogs(appId, deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+                deviceInfo = resolved;
+                const response = await iosObserve.getLogs(appId, resolved.id);
                 logs = Array.isArray(response.logs) ? response.logs : [];
             }
             // Filter crash lines (e.g. lines containing 'FATAL EXCEPTION') for internal or AI use
@@ -321,20 +543,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ]
             };
         }
+        if (name === "list_devices") {
+            const { platform, appId } = (args || {});
+            const devices = await listDevices(platform, appId);
+            return wrapResponse({ devices });
+        }
         if (name === "capture_screenshot") {
             const { platform, deviceId } = args;
             let screenshot;
             let resolution;
             let deviceInfo;
             if (platform === "android") {
-                deviceInfo = await androidObserve.getDeviceMetadata("", deviceId);
-                const result = await androidObserve.captureScreen(deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+                deviceInfo = resolved;
+                const result = await androidObserve.captureScreen(resolved.id);
                 screenshot = result.screenshot;
                 resolution = result.resolution;
             }
             else {
-                deviceInfo = await iosObserve.getDeviceMetadata(deviceId);
-                const result = await iosObserve.captureScreenshot(deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
+                deviceInfo = resolved;
+                const result = await iosObserve.captureScreenshot(resolved.id);
                 screenshot = result.screenshot;
                 resolution = result.resolution;
             }
@@ -361,10 +590,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { platform, deviceId } = args;
             let result;
             if (platform === "android") {
-                result = await androidObserve.getUITree(deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+                result = await androidObserve.getUITree(resolved.id);
             }
             else if (platform === "ios") {
-                result = await iosObserve.getUITree(deviceId);
+                const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
+                result = await iosObserve.getUITree(resolved.id);
             }
             else {
                 throw new Error(`Platform ${platform} not supported for get_ui_tree`);
@@ -373,9 +604,125 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         if (name === "get_current_screen") {
             const { deviceId } = (args || {});
-            const result = await androidObserve.getCurrentScreen(deviceId);
+            const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+            const result = await androidObserve.getCurrentScreen(resolved.id);
+            return wrapResponse(result);
+        }
+        if (name === "wait_for_element") {
+            const { platform, text, timeout, deviceId } = (args || {});
+            const effectiveTimeout = timeout ?? 10000;
+            let result;
+            if (platform === "android") {
+                const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+                result = await androidInteract.waitForElement(text, effectiveTimeout, resolved.id);
+            }
+            else {
+                const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
+                result = await iosInteract.waitForElement(text, effectiveTimeout, resolved.id);
+            }
+            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") {
+                const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+                result = await androidInteract.tap(x, y, resolved.id);
+            }
+            else {
+                const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
+                result = await iosInteract.tap(x, y, resolved.id);
+            }
+            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") {
+                const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+                result = await androidInteract.swipe(x1, y1, x2, y2, duration, resolved.id);
+            }
+            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") {
+                const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+                result = await androidInteract.typeText(text, resolved.id);
+            }
+            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 resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+            const result = await androidInteract.pressBack(resolved.id);
+            return wrapResponse(result);
+        }
+        if (name === 'start_log_stream') {
+            const { platform, packageName, level, sessionId: argSession, deviceId } = args;
+            const sessionId = argSession || 'default';
+            const effectivePlatform = platform || 'android';
+            if (effectivePlatform === 'android') {
+                const resolved = await resolveTargetDevice({ platform: 'android', appId: packageName, deviceId });
+                const res = await startAndroidLogStream(packageName, level || 'error', resolved.id, sessionId);
+                return wrapResponse(res);
+            }
+            else {
+                const resolved = await resolveTargetDevice({ platform: 'ios', appId: packageName, deviceId });
+                const res = await startIOSLogStream(packageName, level || 'error', resolved.id, sessionId);
+                return wrapResponse(res);
+            }
+        }
+        if (name === 'read_log_stream') {
+            const { platform, sessionId: argSession, limit, since } = (args || {});
+            const sid = argSession || 'default';
+            const effectivePlatform = platform || 'android';
+            if (effectivePlatform === 'android') {
+                const { entries, crash_summary } = await readLogStreamLines(sid, limit ?? 100, since);
+                return wrapResponse({ entries, crash_summary });
+            }
+            else {
+                const { entries, crash_summary } = await readIOSLogStreamLines(sid, limit ?? 100, since);
+                return wrapResponse({ entries, crash_summary });
+            }
+        }
+        if (name === 'stop_log_stream') {
+            const { platform, sessionId: argSession } = (args || {});
+            const sid = argSession || 'default';
+            const effectivePlatform = platform || 'android';
+            if (effectivePlatform === 'android') {
+                const res = await stopAndroidLogStream(sid);
+                return wrapResponse(res);
+            }
+            else {
+                const res = await stopIOSLogStream(sid);
+                return wrapResponse(res);
+            }
+        }
     }
     catch (error) {
         return {

package/docs/CHANGELOG.md

@@ -2,12 +2,27 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
-## [0.6.0] - 2026-03-11
+## [0.8.0]
 
 ### Added
+- **`list_devices` tool**: enumerate connected Android devices and iOS simulators. Returns device metadata (id, platform, osVersion, model, simulator, appInstalled).
+- **`install_app` tool**: install an APK (.apk) on Android or an app bundle (.app/.ipa) on iOS simulators/devices. Uses `adb install -r` for Android and `simctl`/`idb` for iOS.
+- **`start_log_stream`, `read_log_stream`, `stop_log_stream` tools**: stream Android logcat filtered by application PID, poll parsed entries, support incremental reads (limit/since) and basic crash detection metadata (crash_detected, exception, sample).
+
+### Changed
+- Device-selection: server handlers now use a central resolver to pick a sensible default device when `deviceId` is omitted. This reduces duplication and makes behavior deterministic when multiple devices are attached.
+
+## [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.8.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
@@ -9,7 +9,10 @@
   "scripts": {
     "build": "tsc",
     "start": "node ./dist/server.js",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "test:unit": "tsx test/unit/index.ts",
+    "test:integration": "tsx test/integration/index.ts",
+    "test": "npm run test:unit && npm run test:integration"
   },
   "engines": {
     "node": ">=18"
@@ -21,6 +24,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.4.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }
 }