mobile-debug-mcp 0.19.2 → 0.20.1

package/README.md

@@ -2,7 +2,10 @@
 
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, and inspect Android/iOS apps from an MCP-compatible client.
 
-> **Note:** iOS support is limited currently, Please use with caution and report any issues.
+> **Note:**
+> * iOS only tested on simulator.
+> * Flutter iOS projects not fetching logs
+> * React native not tested
 
 ## Requirements
 
@@ -28,10 +31,9 @@ You will need to add ADB_PATH for Android and XCRUN_PATH and IDB_PATH for iOS.
 
 ## Usage
 
-Example: 
-After a crash tell the agent the following:
-
-I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available
+Examples: 
+* I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available
+* Add a button, hook into the repository and confirm API request successful
 
 ## Docs
 

package/dist/manage/android.js

@@ -64,10 +64,13 @@ export class AndroidManage {
                 const spawnOpts = { cwd: apkPath, env };
                 if (useWrapper) {
                     await fs.chmod(wrapperPath, 0o755).catch(() => { });
+                    // Run wrapper directly to avoid shell splitting of args
+                    spawnOpts.shell = false;
+                }
+                else {
+                    // Execute gradle directly without a shell so paths with spaces are preserved
                     spawnOpts.shell = false;
                 }
-                else
-                    spawnOpts.shell = true;
                 const proc = spawn(execCmd, gradleArgs, spawnOpts);
                 let stderr = '';
                 await new Promise((resolve, reject) => {

package/dist/server.js

@@ -7,10 +7,6 @@ import { ToolsInteract } from './interact/index.js';
 import { ToolsObserve } from './observe/index.js';
 import { AndroidManage } from './manage/index.js';
 import { iOSManage } from './manage/index.js';
-import { ensureAdbAvailable } from './utils/android/utils.js';
-import { getIdbCmd, isIDBInstalled } from './utils/ios/utils.js';
-import { getXcrunCmd } from './utils/ios/utils.js';
-import { execSync } from 'child_process';
 const server = new Server({
     name: "mobile-debug-mcp",
     version: "0.7.0"
@@ -19,50 +15,11 @@ const server = new Server({
         tools: {}
     }
 });
-// Startup healthchecks (non-fatal) — verify adb availability and log chosen command
-(async () => {
-    try {
-        const adbCheck = ensureAdbAvailable();
-        if (adbCheck.ok)
-            console.debug('[startup] adb available:', adbCheck.adbCmd, adbCheck.version);
-        else
-            console.warn('[startup] adb not available or failed to run:', adbCheck.adbCmd, adbCheck.error);
-    }
-    catch (e) {
-        if (e instanceof Error) {
-            console.warn('[startup] error during adb healthcheck:', e.message);
-        }
-        else {
-            console.warn('[startup] error during adb healthcheck:', String(e));
-        }
-    }
-    // Check idb availability (non-fatal)
-    try {
-        const idbInstalled = await isIDBInstalled();
-        const idbCmd = getIdbCmd();
-        if (idbInstalled)
-            console.debug('[startup] idb available:', idbCmd);
-        else
-            console.debug('[startup] idb not available or failed to run:', idbCmd);
-    }
-    catch (e) {
-        console.warn('[startup] error during idb healthcheck:', e instanceof Error ? e.message : String(e));
-    }
-    // Check xcrun availability (non-fatal)
-    try {
-        const xcrun = getXcrunCmd();
-        try {
-            const out = execSync(`${xcrun} --version`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
-            console.debug('[startup] xcrun available:', xcrun, out.split('\n')[0]);
-        }
-        catch (err) {
-            console.warn('[startup] xcrun not available or failed to run:', xcrun, err instanceof Error ? err.message : String(err));
-        }
-    }
-    catch (e) {
-        console.warn('[startup] error during xcrun healthcheck:', e instanceof Error ? e.message : String(e));
-    }
-})();
+import { getSystemStatus } from './system/index.js';
+// Run a quick startup healthcheck (non-fatal) by calling getSystemStatus directly and log a short summary
+getSystemStatus().then(res => {
+    console.debug('[startup] system status summary:', { adb: res.adbAvailable, ios: res.iosAvailable, devices: res.devices, iosDevices: res.iosDevices });
+}).catch(e => console.warn('[startup] healthcheck failed:', e instanceof Error ? e.message : String(e)));
 function wrapResponse(data) {
     return {
         content: [{
@@ -225,6 +182,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 }
             }
         },
+        {
+            name: "get_system_status",
+            description: "Quick healthcheck of local mobile debugging environment (adb, devices, logs, env, iOS).",
+            inputSchema: { type: "object", properties: {} }
+        },
         {
             name: "capture_screenshot",
             description: "Capture a screenshot from an Android device or iOS simulator. Returns device metadata and the screenshot image.",
@@ -625,6 +587,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const res = await ToolsManage.listDevicesHandler({ platform, appId });
             return wrapResponse(res);
         }
+        if (name === "get_system_status") {
+            const result = await getSystemStatus();
+            return wrapResponse(result);
+        }
         if (name === "capture_screenshot") {
             const { platform, deviceId } = args;
             const res = await ToolsObserve.captureScreenshotHandler({ platform, deviceId });

package/dist/system/android.js

@@ -0,0 +1,78 @@
+import { execSync } from 'child_process';
+import { ensureAdbAvailable } from '../utils/android/utils.js';
+export async function checkAndroid() {
+    const issues = [];
+    let adbAvailable = false;
+    let adbVersion = '';
+    let devices = 0;
+    let deviceStates = '';
+    let logsAvailable = false;
+    let envValid = false;
+    let appInstalled = undefined;
+    try {
+        const adbCheck = ensureAdbAvailable();
+        const adbCmd = adbCheck.adbCmd || 'adb';
+        adbAvailable = !!adbCheck.ok;
+        adbVersion = (adbCheck.version || '').toString().split('\n')[0];
+        if (!adbAvailable)
+            issues.push('ADB not available');
+        try {
+            const out = execSync(`${adbCmd} devices -l`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+            const lines = out.split('\n').map(l => l.trim()).filter(Boolean);
+            const deviceLines = lines.filter(l => !l.startsWith('List of devices'));
+            const stateCounts = {};
+            for (const l of deviceLines) {
+                const parts = l.split(/\s+/);
+                const state = parts[1] || '';
+                stateCounts[state] = (stateCounts[state] || 0) + 1;
+            }
+            devices = deviceLines.length;
+            const parts = Object.entries(stateCounts).map(([k, v]) => `${v} ${k}`);
+            deviceStates = parts.join(', ');
+            if (devices === 0)
+                issues.push('No Android devices connected');
+            if (stateCounts['unauthorized'])
+                issues.push(`${stateCounts['unauthorized']} device(s) unauthorized`);
+            if (stateCounts['offline'])
+                issues.push(`${stateCounts['offline']} device(s) offline`);
+        }
+        catch (e) {
+            console.debug('[get_system_status] adb devices failed: ' + String(e));
+            issues.push('Failed to list Android devices');
+        }
+        if (adbAvailable && devices > 0) {
+            try {
+                const lo = execSync(`${adbCmd} logcat -d -t 1`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+                logsAvailable = !!lo;
+                if (!logsAvailable)
+                    issues.push('Log access failed');
+            }
+            catch (e) {
+                logsAvailable = false;
+                console.debug('[get_system_status] logcat check failed: ' + String(e));
+            }
+        }
+        const sdkRoot = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME;
+        envValid = !!sdkRoot || (adbAvailable === true && !!(adbCheck.adbCmd && adbCheck.adbCmd !== 'adb'));
+        if (!envValid)
+            issues.push('ANDROID_SDK_ROOT/ANDROID_HOME missing and adb not found in PATH');
+        const pkg = process.env.MCP_TARGET_PACKAGE || process.env.MCP_TARGET_APP_ID;
+        if (pkg && adbAvailable && devices > 0) {
+            try {
+                const pm = execSync(`${adbCmd} shell pm path ${pkg}`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+                appInstalled = (pm || '').includes('package:');
+                if (!appInstalled)
+                    issues.push(`App ${pkg} not installed on devices`);
+            }
+            catch (e) {
+                appInstalled = false;
+                console.debug('[get_system_status] pm check failed: ' + String(e));
+            }
+        }
+    }
+    catch (e) {
+        console.debug('[get_system_status] adb availability check failed: ' + String(e));
+        issues.push('ADB check failed');
+    }
+    return { adbAvailable, adbVersion, devices, deviceStates, logsAvailable, envValid, appInstalled, issues };
+}

package/dist/system/gradle.js

@@ -0,0 +1,101 @@
+import { readFileSync, existsSync } from 'fs';
+import path from 'path';
+import os from 'os';
+function readPropertiesFile(p) {
+    try {
+        const txt = readFileSync(p, { encoding: 'utf8' });
+        const lines = String(txt).split(/\r?\n/);
+        const out = {};
+        for (const l of lines) {
+            const trimmed = l.trim();
+            if (!trimmed || trimmed.startsWith('#'))
+                continue;
+            const idx = trimmed.indexOf('=');
+            if (idx === -1)
+                continue;
+            const k = trimmed.substring(0, idx).trim();
+            const v = trimmed.substring(idx + 1).trim();
+            out[k] = v;
+        }
+        return out;
+    }
+    catch (e) {
+        return {};
+    }
+}
+function javaBinExists(p) {
+    if (!p)
+        return false;
+    try {
+        const javaPath = path.join(p, 'bin', 'java');
+        if (existsSync(javaPath))
+            return true;
+        const alt = path.join(p, 'Contents', 'Home', 'bin', 'java');
+        if (existsSync(alt))
+            return true;
+        return false;
+    }
+    catch (e) {
+        return false;
+    }
+}
+export async function checkGradle() {
+    const issues = [];
+    const filesChecked = [];
+    const suggestedFixes = [];
+    let gradleJavaHome;
+    // 1) explicit env
+    if (process.env.GRADLE_JAVA_HOME) {
+        gradleJavaHome = process.env.GRADLE_JAVA_HOME;
+        if (!javaBinExists(gradleJavaHome)) {
+            issues.push(`GRADLE_JAVA_HOME is set to '${gradleJavaHome}' but no java binary was found there`);
+            suggestedFixes.push('Unset GRADLE_JAVA_HOME or point it to a valid JDK (e.g., /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home)');
+        }
+    }
+    // 2) user gradle.properties
+    const gradleUserHome = process.env.GRADLE_USER_HOME || path.join(os.homedir(), '.gradle');
+    const userProps = path.join(gradleUserHome, 'gradle.properties');
+    filesChecked.push(userProps);
+    try {
+        const props = readPropertiesFile(userProps);
+        if (props['org.gradle.java.home']) {
+            const p = props['org.gradle.java.home'];
+            gradleJavaHome = gradleJavaHome || p;
+            if (!javaBinExists(p)) {
+                issues.push(`org.gradle.java.home in ${userProps} points to '${p}' which does not look like a valid JDK`);
+                suggestedFixes.push(`Edit ${userProps} to remove or correct org.gradle.java.home`);
+            }
+        }
+    }
+    catch (e) { /* ignore */ }
+    // 3) system gradle.properties
+    const systemProps = '/etc/gradle/gradle.properties';
+    filesChecked.push(systemProps);
+    try {
+        const props = readPropertiesFile(systemProps);
+        if (props['org.gradle.java.home']) {
+            const p = props['org.gradle.java.home'];
+            gradleJavaHome = gradleJavaHome || p;
+            if (!javaBinExists(p)) {
+                issues.push(`org.gradle.java.home in ${systemProps} points to '${p}' which does not look like a valid JDK`);
+                suggestedFixes.push(`Edit ${systemProps} to remove or correct org.gradle.java.home`);
+            }
+        }
+    }
+    catch (e) { /* ignore */ }
+    // 4) GRADLE_HOME fallback
+    if (!gradleJavaHome && process.env.GRADLE_HOME) {
+        filesChecked.push(process.env.GRADLE_HOME);
+        if (javaBinExists(process.env.GRADLE_HOME)) {
+            gradleJavaHome = process.env.GRADLE_HOME;
+        }
+    }
+    const gradleValid = !!gradleJavaHome && javaBinExists(gradleJavaHome);
+    if (!gradleJavaHome) {
+        // no explicit gradle java home detected — not an issue
+    }
+    else if (!gradleValid) {
+        issues.push(`Detected org.gradle.java.home = '${gradleJavaHome}' but it is invalid`);
+    }
+    return { gradleJavaHome, gradleValid, filesChecked, issues, suggestedFixes };
+}

package/dist/system/index.js

@@ -0,0 +1,32 @@
+import { checkAndroid } from './android.js';
+import { checkIOS } from './ios.js';
+import { checkGradle } from './gradle.js';
+export async function getSystemStatus() {
+    try {
+        const android = await checkAndroid();
+        const ios = await checkIOS();
+        const gradle = await checkGradle();
+        const issues = [...android.issues, ...ios.issues, ...(gradle.issues || [])];
+        const success = issues.length === 0;
+        return {
+            success,
+            adbAvailable: android.adbAvailable,
+            adbVersion: android.adbVersion,
+            devices: android.devices,
+            deviceStates: android.deviceStates,
+            logsAvailable: android.logsAvailable,
+            envValid: android.envValid,
+            issues,
+            appInstalled: android.appInstalled,
+            iosAvailable: ios.iosAvailable,
+            iosDevices: ios.iosDevices,
+            gradleJavaHome: gradle.gradleJavaHome,
+            gradleValid: gradle.gradleValid,
+            gradleFilesChecked: gradle.filesChecked,
+            gradleSuggestedFixes: gradle.suggestedFixes
+        };
+    }
+    catch (e) {
+        return { success: false, issues: ['Internal error: ' + (e instanceof Error ? e.message : String(e))] };
+    }
+}

package/dist/system/ios.js

@@ -0,0 +1,38 @@
+import { execSync } from 'child_process';
+import { getXcrunCmd } from '../utils/ios/utils.js';
+export async function checkIOS() {
+    const issues = [];
+    let iosAvailable = false;
+    let iosDevices = 0;
+    try {
+        const xcrun = getXcrunCmd();
+        try {
+            execSync(`${xcrun} --version`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500 });
+            iosAvailable = true;
+            try {
+                const simOut = execSync(`${xcrun} simctl list devices booted --json`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] });
+                const data = JSON.parse(simOut);
+                let count = 0;
+                for (const k in data.devices) {
+                    const arr = data.devices[k];
+                    if (Array.isArray(arr))
+                        count += arr.filter((d) => (d.state || '').toLowerCase() === 'booted').length;
+                }
+                iosDevices = count;
+                if (iosDevices === 0)
+                    issues.push('No iOS simulators/devices booted');
+            }
+            catch (e) {
+                console.debug('[get_system_status] simctl list failed: ' + String(e));
+            }
+        }
+        catch (e) {
+            iosAvailable = false;
+            console.debug('[get_system_status] xcrun --version failed: ' + String(e));
+        }
+    }
+    catch (e) {
+        console.debug('[get_system_status] xcrun check failed: ' + String(e));
+    }
+    return { iosAvailable, iosDevices, issues };
+}

package/dist/utils/android/utils.js

@@ -3,6 +3,7 @@ import path from 'path';
 import { detectJavaHome } from '../java.js';
 import { execCmd } from '../exec.js';
 import { spawnSync } from 'child_process';
+import { checkGradle } from '../../system/gradle.js';
 function findInPath(cmd) {
     try {
         // prefer command -v for POSIX
@@ -76,6 +77,14 @@ export async function prepareGradle(projectPath) {
         gradleArgs.push('-Dorg.gradle.caching=false');
     }
     const detectedJavaHome = await detectJavaHome().catch(() => undefined);
+    // Check for problematic org.gradle.java.home entries (env or properties) and avoid passing invalid values to Gradle
+    let gradleCheck;
+    try {
+        gradleCheck = await checkGradle();
+    }
+    catch (e) {
+        gradleCheck = { gradleJavaHome: undefined, gradleValid: false, filesChecked: [], issues: [] };
+    }
     const env = Object.assign({}, process.env);
     // Ensure child processes can find Android platform-tools (adb, etc.) by
     // prepending the platform-tools directory to PATH for spawned processes.
@@ -90,6 +99,7 @@ export async function prepareGradle(projectPath) {
         console.debug(`[prepareGradle] error resolving adbPath: ${String(e)}`);
     }
     const pathParts = [];
+    // Prefer a detected (validated) Java home from the system/IDE
     if (detectedJavaHome) {
         if (env.JAVA_HOME !== detectedJavaHome) {
             env.JAVA_HOME = detectedJavaHome;
@@ -100,6 +110,26 @@ export async function prepareGradle(projectPath) {
         gradleArgs.push('--no-daemon');
         env.GRADLE_JAVA_HOME = detectedJavaHome;
     }
+    else if (gradleCheck && gradleCheck.gradleJavaHome) {
+        // There's an org.gradle.java.home configured somewhere (env or gradle.properties)
+        if (gradleCheck.gradleValid) {
+            const p = gradleCheck.gradleJavaHome;
+            const javaBin = path.join(p, 'bin');
+            if (!env.PATH || !env.PATH.includes(javaBin))
+                pathParts.push(javaBin);
+            gradleArgs.push(`-Dorg.gradle.java.home=${p}`);
+            gradleArgs.push('--no-daemon');
+            env.GRADLE_JAVA_HOME = p;
+        }
+        else {
+            // Invalid gradle java home detected: avoid passing it to Gradle and remove from spawn env
+            console.debug(`[prepareGradle] Invalid org.gradle.java.home detected (${gradleCheck.gradleJavaHome}); removing from spawn env to avoid Gradle error.`);
+            try {
+                delete env.GRADLE_JAVA_HOME;
+            }
+            catch (e) { }
+        }
+    }
     if (platformToolsDir) {
         // Prepend platform-tools so gradle and child tools find adb without modifying global env
         if (!env.PATH || !env.PATH.includes(platformToolsDir)) {
@@ -138,10 +168,12 @@ export async function prepareGradle(projectPath) {
         catch (e) {
             console.debug('[prepareGradle] chmod failed for gradlew:', String(e));
         }
+        // Execute the wrapper directly without a shell to avoid shell tokenization of args (spaces in paths)
         spawnOpts.shell = false;
     }
     else {
-        spawnOpts.shell = true;
+        // Prefer executing gradle directly without invoking a shell to preserve argument boundaries
+        spawnOpts.shell = false;
     }
     return { execCmd, gradleArgs, spawnOpts };
 }

package/docs/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.20.1]
+- Fixes gradle home issue for android
+
+## [0.20.0]
+- Added `get_system_status` tool and refactored system health checks into `src/system`.
+  - Provides a fast environment healthcheck (ADB availability/version, connected devices, log access, Android env vars, and basic iOS xcrun/simulator checks).
+  - Designed to be fast, non-throwing, and to gate agent actions early. Unit tests added.
+
+
 ## [0.19.2]
 - Added healthcheck improvments
 - Added skills 

package/docs/tools/TOOLS.md

@@ -7,5 +7,6 @@ See:
 - [mange](manage.md) — build, install and device management tools
 - [observe](observe.md) — logs, screenshots and UI inspection tools
 - [interact](interact.md) — UI interaction tools (tap, swipe, type, wait)
+- [system](system.md) — environment and health checks (get_system_status)
 
 For per-tool deep dives, open the linked files above.

package/docs/tools/system.md

@@ -0,0 +1,48 @@
+# System (environment & health checks)
+
+Tools that provide a lightweight view of the local mobile debugging environment and surface issues early so agents can decide whether to proceed.
+
+## get_system_status
+A fast, non-throwing healthcheck that inspects key dependencies and connections required for mobile debugging.
+
+Input:
+
+```
+{}
+```
+
+Response (example):
+
+```json
+{
+  "success": true,
+  "adbAvailable": true,
+  "adbVersion": "8.1.0",
+  "devices": 1,
+  "deviceStates": "1 device",
+  "logsAvailable": true,
+  "envValid": true,
+  "issues": [],
+  "appInstalled": true,
+  "iosAvailable": true,
+  "iosDevices": 1
+}
+```
+
+Checks performed (fast, best-effort):
+- ADB availability and version (adb --version)
+- Connected Android devices (adb devices -l), counts and state summary (device/unauthorized/offline)
+- Log access probe (adb logcat -d -t 1)
+- Android environment variables (ANDROID_SDK_ROOT / ANDROID_HOME / PATH contains adb)
+- Optional: app installation check if MCP_TARGET_PACKAGE/MCP_TARGET_APP_ID is set (pm path)
+- Basic iOS checks (xcrun --version and simctl list devices booted)
+
+Behavior notes:
+- Always returns structured JSON and never throws; any failures are surfaced in the `issues` array.
+- Designed to be fast (<~1s probes where possible); startup callers may prefer a `fastMode` variant that only checks existence.
+- Useful to call at the start of an agent session to gate subsequent actions.
+
+Usage guidance:
+- Call before build/install flows to avoid wasted build attempts on misconfigured systems.
+- If `success: false`, attempt recovery steps or report issues to the user.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.19.2",
+  "version": "0.20.1",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/src/manage/android.ts

@@ -64,8 +64,12 @@ export class AndroidManage {
         const spawnOpts: any = { cwd: apkPath, env }
         if (useWrapper) {
           await fs.chmod(wrapperPath, 0o755).catch(() => {})
+          // Run wrapper directly to avoid shell splitting of args
           spawnOpts.shell = false
-        } else spawnOpts.shell = true
+        } else {
+          // Execute gradle directly without a shell so paths with spaces are preserved
+          spawnOpts.shell = false
+        }
 
         const proc = spawn(execCmd, gradleArgs, spawnOpts)
         let stderr = ''

package/src/server.ts

@@ -20,10 +20,6 @@ import { ToolsInteract } from './interact/index.js'
 import { ToolsObserve } from './observe/index.js'
 import { AndroidManage } from './manage/index.js'
 import { iOSManage } from './manage/index.js'
-import { ensureAdbAvailable } from './utils/android/utils.js'
-import { getIdbCmd, isIDBInstalled } from './utils/ios/utils.js'
-import { getXcrunCmd } from './utils/ios/utils.js'
-import { execSync } from 'child_process'
 
 
 const server = new Server(
@@ -38,44 +34,12 @@ const server = new Server(
   }
 );
 
-// Startup healthchecks (non-fatal) — verify adb availability and log chosen command
-(async () => {
-  try {
-    const adbCheck = ensureAdbAvailable()
-    if (adbCheck.ok) console.debug('[startup] adb available:', adbCheck.adbCmd, adbCheck.version)
-    else console.warn('[startup] adb not available or failed to run:', adbCheck.adbCmd, adbCheck.error)
-  } catch (e: unknown) {
-    if (e instanceof Error) {
-      console.warn('[startup] error during adb healthcheck:', e.message)
-    } else {
-      console.warn('[startup] error during adb healthcheck:', String(e))
-    }
-  }
-
-  // Check idb availability (non-fatal)
-  try {
-    const idbInstalled = await isIDBInstalled()
-    const idbCmd = getIdbCmd()
-    if (idbInstalled) console.debug('[startup] idb available:', idbCmd)
-    else console.debug('[startup] idb not available or failed to run:', idbCmd)
-  } catch (e: unknown) {
-    console.warn('[startup] error during idb healthcheck:', e instanceof Error ? e.message : String(e))
-  }
-
-  // Check xcrun availability (non-fatal)
-  try {
-    const xcrun = getXcrunCmd()
-    try {
-      const out = execSync(`${xcrun} --version`, { stdio: ['ignore','pipe','ignore'] }).toString().trim()
-      console.debug('[startup] xcrun available:', xcrun, out.split('\n')[0])
-    } catch (err: unknown) {
-      console.warn('[startup] xcrun not available or failed to run:', xcrun, err instanceof Error ? err.message : String(err))
-    }
-  } catch (e: unknown) {
-    console.warn('[startup] error during xcrun healthcheck:', e instanceof Error ? e.message : String(e))
-  }
+import { getSystemStatus } from './system/index.js'
 
-})()
+// Run a quick startup healthcheck (non-fatal) by calling getSystemStatus directly and log a short summary
+getSystemStatus().then(res => {
+  console.debug('[startup] system status summary:', { adb: res.adbAvailable, ios: res.iosAvailable, devices: res.devices, iosDevices: res.iosDevices })
+}).catch(e => console.warn('[startup] healthcheck failed:', e instanceof Error ? e.message : String(e)))
 
 function wrapResponse<T>(data: T) {
   return {
@@ -241,6 +205,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         }
       }
     },
+    {
+      name: "get_system_status",
+      description: "Quick healthcheck of local mobile debugging environment (adb, devices, logs, env, iOS).",
+      inputSchema: { type: "object", properties: {} }
+    },
     {
       name: "capture_screenshot",
       description: "Capture a screenshot from an Android device or iOS simulator. Returns device metadata and the screenshot image.",
@@ -658,6 +627,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typ
       return wrapResponse(res)
     }
 
+    if (name === "get_system_status") {
+      const result = await getSystemStatus()
+      return wrapResponse(result)
+    }
+
 
     if (name === "capture_screenshot") {
       const { platform, deviceId } = args as any

package/src/system/android.ts

@@ -0,0 +1,62 @@
+import { execSync } from 'child_process'
+import { ensureAdbAvailable } from '../utils/android/utils.js'
+
+export async function checkAndroid() {
+  const issues: string[] = []
+  let adbAvailable = false
+  let adbVersion = ''
+  let devices = 0
+  let deviceStates = ''
+  let logsAvailable = false
+  let envValid = false
+  let appInstalled: boolean | undefined = undefined
+
+  try {
+    const adbCheck = ensureAdbAvailable()
+    const adbCmd = adbCheck.adbCmd || 'adb'
+    adbAvailable = !!adbCheck.ok
+    adbVersion = (adbCheck.version || '').toString().split('\n')[0]
+    if (!adbAvailable) issues.push('ADB not available')
+
+    try {
+      const out = execSync(`${adbCmd} devices -l`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore','pipe','ignore'] }).toString()
+      const lines = out.split('\n').map(l => l.trim()).filter(Boolean)
+      const deviceLines = lines.filter(l => !l.startsWith('List of devices'))
+      const stateCounts: Record<string, number> = {}
+      for (const l of deviceLines) {
+        const parts = l.split(/\s+/)
+        const state = parts[1] || ''
+        stateCounts[state] = (stateCounts[state] || 0) + 1
+      }
+      devices = deviceLines.length
+      const parts = Object.entries(stateCounts).map(([k,v]) => `${v} ${k}`)
+      deviceStates = parts.join(', ')
+      if (devices === 0) issues.push('No Android devices connected')
+      if (stateCounts['unauthorized']) issues.push(`${stateCounts['unauthorized']} device(s) unauthorized`)
+      if (stateCounts['offline']) issues.push(`${stateCounts['offline']} device(s) offline`)
+    } catch (e: unknown) { console.debug('[get_system_status] adb devices failed: ' + String(e)); issues.push('Failed to list Android devices') }
+
+    if (adbAvailable && devices > 0) {
+      try {
+        const lo = execSync(`${adbCmd} logcat -d -t 1`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore','pipe','ignore'] }).toString()
+        logsAvailable = !!lo
+        if (!logsAvailable) issues.push('Log access failed')
+      } catch (e: unknown) { logsAvailable = false; console.debug('[get_system_status] logcat check failed: ' + String(e)) }
+    }
+
+    const sdkRoot = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME
+    envValid = !!sdkRoot || (adbAvailable === true && !!(adbCheck.adbCmd && adbCheck.adbCmd !== 'adb'))
+    if (!envValid) issues.push('ANDROID_SDK_ROOT/ANDROID_HOME missing and adb not found in PATH')
+
+    const pkg = process.env.MCP_TARGET_PACKAGE || process.env.MCP_TARGET_APP_ID
+    if (pkg && adbAvailable && devices > 0) {
+      try {
+        const pm = execSync(`${adbCmd} shell pm path ${pkg}`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore','pipe','ignore'] }).toString()
+        appInstalled = (pm || '').includes('package:')
+        if (!appInstalled) issues.push(`App ${pkg} not installed on devices`)
+      } catch (e: unknown) { appInstalled = false; console.debug('[get_system_status] pm check failed: ' + String(e)) }
+    }
+  } catch (e: unknown) { console.debug('[get_system_status] adb availability check failed: ' + String(e)); issues.push('ADB check failed') }
+
+  return { adbAvailable, adbVersion, devices, deviceStates, logsAvailable, envValid, appInstalled, issues }
+}

package/src/system/gradle.ts

@@ -0,0 +1,98 @@
+import { readFileSync, existsSync } from 'fs'
+import path from 'path'
+import os from 'os'
+
+function readPropertiesFile(p: string): Record<string,string> {
+  try {
+    const txt = readFileSync(p, { encoding: 'utf8' })
+    const lines = String(txt).split(/\r?\n/)
+    const out: Record<string,string> = {}
+    for (const l of lines) {
+      const trimmed = l.trim()
+      if (!trimmed || trimmed.startsWith('#')) continue
+      const idx = trimmed.indexOf('=')
+      if (idx === -1) continue
+      const k = trimmed.substring(0, idx).trim()
+      const v = trimmed.substring(idx+1).trim()
+      out[k] = v
+    }
+    return out
+  } catch (e: unknown) {
+    return {}
+  }
+}
+
+function javaBinExists(p?: string): boolean {
+  if (!p) return false
+  try {
+    const javaPath = path.join(p, 'bin', 'java')
+    if (existsSync(javaPath)) return true
+    const alt = path.join(p, 'Contents', 'Home', 'bin', 'java')
+    if (existsSync(alt)) return true
+    return false
+  } catch (e: unknown) { return false }
+}
+
+export async function checkGradle(): Promise<{ gradleJavaHome?: string; gradleValid: boolean; filesChecked: string[]; issues: string[]; suggestedFixes?: string[] }> {
+  const issues: string[] = []
+  const filesChecked: string[] = []
+  const suggestedFixes: string[] = []
+  let gradleJavaHome: string | undefined
+
+  // 1) explicit env
+  if (process.env.GRADLE_JAVA_HOME) {
+    gradleJavaHome = process.env.GRADLE_JAVA_HOME
+    if (!javaBinExists(gradleJavaHome)) {
+      issues.push(`GRADLE_JAVA_HOME is set to '${gradleJavaHome}' but no java binary was found there`)
+      suggestedFixes.push('Unset GRADLE_JAVA_HOME or point it to a valid JDK (e.g., /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home)')
+    }
+  }
+
+  // 2) user gradle.properties
+  const gradleUserHome = process.env.GRADLE_USER_HOME || path.join(os.homedir(), '.gradle')
+  const userProps = path.join(gradleUserHome, 'gradle.properties')
+  filesChecked.push(userProps)
+  try {
+    const props = readPropertiesFile(userProps)
+    if (props['org.gradle.java.home']) {
+      const p = props['org.gradle.java.home']
+      gradleJavaHome = gradleJavaHome || p
+      if (!javaBinExists(p)) {
+        issues.push(`org.gradle.java.home in ${userProps} points to '${p}' which does not look like a valid JDK`)
+        suggestedFixes.push(`Edit ${userProps} to remove or correct org.gradle.java.home`)
+      }
+    }
+  } catch (e: unknown) { /* ignore */ }
+
+  // 3) system gradle.properties
+  const systemProps = '/etc/gradle/gradle.properties'
+  filesChecked.push(systemProps)
+  try {
+    const props = readPropertiesFile(systemProps)
+    if (props['org.gradle.java.home']) {
+      const p = props['org.gradle.java.home']
+      gradleJavaHome = gradleJavaHome || p
+      if (!javaBinExists(p)) {
+        issues.push(`org.gradle.java.home in ${systemProps} points to '${p}' which does not look like a valid JDK`)
+        suggestedFixes.push(`Edit ${systemProps} to remove or correct org.gradle.java.home`)
+      }
+    }
+  } catch (e: unknown) { /* ignore */ }
+
+  // 4) GRADLE_HOME fallback
+  if (!gradleJavaHome && process.env.GRADLE_HOME) {
+    filesChecked.push(process.env.GRADLE_HOME)
+    if (javaBinExists(process.env.GRADLE_HOME)) {
+      gradleJavaHome = process.env.GRADLE_HOME
+    }
+  }
+
+  const gradleValid = !!gradleJavaHome && javaBinExists(gradleJavaHome)
+  if (!gradleJavaHome) {
+    // no explicit gradle java home detected — not an issue
+  } else if (!gradleValid) {
+    issues.push(`Detected org.gradle.java.home = '${gradleJavaHome}' but it is invalid`)
+  }
+
+  return { gradleJavaHome, gradleValid, filesChecked, issues, suggestedFixes }
+}

package/src/system/index.ts

@@ -0,0 +1,33 @@
+import { checkAndroid } from './android.js'
+import { checkIOS } from './ios.js'
+import { checkGradle } from './gradle.js'
+
+export async function getSystemStatus() {
+  try {
+    const android = await checkAndroid()
+    const ios = await checkIOS()
+    const gradle = await checkGradle()
+    const issues = [...android.issues, ...ios.issues, ...(gradle.issues || [])]
+
+    const success = issues.length === 0
+    return {
+      success,
+      adbAvailable: android.adbAvailable,
+      adbVersion: android.adbVersion,
+      devices: android.devices,
+      deviceStates: android.deviceStates,
+      logsAvailable: android.logsAvailable,
+      envValid: android.envValid,
+      issues,
+      appInstalled: android.appInstalled,
+      iosAvailable: ios.iosAvailable,
+      iosDevices: ios.iosDevices,
+      gradleJavaHome: gradle.gradleJavaHome,
+      gradleValid: gradle.gradleValid,
+      gradleFilesChecked: gradle.filesChecked,
+      gradleSuggestedFixes: gradle.suggestedFixes
+    }
+  } catch (e: unknown) {
+    return { success: false, issues: ['Internal error: ' + (e instanceof Error ? e.message : String(e))] }
+  }
+}

package/src/system/ios.ts

@@ -0,0 +1,28 @@
+import { execSync } from 'child_process'
+import { getXcrunCmd } from '../utils/ios/utils.js'
+
+export async function checkIOS() {
+  const issues: string[] = []
+  let iosAvailable = false
+  let iosDevices = 0
+  try {
+    const xcrun = getXcrunCmd()
+    try {
+      execSync(`${xcrun} --version`, { stdio: ['ignore','pipe','ignore'], timeout: 1500 })
+      iosAvailable = true
+      try {
+        const simOut = execSync(`${xcrun} simctl list devices booted --json`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore','pipe','ignore'] })
+        const data = JSON.parse(simOut)
+        type SimDevice = { state?: string }
+        let count = 0
+        for (const k in data.devices) {
+          const arr = data.devices[k]
+          if (Array.isArray(arr)) count += arr.filter((d: SimDevice) => (d.state || '').toLowerCase() === 'booted').length
+        }
+        iosDevices = count
+        if (iosDevices === 0) issues.push('No iOS simulators/devices booted')
+      } catch (e: unknown) { console.debug('[get_system_status] simctl list failed: ' + String(e)) }
+    } catch (e: unknown) { iosAvailable = false; console.debug('[get_system_status] xcrun --version failed: ' + String(e)) }
+  } catch (e: unknown) { console.debug('[get_system_status] xcrun check failed: ' + String(e)) }
+  return { iosAvailable, iosDevices, issues }
+}

package/src/utils/android/utils.ts

@@ -4,6 +4,7 @@ import path from 'path'
 import { detectJavaHome } from '../java.js'
 import { execCmd } from '../exec.js'
 import { spawnSync } from 'child_process'
+import { checkGradle } from '../../system/gradle.js'
 
 function findInPath(cmd: string): string | null {
   try {
@@ -73,6 +74,14 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
   }
 
   const detectedJavaHome = await detectJavaHome().catch(() => undefined)
+  // Check for problematic org.gradle.java.home entries (env or properties) and avoid passing invalid values to Gradle
+  let gradleCheck
+  try {
+    gradleCheck = await checkGradle()
+  } catch (e: unknown) {
+    gradleCheck = { gradleJavaHome: undefined, gradleValid: false, filesChecked: [], issues: [] }
+  }
+
   const env = Object.assign({}, process.env)
 
   // Ensure child processes can find Android platform-tools (adb, etc.) by
@@ -86,6 +95,7 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
   } catch (e: unknown) { console.debug(`[prepareGradle] error resolving adbPath: ${String(e)}`) }
 
   const pathParts: string[] = []
+  // Prefer a detected (validated) Java home from the system/IDE
   if (detectedJavaHome) {
     if (env.JAVA_HOME !== detectedJavaHome) {
       env.JAVA_HOME = detectedJavaHome
@@ -95,6 +105,20 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
     gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`)
     gradleArgs.push('--no-daemon')
     env.GRADLE_JAVA_HOME = detectedJavaHome
+  } else if (gradleCheck && gradleCheck.gradleJavaHome) {
+    // There's an org.gradle.java.home configured somewhere (env or gradle.properties)
+    if (gradleCheck.gradleValid) {
+      const p = gradleCheck.gradleJavaHome as string
+      const javaBin = path.join(p, 'bin')
+      if (!env.PATH || !env.PATH.includes(javaBin)) pathParts.push(javaBin)
+      gradleArgs.push(`-Dorg.gradle.java.home=${p}`)
+      gradleArgs.push('--no-daemon')
+      env.GRADLE_JAVA_HOME = p
+    } else {
+      // Invalid gradle java home detected: avoid passing it to Gradle and remove from spawn env
+      console.debug(`[prepareGradle] Invalid org.gradle.java.home detected (${gradleCheck.gradleJavaHome}); removing from spawn env to avoid Gradle error.`)
+      try { delete env.GRADLE_JAVA_HOME } catch (e: unknown) { }
+    }
   }
 
   if (platformToolsDir) {
@@ -126,9 +150,11 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
   const spawnOpts: any = { cwd: projectPath, env }
   if (useWrapper) {
     try { await fsPromises.chmod(gradlewPath, 0o755) } catch (e: unknown) { console.debug('[prepareGradle] chmod failed for gradlew:', String(e)) }
+    // Execute the wrapper directly without a shell to avoid shell tokenization of args (spaces in paths)
     spawnOpts.shell = false
   } else {
-    spawnOpts.shell = true
+    // Prefer executing gradle directly without invoking a shell to preserve argument boundaries
+    spawnOpts.shell = false
   }
 
   return { execCmd, gradleArgs, spawnOpts }

package/test/system/adb_version.test.ts

@@ -0,0 +1,25 @@
+import assert from 'assert'
+import * as androidUtils from '../../src/utils/android/utils.js'
+import * as systemStatus from '../../src/system/index.js'
+
+const origEnsure = (androidUtils as any).ensureAdbAvailable
+
+function mockEnsure(returnVal: any) {
+  (androidUtils as any).ensureAdbAvailable = () => returnVal
+}
+
+function restoreEnsure() {
+  (androidUtils as any).ensureAdbAvailable = origEnsure
+}
+
+describe('adb version parsing', () => {
+  afterEach(() => {
+    restoreEnsure()
+  })
+
+  it('uses only the first line of multi-line adb --version output', async () => {
+    mockEnsure({ adbCmd: 'adb', ok: true, version: 'Android Debug Bridge version 1.0.41\nRevision 8f3b7' })
+    const res = await systemStatus.getSystemStatus()
+    assert.strictEqual(res.adbVersion, 'Android Debug Bridge version 1.0.41')
+  })
+})

package/test/system/get_system_status.test.ts

@@ -0,0 +1,52 @@
+import assert from 'assert'
+import { ensureAdbAvailable } from '../../src/utils/android/utils.js'
+import { getXcrunCmd } from '../../src/utils/ios/utils.js'
+
+// We import the server handler module to access the internal get_system_status implementation.
+import * as server from '../../src/server.js'
+
+// Small helper to call the tool handler similarly to how the MCP transport would.
+async function callGetSystemStatus() {
+  const req = { params: { name: 'get_system_status', arguments: {} } }
+  // @ts-ignore - use the handler exported from server
+  const handler = (server as any).defaultRequestHandler || (server as any).callToolHandler || (server as any).__callTool
+  if (!handler) {
+    // fallback: require the module and call the exported server instance's request handler
+    // The server code registers the handler directly; we will emulate by requiring compiled code in dist if available.
+    try {
+      const dist = await import('../../dist/server.js')
+      // Try to execute by sending a call via the server instance if exported
+      if (dist && dist.server && typeof dist.server._handleCall === 'function') {
+        return dist.server._handleCall(req)
+      }
+    } catch {
+      // best effort only
+    }
+    throw new Error('Cannot locate server call handler for tests')
+  }
+
+  return handler(req)
+}
+
+describe('get_system_status tool (unit)', () => {
+  it('returns structured result without throwing', async () => {
+    const res = await callGetSystemStatus()
+    // Handler returns { content: [{ type: 'text', text: JSON.stringify(...) }] }
+    assert(res && res.content && Array.isArray(res.content))
+    const textBlock = res.content.find((c: any) => c.type === 'text')
+    assert(textBlock && textBlock.text)
+    const payload = JSON.parse(textBlock.text)
+    assert(typeof payload.success === 'boolean')
+    assert(Array.isArray(payload.issues))
+  }).timeout(5000)
+
+  it('detects adb availability helper works', () => {
+    const adb = ensureAdbAvailable()
+    assert(adb && typeof adb.ok === 'boolean')
+  })
+
+  it('detects xcrun command helper exists', () => {
+    const cmd = getXcrunCmd()
+    assert(typeof cmd === 'string')
+  })
+})

package/test/system/system_status.test.ts

@@ -0,0 +1,109 @@
+import assert from 'assert'
+import child_process from 'child_process'
+
+import * as androidUtils from '../../src/utils/android/utils.js'
+import * as iosUtils from '../../src/utils/ios/utils.js'
+import * as systemStatus from '../../src/system/index.js'
+
+const origExecSync = child_process.execSync
+const origEnsure = (androidUtils as any).ensureAdbAvailable
+const origGetXcrun = (iosUtils as any).getXcrunCmd
+
+function mockExec(behaviour: (cmd: string) => string) {
+  (child_process as any).execSync = (cmd: string) => {
+    const s = typeof cmd === 'string' ? cmd : (Array.isArray(cmd) ? cmd.join(' ') : String(cmd))
+    const out = behaviour(s)
+    if (out instanceof Error) throw out
+    return out
+  }
+}
+
+function restoreExec() {
+  (child_process as any).execSync = origExecSync
+}
+
+function mockEnsure(returnVal: any) {
+  (androidUtils as any).ensureAdbAvailable = () => returnVal
+}
+
+function restoreEnsure() {
+  (androidUtils as any).ensureAdbAvailable = origEnsure
+}
+
+function mockGetXcrun(val: string) {
+  (iosUtils as any).getXcrunCmd = () => val
+}
+
+function restoreGetXcrun() {
+  (iosUtils as any).getXcrunCmd = origGetXcrun
+}
+
+describe('system_status checks', () => {
+  afterEach(() => {
+    restoreExec(); restoreEnsure(); restoreGetXcrun()
+  })
+
+  it('reports healthy system when adb and xcrun present', async () => {
+    mockEnsure({ adbCmd: 'adb', ok: true, version: '8.1.0' })
+    mockGetXcrun('xcrun')
+
+    mockExec((cmd) => {
+      if (cmd.startsWith('adb devices')) return 'List of devices attached\nemulator-5554\tdevice'
+      if (cmd.includes('adb logcat')) return 'I/Tag: ok'
+      if (cmd.includes('adb shell pm path')) return 'package:/data/app/com.example-1/base.apk'
+      if (cmd.startsWith('xcrun --version')) return 'xcrun version 123'
+      if (cmd.includes('simctl list devices booted --json')) return JSON.stringify({ devices: {} })
+      return ''
+    })
+
+    const res = await systemStatus.getSystemStatus()
+    assert.strictEqual(res.success, true)
+    assert.strictEqual(res.adbAvailable, true)
+    assert.strictEqual(typeof res.adbVersion, 'string')
+  })
+
+  it('reports adb missing', async () => {
+    mockEnsure({ adbCmd: 'adb', ok: false, error: 'not found' })
+    mockGetXcrun('xcrun')
+    mockExec((cmd) => {
+      if (cmd.startsWith('xcrun --version')) return 'xcrun version'
+      return ''
+    })
+
+    const res = await systemStatus.getSystemStatus()
+    assert.strictEqual(res.success, false)
+    assert(res.issues.some((i: string) => i.includes('ADB')))
+  })
+
+  it('detects unauthorized/offline devices', async () => {
+    mockEnsure({ adbCmd: 'adb', ok: true, version: '8.1.0' })
+    mockGetXcrun('xcrun')
+    mockExec((cmd) => {
+      if (cmd.startsWith('adb devices')) return 'List of devices attached\nserial1\tunauthorized\nserial2\toffline\n'
+      if (cmd.startsWith('xcrun --version')) return 'xcrun version'
+      return ''
+    })
+
+    const res = await systemStatus.getSystemStatus()
+    assert.strictEqual(res.success, false)
+    assert(res.issues.some((i: string) => i.includes('unauthorized')))
+    assert(res.issues.some((i: string) => i.includes('offline')))
+  })
+
+  it('handles missing xcrun gracefully', async () => {
+    mockEnsure({ adbCmd: 'adb', ok: true, version: '8.1.0' })
+    mockGetXcrun('xcrun')
+    mockExec((cmd) => {
+      if (cmd.startsWith('adb devices')) return 'List of devices attached\nemulator-5554\tdevice'
+      if (cmd.startsWith('xcrun --version')) throw new Error('not found')
+      return ''
+    })
+
+    const res = await systemStatus.getSystemStatus()
+    // Expect iOS check to be false and Android to be healthy
+    assert.strictEqual(res.iosAvailable, false)
+    assert.strictEqual(res.adbAvailable, true)
+    // overall success may still be true (Android ok) but issues should include an xcrun-related message
+    assert(res.issues.some((i: string) => i.toLowerCase().includes('xcrun') || i.toLowerCase().includes('ios')))
+  })
+})