mobile-debug-mcp 0.4.0 → 0.5.0

package/.github/copilot-instructions.md

@@ -0,0 +1,33 @@
+# Copilot Instructions for mobile-debug-mcp
+
+## Build and Run
+- **Build**: `npm run build` (runs `tsc` to compile TypeScript to `dist/`)
+- **Start**: `npm start` (runs the compiled server at `dist/server.js`)
+- **Dev Workflow**: modify `src/*.ts` -> `npm run build` -> `npm start` to test changes.
+
+## Architecture
+- **Core**: `src/server.ts` implements the MCP server using `@modelcontextprotocol/sdk`. It handles tool registration and execution.
+- **Platform Modules**:
+  - `src/android.ts`: Encapsulates `adb` commands for Android device interaction.
+  - `src/ios.ts`: Encapsulates `xcrun simctl` commands for iOS simulator interaction.
+- **Types**: `src/types.ts` defines shared interfaces for device info and tool responses.
+
+## Key Conventions
+
+### Tool Implementation
+- **Response Format**: Tools typically return a list of content blocks.
+  - `start_app`: Returns a single text block containing JSON (via `wrapResponse`).
+  - `terminate_app`: Returns a single text block containing JSON (via `wrapResponse`).
+  - `restart_app`: Returns a single text block containing JSON (via `wrapResponse`).
+  - `reset_app_data`: Returns a single text block containing JSON (via `wrapResponse`).
+  - `get_logs`: Returns a text block (JSON metadata) AND a text block (raw logs).
+  - `capture_screenshot`: Returns a text block (JSON metadata) AND an image block (base64 PNG).
+- **Metadata**: Always include a `device` object (platform, id, model, etc.) in the JSON response part.
+
+### External Tools
+- **Android**: Uses `process.env.ADB_PATH` or defaults to `adb`.
+- **iOS**: Uses `process.env.XCRUN_PATH` or defaults to `xcrun`. Assumes a booted simulator.
+- **Execution**: Uses `child_process.exec` for running shell commands.
+
+### Error Handling
+- Tools should catch execution errors and return a user-friendly error message in a `text` content block, rather than crashing the server.

package/README.md

@@ -1,6 +1,10 @@
 # Mobile Debug MCP
 
-**Mobile Debug MCP** is a minimal MCP server for AI-assisted mobile development. It allows you to **launch Android or iOS apps** and **read their logs** from an MCP-compatible AI client.
+**Mobile Debug MCP** is a minimal, secure MCP server for AI-assisted mobile development. It allows you to **launch Android or iOS apps**, **read their logs**, and **inspect UI** from an MCP-compatible AI client.
+
+This server is designed with security in mind, using strict argument handling to prevent shell injection, and reliability, with robust process management to avoid hanging operations.
+
+> **Note:** iOS support is currently an untested Work In Progress (WIP). Please use with caution and report any issues.
 
 ---
 
@@ -9,6 +13,9 @@
 - Launch Android apps via package name.
 - Launch iOS apps via bundle ID on a booted simulator.
 - Fetch recent logs from Android or iOS apps.
+- Terminate and restart apps.
+- Clear app data for fresh installs.
+- Capture screenshots.
 - Cross-platform support (Android + iOS).
 - Minimal, focused design for fast debugging loops.
 
@@ -25,7 +32,9 @@
 
 ## Installation
 
-Clone the repo and build:
+You can install and use **Mobile Debug MCP** in one of two ways:
+
+### 1. Clone the repository for local development
 
 ```bash
 git clone https://github.com/YOUR_USERNAME/mobile-debug-mcp.git
@@ -34,74 +43,194 @@ npm install
 npm run build
 ```
 
-Alternatively, you can publish to npm and install globally:
+This option is suitable if you want to modify or contribute to the code.
+
+### 2. Install via npm for standard use
 
 ```bash
 npm install -g mobile-debug-mcp
 ```
 
----
+This option installs the package globally for easy use without cloning the repo.
 
-## MCP Server Configuration
+---
 
