mobile-debug-mcp 0.19.1 → 0.19.2

package/dist/server.js

@@ -8,6 +8,9 @@ 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"
@@ -33,6 +36,32 @@ const server = new Server({
             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));
+    }
 })();
 function wrapResponse(data) {
     return {

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.19.1",
+  "version": "0.19.2",
   "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

@@ -21,6 +21,9 @@ 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(
@@ -48,6 +51,30 @@ const server = new Server(
       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))
+  }
+
 })()
 
 function wrapResponse<T>(data: T) {

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
     }
   }