mobile-debug-mcp 0.9.0 → 0.10.0

package/dist/server.js

@@ -2,20 +2,12 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-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 { installAppHandler } from './tools/install.js';
-import { startAppHandler, terminateAppHandler, restartAppHandler, resetAppDataHandler } from './tools/app.js';
-import { getLogsHandler, startLogStreamHandler, readLogStreamHandler, stopLogStreamHandler } from './tools/logs.js';
-import { listDevicesHandler } from './tools/devices.js';
-import { captureScreenshotHandler } from './tools/screenshot.js';
-import { getUITreeHandler, getCurrentScreenHandler, waitForElementHandler, tapHandler, swipeHandler, typeTextHandler, pressBackHandler } from './tools/ui.js';
-const androidObserve = new AndroidObserve();
-const androidInteract = new AndroidInteract();
-const iosObserve = new iOSObserve();
-const iosInteract = new iOSInteract();
+import { ToolsInteract } from './tools/interact.js';
+import { ToolsObserve } from './tools/observe.js';
+import { AndroidInteract } from './android/interact.js';
+import { iOSInteract } from './ios/interact.js';
+import { AndroidObserve } from './android/observe.js';
+import { iOSObserve } from './ios/observe.js';
 const server = new Server({
     name: "mobile-debug-mcp",
     version: "0.7.0"
@@ -383,46 +375,46 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         if (name === "start_app") {
             const { platform, appId, deviceId } = args;
-            const result = await startAppHandler({ platform, appId, deviceId });
+            const res = await (platform === 'android' ? new AndroidInteract().startApp(appId, deviceId) : new iOSInteract().startApp(appId, deviceId));
             const response = {
-                device: result.device,
-                appStarted: result.appStarted,
-                launchTimeMs: result.launchTimeMs
+                device: res.device,
+                appStarted: res.appStarted,
+                launchTimeMs: res.launchTimeMs
             };
             return wrapResponse(response);
         }
         if (name === "terminate_app") {
             const { platform, appId, deviceId } = args;
-            const result = await terminateAppHandler({ platform, appId, deviceId });
-            const response = { device: result.device, appTerminated: result.appTerminated };
+            const res = await (platform === 'android' ? new AndroidInteract().terminateApp(appId, deviceId) : new iOSInteract().terminateApp(appId, deviceId));
+            const response = { device: res.device, appTerminated: res.appTerminated };
             return wrapResponse(response);
         }
         if (name === "restart_app") {
             const { platform, appId, deviceId } = args;
-            const result = await restartAppHandler({ platform, appId, deviceId });
-            const response = { device: result.device, appRestarted: result.appRestarted, launchTimeMs: result.launchTimeMs };
+            const res = await (platform === 'android' ? new AndroidInteract().restartApp(appId, deviceId) : new iOSInteract().restartApp(appId, deviceId));
+            const response = { device: res.device, appRestarted: res.appRestarted, launchTimeMs: res.launchTimeMs };
             return wrapResponse(response);
         }
         if (name === "reset_app_data") {
             const { platform, appId, deviceId } = args;
-            const result = await resetAppDataHandler({ platform, appId, deviceId });
-            const response = { device: result.device, dataCleared: result.dataCleared };
+            const res = await (platform === 'android' ? new AndroidInteract().resetAppData(appId, deviceId) : new iOSInteract().resetAppData(appId, deviceId));
+            const response = { device: res.device, dataCleared: res.dataCleared };
             return wrapResponse(response);
         }
         if (name === "install_app") {
             const { platform, appPath, deviceId } = args;
-            const result = await installAppHandler({ platform, appPath, deviceId });
+            const res = await ToolsInteract.installAppHandler({ platform, appPath, deviceId });
             const response = {
-                device: result.device,
-                installed: result.installed,
-                output: result.output,
-                error: result.error
+                device: res.device,
+                installed: res.installed,
+                output: res.output,
+                error: res.error
             };
             return wrapResponse(response);
         }
         if (name === "get_logs") {
             const { platform, appId, deviceId, lines } = args;
-            const res = await getLogsHandler({ platform, appId, deviceId, lines });
+            const res = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, lines });
             return {
                 content: [
                     { type: 'text', text: JSON.stringify({ device: res.device, result: { lines: res.logs.length, crashLines: res.crashLines.length > 0 ? res.crashLines : undefined } }, null, 2) },
@@ -432,12 +424,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         if (name === "list_devices") {
             const { platform, appId } = (args || {});
-            const res = await listDevicesHandler({ platform, appId });
+            const res = await ToolsObserve.listDevicesHandler({ platform, appId });
             return wrapResponse(res);
         }
         if (name === "capture_screenshot") {
             const { platform, deviceId } = args;
-            const res = await captureScreenshotHandler({ platform, deviceId });
+            const res = await ToolsObserve.captureScreenshotHandler({ platform, deviceId });
             return {
                 content: [
                     { type: 'text', text: JSON.stringify({ device: res.device, result: { resolution: res.resolution } }, null, 2) },
@@ -447,52 +439,52 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         if (name === "get_ui_tree") {
             const { platform, deviceId } = args;
-            const res = await getUITreeHandler({ platform, deviceId });
+            const res = await (platform === 'android' ? new AndroidObserve().getUITree(deviceId) : new iOSObserve().getUITree(deviceId));
             return wrapResponse(res);
         }
         if (name === "get_current_screen") {
             const { deviceId } = (args || {});
-            const res = await getCurrentScreenHandler({ deviceId });
+            const res = await new AndroidObserve().getCurrentScreen(deviceId);
             return wrapResponse(res);
         }
         if (name === "wait_for_element") {
             const { platform, text, timeout, deviceId } = (args || {});
-            const res = await waitForElementHandler({ platform, text, timeout, deviceId });
+            const res = await (platform === 'android' ? new AndroidInteract().waitForElement(text, timeout, deviceId) : new iOSInteract().waitForElement(text, timeout, deviceId));
             return wrapResponse(res);
         }
         if (name === "tap") {
             const { platform, x, y, deviceId } = (args || {});
-            const res = await tapHandler({ platform, x, y, deviceId });
+            const res = await (platform === 'android' ? new AndroidInteract().tap(x, y, deviceId) : new iOSInteract().tap(x, y, deviceId));
             return wrapResponse(res);
         }
         if (name === "swipe") {
             const { x1, y1, x2, y2, duration, deviceId } = (args || {});
-            const res = await swipeHandler({ x1, y1, x2, y2, duration, deviceId });
+            const res = await new AndroidInteract().swipe(x1, y1, x2, y2, duration, deviceId);
             return wrapResponse(res);
         }
         if (name === "type_text") {
             const { text, deviceId } = (args || {});
-            const res = await typeTextHandler({ text, deviceId });
+            const res = await new AndroidInteract().typeText(text, deviceId);
             return wrapResponse(res);
         }
         if (name === "press_back") {
             const { deviceId } = (args || {});
-            const res = await pressBackHandler({ deviceId });
+            const res = await new AndroidInteract().pressBack(deviceId);
             return wrapResponse(res);
         }
         if (name === 'start_log_stream') {
             const { platform, packageName, level, sessionId, deviceId } = args;
-            const res = await startLogStreamHandler({ platform, packageName, level, sessionId, deviceId });
+            const res = await ToolsObserve.startLogStreamHandler({ platform, packageName, level, sessionId, deviceId });
             return wrapResponse(res);
         }
         if (name === 'read_log_stream') {
             const { platform, sessionId, limit, since } = args;
-            const res = await readLogStreamHandler({ platform, sessionId, limit, since });
+            const res = await ToolsObserve.readLogStreamHandler({ platform, sessionId, limit, since });
             return wrapResponse(res);
         }
         if (name === 'stop_log_stream') {
             const { platform, sessionId } = (args || {});
-            const res = await stopLogStreamHandler({ platform, sessionId });
+            const res = await ToolsObserve.stopLogStreamHandler({ platform, sessionId });
             return wrapResponse(res);
         }
     }

package/dist/tools/install.js

@@ -31,7 +31,7 @@ export async function installAppHandler({ platform, appPath, deviceId }) {
                 chosenPlatform = 'android';
         }
     }
-    catch (e) {
+    catch {
         chosenPlatform = 'android';
     }
     if (chosenPlatform === 'android') {

package/dist/tools/interact.js

@@ -0,0 +1,89 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { resolveTargetDevice } from '../resolve-device.js';
+import { AndroidInteract } from '../android/interact.js';
+import { iOSInteract } from '../ios/interact.js';
+export class ToolsInteract {
+    static async installAppHandler({ platform, appPath, deviceId }) {
+        let chosenPlatform = platform;
+        try {
+            const stat = await fs.stat(appPath).catch(() => null);
+            if (stat && stat.isDirectory()) {
+                const files = (await fs.readdir(appPath).catch(() => []));
+                if (files.some(f => f.endsWith('.xcodeproj') || f.endsWith('.xcworkspace'))) {
+                    chosenPlatform = 'ios';
+                }
+                else if (files.includes('gradlew') || files.includes('build.gradle') || files.includes('settings.gradle') || (files.includes('app') && (await fs.stat(path.join(appPath, 'app')).catch(() => null)))) {
+                    chosenPlatform = 'android';
+                }
+                else {
+                    chosenPlatform = 'android';
+                }
+            }
+            else if (typeof appPath === 'string') {
+                const ext = path.extname(appPath).toLowerCase();
+                if (ext === '.apk')
+                    chosenPlatform = 'android';
+                else if (ext === '.ipa' || ext === '.app')
+                    chosenPlatform = 'ios';
+                else
+                    chosenPlatform = 'android';
+            }
+        }
+        catch {
+            chosenPlatform = 'android';
+        }
+        if (chosenPlatform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+            const androidInteract = new AndroidInteract();
+            const result = await androidInteract.installApp(appPath, resolved.id);
+            return result;
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
+            const iosInteract = new iOSInteract();
+            const result = await iosInteract.installApp(appPath, resolved.id);
+            return result;
+        }
+    }
+    static async startAppHandler({ platform, appId, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            return await new AndroidInteract().startApp(appId, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            return await new iOSInteract().startApp(appId, resolved.id);
+        }
+    }
+    static async terminateAppHandler({ platform, appId, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            return await new AndroidInteract().terminateApp(appId, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            return await new iOSInteract().terminateApp(appId, resolved.id);
+        }
+    }
+    static async restartAppHandler({ platform, appId, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            return await new AndroidInteract().restartApp(appId, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            return await new iOSInteract().restartApp(appId, resolved.id);
+        }
+    }
+    static async resetAppDataHandler({ platform, appId, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            return await new AndroidInteract().resetAppData(appId, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            return await new iOSInteract().resetAppData(appId, resolved.id);
+        }
+    }
+}

package/dist/tools/logs.js

@@ -23,7 +23,7 @@ export async function getLogsHandler({ platform, appId, deviceId, lines }) {
             const crashLines = logs.filter(l => l.includes('FATAL EXCEPTION'));
             return { device: deviceInfo, logs, crashLines };
         }
-        catch (e) {
+        catch {
             return { device: deviceInfo, logs: [], crashLines: [] };
         }
     }
@@ -37,7 +37,7 @@ export async function startLogStreamHandler({ platform, packageName, level, sess
     }
     else {
         const resolved = await resolveTargetDevice({ platform: 'ios', appId: packageName, deviceId });
-        return await startIOSLogStream(packageName, level || 'error', resolved.id, sid);
+        return await startIOSLogStream(packageName, resolved.id, sid);
     }
 }
 export async function readLogStreamHandler({ platform, sessionId, limit, since }) {

package/dist/tools/observe.js

@@ -0,0 +1,126 @@
+import { resolveTargetDevice, listDevices } from '../resolve-device.js';
+import { AndroidObserve } from '../android/observe.js';
+import { iOSObserve } from '../ios/observe.js';
+import { AndroidInteract } from '../android/interact.js';
+import { iOSInteract } from '../ios/interact.js';
+export class ToolsObserve {
+    static async getLogsHandler({ platform, appId, deviceId, lines }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            const response = await new AndroidObserve().getLogs(appId, lines ?? 200, resolved.id);
+            const logs = Array.isArray(response.logs) ? response.logs : [];
+            const crashLines = logs.filter(line => line.includes('FATAL EXCEPTION'));
+            return { device: response.device, logs, crashLines };
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            const resp = await new iOSObserve().getLogs(appId, resolved.id);
+            const logs = Array.isArray(resp.logs) ? resp.logs : [];
+            const crashLines = logs.filter(l => l.includes('FATAL EXCEPTION'));
+            return { device: resp.device, logs, crashLines };
+        }
+    }
+    static async startLogStreamHandler({ platform, packageName, level, sessionId, deviceId }) {
+        const effectivePlatform = platform || 'android';
+        const sid = sessionId || 'default';
+        if (effectivePlatform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId: packageName, deviceId });
+            // AndroidObserve uses utils for log stream control; delegate to android/utils functions where appropriate
+            const { startAndroidLogStream } = await import('../android/utils.js');
+            return await startAndroidLogStream(packageName, level || 'error', resolved.id, sid);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId: packageName, deviceId });
+            // iOSObserve implements startIOSLogStream via ios/utils; use its helper
+            const { startIOSLogStream } = await import('../ios/utils.js');
+            return await startIOSLogStream(packageName, resolved.id, sid);
+        }
+    }
+    static async readLogStreamHandler({ platform, sessionId, limit, since }) {
+        const effectivePlatform = platform || 'android';
+        const sid = sessionId || 'default';
+        if (effectivePlatform === 'android') {
+            const { readLogStreamLines } = await import('../android/utils.js');
+            return await readLogStreamLines(sid, limit ?? 100, since);
+        }
+        else {
+            const { readIOSLogStreamLines } = await import('../ios/utils.js');
+            return await readIOSLogStreamLines(sid, limit ?? 100, since);
+        }
+    }
+    static async stopLogStreamHandler({ platform, sessionId }) {
+        const effectivePlatform = platform || 'android';
+        const sid = sessionId || 'default';
+        if (effectivePlatform === 'android') {
+            const { stopAndroidLogStream } = await import('../android/utils.js');
+            return await stopAndroidLogStream(sid);
+        }
+        else {
+            const { stopIOSLogStream } = await import('../ios/utils.js');
+            return await stopIOSLogStream(sid);
+        }
+    }
+    static async getUITreeHandler({ platform, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+            return await new AndroidObserve().getUITree(resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
+            return await new iOSObserve().getUITree(resolved.id);
+        }
+    }
+    static async getCurrentScreenHandler({ deviceId }) {
+        const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+        return await new AndroidObserve().getCurrentScreen(resolved.id);
+    }
+    static async waitForElementHandler({ platform, text, timeout, deviceId }) {
+        const effectiveTimeout = timeout ?? 10000;
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+            return await new AndroidInteract().waitForElement(text, effectiveTimeout, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
+            return await new iOSInteract().waitForElement(text, effectiveTimeout, resolved.id);
+        }
+    }
+    static async tapHandler({ platform, x, y, deviceId }) {
+        const effectivePlatform = platform || 'android';
+        if (effectivePlatform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+            return await new AndroidInteract().tap(x, y, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
+            return await new iOSInteract().tap(x, y, resolved.id);
+        }
+    }
+    static async swipeHandler({ x1, y1, x2, y2, duration, deviceId }) {
+        const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+        return await new AndroidInteract().swipe(x1, y1, x2, y2, duration, resolved.id);
+    }
+    static async typeTextHandler({ text, deviceId }) {
+        const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+        return await new AndroidInteract().typeText(text, resolved.id);
+    }
+    static async pressBackHandler({ deviceId }) {
+        const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+        return await new AndroidInteract().pressBack(resolved.id);
+    }
+    static async listDevicesHandler({ platform, appId }) {
+        const devices = await listDevices(platform, appId);
+        return { devices };
+    }
+    static async captureScreenshotHandler({ platform, deviceId }) {
+        const effectivePlatform = platform || 'android';
+        if (effectivePlatform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+            return await new AndroidObserve().captureScreen(resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
+            return await new iOSObserve().captureScreenshot(resolved.id);
+        }
+    }
+}

package/dist/utils/index.js

@@ -0,0 +1 @@
+export { detectJavaHome } from './java.js';

package/dist/utils/java.js

@@ -0,0 +1,76 @@
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import path from 'path';
+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('[java.detect] Existing JAVA_HOME does not appear to be Java 17, will search for JDK17');
+            }
+            catch {
+                console.debug('[java.detect] 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 { }
+    return undefined;
+}

package/docs/CHANGELOG.md

@@ -2,14 +2,29 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
-## [0.9.0] - 2026-03-14
+## [0.10.0]
 
 ### Added / Changed
-- install_app now builds apps when given a project directory and then installs the produced artifact (Android: Gradle wrapper assembleDebug; iOS: xcodebuild where applicable).
-- Auto-detects and prefers JDK 17 (Android Studio JBR or system JDK). Any JAVA_HOME overrides are scoped to the spawned build process, avoiding global system changes.
-- Respects ADB_PATH and falls back to PATH if unset. Set ADB_PATH to an explicit adb binary to avoid PATH discovery issues.
-- Increased default adb timeout to 120s for installs; timeout can be configured via MCP_ADB_TIMEOUT or ADB_TIMEOUT environment variables.
-- Improved logging and error messages for build/install steps. Unit and integration tests updated and converted to TypeScript.
+- Tools refactor: consolidated handlers into ToolsInteract and ToolsObserve classes to centralise tool wiring and simplify platform delegation.
+- install_app now builds project directories (Gradle/xcodebuild) and supports streamed installs with robust fallbacks (adb push + pm install).
+- Added log streaming utilities and improved log parsing/crash detection heuristics.
+- CI: added lint and unit tests for handler parity; updated README links to docs and changelog.
+- Docs: Created docs/TOOLS.md with comprehensive tool definitions and examples.
+
+
+## [0.9.0] 
+
+### Added / Changed
+- install_app now builds apps when given a project directory and then installs the produced artifact (Android: Gradle wrapper assembleDebug; iOS: xcodebuild where applicable). When a workspace (.xcworkspace) is present, the iOS build uses `-workspace` instead of `-project` to support CocoaPods and multi-project setups.
+- Build orchestration uses a scoped JAVA_HOME (detectJavaHome) and prefers JDK 17 when available; Gradle invocations avoid mutating global env and pass java home via `-Dorg.gradle.java.home`.
+- Streaming ADB support: added `spawnAdb()` (streams stdout/stderr and returns exit code) alongside `execAdb()` (returns buffered stdout). This enables live install output and robust fallbacks.
+- Resilient install flow: streamed `adb install` is attempted first; on failure MCP falls back to `adb push` + `pm install -r` to improve reliability on devices that don't support streamed install or when install times out.
+- Centralised timeout logic: extracted `getAdbTimeout(args, customTimeout)` to standardise timeout selection (precedence: custom timeout > MCP_ADB_TIMEOUT/ADB_TIMEOUT env > per-command defaults — install: 120s, logcat: 10s, uiautomator dump: 20s).
+- Improved types: `execAdb` / `spawnAdb` now accept `SpawnOptionsWithTimeout` (typed extension of Node's SpawnOptions with an optional timeout property).
+- Linting and CI: added ESLint (unused-imports plugin), added `npm run lint` / `npm run lint:fix` scripts, and updated CI to run lint in the unit job. ESLint config converted to the flat `eslint.config.js` format.
+- Tests: unit tests updated to exercise real build/install flows using fake `adb` and `gradlew` wrappers; added detectJavaHome smoke tests. Integration workflows remain manual and require device/emulator access.
+- Misc: improved logging, more informative error messages, and several internal cleanups (removed redundant try/catch, consolidated helper functions).
+
 
 ## [0.8.0]
 

package/eslint.config.cjs

@@ -0,0 +1,36 @@
+module.exports = [
+  // Files/directories to ignore
+  {
+    ignores: [
+      'dist/',
+      'node_modules/',
+      '.git/',
+      '.vscode/',
+      'coverage/',
+      '.env'
+    ]
+  },
+  // Apply rules to JS/TS source and tests
+  {
+    files: ['src/**/*.ts', 'test/**/*.ts', 'src/**/*.js', 'test/**/*.js'],
+    languageOptions: {
+      parser: require.resolve('@typescript-eslint/parser'),
+      parserOptions: {
+        ecmaVersion: 2020,
+        sourceType: 'module',
+        project: './tsconfig.json'
+      }
+    },
+    plugins: {
+      '@typescript-eslint': require('@typescript-eslint/eslint-plugin'),
+      'unused-imports': require('eslint-plugin-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'
+    }
+  }
+]

package/eslint.config.js

@@ -0,0 +1,60 @@
+import tsParser from '@typescript-eslint/parser'
+import tsPlugin from '@typescript-eslint/eslint-plugin'
+import unusedImports from 'eslint-plugin-unused-imports'
+
+export default [
+  // Files/directories to ignore
+  {
+    ignores: [
+      'dist/',
+      'node_modules/',
+      '.git/',
+      '.vscode/',
+      'coverage/',
+      '.env'
+    ]
+  },
+  // Apply rules to JS/TS source
+  {
+    files: ['src/**/*.ts', 'src/**/*.js'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 2020,
+        sourceType: 'module',
+        project: './tsconfig.json'
+      }
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin,
+      'unused-imports': unusedImports
+    },
+    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'
+    }
+  },
+  // Apply lighter rules to test files (no project reference to avoid TS project parsing)
+  {
+    files: ['test/**/*.ts', 'test/**/*.js'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 2020,
+        sourceType: 'module'
+      }
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin,
+      'unused-imports': unusedImports
+    },
+    rules: {
+      'unused-imports/no-unused-imports': 'error',
+      'unused-imports/no-unused-vars': ['error', { vars: 'all', args: 'after-used', ignoreRestSiblings: true }],
+      '@typescript-eslint/no-unused-vars': 'off'
+    }
+  }
+]