-Example WebUI MCP config:
+## 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
+
+Example WebUI MCP config using `npx --yes` and environment variables:
 
 ```json
 {
   "mcpServers": {
     "mobile-debug": {
-      "command": "node",
-      "args": ["/full/path/to/mobile-debug-mcp/dist/server.js"]
+      "command": "npx",
+      "args": [
+        "--yes",
+        "mobile-debug-mcp",
+        "server"
+      ],
+      "env": {
+        "ADB_PATH": "/path/to/adb",
+        "XCRUN_PATH": "/usr/bin/xcrun"
+      }
     }
   }
 }
 ```
 
-> Make sure to replace `/full/path/to/` with your actual project path.
+> Make sure to set `ADB_PATH` (Android) and `XCRUN_PATH` (iOS) if the tools are not in your system PATH.
 
 ---
 
 ## Tools
 
+All tools accept a JSON input payload and return a structured JSON response. **Every response includes a `device` object** (with information about the selected device/simulator used for the operation), plus the tool-specific output.
+
 ### start_app
 Launch a mobile app.
 
 **Input:**
+```json
+{
+  "platform": "android" | "ios",
+  "appId": "com.example.app", // Android package or iOS bundle ID (Required)
+  "deviceId": "emulator-5554" // Optional: target specific device/simulator
+}
+```
 
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "appStarted": true,
+  "launchTimeMs": 123
+}
+```
+
+### get_logs
+Fetch recent logs from the app or device.
+
+**Input:**
 ```json
 {
   "platform": "android" | "ios",
-  "id": "com.example.app" // Android package or iOS bundle ID
+  "appId": "com.example.app", // Optional: filter logs by app
+  "deviceId": "emulator-5554", // Optional: target specific device
+  "lines": 200 // Optional: number of lines (Android only)
+}
+```
+
+**Response:**
+Returns two content blocks:
+1. JSON metadata:
+```json
+{
+  "device": { /* device info */ },
+  "result": { "lines": 50, "crashLines": [...] }
 }
 ```
+2. Plain text log output.
 
-**Example:**
+### capture_screenshot
+Capture a screenshot of the current device screen.
 
+**Input:**
 ```json
 {
-  "platform": "android",
-  "id": "com.modul8.app"
+  "platform": "android" | "ios",
+  "deviceId": "emulator-5554" // Optional: target specific device
 }
 ```
 
-### get_logs
-Fetch recent logs from the app.
+**Response:**
+Returns two content blocks:
+1. JSON metadata:
+```json
+{
+  "device": { /* device info */ },
+  "result": { "resolution": { "width": 1080, "height": 1920 } }
+}
+```
+2. Image content (image/png) containing the raw PNG data.
+
+### terminate_app
+Terminate a running app.
 
 **Input:**
+```json
+{
+  "platform": "android" | "ios",
+  "appId": "com.example.app", // Android package or iOS bundle ID (Required)
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "appTerminated": true
+}
+```
 
+### restart_app
+Restart an app (terminate then launch).
+
+**Input:**
 ```json
 {
   "platform": "android" | "ios",
-  "lines": 200 // optional, Android only
+  "appId": "com.example.app", // Android package or iOS bundle ID (Required)
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "appRestarted": true,
+  "launchTimeMs": 123
 }
 ```
 
-**Example:**
+### reset_app_data
+Clear app storage (reset to fresh install state).
+
+**Input:**
+```json
+{
+  "platform": "android" | "ios",
+  "appId": "com.example.app", // Android package or iOS bundle ID (Required)
+  "deviceId": "emulator-5554" // Optional
+}
+```
 
+**Response:**
 ```json
 {
-  "platform": "android",
-  "lines": 200
+  "device": { /* device info */ },
+  "dataCleared": true
 }
 ```
 
@@ -112,15 +241,17 @@ Fetch recent logs from the app.
 1. Ensure Android device or iOS simulator is running.
 2. Use `start_app` to launch the app.
 3. Use `get_logs` to read the latest logs.
-4. Repeat for debugging loops.
+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.
 
 ---
 
 ## Notes
 
-- Ensure `adb` and `xcrun` are in your PATH.
-- For iOS, the simulator must be booted before using `start_app` or `get_logs`.
-- You may want to clear Android logs before launching for cleaner output: `adb logcat -c`
+- Ensure `adb` and `xcrun` are in your PATH or set `ADB_PATH` / `XCRUN_PATH` accordingly.
+- For iOS, the simulator must be booted before using tools.
+- The `capture_screenshot` tool returns a multi-block response: a JSON text block with metadata, followed by an image block containing the base64-encoded PNG data.
 
 ---
 

package/dist/android.js

@@ -1,44 +1,186 @@
-import { exec } from "child_process";
+import { spawn } from "child_process";
 const ADB = process.env.ADB_PATH || "adb";
-export function startAndroidApp(pkg) {
-    return new Promise((resolve, reject) => {
-        exec(`${ADB} shell monkey -p ${pkg} -c android.intent.category.LAUNCHER 1`, (err, stdout, stderr) => {
-            if (err)
-                reject(stderr);
-            else
-                resolve(stdout);
-        });
-    });
+// Helper to construct ADB args with optional device ID
+function getAdbArgs(args, deviceId) {
+    if (deviceId) {
+        return ['-s', deviceId, ...args];
+    }
+    return args;
 }
-export function getAndroidLogs(pkg, lines = 200) {
+function execAdb(args, deviceId, options = {}) {
+    const adbArgs = getAdbArgs(args, deviceId);
     return new Promise((resolve, reject) => {
-        exec(`${ADB} shell pidof -s ${pkg}`, (pidErr, pidStdout, pidStderr) => {
-            if (pidErr || !pidStdout.trim()) {
-                reject(pidStderr || "App process not running");
-                return;
-            }
-            const pid = pidStdout.trim();
-            exec(`${ADB} logcat -d --pid=${pid} -t ${lines} -v threadtime`, (err, stdout, stderr) => {
-                if (err)
-                    reject(stderr || err.message);
-                else
-                    resolve(stdout);
+        // Use spawn instead of execFile for better stream control and to avoid potential buffering hangs
+        const child = spawn(ADB, adbArgs, options);
+        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();
             });
+        }
+        const timeoutMs = args.includes('logcat') ? 10000 : 2000; // Shorter timeout for metadata queries
+        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 async function getAndroidCrash(pkg, lines = 200) {
+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 {
-        const logs = await getAndroidLogs(pkg, lines);
-        const crashLines = logs
-            .split('\n')
-            .filter(line => line.includes('FATAL EXCEPTION'));
-        if (crashLines.length === 0) {
-            return "No crashes found.";
+        // 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 };
+    }
+}
+export async function startAndroidApp(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 };
+}
+export async function terminateAndroidApp(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 };
+}
+export async function restartAndroidApp(appId, deviceId) {
+    await terminateAndroidApp(appId, deviceId);
+    const startResult = await startAndroidApp(appId, deviceId);
+    return {
+        device: startResult.device,
+        appRestarted: startResult.appStarted,
+        launchTimeMs: startResult.launchTimeMs
+    };
+}
+export async function resetAndroidAppData(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' };
+}
+export async function getAndroidLogs(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 crashLines.join('\n');
+        return { device: deviceInfo, logs: filteredLogs, logCount: filteredLogs.length };
     }
-    catch (error) {
-        return `Error retrieving crash logs: ${error}`;
+    catch (e) {
+        console.error("Error fetching logs:", e);
+        return { device: deviceInfo, logs: [], logCount: 0 };
     }
 }
+export async function captureAndroidScreen(deviceId) {
+    const metadata = await getAndroidDeviceMetadata("", deviceId);
+    const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
+    return new Promise((resolve, reject) => {
+        const adbArgs = getAdbArgs(['exec-out', 'screencap', '-p'], deviceId);
+        // Using spawn for screencap as well to ensure consistent process handling
+        const child = spawn(ADB, adbArgs);
+        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);
+        });
+    });
+}