mobile-debug-mcp 0.24.6 → 0.24.8

package/.github/workflows/ci.yml

@@ -58,6 +58,4 @@ jobs:
       - name: Build and run Android integration tests
         env:
           ADB_TIMEOUT: 120000
-        run: |
-          npm run build
-          node test/integration/run-install-android.js || true
+        run: npm run test:device

package/README.md

@@ -3,11 +3,11 @@
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, and inspect Android/iOS apps from an MCP-compatible client.
 
 > **Support:**
-> * Android support
-> * iOS only tested on simulator
-> * KMP support
-> * Flutter iOS projects not fetching logs
-> * React native not tested
+> * KMP
+> * Android
+> * iOS
+> * Flutter - not tested
+> * React native - not tested
 
 ## Requirements
 
@@ -52,8 +52,15 @@ Feature building:
 
 - `npm run test:unit` runs every automated unit test under `test/unit/...`
 - `npm run test:device` runs the automated device smoke checks under `test/device/automated/...`
+- `npm run verify` runs the default maintainer verification sequence: lint, build, and unit tests
 - Manual and debug-oriented device scripts live under `test/device/manual/...` and are not part of the default test commands
 
+## Utility Scripts
+
+- `npm run healthcheck` runs the `idb`/tooling healthcheck helper from `src/utils/cli/idb/check-idb.ts`
+- `npm run install-idb` runs the guided `idb` installer helper from `src/utils/cli/idb/install-idb.ts`
+- `npm run preflight-ios` runs the iOS preflight helper from `src/utils/cli/ios/preflight-ios.ts`
+
 ## Agent skills
 
 - `skills/mcp-builder/` contains reusable build/install guidance for agents

package/dist/interact/index.js

