mobile-debug-mcp 0.9.0 → 0.10.0

package/.eslintignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env
+.vscode/
+coverage/

package/.eslintrc.cjs

@@ -0,0 +1,18 @@
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    project: './tsconfig.json'
+  },
+  plugins: ['@typescript-eslint', 'unused-imports'],
+  rules: {
+    // Use plugin to error on unused imports and provide autofix where possible
+    'unused-imports/no-unused-imports': 'error',
+    'unused-imports/no-unused-vars': ['error', { vars: 'all', args: 'after-used', ignoreRestSiblings: true }],
+    // Disable the default TS rule to avoid duplicate warnings
+    '@typescript-eslint/no-unused-vars': 'off'
+  },
+  ignorePatterns: ['dist/', 'node_modules/', '.git/']
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  unit:
+    name: Unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+      - name: Install dependencies
+        run: npm ci
+      - name: Lint
+        run: npm run lint
+      - name: Build
+        run: npm run build
+      - name: Run unit tests
+        run: npm test
+
+  android-integration:
+    name: Android emulator integration (manual)
+    runs-on: ubuntu-latest
+    needs: unit
+    # only run integration when manually triggered to avoid long runs on every PR
+    if: github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start Android emulator
+        uses: reactivecircus/android-emulator-runner@v2
+        with:
+          api-level: 30
+          target: google_apis
+          arch: x86_64
+          force-avd-creation: true
+
+      - name: Build and run Android integration tests
+        env:
+          ADB_TIMEOUT: 120000
+        run: |
+          npm run build
+          node test/integration/run-install-android.js || true

package/README.md

@@ -2,18 +2,6 @@
 
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, and inspect Android/iOS apps from an MCP-compatible client.
 
-This README was shortened to keep high-level info only. Detailed tool definitions moved to docs/TOOLS.md.
-
-## Quick start
-
-```bash
-git clone https://github.com/YOUR_USERNAME/mobile-debug-mcp.git
-cd mobile-debug-mcp
-npm install
-npm run build
-npm start
-```
-
 ## Requirements
 
 - Node.js >= 18
