mobile-debug-mcp 0.19.1 → 0.20.0

package/dist/server.js

@@ -7,7 +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';
 const server = new Server({
     name: "mobile-debug-mcp",
     version: "0.7.0"
@@ -16,24 +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));
-        }
-    }
-})();
+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: [{
@@ -196,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.",
@@ -596,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/index.js

@@ -0,0 +1,26 @@
+import { checkAndroid } from './android.js';
+import { checkIOS } from './ios.js';
+export async function getSystemStatus() {
+    try {
+        const android = await checkAndroid();
+        const ios = await checkIOS();
+        const issues = [...android.issues, ...ios.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
+        };
+    }
+    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/ios/utils.js

@@ -75,12 +75,13 @@ export async function isIDBInstalled() {
         execSync(`command -v ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] });
         return true;
     }
-    catch {
+    catch (e) {
         try {
             execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 });
             return true;
         }
-        catch {
+        catch (e2) {
+            console.debug(`[isIDBInstalled] idb presence check failed for '${cmd}': ${e instanceof Error ? e.message : String(e2)}`);
             return false;
         }
     }

package/docs/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [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 
+
 ## [0.19.1]
 
 - Fixed Android install issues

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.1",
+  "version": "0.20.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/skills/mcp-builder/SKILL.md

@@ -0,0 +1,68 @@
+# MCP Builder skill
+
+name: mcp-builder
+version: 0.1.0
+summary: Reusable procedures for building, validating and installing Android/iOS apps in this repo. Designed for agents to act autonomously with project-specific guidance.
+
+# Purpose
+Provide concise, actionable procedures and schemas that encode the successful sequences used in mobile-debug-mcp: toolchain detection, build orchestration, install fallbacks, diagnostics collection, and verification (lint/tests). Keep core guidance short; link to references for details.
+
+# Activation conditions
+Activate when an agent needs to:
+- build or install an app from this repository
+- diagnose failing CI/dev machine builds
+- run lint/tests and collect reproducible diagnostics
+
+# Surface area (actions)
+- detect-toolchain
+- build-android
+- install-android
+- build-ios
+- install-ios
+- run-lint
+- run-tests
+- collect-diagnostics
+
+# Core guidance (what agent must do)
+1. Prefer project conventions and existing helpers in src/utils and src/manage.
+2. Use detect-toolchain to decide JAVA_HOME/JBR preference and whether adb/idb/xcrun are available.
+3. For Android builds, call prepareGradle() to prepare child PATH and env, then run ./gradlew (wrapper) if present.
+4. For installs, parse adb output defensively (ignore streamed-install noise) and on failure fall back to push+pm path.
+5. For iOS installs, prefer simctl for simulators; if simctl fails check idb and attempt idb install with diagnostics.
+6. On any error, call collect-diagnostics and attach env snapshot, invoked commands, stdout/stderr, and suggested fixes.
+
+# Inputs & outputs (short schemas)
+- detect-toolchain(input: { platform: 'android'|'ios'|'both', preferJBR?: boolean }) -> { tools: [{name, cmd, ok, version, suggestion}] }
+- build-android(input: { projectPath, variant?, clean?, envOverrides? }) -> { success, artifactPath?, logs?, diagnostics? }
+- install-android(input: { appPath, projectPath?, deviceId?, allowBuild? }) -> { installed:boolean, device, output?, diagnostics? }
+- build-ios/install-ios: mirror Android schema but use scheme/workspace/project and resultBundlePath
+- run-lint/run-tests -> { exitCode, stdout, stderr, artifacts[] }
+- collect-diagnostics(input: { reason, platform? }) -> { artifacts: [{ name, contentBase64?, path? }], envSnapshot }
+
+# Failure handling & suggestions
+- Always return structured diagnostics instead of throwing when possible.
+- Provide a short human-friendly suggestion in diagnostics (e.g., "Install Android Platform Tools or set ADB_PATH").
+- Redact sensitive env values (tokens, credentials) when including envSnapshot.
+
+# Progressive disclosure
+- Keep SKILL.md compact (this file). Place heavy references in skills/mcp-builder/references/*.md and instruct agents to load them only when needed.
+
+# References (implement as separate files)
+- references/toolchain-details.md — exact paths/heuristics used for JBR, JAVA_HOME, ANDROID_SDK locations.
+- references/build-flags.md — gradle/xcodebuild flags used, timeouts, and retry rationale.
+- references/diagnostics-schema.md — JSON schema for runResult and collected artifacts.
+
+# Implementation notes for maintainers
+- Implement a thin adapter in src/skills/mcp-builder/index.ts that maps skill actions to existing functions in src/manage and src/utils.
+- Provide unit tests under test/skills/mcp-builder that mock child_process to validate happy/failure paths.
+- Add env toggles: MCP_PREFERS_JBR, MCP_GRADLE_RETRIES, MCP_XCODEBUILD_RETRIES.
+
+# Example agent flow
+1. call detect-toolchain({platform:'android', preferJBR:true})
+2. if ok -> call build-android({projectPath:'/path', variant:'Debug'})
+3. call install-android({appPath:'/path/to.apk', deviceId:'emulator-5554'})
+4. if install fails -> call collect-diagnostics({reason:'install failure', platform:'android'})
+
+# License
+Same as repository (MIT).
+

package/skills/mcp-builder/references/build-flags.md

@@ -0,0 +1,43 @@
+# Build flags and runtime configuration
+
+Purpose: describe the flags, environment variables and spawn-environment handling that agents should use when orchestrating Android and iOS builds for this repo.
+
+Common env variables
+- MCP_GRADLE_RETRIES (default: 1) — number of retry attempts on watchdog kills for Gradle
+- MCP_GRADLE_TIMEOUT_MS (default: 300000) — gradle watch/duration timeout
+- MCP_XCODEBUILD_RETRIES, MCP_XCODEBUILD_TIMEOUT_MS — similar for xcodebuild
+- MCP_PREFERS_JBR — prefer Android Studio JBR for JAVA_HOME
+- MCP_DERIVED_DATA, MCP_XCODE_RESULTBUNDLE_PATH — override DerivedData/result bundle locations
+
+Android (Gradle)
+- Use the Gradle wrapper if present: `./gradlew assemble<Variant>` (e.g., assembleDebug). Prefer wrapper to ensure consistent Gradle version.
+- Prepare spawn env by prepending javaBin and platform-tools dir to PATH and set GRADLE_JAVA_HOME and `-Dorg.gradle.java.home` when necessary.
+- If wrapper exists, ensure `chmod +x ./gradlew` before spawn.
+- Recommended flags:
+  - `--no-daemon` sometimes helpful in CI, but wrap with existing project conventions.
+  - Set `org.gradle.jvmargs` via env or gradle.properties only if needed.
+- Timeouts & watchdog:
+  - Use a watchdog timeout (MCP_GRADLE_TIMEOUT_MS) and retry (MCP_GRADLE_RETRIES) if killed by watchdog. Record stdout/stderr for each attempt.
+
+iOS (xcodebuild)
+- Use `xcodebuild -workspace <ws> -scheme <scheme> -configuration Debug -sdk iphonesimulator build` for simulator builds.
+- Provide `-derivedDataPath` and `-resultBundlePath` to isolate builds and produce diagnostics. Default result bundle path should be unique per run to avoid collisions.
+- Recommended flags: `-parallelizeTargets -jobs <N>` where N is from MCP_XCODE_JOBS or sensible default (4).
+- When a destination UDID is available, always pass `-destination "platform=iOS Simulator,id=<UDID>"` to avoid ambiguous device selection.
+- Timeouts & retries: respect MCP_XCODEBUILD_TIMEOUT_MS and MCP_XCODEBUILD_RETRIES; capture stdout/stderr and save logs under build-results.
+
+Install-time behavior
+- Android: prefer `adb install -r <apk>` for fast installs. If output contains spurious lines (e.g., "Performing Streamed Install" followed by "Success"), parse to extract final status. On failure try `adb push` to `/data/local/tmp` + `pm install -r <remote>` as a fallback collect push/install diagnostics.
+- iOS: prefer `xcrun simctl install <device> <app>` for simulator. On failure attempt idb install if idb exists: `idb install <ipa|app> --udid <udid>` and record its stdout/stderr.
+
+Diagnostics capture
+- Save stdout/stderr, exitCode and environment snapshot for each command. Persist logs under workspace/build-results or a temp dir provided by the caller.
+- For builds, also capture produced artifact paths to return to caller.
+
+Examples
+- Gradle invocation (pseudo):
+  spawnOpts.env.PATH = `${javaBin}:${platformTools}:${process.env.PATH}`
+  spawn('./gradlew', ['assembleDebug'], { cwd: projectRoot, env: spawnOpts.env })
+
+- xcodebuild invocation (pseudo):
+  xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Debug -sdk iphonesimulator -derivedDataPath /tmp/derived -resultBundlePath /tmp/Result-123.xcresult -parallelizeTargets -jobs 4 build

package/skills/mcp-builder/references/diagnostics-schema.md

@@ -0,0 +1,48 @@
+# Diagnostics schema
+
+This document defines the JSON shapes that mcp-builder actions return when collecting diagnostics. Agents and tooling should rely on these keys.
+
+Top-level diagnostic object
+{
+  "error": "short human-friendly message",
+  "runResult": {
+    "command": "/usr/bin/adb",
+    "args": ["install", "app.apk"],
+    "exitCode": 1,
+    "stdout": "...",
+    "stderr": "...",
+    "startTimeMs": 1650000000000,
+    "endTimeMs": 1650000001000,
+    "envSnapshot": { "PATH": "...", "JAVA_HOME": "REDACTED" }
+  },
+  "artifacts": [ { name, path?, contentBase64?, type? } ],
+  "suggestedFixes": ["Install Android Platform Tools", "Set JAVA_HOME to JDK 17"]
+}
+
+Fields
+- error: short message summarising the failure.
+- runResult: information captured from a single command invocation. Use this for programmatic retries or human debugging.
+  - command, args: the executed command
+  - exitCode: numeric exit code, null for killed/unknown
+  - stdout, stderr: captured text
+  - startTimeMs, endTimeMs: epoch ms for duration
+  - envSnapshot: a restricted set of env variables (PATH, JAVA_HOME, ADB_PATH, IDB_PATH, XCRUN_PATH). Any value matching sensitive patterns (e.g., /token|secret|key|passwd/i) must be redacted to "REDACTED".
+- artifacts: array of captured files. Each artifact: { name: string, path?: string, contentBase64?: string, type?: "log"|"archive"|"image" }
+- suggestedFixes: short actionable suggestions for human/operator.
+
+Notes on size and transmission
+- Prefer storing large artifacts on disk and returning paths rather than inlining large base64 blobs. If transmitting, limit base64 inlined artifacts to a configurable max (e.g., 5MB) and prefer compression/archiving.
+
+Example: adb install failure
+{
+  "error": "adb: device not found",
+  "runResult": {
+    "command": "adb",
+    "args": ["devices"],
+    "exitCode": 0,
+    "stdout": "List of devices attached\n\n",
+    "stderr": "",
+    "envSnapshot": { "PATH": "/usr/local/bin:/usr/bin", "JAVA_HOME": null }
+  },
+  "suggestedFixes": ["Connect an Android device or start an emulator", "Ensure adb is on PATH or set ADB_PATH"]
+}

package/skills/mcp-builder/references/toolchain-details.md

@@ -0,0 +1,62 @@
+# Toolchain details
+
+This reference documents the exact heuristics and commands used by the mcp-builder skill to detect and validate the native toolchain (Android & iOS) on contributor machines.
+
+Key environment variables
+- ADB_PATH: explicit path to adb binary
+- ANDROID_SDK_ROOT / ANDROID_HOME: SDK root; platform-tools/adb under these
+- ANDROID_STUDIO_JBR / ANDROID_STUDIO_JDK: explicit Android Studio JBR/JDK path
+- JAVA_HOME: system JDK
+- IDB_PATH / MCP_IDB_PATH: idb path for iOS
+- XCRUN_PATH: explicit xcrun path
+- MCP_PREFERS_JBR: boolean to prefer Android Studio JBR when present
+
+Android Java detection precedence
+1. ANDROID_STUDIO_JBR / ANDROID_STUDIO_JDK env vars (preferred when MCP_PREFERS_JBR set)
+2. Known Android Studio JBR locations (macOS):
+   - /Applications/Android Studio.app/Contents/jbr/Contents/Home
+   - /Applications/Android Studio Preview.app/Contents/jbr/Contents/Home
+3. Explicit JAVA_HOME (validate via `java -version`)
+4. macOS `/usr/libexec/java_home -v 17` or `-v 21`
+5. Common Linux JDK locations: `/usr/lib/jvm/*temurin*`, `/usr/lib/jvm/*zulu*`
+
+Validation rules
+- Accept only Java 17 or Java 21 for Gradle builds in this project (both tested/known working).
+- Reject GraalVM / Java 23 that causes Gradle jlink errors. If detected, return suggestion: "Prefer an Apple/Temurin/JBR Java 17 or 21. Set ANDROID_STUDIO_JBR or JAVA_HOME to a supported JDK."
+
+ADB resolution precedence
+1. process.env.ADB_PATH (explicit)
+2. ANDROID_SDK_ROOT or ANDROID_HOME -> platform-tools/adb
+3. Common SDK locations (macOS/Linux): $HOME/Library/Android/sdk/platform-tools, /opt/android-sdk/platform-tools
+4. `command -v adb` / `which adb` on PATH
+5. fallback to `adb` (best-effort)
+
+IDB / XCRUN detection (iOS)
+- IDB: check MCP_IDB_PATH -> IDB_PATH -> common locations (/opt/homebrew/bin/idb, /usr/local/bin/idb, $HOME/Library/Python/*/bin/idb). Validate by running `idb --version` or `idb list-targets --json`.
+- XCRUN: check XCRUN_PATH -> run `xcrun --version`.
+
+How to probe (commands)
+- adb: `adb --version` and `adb devices --print` (or `adb devices -l`) to list.
+- java: `java -XshowSettings:properties -version` or `java -version` parse first line.
+- xcrun: `xcrun --version`
+- idb: `idb --version` or `idb list-targets --json`
+
+Output format
+- Each probe returns { name, cmd, ok, version?, suggestion? } so agents can reason programmatically.
+- Include env snapshot (PATH, JAVA_HOME, ADB_PATH, ANDROID_SDK_ROOT, IDB_PATH, XCRUN_PATH) to aid diagnostics.
+
+Notes & rationale
+- Prefer Android Studio JBR (JBR is bundled & known-good) because developer machines often have mismatched system JDKs (e.g., Graal). Allow override via env for CI.
+- For long-running server processes, prepend java/bin and platform-tools to spawn env PATH when running child builds so external PATH/JAVA_HOME changes don't require a server restart.
+
+Examples
+- Detected result (JSON):
+  {
+    "name": "adb",
+    "cmd": "/Users/xxx/Library/Android/sdk/platform-tools/adb",
+    "ok": true,
+    "version": "Android Debug Bridge version 1.0.41"
+  }
+
+- Java suggestion when incompatible:
+  { "name": "java", "ok": false, "suggestion": "Found GraalVM (Java 23). Use Java 17 or 21: set ANDROID_STUDIO_JBR or JAVA_HOME." }

package/src/server.ts

@@ -20,7 +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'
 
 
 const server = new Server(
@@ -35,20 +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))
-    }
-  }
-})()
+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 {
@@ -214,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.",
@@ -631,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/index.ts

@@ -0,0 +1,27 @@
+import { checkAndroid } from './android.js'
+import { checkIOS } from './ios.js'
+
+export async function getSystemStatus() {
+  try {
+    const android = await checkAndroid()
+    const ios = await checkIOS()
+    const issues = [...android.issues, ...ios.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
+    }
+  } 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/ios/utils.ts

@@ -62,11 +62,12 @@ export async function isIDBInstalled(): Promise<boolean> {
   try {
     execSync(`command -v ${cmd}`, { stdio: ['ignore','pipe','ignore'] })
     return true
-  } catch {
+  } catch (e: unknown) {
     try {
       execSync(`${cmd} list-targets --json`, { stdio: ['ignore','pipe','ignore'], timeout: 2000 })
       return true
-    } catch {
+    } catch (e2: unknown) {
+      console.debug(`[isIDBInstalled] idb presence check failed for '${cmd}': ${e instanceof Error ? e.message : String(e2)}`)
       return false
     }
   }

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