@@ -7,6 +7,14 @@ import { ToolsObserve } from '../observe/index.js';
 import { nextActionId } from '../server/common.js';
 export class ToolsInteract {
     static _maxResolvedUiElements = 256;
+    static _sliderSearchLookahead = 8;
+    static _sliderNegativeGapTolerancePx = 32;
+    static _sliderPositiveGapLimitPx = 640;
+    static _sliderTrackMinLengthPx = 220;
+    static _sliderTrackMaxThicknessPx = 180;
+    static _sliderTrackLengthRatio = 0.18;
+    static _sliderTrackThicknessRatio = 0.08;
+    static _sliderLabelWidthRatio = 1.5;
     static _resolvedUiElements = new Map();
     static _normalize(s) {
         if (s === null || s === undefined)
@@ -174,6 +182,63 @@ export class ToolsInteract {
         }
         return best;
     }
+    static _resolveNearbyActionableControl(elements, chosen, screen) {
+        if (!chosen)
+            return null;
+        const labelBounds = ToolsInteract._normalizeBounds(chosen.el.bounds);
+        if (!labelBounds)
+            return null;
+        const [labelLeft, labelTop, labelRight, labelBottom] = labelBounds;
+        const labelWidth = labelRight - labelLeft;
+        const labelHeight = labelBottom - labelTop;
+        const screenWidth = Number(screen?.width) > 0 ? Number(screen?.width) : 0;
+        const screenHeight = Number(screen?.height) > 0 ? Number(screen?.height) : 0;
+        const minTrackLengthPx = Math.max(ToolsInteract._sliderTrackMinLengthPx, screenWidth > 0 ? Math.floor(screenWidth * ToolsInteract._sliderTrackLengthRatio) : 0, screenHeight > 0 ? Math.floor(screenHeight * ToolsInteract._sliderTrackLengthRatio) : 0);
+        const maxTrackThicknessPx = Math.max(ToolsInteract._sliderTrackMaxThicknessPx, screenWidth > 0 ? Math.floor(screenWidth * ToolsInteract._sliderTrackThicknessRatio) : 0, screenHeight > 0 ? Math.floor(screenHeight * ToolsInteract._sliderTrackThicknessRatio) : 0);
+        let best = null;
+        let bestScore = Infinity;
+        for (let i = chosen.idx + 1; i < Math.min(elements.length, chosen.idx + ToolsInteract._sliderSearchLookahead); i++) {
+            const candidate = elements[i];
+            if (!candidate || !(candidate.clickable || candidate.focusable) || candidate.visible === false)
+                continue;
+            const candidateBounds = ToolsInteract._normalizeBounds(candidate.bounds);
+            if (!candidateBounds)
+                continue;
+            const [left, top, right] = candidateBounds;
+            const width = right - left;
+            const height = candidateBounds[3] - top;
+            const verticalGap = top - labelBottom;
+            if (verticalGap < -ToolsInteract._sliderNegativeGapTolerancePx || verticalGap > ToolsInteract._sliderPositiveGapLimitPx)
+                continue;
+            const horizontalOverlap = Math.min(labelRight, right) - Math.max(labelLeft, left);
+            if (horizontalOverlap < -ToolsInteract._sliderNegativeGapTolerancePx)
+                continue;
+            const candidateText = ToolsInteract._normalize(candidate.text ?? candidate.label ?? candidate.value ?? '');
+            const candidateContent = ToolsInteract._normalize(candidate.contentDescription ?? candidate.contentDesc ?? candidate.accessibilityLabel ?? '');
+            const candidateClass = ToolsInteract._normalize(candidate.type ?? candidate.class ?? '');
+            let score = verticalGap;
+            const horizontalTrackLike = width >= Math.max(minTrackLengthPx, Math.floor(labelWidth * ToolsInteract._sliderLabelWidthRatio)) &&
+                height <= maxTrackThicknessPx;
+            const verticalTrackLike = height >= Math.max(minTrackLengthPx, Math.floor(labelHeight * ToolsInteract._sliderLabelWidthRatio)) &&
+                width <= maxTrackThicknessPx;
+            const trackLike = /slider|seek|range/i.test(candidateClass) || horizontalTrackLike || verticalTrackLike;
+            if (!candidateText && !candidateContent)
+                score -= 18;
+            if (trackLike)
+                score -= 30;
+            if (/view|layout|group|frame/i.test(candidateClass))
+                score -= 10;
+            if (width > labelWidth * ToolsInteract._sliderLabelWidthRatio)
+                score -= 8;
+            if (candidateText || candidateContent)
+                score += 20;
+            if (score < bestScore) {
+                bestScore = score;
+                best = { el: candidate, idx: i, sliderLike: trackLike };
+            }
+        }
+        return best;
+    }
     static async getInteractionService(platform, deviceId) {
         const effectivePlatform = platform || 'android';
         const resolved = await resolveTargetDevice({ platform: effectivePlatform, deviceId });
@@ -262,6 +327,7 @@ export class ToolsInteract {
             return { found: false, error: 'Empty query' };
         let best = null;
         let bestScore = 0;
+        let lastTree = null;
         const scoreElement = (el) => {
             if (!el || !el.visible)
                 return 0;
@@ -305,6 +371,7 @@ export class ToolsInteract {
         while (Date.now() <= deadline) {
             try {
                 const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+                lastTree = tree;
                 if (tree && Array.isArray(tree.elements)) {
                     const elements = tree.elements;
                     for (let i = 0; i < elements.length; i++) {
@@ -342,8 +409,8 @@ export class ToolsInteract {
             return { found: false, error: 'Element not found' };
         // If the best match is not interactable, try to resolve an actionable ancestor.
         try {
-            const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
-            const elements = (tree && Array.isArray(tree.elements)) ? tree.elements : [];
+            const elements = (lastTree && Array.isArray(lastTree.elements)) ? lastTree.elements : [];
+            const screen = lastTree?.resolution && typeof lastTree.resolution === 'object' ? lastTree.resolution : null;
             let chosen = best;
             const childBounds = Array.isArray(chosen?.bounds) ? chosen.bounds : null;
             // Strategy 1: if parentId references an index, climb that chain
@@ -412,6 +479,15 @@ export class ToolsInteract {
                 // small score bump to reflect actionability
                 bestScore = Math.min(1, bestScore + 0.02);
             }
+            if (best && !(best.clickable || best.focusable)) {
+                const nearbyActionable = ToolsInteract._resolveNearbyActionableControl(elements, { el: best, idx: best._index ?? elements.indexOf(best) }, screen);
+                if (nearbyActionable) {
+                    best = nearbyActionable.el;
+                    best._index = nearbyActionable.idx;
+                    best._interactable = true;
+                    best._sliderLike = nearbyActionable.sliderLike;
+                }
+            }
         }
         catch (e) {
             console.error('Error resolving ancestor:', e);
@@ -431,9 +507,19 @@ export class ToolsInteract {
             tapCoordinates,
             telemetry: {
                 matchedIndex: best?._index ?? null,
-                matchedInteractable: !!best?._interactable
+                matchedInteractable: !!best?._interactable,
+                sliderLike: !!best?._sliderLike
             }
         };
+        if (best?._sliderLike) {
+            const isVertical = !!boundsObj && (boundsObj.bottom - boundsObj.top) > (boundsObj.right - boundsObj.left);
+            const interactionHint = {
+                kind: 'slider',
+                axis: isVertical ? 'vertical' : 'horizontal',
+                trackBounds: boundsObj
+            };
+            outEl.interactionHint = interactionHint;
+        }
         const scoreVal = Math.min(1, Number(bestScore.toFixed(3)));
         return { found: true, element: outEl, score: scoreVal, confidence: scoreVal };
     }

package/dist/manage/android.js

@@ -2,7 +2,7 @@ import { promises as fs } from 'fs';
 import { spawn } from 'child_process';
 import path from 'path';
 import { existsSync } from 'fs';
-import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from '../utils/android/utils.js';
+import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk, prepareGradle } from '../utils/android/utils.js';
 import { execAdbWithDiagnostics } from '../utils/diagnostics.js';
 import { detectJavaHome } from '../utils/java.js';
 import { AndroidObserve } from '../observe/android.js';
@@ -10,11 +10,15 @@ export class AndroidManage {
     isTestOnlyInstallFailure(output) {
         return typeof output === 'string' && output.includes('INSTALL_FAILED_TEST_ONLY');
     }
-    async build(projectPath, _variant) {
-        void _variant;
+    async build(projectPath, optionsOrVariant) {
+        const options = typeof optionsOrVariant === 'string' ? { variant: optionsOrVariant } : (optionsOrVariant || {});
         try {
+            const env = {
+                ...(options.env || {}),
+                ...(options.variant ? { MCP_GRADLE_TASK: options.variant } : {})
+            };
             // Always use the shared prepareGradle utility for consistent env/setup
-            const { execCmd, gradleArgs, spawnOpts } = await (await import('../utils/android/utils.js')).prepareGradle(projectPath);
+            const { execCmd, gradleArgs, spawnOpts } = await prepareGradle(projectPath, env);
             await new Promise((resolve, reject) => {
                 const proc = spawn(execCmd, gradleArgs, spawnOpts);
                 let stderr = '';
@@ -44,7 +48,7 @@ export class AndroidManage {
             const stat = await fs.stat(apkPath).catch(() => null);
             if (stat && stat.isDirectory()) {
                 const detectedJavaHome = await detectJavaHome().catch(() => undefined);
-                const env = Object.assign({}, process.env);
+                const env = { ...process.env };
                 if (detectedJavaHome) {
                     if (env.JAVA_HOME !== detectedJavaHome) {
                         env.JAVA_HOME = detectedJavaHome;

package/dist/manage/index.js

@@ -70,31 +70,35 @@ export async function detectProjectPlatform(projectPath) {
         return 'unknown';
     }
 }
+function mergeDefinedEnv(...parts) {
+    const merged = {};
+    for (const part of parts) {
+        if (!part)
+            continue;
+        for (const [key, value] of Object.entries(part)) {
+            if (typeof value === 'undefined')
+                continue;
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
 export class ToolsManage {
     static async build_android({ projectPath, gradleTask, maxWorkers, gradleCache, forceClean }) {
         const android = new AndroidManage();
-        // prepare gradle options via environment hints
-        if (typeof maxWorkers === 'number')
-            process.env.MCP_GRADLE_WORKERS = String(maxWorkers);
-        if (typeof gradleCache === 'boolean')
-            process.env.MCP_GRADLE_CACHE = gradleCache ? '1' : '0';
-        if (forceClean)
-            process.env.MCP_FORCE_CLEAN_ANDROID = '1';
         const task = gradleTask || 'assembleDebug';
-        const artifact = await android.build(projectPath, task);
-        return artifact;
+        return await android.build(projectPath, {
+            variant: task,
+            env: mergeDefinedEnv({
+                MCP_GRADLE_TASK: task,
+                MCP_GRADLE_WORKERS: typeof maxWorkers === 'number' ? String(maxWorkers) : undefined,
+                MCP_GRADLE_CACHE: typeof gradleCache === 'boolean' ? (gradleCache ? '1' : '0') : undefined,
+                MCP_FORCE_CLEAN_ANDROID: forceClean ? '1' : undefined
+            })
+        });
     }
     static async build_ios({ projectPath, workspace: _workspace, project: _project, scheme: _scheme, destinationUDID, derivedDataPath, buildJobs, forceClean }) {
         const ios = new iOSManage();
-        // Use provided options rather than env-only; still set env fallbacks for downstream tools
-        if (derivedDataPath)
-            process.env.MCP_DERIVED_DATA = derivedDataPath;
-        if (typeof buildJobs === 'number')
-            process.env.MCP_BUILD_JOBS = String(buildJobs);
-        if (forceClean)
-            process.env.MCP_FORCE_CLEAN_IOS = '1';
-        if (destinationUDID)
-            process.env.MCP_XCODE_DESTINATION_UDID = destinationUDID;
         const opts = {};
         if (_workspace)
             opts.workspace = _workspace;
@@ -106,13 +110,23 @@ export class ToolsManage {
             opts.destinationUDID = destinationUDID;
         if (derivedDataPath)
             opts.derivedDataPath = derivedDataPath;
-        if (forceClean)
+        if (typeof buildJobs === 'number')
+            opts.buildJobs = buildJobs;
+        if (typeof forceClean === 'boolean')
             opts.forceClean = forceClean;
         // prefer explicit xcodebuild path from env
         if (process.env.XCODEBUILD_PATH)
             opts.xcodeCmd = process.env.XCODEBUILD_PATH;
-        const artifact = await ios.build(projectPath, opts);
-        return artifact;
+        return await ios.build(projectPath, {
+            ...opts,
+            env: mergeDefinedEnv({
+                MCP_DERIVED_DATA: derivedDataPath,
+                MCP_XCODE_JOBS: typeof buildJobs === 'number' ? String(buildJobs) : undefined,
+                MCP_FORCE_CLEAN: typeof forceClean === 'boolean' ? (forceClean ? '1' : '0') : undefined,
+                MCP_XCODE_DESTINATION_UDID: destinationUDID,
+                XCODEBUILD_PATH: process.env.XCODEBUILD_PATH
+            })
+        });
     }
     static async build_flutter({ projectPath, platform, buildMode, maxWorkers: _maxWorkers, forceClean: _forceClean }) {
         // Prefer using flutter CLI when available; otherwise delegate to native subproject builders
@@ -199,12 +213,12 @@ export class ToolsManage {
         const chosen = platform || 'android';
         if (chosen === 'android') {
             const android = new AndroidManage();
-            const artifact = await android.build(projectPath, variant);
+            const artifact = await android.build(projectPath, { variant });
             return artifact;
         }
         else {
             const ios = new iOSManage();
-            const artifact = await ios.build(projectPath, variant);
+            const artifact = await ios.build(projectPath, { variant });
             return artifact;
         }
     }

package/dist/manage/ios.js

@@ -6,11 +6,8 @@ import path from "path";
 export class iOSManage {
     async build(projectPath, optsOrVariant) {
         // Support legacy variant string as second arg
-        let opts = {};
-        if (typeof optsOrVariant === 'string')
-            opts.variant = optsOrVariant;
-        else
-            opts = optsOrVariant || {};
+        const opts = typeof optsOrVariant === 'string' ? {} : (optsOrVariant || {});
+        const env = { ...process.env, ...(opts.env || {}) };
         try {
             // Look for an Xcode workspace or project at the provided path. If not present, scan subdirectories (limited depth)
             async function findProject(root, maxDepth = 4) {
@@ -66,7 +63,7 @@ export class iOSManage {
                 proj = projectInfo.proj;
             }
             // Determine destination: prefer explicit option, then env var, otherwise use booted simulator UDID
-            let destinationUDID = opts.destinationUDID || process.env.MCP_XCODE_DESTINATION_UDID || process.env.MCP_XCODE_DESTINATION || '';
+            let destinationUDID = opts.destinationUDID || env.MCP_XCODE_DESTINATION_UDID || env.MCP_XCODE_DESTINATION || '';
             if (!destinationUDID) {
                 try {
                     const meta = await getIOSDeviceMetadata('booted');
@@ -76,7 +73,7 @@ export class iOSManage {
                 catch { }
             }
             // Determine xcode command early so it can be used when detecting schemes
-            const xcodeCmd = opts.xcodeCmd || process.env.XCODEBUILD_PATH || 'xcodebuild';
+            const xcodeCmd = opts.xcodeCmd || env.XCODEBUILD_PATH || 'xcodebuild';
             // Determine available schemes by querying xcodebuild -list rather than guessing
             async function detectScheme(xcodeCmdInner, workspacePath, projectPathFull, cwd) {
                 try {
@@ -99,11 +96,11 @@ export class iOSManage {
             let buildArgs;
             let chosenScheme = opts.scheme || null;
             // Derived data and result bundle (agent-configurable)
-            const derivedDataPath = opts.derivedDataPath || process.env.MCP_DERIVED_DATA || path.join(projectRootDir, 'build', 'DerivedData');
+            const derivedDataPath = opts.derivedDataPath || env.MCP_DERIVED_DATA || path.join(projectRootDir, 'build', 'DerivedData');
             // Use unique result bundle path by default to avoid collisions
-            const resultBundlePath = process.env.MCP_XCODE_RESULTBUNDLE_PATH || path.join(projectRootDir, 'build', 'xcresults', `ResultBundle-${Date.now()}-${Math.random().toString(36).slice(2)}.xcresult`);
-            const xcodeJobs = parseInt(process.env.MCP_XCODE_JOBS || '', 10) || 4;
-            const forceClean = opts.forceClean || process.env.MCP_FORCE_CLEAN === '1';
+            const resultBundlePath = env.MCP_XCODE_RESULTBUNDLE_PATH || path.join(projectRootDir, 'build', 'xcresults', `ResultBundle-${Date.now()}-${Math.random().toString(36).slice(2)}.xcresult`);
+            const xcodeJobs = typeof opts.buildJobs === 'number' ? opts.buildJobs : (parseInt(env.MCP_XCODE_JOBS || '', 10) || 4);
+            const forceClean = typeof opts.forceClean === 'boolean' ? opts.forceClean : env.MCP_FORCE_CLEAN === '1';
             // ensure result dirs exist
             await fs.mkdir(path.dirname(resultBundlePath), { recursive: true }).catch(() => { });
             await fs.mkdir(derivedDataPath, { recursive: true }).catch(() => { });
@@ -144,8 +141,8 @@ export class iOSManage {
             // Remove any stale results to avoid xcodebuild complaining about existing result bundles
             await fs.rm(resultsDir, { recursive: true, force: true }).catch(() => { });
             await fs.mkdir(resultsDir, { recursive: true }).catch(() => { });
-            const XCODEBUILD_TIMEOUT = parseInt(process.env.MCP_XCODEBUILD_TIMEOUT || '', 10) || 180000; // default 3 minutes
-            const MAX_RETRIES = parseInt(process.env.MCP_XCODEBUILD_RETRIES || '', 10) || 1;
+            const XCODEBUILD_TIMEOUT = parseInt(env.MCP_XCODEBUILD_TIMEOUT || '', 10) || 180000; // default 3 minutes
+            const MAX_RETRIES = parseInt(env.MCP_XCODEBUILD_RETRIES || '', 10) || 1;
             const tries = MAX_RETRIES + 1;
             let lastStdout = '';
             let lastStderr = '';
@@ -153,7 +150,7 @@ export class iOSManage {
             for (let attempt = 1; attempt <= tries; attempt++) {
                 // Run xcodebuild with a watchdog
                 const res = await new Promise((resolve) => {
-                    const proc = spawn(xcodeCmd, buildArgs, { cwd: projectRootDir });
+                    const proc = spawn(xcodeCmd, buildArgs, { cwd: projectRootDir, env });
                     let stdout = '';
                     let stderr = '';
                     proc.stdout?.on('data', d => stdout += d.toString());
@@ -204,7 +201,7 @@ export class iOSManage {
             if (lastErr) {
                 // Include diagnostics and result bundle path when available; provide structured info useful for agents
                 const invokedCommand = `${xcodeCmd} ${buildArgs.map(a => a.includes(' ') ? `"${a}"` : a).join(' ')}`;
-                const envSnapshot = { PATH: process.env.PATH };
+                const envSnapshot = { PATH: env.PATH };
                 return { error: `xcodebuild failed: ${lastErr.message}. See build-results for logs.`, output: `stdout:\n${lastStdout}\nstderr:\n${lastStderr}`, diagnostics: { exitCode: lastErr.code || null, invokedCommand, cwd: projectRootDir, envSnapshot } };
             }
             // Try to locate built .app. First search project tree, then DerivedData if necessary

package/dist/server/common.js

@@ -7,6 +7,52 @@ export function wrapResponse(data) {
             }]
     };
 }
+export function getStringArg(args, key) {
+    const value = args[key];
+    return typeof value === 'string' ? value : undefined;
+}
+export function requireStringArg(args, key) {
+    const value = getStringArg(args, key);
+    if (value === undefined)
+        throw new Error(`Missing or invalid string argument: ${key}`);
+    return value;
+}
+export function getNumberArg(args, key) {
+    const value = args[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+export function requireNumberArg(args, key) {
+    const value = getNumberArg(args, key);
+    if (value === undefined)
+        throw new Error(`Missing or invalid number argument: ${key}`);
+    return value;
+}
+export function getBooleanArg(args, key) {
+    const value = args[key];
+    return typeof value === 'boolean' ? value : undefined;
+}
+export function requireBooleanArg(args, key) {
+    const value = getBooleanArg(args, key);
+    if (value === undefined)
+        throw new Error(`Missing or invalid boolean argument: ${key}`);
+    return value;
+}
+export function getObjectArg(args, key) {
+    const value = args[key];
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    return value;
+}
+export function requireObjectArg(args, key) {
+    const value = getObjectArg(args, key);
+    if (value === undefined)
+        throw new Error(`Missing or invalid object argument: ${key}`);
+    return value;
+}
+export function getArrayArg(args, key) {
+    const value = args[key];
+    return Array.isArray(value) ? value : undefined;
+}
 let actionSequence = 0;
 export function nextActionId(actionType, timestamp) {
     actionSequence += 1;