@@ -34,14 +22,13 @@ npm start
   }
 }
 ```
-
-> Note: Avoid using `jsonc` fences with inline comments in README code blocks to prevent syntax-highlighting issues on some renderers.
+## Usage
+//TODO add examples
 
 ## Docs
 
-- Tools: docs/TOOLS.md (full input/response examples)
-- Changelog: docs/CHANGELOG.md
-- Tests: test/
+- Tools: [Tools](docs/TOOLS.md) — full input/response examples
+- Changelog: [Changelog](docs/CHANGELOG.md)
 
 ## License
 

package/dist/android/interact.js

@@ -1,4 +1,5 @@
-import { execAdb, getAndroidDeviceMetadata, getDeviceInfo, detectJavaHome } from "./utils.js";
+import { execAdb, getAndroidDeviceMetadata, getDeviceInfo, spawnAdb } from "./utils.js";
+import { detectJavaHome } from "../utils/java.js";
 import { AndroidObserve } from "./observe.js";
 import { promises as fs } from "fs";
 import { spawn } from "child_process";
@@ -124,7 +125,7 @@ export class AndroidInteract {
                         // Remove obvious shell profile hints; avoid touching SDKMAN symlinks or on-disk state.
                         delete env.SHELL;
                     }
-                    catch (e) { }
+                    catch { }
                     // If we detected a compatible JDK, instruct Gradle to use it and avoid daemon reuse
                     // Prepare gradle invocation
                     const gradleArgs = ['assembleDebug'];
@@ -164,8 +165,29 @@ export class AndroidInteract {
                     throw new Error('Could not locate built APK after running Gradle');
                 apkToInstall = built;
             }
-            const output = await execAdb(['install', '-r', apkToInstall], deviceId);
-            return { device: deviceInfo, installed: true, output };
+            // Try normal adb install with streaming attempt
+            try {
+                const res = await spawnAdb(['install', '-r', apkToInstall], deviceId);
+                if (res.code === 0) {
+                    return { device: deviceInfo, installed: true, output: res.stdout };
+                }
+                // fallthrough to fallback
+            }
+            catch (e) {
+                // Log and continue to fallback
+                console.debug('[android] adb install failed, attempting push+pm fallback:', e instanceof Error ? e.message : String(e));
+            }
+            // Fallback: push APK to device and use pm install -r
+            const basename = path.basename(apkToInstall);
+            const remotePath = `/data/local/tmp/${basename}`;
+            await execAdb(['push', apkToInstall, remotePath], deviceId);
+            const pmOut = await execAdb(['shell', 'pm', 'install', '-r', remotePath], deviceId);
+            // cleanup remote file
+            try {
+                await execAdb(['shell', 'rm', remotePath], deviceId);
+            }
+            catch { }
+            return { device: deviceInfo, installed: true, output: pmOut };
         }
         catch (e) {
             return { device: deviceInfo, installed: false, error: e instanceof Error ? e.message : String(e) };

package/dist/android/observe.js

@@ -22,7 +22,7 @@ async function getScreenResolution(deviceId) {
             return { width: parseInt(match[1]), height: parseInt(match[2]) };
         }
     }
-    catch (e) {
+    catch {
         // ignore
     }
     return { width: 0, height: 0 };
@@ -117,8 +117,8 @@ export class AndroidObserve {
                         break; // Success
                     }
                 }
-                catch (err) {
-                    console.error(`Attempt ${attempts} failed: ${err}`);
+                catch (e) {
+                    console.error(`Attempt ${attempts} failed: ${e}`);
                 }
                 if (attempts === maxAttempts) {
                     throw new Error(`Failed to retrieve valid UI dump after ${maxAttempts} attempts.`);

package/dist/android/utils.js

@@ -1,80 +1,7 @@
-import { spawn, execSync } from 'child_process';
-import { existsSync, createWriteStream, promises as fsPromises } from 'fs';
+import { spawn } from 'child_process';
+import { createWriteStream, promises as fsPromises } from 'fs';
 import path from 'path';
 export const ADB = process.env.ADB_PATH || 'adb';
-export async function detectJavaHome() {
-    try {
-        // If JAVA_HOME is set, validate it's Java 17
-        if (process.env.JAVA_HOME) {
-            try {
-                const javaBin = path.join(process.env.JAVA_HOME, 'bin', 'java');
-                const v = execSync(`"${javaBin}" -version`, { stdio: ['ignore', 'pipe', 'pipe'] }).toString();
-                if (/\b17\b/.test(v) || /17\./.test(v))
-                    return process.env.JAVA_HOME;
-                console.debug('[android] Existing JAVA_HOME does not appear to be Java 17, will search for JDK17');
-            }
-            catch (e) {
-                console.debug('[android] Failed to validate existing JAVA_HOME, searching for JDK17');
-            }
-        }
-        // macOS explicit path
-        const explicit = '/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home';
-        if (existsSync(explicit))
-            return explicit;
-        // Android Studio JBR candidates
-        const jbrCandidates = [
-            '/Applications/Android Studio.app/Contents/jbr',
-            '/Applications/Android Studio Preview.app/Contents/jbr',
-            '/Applications/Android Studio Preview 2022.3.app/Contents/jbr',
-            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr'
-        ];
-        for (const p of jbrCandidates) {
-            const javaBin = path.join(p, 'bin', 'java');
-            if (existsSync(javaBin)) {
-                try {
-                    const v = execSync(`"${javaBin}" -version`, { stdio: ['ignore', 'pipe', 'pipe'] }).toString();
-                    if (/\b17\b/.test(v) || /17\./.test(v))
-                        return p;
-                }
-                catch { }
-            }
-        }
-        // macOS /usr/libexec/java_home
-        try {
-            const out = execSync('/usr/libexec/java_home -v 17', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
-            if (out)
-                return out;
-        }
-        catch { }
-        // macOS common JDK locations
-        try {
-            const homes = execSync('ls -1 /Library/Java/JavaVirtualMachines || true', { stdio: ['ignore', 'pipe', 'inherit'] }).toString().split(/\r?\n/).filter(Boolean);
-            for (const h of homes) {
-                if (h.toLowerCase().includes('17') || h.toLowerCase().includes('jdk-17')) {
-                    const candidate = `/Library/Java/JavaVirtualMachines/${h}/Contents/Home`;
-                    return candidate;
-                }
-            }
-        }
-        catch { }
-        // Linux locations
-        const linuxCandidates = [
-            '/usr/lib/jvm/java-17-openjdk-amd64',
-            '/usr/lib/jvm/java-17-openjdk',
-            '/usr/lib/jvm/zulu17',
-            '/usr/lib/jvm/temurin-17-jdk'
-        ];
-        for (const p of linuxCandidates) {
-            try {
-                if (existsSync(p))
-                    return p;
-            }
-            catch { }
-        }
-    }
-    catch (e) { }
-    return undefined;
-}
 // Helper to construct ADB args with optional device ID
 function getAdbArgs(args, deviceId) {
     if (deviceId) {
@@ -82,6 +9,24 @@ function getAdbArgs(args, deviceId) {
     }
     return args;
 }
+/**
+ * Determine an effective ADB timeout (ms) prioritizing:
+ * 1. provided customTimeout
+ * 2. MCP_ADB_TIMEOUT or ADB_TIMEOUT env vars
+ * 3. sensible per-command defaults
+ */
+function getAdbTimeout(args, customTimeout) {
+    if (typeof customTimeout === 'number' && !isNaN(customTimeout))
+        return customTimeout;
+    const envTimeout = parseInt(process.env.MCP_ADB_TIMEOUT || process.env.ADB_TIMEOUT || '', 10);
+    if (!isNaN(envTimeout) && envTimeout > 0)
+        return envTimeout;
+    if (args.includes('logcat'))
+        return 10000;
+    if (args.includes('uiautomator') && args.includes('dump'))
+        return 20000;
+    return 120000;
+}
 export function execAdb(args, deviceId, options = {}) {
     const adbArgs = getAdbArgs(args, deviceId);
     return new Promise((resolve, reject) => {
@@ -101,27 +46,7 @@ export function execAdb(args, deviceId, options = {}) {
                 stderr += data.toString();
             });
         }
-        let timeoutMs;
-        if (typeof customTimeout === 'number' && !isNaN(customTimeout)) {
-            timeoutMs = customTimeout;
-        }
-        else {
-            const envTimeout = parseInt(process.env.MCP_ADB_TIMEOUT || process.env.ADB_TIMEOUT || '', 10);
-            if (!isNaN(envTimeout) && envTimeout > 0) {
-                timeoutMs = envTimeout;
-            }
-            else {
-                if (args.includes('logcat')) {
-                    timeoutMs = 10000;
-                }
-                else if (args.includes('uiautomator') && args.includes('dump')) {
-                    timeoutMs = 20000; // UI dump can be slow
-                }
-                else {
-                    timeoutMs = 120000; // default 2 minutes for installs and slow commands
-                }
-            }
-        }
+        const timeoutMs = getAdbTimeout(args, customTimeout);
         const timeout = setTimeout(() => {
             child.kill();
             reject(new Error(`ADB command timed out after ${timeoutMs}ms: ${args.join(' ')}`));
@@ -143,6 +68,36 @@ export function execAdb(args, deviceId, options = {}) {
         });
     });
 }
+// Spawn adb but return full streams and exit code so callers can implement fallbacks or stream output
+export function spawnAdb(args, deviceId, options = {}) {
+    const adbArgs = getAdbArgs(args, deviceId);
+    return new Promise((resolve, reject) => {
+        const { timeout: customTimeout, ...spawnOptions } = options;
+        const child = spawn(ADB, adbArgs, spawnOptions);
+        let stdout = '';
+        let stderr = '';
+        if (child.stdout)
+            child.stdout.on('data', d => { stdout += d.toString(); });
+        if (child.stderr)
+            child.stderr.on('data', d => { stderr += d.toString(); });
+        const timeoutMs = getAdbTimeout(args, customTimeout);
+        const timeout = setTimeout(() => {
+            try {
+                child.kill();
+            }
+            catch { }
+            reject(new Error(`ADB command timed out after ${timeoutMs}ms: ${args.join(' ')}`));
+        }, timeoutMs);
+        child.on('close', (code) => {
+            clearTimeout(timeout);
+            resolve({ stdout: stdout.trim(), stderr: stderr.trim(), code });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+    });
+}
 export function getDeviceInfo(deviceId, metadata = {}) {
     return {
         platform: 'android',
@@ -169,7 +124,7 @@ export async function getAndroidDeviceMetadata(appId, deviceId) {
                     resolvedDeviceId = deviceLines[0];
                 }
             }
-            catch (e) {
+            catch {
                 // ignore and continue without resolvedDeviceId
             }
         }
@@ -182,7 +137,7 @@ export async function getAndroidDeviceMetadata(appId, deviceId) {
         const simulator = simOutput === '1';
         return { platform: 'android', id: resolvedDeviceId || 'default', osVersion, model, simulator };
     }
-    catch (e) {
+    catch {
         return { platform: 'android', id: deviceId || 'default', osVersion: '', model: '', simulator: false };
     }
 }
@@ -219,7 +174,7 @@ export async function listAndroidDevices(appId) {
         }));
         return infos;
     }
-    catch (e) {
+    catch {
         return [];
     }
 }
@@ -354,7 +309,7 @@ export async function startAndroidLogStream(packageName, level = 'error', device
             try {
                 activeLogStreams.get(sessionId).proc.kill();
             }
-            catch (e) { }
+            catch { }
             activeLogStreams.delete(sessionId);
         }
         // Start logcat process
@@ -381,14 +336,14 @@ export async function startAndroidLogStream(packageName, level = 'error', device
                 stream.write(JSON.stringify(entry) + '\n');
             }
         });
-        proc.on('close', (code) => {
+        proc.on('close', () => {
             stream.end();
             activeLogStreams.delete(sessionId);
         });
         activeLogStreams.set(sessionId, { proc, file });
         return { success: true, stream_started: true };
     }
-    catch (err) {
+    catch {
         return { success: false, error: 'log_stream_start_failed' };
     }
 }
@@ -399,7 +354,7 @@ export async function stopAndroidLogStream(sessionId = 'default') {
     try {
         entry.proc.kill();
     }
-    catch (e) { }
+    catch { }
     activeLogStreams.delete(sessionId);
     return { success: true };
 }
@@ -468,7 +423,7 @@ export async function readLogStreamLines(sessionId = 'default', limit = 100, sin
         const crash_summary = crashEntry ? { crash_detected: true, exception: crashEntry.exception, sample: crashEntry.message } : { crash_detected: false };
         return { entries, crash_summary };
     }
-    catch (e) {
+    catch {
         return { entries: [], crash_summary: { crash_detected: false } };
     }
 }

package/dist/ios/interact.js

@@ -166,7 +166,7 @@ export class iOSInteract {
                         return { device, installed: true };
                     }
                 }
-                catch (inner) {
+                catch {
                     // fallthrough
                 }
                 return { device, installed: false, error: e instanceof Error ? e.message : String(e) };
@@ -233,8 +233,8 @@ export class iOSInteract {
                 dataCleared: true
             };
         }
-        catch (err) {
-            throw new Error(`Failed to clear data for ${bundleId}: ${err instanceof Error ? err.message : String(err)}`);
+        catch (e) {
+            throw new Error(`Failed to clear data for ${bundleId}: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
 }

