mobile-debug-mcp 0.5.0 → 0.6.0

package/README.md

@@ -26,6 +26,7 @@ This server is designed with security in mind, using strict argument handling to
 - Node.js >= 18
 - Android SDK (`adb` in PATH) for Android support
 - Xcode command-line tools (`xcrun simctl`) for iOS support
+- **iOS Device Bridge (`idb`)** for iOS UI tree support
 - Booted iOS simulator for iOS testing
 
 ---
@@ -34,7 +35,18 @@ This server is designed with security in mind, using strict argument handling to
 
 You can install and use **Mobile Debug MCP** in one of two ways:
 
-### 1. Clone the repository for local development
+### 1. Install Dependencies
+
+**iOS Prerequisite (`idb`):**
+To use the `get_ui_tree` tool on iOS, you must install Facebook's `idb`:
+
+```bash
+brew tap facebook/fb
+brew install idb-companion
+pip3 install fb-idb
+```
+
+### 2. Clone the repository for local development
 
 ```bash
 git clone https://github.com/YOUR_USERNAME/mobile-debug-mcp.git
@@ -45,7 +57,7 @@ npm run build
 
 This option is suitable if you want to modify or contribute to the code.
 
-### 2. Install via npm for standard use
+### 3. Install via npm for standard use
 
 ```bash
 npm install -g mobile-debug-mcp
@@ -55,27 +67,7 @@ This option installs the package globally for easy use without cloning the repo.
 
 ---
 
-## Testing
-33. 
-34. The repository includes a smoke test script to verify end-to-end functionality on real devices or simulators.
-35. 
-36. ```bash
-37. # Run smoke test for Android
-38. npx tsx smoke-test.ts android com.example.package
-39. 
-40. # Run smoke test for iOS
-41. npx tsx smoke-test.ts ios com.example.bundleid
-42. ```
-43. 
-44. The smoke test performs the following sequence:
-45. 1. Starts the app
-46. 2. Captures a screenshot
-47. 3. Fetches logs
-48. 4. Terminates the app
-49. 
-50. ---
-51. 
-52. ## MCP Server Configuration
+## MCP Server Configuration
 
 Example WebUI MCP config using `npx --yes` and environment variables:
 
@@ -110,7 +102,7 @@ All tools accept a JSON input payload and return a structured JSON response. **E
 Launch a mobile app.
 
 **Input:**
