mobile-debug-mcp 0.4.0 → 0.6.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.
 
@@ -19,13 +26,27 @@
 - 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
 
 ---
 
 ## Installation
 
-Clone the repo and build:
+You can install and use **Mobile Debug MCP** in one of two ways:
+
+### 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
@@ -34,74 +55,230 @@ 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.
+
+### 3. 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:
+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:**
+```jsonc
+{
+  "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:**
+```jsonc
 {
   "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)
 }
 ```
 
-**Example:**
+**Response:**
+Returns two content blocks:
+1. JSON metadata:
+```json
+{
+  "device": { /* device info */ },
+  "result": { "lines": 50, "crashLines": [...] }
+}
+```
+2. Plain text log output.
+
+### capture_screenshot
+Capture a screenshot of the current device screen.
+
+**Input:**
+```jsonc
+{
+  "platform": "android" | "ios",
+  "deviceId": "emulator-5554" // Optional: target specific device
+}
+```
 
+**Response:**
+Returns two content blocks:
+1. JSON metadata:
 ```json
 {
-  "platform": "android",
-  "id": "com.modul8.app"
+  "device": { /* device info */ },
+  "result": { "resolution": { "width": 1080, "height": 1920 } }
 }
 ```
+2. Image content (image/png) containing the raw PNG data.
 
-### get_logs
-Fetch recent logs from the app.
+### terminate_app
+Terminate a running app.
+
+**Input:**
+```jsonc
+{
+  "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:**
+```jsonc
+{
+  "platform": "android" | "ios",
+  "appId": "com.example.app", // Android package or iOS bundle ID (Required)
+  "deviceId": "emulator-5554" // Optional
+}
+```
+
+**Response:**
+```json
+{
+  "device": { /* device info */ },
+  "appRestarted": true,
+  "launchTimeMs": 123
+}
+```
+
+### reset_app_data
+Clear app storage (reset to fresh install state).
 
 **Input:**
+```jsonc
+{
+  "platform": "android" | "ios",
+  "appId": "com.example.app", // Android package or iOS bundle ID (Required)
+  "deviceId": "emulator-5554" // Optional
+}
+```
 
+**Response:**
 ```json
+{
+  "device": { /* device info */ },
+  "dataCleared": true
+}
+```
+
+### 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",
-  "lines": 200 // optional, Android only
+  "deviceId": "emulator-5554" // Optional
 }
 ```
 
-**Example:**
+**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
 {
-  "platform": "android",
-  "lines": 200
+  "device": { /* device info */ },
+  "package": "com.example.app",
+  "activity": "com.example.app.LoginActivity",
+  "shortActivity": "LoginActivity"
 }
 ```
 
@@ -112,15 +289,37 @@ 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.
+
+---
+
+## 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
 
 ---
 

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' };
+    }
+}