package/dist/ios/observe.js

@@ -119,10 +119,10 @@ export class iOSObserve {
                 resolution: { width: 0, height: 0 },
             };
         }
-        catch (err) {
+        catch (e) {
             // Ensure cleanup happens even on error
             await fs.rm(tmpFile).catch(() => { });
-            throw new Error(`Failed to capture screenshot: ${err instanceof Error ? err.message : String(err)}`);
+            throw new Error(`Failed to capture screenshot: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
     async getUITree(deviceId = "booted") {
@@ -174,8 +174,8 @@ export class iOSObserve {
                     break; // Success
                 }
             }
-            catch (err) {
-                console.error(`Attempt ${attempts} failed: ${err}`);
+            catch (e) {
+                console.error(`Attempt ${attempts} failed: ${e}`);
             }
             if (attempts === maxAttempts) {
                 return {

package/dist/ios/utils.js

@@ -106,7 +106,7 @@ export async function getIOSDeviceMetadata(deviceId = "booted") {
                 }
                 resolve(fallback);
             }
-            catch (error) {
+            catch {
                 resolve(fallback);
             }
         });
@@ -149,7 +149,7 @@ export async function listIOSDevices(appId) {
                 }
                 Promise.all(checks).then(() => resolve(out)).catch(() => resolve(out));
             }
-            catch (e) {
+            catch {
                 resolve([]);
             }
         });
@@ -167,7 +167,7 @@ export function _setIOSActiveLogStream(sessionId, file) {
 export function _clearIOSActiveLogStream(sessionId) {
     iosActiveLogStreams.delete(sessionId);
 }
-export async function startIOSLogStream(bundleId, level = 'error', deviceId = 'booted', sessionId = 'default') {
+export async function startIOSLogStream(bundleId, deviceId = 'booted', sessionId = 'default') {
     try {
         // Build predicate to filter by process or subsystem
         const predicate = `process == "${bundleId}" or subsystem contains "${bundleId}"`;
@@ -176,7 +176,7 @@ export async function startIOSLogStream(bundleId, level = 'error', deviceId = 'b
             try {
                 iosActiveLogStreams.get(sessionId).proc.kill();
             }
-            catch (e) { }
+            catch { }
             iosActiveLogStreams.delete(sessionId);
         }
         // Start simctl log stream: xcrun simctl spawn <device> log stream --style syslog --predicate '<predicate>'
@@ -203,14 +203,14 @@ export async function startIOSLogStream(bundleId, level = 'error', deviceId = 'b
                 stream.write(JSON.stringify(entry) + '\n');
             }
         });
-        proc.on('close', (code) => {
+        proc.on('close', () => {
             stream.end();
             iosActiveLogStreams.delete(sessionId);
         });
         iosActiveLogStreams.set(sessionId, { proc, file });
         return { success: true, stream_started: true };
     }
-    catch (err) {
+    catch {
         return { success: false, error: 'log_stream_start_failed' };
     }
 }
@@ -221,7 +221,7 @@ export async function stopIOSLogStream(sessionId = 'default') {
     try {
         entry.proc.kill();
     }
-    catch (e) { }
+    catch { }
     iosActiveLogStreams.delete(sessionId);
     return { success: true };
 }
@@ -262,7 +262,7 @@ export async function readIOSLogStreamLines(sessionId = 'default', limit = 100,
         const crash_summary = crashEntry ? { crash_detected: true, exception: crashEntry.exception, sample: crashEntry.message } : { crash_detected: false };
         return { entries, crash_summary };
     }
-    catch (e) {
+    catch {
         return { entries: [], crash_summary: { crash_detected: false } };
     }
 }