-```json
+```jsonc
 {
   "platform": "android" | "ios",
   "appId": "com.example.app", // Android package or iOS bundle ID (Required)
@@ -131,7 +123,7 @@ Launch a mobile app.
 Fetch recent logs from the app or device.
 
 **Input:**
-```json
+```jsonc
 {
   "platform": "android" | "ios",
   "appId": "com.example.app", // Optional: filter logs by app
@@ -155,7 +147,7 @@ Returns two content blocks:
 Capture a screenshot of the current device screen.
 
 **Input:**
-```json
+```jsonc
 {
   "platform": "android" | "ios",
   "deviceId": "emulator-5554" // Optional: target specific device
@@ -177,7 +169,7 @@ Returns two content blocks:
 Terminate a running app.
 
 **Input:**
-```json
+```jsonc
 {
   "platform": "android" | "ios",
   "appId": "com.example.app", // Android package or iOS bundle ID (Required)
@@ -197,7 +189,7 @@ Terminate a running app.
 Restart an app (terminate then launch).
 
 **Input:**
-```json
+```jsonc
 {
   "platform": "android" | "ios",
   "appId": "com.example.app", // Android package or iOS bundle ID (Required)
@@ -218,7 +210,7 @@ Restart an app (terminate then launch).
 Clear app storage (reset to fresh install state).
 
 **Input:**
-```json
+```jsonc
 {
   "platform": "android" | "ios",
   "appId": "com.example.app", // Android package or iOS bundle ID (Required)
@@ -234,6 +226,62 @@ Clear app storage (reset to fresh install state).
 }
 ```
 
+### get_ui_tree
+Get the current UI hierarchy from the device. Returns a structured JSON representation of the screen content.
+
+**Input:**
+```jsonc
+{
+  "platform": "android" | "ios",
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "screen": "",
+  "resolution": { "width": 1080, "height": 1920 },
+  "elements": [
+    {
+      "text": "Login",
+      "contentDescription": null,
+      "type": "android.widget.Button",
+      "resourceId": "com.example:id/login_button",
+      "clickable": true,
+      "enabled": true,
+      "visible": true,
+      "bounds": [120,400,280,450],
+      "center": [200, 425],
+      "depth": 1,
+      "parentId": 0,
+      "children": []
+    }
+  ]
+}
+```
+
+### get_current_screen
+Get the currently visible activity on an Android device.
+
+**Input:**
+```jsonc
+{
+  "deviceId": "emulator-5554" // Optional: target specific device
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "package": "com.example.app",
+  "activity": "com.example.app.LoginActivity",
+  "shortActivity": "LoginActivity"
+}
+```
+
 ---
 
 ## Recommended Workflow
@@ -255,6 +303,26 @@ Clear app storage (reset to fresh install state).
 
 ---
 
+## Testing
+
+The repository includes a smoke test script to verify end-to-end functionality on real devices or simulators.
+
+```bash
+# Run smoke test for Android
+npx tsx smoke-test.ts android com.example.package
+
+# Run smoke test for iOS
+npx tsx smoke-test.ts ios com.example.bundleid
+```
+
+The smoke test performs the following sequence:
+1. Starts the app
+2. Captures a screenshot
+3. Fetches logs
+4. Terminates the app
+
+---
+
 ## License
 
 MIT License

package/dist/android/interact.js

@@ -0,0 +1,30 @@
+import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js";
+export class AndroidInteract {
+    async startApp(appId, deviceId) {
+        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, deviceId) {
+        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, deviceId) {
+        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, deviceId) {
+        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' };
+    }
+}

package/dist/android/observe.js

@@ -0,0 +1,313 @@
+import { spawn } from "child_process";
+import { XMLParser } from "fast-xml-parser";
+import { ADB, execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js";
+// --- Helper Functions Specific to Observe ---
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+function parseBounds(bounds) {
+    const match = bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+    if (match) {
+        return [parseInt(match[1]), parseInt(match[2]), parseInt(match[3]), parseInt(match[4])];
+    }
+    return [0, 0, 0, 0];
+}
+function getCenter(bounds) {
+    const [x1, y1, x2, y2] = bounds;
+    return [Math.floor((x1 + x2) / 2), Math.floor((y1 + y2) / 2)];
+}
+async function getScreenResolution(deviceId) {
+    try {
+        const output = await execAdb(['shell', 'wm', 'size'], deviceId);
+        const match = output.match(/Physical size: (\d+)x(\d+)/);
+        if (match) {
+            return { width: parseInt(match[1]), height: parseInt(match[2]) };
+        }
+    }
+    catch (e) {
+        // ignore
+    }
+    return { width: 0, height: 0 };
+}
+function traverseNode(node, elements, parentIndex = -1, depth = 0) {
+    if (!node)
+        return -1;
+    let currentIndex = -1;
+    // Check if it's a valid node with attributes we care about
+    if (node['@_class']) {
+        const text = node['@_text'] || null;
+        const contentDescription = node['@_content-desc'] || null;
+        const clickable = node['@_clickable'] === 'true';
+        const bounds = parseBounds(node['@_bounds'] || '[0,0][0,0]');
+        // Filtering Logic:
+        // Keep if clickable OR has visible text OR has content description
+        const isUseful = clickable || (text && text.length > 0) || (contentDescription && contentDescription.length > 0);
+        if (isUseful) {
+            const element = {
+                text,
+                contentDescription,
+                type: node['@_class'] || 'unknown',
+                resourceId: node['@_resource-id'] || null,
+                clickable,
+                enabled: node['@_enabled'] === 'true',
+                visible: true,
+                bounds,
+                center: getCenter(bounds),
+                depth
+            };
+            if (parentIndex !== -1) {
+                element.parentId = parentIndex;
+            }
+            elements.push(element);
+            currentIndex = elements.length - 1;
+        }
+    }
+    // If current node was skipped (not useful or no class), children inherit parentIndex
+    // If current node was added, children use currentIndex
+    const nextParentIndex = currentIndex !== -1 ? currentIndex : parentIndex;
+    const nextDepth = currentIndex !== -1 ? depth + 1 : depth;
+    const childrenIndices = [];
+    // Traverse children
+    if (node.node) {
+        if (Array.isArray(node.node)) {
+            node.node.forEach((child) => {
+                const childIndex = traverseNode(child, elements, nextParentIndex, nextDepth);
+                if (childIndex !== -1)
+                    childrenIndices.push(childIndex);
+            });
+        }
+        else {
+            const childIndex = traverseNode(node.node, elements, nextParentIndex, nextDepth);
+            if (childIndex !== -1)
+                childrenIndices.push(childIndex);
+        }
+    }
+    // Update current element with children if it was added
+    if (currentIndex !== -1 && childrenIndices.length > 0) {
+        elements[currentIndex].children = childrenIndices;
+    }
+    return currentIndex;
+}
+export class AndroidObserve {
+    async getDeviceMetadata(appId, deviceId) {
+        return getAndroidDeviceMetadata(appId, deviceId);
+    }
+    async getUITree(deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            // Get screen resolution first
+            const resolution = await getScreenResolution(deviceId);
+            if (resolution.width === 0 && resolution.height === 0) {
+                throw new Error("Failed to get screen resolution. Is the device connected and authorized?");
+            }
+            // Retry Logic
+            let xmlContent = '';
+            let attempts = 0;
+            const maxAttempts = 3;
+            while (attempts < maxAttempts) {
+                attempts++;
+                try {
+                    // Stabilization delay
+                    await delay(300 + (attempts * 100)); // 300ms, 400ms, 500ms...
+                    // Dump UI hierarchy
+                    await execAdb(['shell', 'uiautomator', 'dump', '/sdcard/ui.xml'], deviceId);
+                    // Read the file
+                    xmlContent = await execAdb(['shell', 'cat', '/sdcard/ui.xml'], deviceId);
+                    // Check validity
+                    if (xmlContent && xmlContent.trim().length > 0 && !xmlContent.includes("ERROR:")) {
+                        break; // Success
+                    }
+                }
+                catch (err) {
+                    console.error(`Attempt ${attempts} failed: ${err}`);
+                }
+                if (attempts === maxAttempts) {
+                    throw new Error(`Failed to retrieve valid UI dump after ${maxAttempts} attempts.`);
+                }
+            }
+            const parser = new XMLParser({
+                ignoreAttributes: false,
+                attributeNamePrefix: "@_"
+            });
+            const result = parser.parse(xmlContent);
+            const elements = [];
+            // The root is usually hierarchy -> node
+            if (result.hierarchy && result.hierarchy.node) {
+                // If the root is an array (unlikely for root, but good to be safe) or single object
+                if (Array.isArray(result.hierarchy.node)) {
+                    result.hierarchy.node.forEach((n) => traverseNode(n, elements));
+                }
+                else {
+                    traverseNode(result.hierarchy.node, elements);
+                }
+            }
+            return {
+                device: deviceInfo,
+                screen: "",
+                resolution,
+                elements
+            };
+        }
+        catch (e) {
+            const errorMessage = `Failed to get UI tree. ADB Path: '${ADB}'. Error: ${e instanceof Error ? e.message : String(e)}`;
+            console.error(errorMessage);
+            return {
+                device: deviceInfo,
+                screen: "",
+                resolution: { width: 0, height: 0 },
+                elements: [],
+                error: errorMessage
+            };
+        }
+    }
+    async getLogs(appId, lines = 200, deviceId) {
+        const metadata = await getAndroidDeviceMetadata(appId || "", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            // We'll skip PID lookup for now to avoid potential hangs with 'pidof' on some emulators
+            // and rely on robust string matching against the log line.
+            // Get logs
+            const stdout = await execAdb(['logcat', '-d', '-t', lines.toString(), '-v', 'threadtime'], deviceId);
+            const allLogs = stdout.split('\n');
+            let filteredLogs = allLogs;
+            if (appId) {
+                // Filter by checking if the line contains the appId string.
+                const matchingLogs = allLogs.filter(line => line.includes(appId));
+                if (matchingLogs.length > 0) {
+                    filteredLogs = matchingLogs;
+                }
+                else {
+                    // Fallback: if no logs match the appId, return the raw logs (last N lines)
+                    // This matches the behavior of the "working" version provided by the user,
+                    // ensuring they at least see system activity if the app is silent or crashing early.
+                    filteredLogs = allLogs;
+                }
+            }
+            return { device: deviceInfo, logs: filteredLogs, logCount: filteredLogs.length };
+        }
+        catch (e) {
+            console.error("Error fetching logs:", e);
+            return { device: deviceInfo, logs: [], logCount: 0 };
+        }
+    }
+    async captureScreen(deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        return new Promise((resolve, reject) => {
+            // Need to construct ADB args manually since spawn handles it
+            const args = deviceId ? ['-s', deviceId, 'exec-out', 'screencap', '-p'] : ['exec-out', 'screencap', '-p'];
+            // Using spawn for screencap as well to ensure consistent process handling
+            const child = spawn(ADB, args);
+            const chunks = [];
+            let stderr = '';
+            child.stdout.on('data', (chunk) => {
+                chunks.push(Buffer.from(chunk));
+            });
+            child.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+            const timeout = setTimeout(() => {
+                child.kill();
+                reject(new Error(`ADB screencap timed out after 10s`));
+            }, 10000);
+            child.on('close', (code) => {
+                clearTimeout(timeout);
+                if (code !== 0) {
+                    reject(new Error(stderr.trim() || `Screencap failed with code ${code}`));
+                    return;
+                }
+                const screenshotBuffer = Buffer.concat(chunks);
+                const screenshotBase64 = screenshotBuffer.toString('base64');
+                // Get resolution
+                execAdb(['shell', 'wm', 'size'], deviceId)
+                    .then(sizeStdout => {
+                    let width = 0;
+                    let height = 0;
+                    const match = sizeStdout.match(/Physical size: (\d+)x(\d+)/);
+                    if (match) {
+                        width = parseInt(match[1], 10);
+                        height = parseInt(match[2], 10);
+                    }
+                    resolve({
+                        device: deviceInfo,
+                        screenshot: screenshotBase64,
+                        resolution: { width, height }
+                    });
+                })
+                    .catch(() => {
+                    resolve({
+                        device: deviceInfo,
+                        screenshot: screenshotBase64,
+                        resolution: { width: 0, height: 0 }
+                    });
+                });
+            });
+            child.on('error', (err) => {
+                clearTimeout(timeout);
+                reject(err);
+            });
+        });
+    }
+    async getCurrentScreen(deviceId) {
+        const metadata = await getAndroidDeviceMetadata("", deviceId);
+        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+        try {
+            // Dumpsys activity can be slow on some devices, so we increase timeout to 10s
+            const output = await execAdb(['shell', 'dumpsys', 'activity', 'activities'], deviceId, { timeout: 10000 });
+            // Find the line with mResumedActivity or ResumedActivity (some versions might differ)
+            const lines = output.split('\n');
+            // Prioritize mResumedActivity, then ResumedActivity. 
+            // Use strict regex match to ensure it starts with the key, avoiding false positives like 'mLastResumedActivity'.
+            let resumedLine = lines.find(line => /^\s*mResumedActivity:/.test(line));
+            if (!resumedLine) {
+                resumedLine = lines.find(line => /^\s*ResumedActivity:/.test(line));
+            }
+            if (!resumedLine) {
+                return {
+                    device: deviceInfo,
+                    package: "",
+                    activity: "",
+                    shortActivity: "",
+                    error: "Could not find 'mResumedActivity' in dumpsys output"
+                };
+            }
+            // Regex to parse the line: ActivityRecord{... package/activity ...}
+            // Matches: ActivityRecord{<hex> <user> <package>/<activity> ...}
+            // We want to capture the component "package/activity" which is separated by space from other tokens.
+            // We use greedy match ([^ \{}]+) for activity to ensure we get the full name until a space or closing brace.
+            const match = resumedLine.match(/ActivityRecord\{[^ ]*(?:\s+[^ ]+)*\s+([^\/ ]+)\/([^ \{}]+)[^}]*\}/);
+            if (match) {
+                const packageName = match[1];
+                let activityName = match[2];
+                // Handle relative activity names (e.g. .LoginActivity)
+                if (activityName.startsWith('.')) {
+                    activityName = packageName + activityName;
+                }
+                const shortActivity = activityName.split('.').pop() || activityName;
+                return {
+                    device: deviceInfo,
+                    package: packageName,
+                    activity: activityName,
+                    shortActivity: shortActivity
+                };
+            }
+            else {
+                return {
+                    device: deviceInfo,
+                    package: "",
+                    activity: "",
+                    shortActivity: "",
+                    error: `Found resumed activity line but failed to parse: '${resumedLine.trim()}'`
+                };
+            }
+        }
+        catch (e) {
+            return {
+                device: deviceInfo,
+                package: "",
+                activity: "",
+                shortActivity: "",
+                error: e instanceof Error ? e.message : String(e)
+            };
+        }
+    }
+}

package/dist/android/utils.js

@@ -0,0 +1,82 @@
+import { spawn } from "child_process";
+export const ADB = process.env.ADB_PATH || "adb";
+// Helper to construct ADB args with optional device ID
+function getAdbArgs(args, deviceId) {
+    if (deviceId) {
+        return ['-s', deviceId, ...args];
+    }
+    return args;
+}
+export function execAdb(args, deviceId, options = {}) {
+    const adbArgs = getAdbArgs(args, deviceId);
+    return new Promise((resolve, reject) => {
+        // Extract timeout from options if present, otherwise pass options to spawn
+        const { timeout: customTimeout, ...spawnOptions } = options;
+        // Use spawn instead of execFile for better stream control and to avoid potential buffering hangs
+        const child = spawn(ADB, adbArgs, spawnOptions);
+        let stdout = '';
+        let stderr = '';
+        if (child.stdout) {
+            child.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+        }
+        if (child.stderr) {
+            child.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+        }
+        let timeoutMs = customTimeout || 2000;
+        if (!customTimeout) {
+            if (args.includes('logcat')) {
+                timeoutMs = 10000;
+            }
+            else if (args.includes('uiautomator') && args.includes('dump')) {
+                timeoutMs = 20000; // UI dump can be slow
+            }
+        }
+        const timeout = setTimeout(() => {
+            child.kill();
+            reject(new Error(`ADB command timed out after ${timeoutMs}ms: ${args.join(' ')}`));
+        }, timeoutMs);
+        child.on('close', (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                // If there's an actual error (non-zero exit code), reject
+                reject(new Error(stderr.trim() || `Command failed with code ${code}`));
+            }
+            else {
+                // If exit code is 0, resolve with stdout
+                resolve(stdout.trim());
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+    });
+}
+export function getDeviceInfo(deviceId, metadata = {}) {
+    return {
+        platform: 'android',
+        id: deviceId || 'default',
+        osVersion: metadata.osVersion || '',
+        model: metadata.model || '',
+        simulator: metadata.simulator || false
+    };
+}
+export async function getAndroidDeviceMetadata(appId, deviceId) {
+    try {
+        // Run these in parallel to avoid sequential timeouts
+        const [osVersion, model, simOutput] = await Promise.all([
+            execAdb(['shell', 'getprop', 'ro.build.version.release'], deviceId).catch(() => ''),
+            execAdb(['shell', 'getprop', 'ro.product.model'], deviceId).catch(() => ''),
+            execAdb(['shell', 'getprop', 'ro.kernel.qemu'], deviceId).catch(() => '0')
+        ]);
+        const simulator = simOutput === '1';
+        return { platform: 'android', id: deviceId || 'default', osVersion, model, simulator };
+    }
+    catch (e) {
+        return { platform: 'android', id: deviceId || 'default', osVersion: '', model: '', simulator: false };
+    }
+}