mobile-debug-mcp 0.19.2 → 0.20.0

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/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/docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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 

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

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