mobile-debug-mcp 0.24.5 → 0.24.7

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

@@ -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/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/observe/index.js

@@ -66,7 +66,7 @@ function deriveSnapshotSemantic(raw) {
         return null;
     const hasErrorLogs = raw.logs.some((entry) => /error|fatal exception|exception|failed/i.test(entry.message));
     const hasLoadingSignals = texts.some((text) => /loading|please wait|spinner|progress/i.test(text));
-    const hasPrimaryText = texts.some((text) => /sign in|log in|log in|login|home|checkout|settings|menu|profile|search/i.test(text));
+    const hasPrimaryText = texts.some((text) => /sign in|log in|login|home|checkout|settings|menu|profile|search/i.test(text));
     const hasScreenshot = typeof raw.screenshot === 'string' && raw.screenshot.length > 0;
     const hasUiTree = !!tree && Array.isArray(tree.elements);
     const signals = {
@@ -105,7 +105,7 @@ function deriveSnapshotSemantic(raw) {
         signals,
         actions_available: actionables.length > 0 ? actionables.slice(0, 10) : null,
         confidence,
-        warnings: confidence >= 0.7 && warnings.length === 0 ? [] : warnings
+        warnings
     };
 }
 export class ToolsObserve {

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;

package/dist/server/tool-handlers.js

@@ -4,9 +4,11 @@ import { ToolsObserve } from '../observe/index.js';
 import { classifyActionOutcome } from '../interact/classify.js';
 import { ToolsNetwork } from '../network/index.js';
 import { getSystemStatus } from '../system/index.js';
-import { buildActionExecutionResult, captureActionFingerprint, inferGenericFailure, inferScrollFailure, wrapResponse, wrapToolError } from './common.js';
+import { buildActionExecutionResult, captureActionFingerprint, getArrayArg, getBooleanArg, getNumberArg, getObjectArg, getStringArg, inferGenericFailure, inferScrollFailure, requireBooleanArg, requireNumberArg, requireObjectArg, requireStringArg, wrapResponse, wrapToolError } from './common.js';
 async function handleStartApp(args) {
-    const { platform, appId, deviceId } = args;
+    const platform = requireStringArg(args, 'platform');
+    const appId = requireStringArg(args, 'appId');
+    const deviceId = getStringArg(args, 'deviceId');
     const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId);
     ToolsNetwork.notifyActionStart();
     const res = await (platform === 'android' ? new AndroidManage().startApp(appId, deviceId) : new iOSManage().startApp(appId, deviceId));
@@ -29,13 +31,17 @@ async function handleStartApp(args) {
     }));
 }
 async function handleTerminateApp(args) {
-    const { platform, appId, deviceId } = args;
+    const platform = requireStringArg(args, 'platform');
+    const appId = requireStringArg(args, 'appId');
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await (platform === 'android' ? new AndroidManage().terminateApp(appId, deviceId) : new iOSManage().terminateApp(appId, deviceId));
     const response = { device: res.device, appTerminated: res.appTerminated };
     return wrapResponse(response);
 }
 async function handleRestartApp(args) {
-    const { platform, appId, deviceId } = args;
+    const platform = requireStringArg(args, 'platform');
+    const appId = requireStringArg(args, 'appId');
+    const deviceId = getStringArg(args, 'deviceId');
     const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId);
     ToolsNetwork.notifyActionStart();
     const res = await (platform === 'android' ? new AndroidManage().restartApp(appId, deviceId) : new iOSManage().restartApp(appId, deviceId));
@@ -59,13 +65,18 @@ async function handleRestartApp(args) {
     }));
 }
 async function handleResetAppData(args) {
-    const { platform, appId, deviceId } = args;
+    const platform = requireStringArg(args, 'platform');
+    const appId = requireStringArg(args, 'appId');
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await (platform === 'android' ? new AndroidManage().resetAppData(appId, deviceId) : new iOSManage().resetAppData(appId, deviceId));
     const response = { device: res.device, dataCleared: res.dataCleared };
     return wrapResponse(response);
 }
 async function handleInstallApp(args) {
-    const { platform, projectType, appPath, deviceId } = args;
+    const platform = requireStringArg(args, 'platform');
+    const projectType = requireStringArg(args, 'projectType');
+    const appPath = requireStringArg(args, 'appPath');
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await ToolsManage.installAppHandler({ platform, appPath, deviceId, projectType });
     const response = {
         device: res.device,
@@ -76,12 +87,19 @@ async function handleInstallApp(args) {
     return wrapResponse(response);
 }
 async function handleBuildApp(args) {
-    const { platform, projectType, projectPath, variant } = args;
+    const platform = requireStringArg(args, 'platform');
+    const projectType = requireStringArg(args, 'projectType');
+    const projectPath = requireStringArg(args, 'projectPath');
+    const variant = getStringArg(args, 'variant');
     const res = await ToolsManage.buildAppHandler({ platform, projectPath, variant, projectType });
     return wrapResponse(res);
 }
 async function handleBuildAndInstall(args) {
-    const { platform, projectType, projectPath, deviceId, timeout } = args;
+    const platform = requireStringArg(args, 'platform');
+    const projectType = requireStringArg(args, 'projectType');
+    const projectPath = requireStringArg(args, 'projectPath');
+    const deviceId = getStringArg(args, 'deviceId');
+    const timeout = getNumberArg(args, 'timeout');
     const res = await ToolsManage.buildAndInstallHandler({ platform, projectPath, deviceId, timeout, projectType });
     return {
         content: [
@@ -91,7 +109,16 @@ async function handleBuildAndInstall(args) {
     };
 }
 async function handleGetLogs(args) {
-    const { platform, appId, deviceId, pid, tag, level, contains, since_seconds, limit, lines } = args;
+    const platform = requireStringArg(args, 'platform');
+    const appId = getStringArg(args, 'appId');
+    const deviceId = getStringArg(args, 'deviceId');
+    const pid = getNumberArg(args, 'pid');
+    const tag = getStringArg(args, 'tag');
+    const level = getStringArg(args, 'level');
+    const contains = getStringArg(args, 'contains');
+    const since_seconds = getNumberArg(args, 'since_seconds');
+    const limit = getNumberArg(args, 'limit');
+    const lines = getNumberArg(args, 'lines');
     const res = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, pid, tag, level, contains, since_seconds, limit, lines });
     const filtered = !!(pid || tag || level || contains || since_seconds || appId);
     return {
@@ -102,7 +129,8 @@ async function handleGetLogs(args) {
     };
 }
 async function handleListDevices(args) {
-    const { platform, appId } = args;
+    const platform = getStringArg(args, 'platform');
+    const appId = getStringArg(args, 'appId');
     const res = await ToolsManage.listDevicesHandler({ platform, appId });
     return wrapResponse(res);
 }
@@ -111,7 +139,8 @@ async function handleGetSystemStatus() {
     return wrapResponse(result);
 }
 async function handleCaptureScreenshot(args) {
-    const { platform, deviceId } = args;
+    const platform = requireStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await ToolsObserve.captureScreenshotHandler({ platform, deviceId });
     const mime = res.screenshot_mime || 'image/png';
     const content = [
@@ -125,52 +154,86 @@ async function handleCaptureScreenshot(args) {
     return { content };
 }
 async function handleCaptureDebugSnapshot(args) {
-    const { reason, includeLogs, logLines, platform, appId, deviceId, sessionId } = args;
+    const reason = getStringArg(args, 'reason');
+    const includeLogs = getBooleanArg(args, 'includeLogs');
+    const logLines = getNumberArg(args, 'logLines');
+    const platform = getStringArg(args, 'platform');
+    const appId = getStringArg(args, 'appId');
+    const deviceId = getStringArg(args, 'deviceId');
+    const sessionId = getStringArg(args, 'sessionId');
     const res = await ToolsObserve.captureDebugSnapshotHandler({ reason, includeLogs, logLines, platform, appId, deviceId, sessionId });
     return wrapResponse(res);
 }
 async function handleGetUITree(args) {
-    const { platform, deviceId } = args;
+    const platform = requireStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await ToolsObserve.getUITreeHandler({ platform, deviceId });
     return wrapResponse(res);
 }
 async function handleGetCurrentScreen(args) {
-    const { deviceId } = args;
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await ToolsObserve.getCurrentScreenHandler({ deviceId });
     return wrapResponse(res);
 }
 async function handleGetScreenFingerprint(args) {
-    const { platform, deviceId } = args;
+    const platform = getStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
     return wrapResponse(res);
 }
 async function handleWaitForScreenChange(args) {
-    const { platform, previousFingerprint, timeoutMs, pollIntervalMs, deviceId } = args;
+    const platform = getStringArg(args, 'platform');
+    const previousFingerprint = requireStringArg(args, 'previousFingerprint');
+    const timeoutMs = getNumberArg(args, 'timeoutMs');
+    const pollIntervalMs = getNumberArg(args, 'pollIntervalMs');
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await ToolsInteract.waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs, pollIntervalMs, deviceId });
     return wrapResponse(res);
 }
 async function handleExpectScreen(args) {
-    const { platform, fingerprint, screen, deviceId } = args;
+    const platform = getStringArg(args, 'platform');
+    const fingerprint = getStringArg(args, 'fingerprint');
+    const screen = getStringArg(args, 'screen');
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await ToolsInteract.expectScreenHandler({ platform, fingerprint, screen, deviceId });
     return wrapResponse(res);
 }
 async function handleExpectElementVisible(args) {
-    const { selector, element_id, timeout_ms, poll_interval_ms, platform, deviceId } = args;
+    const selector = requireObjectArg(args, 'selector');
+    const element_id = getStringArg(args, 'element_id');
+    const timeout_ms = getNumberArg(args, 'timeout_ms');
+    const poll_interval_ms = getNumberArg(args, 'poll_interval_ms');
+    const platform = getStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await ToolsInteract.expectElementVisibleHandler({ selector, element_id, timeout_ms, poll_interval_ms, platform, deviceId });
     return wrapResponse(res);
 }
 async function handleWaitForUI(args) {
-    const { selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry, platform, deviceId } = args;
+    const selector = getObjectArg(args, 'selector');
+    const condition = getStringArg(args, 'condition') ?? 'exists';
+    const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000;
+    const poll_interval_ms = getNumberArg(args, 'poll_interval_ms') ?? 300;
+    const match = getObjectArg(args, 'match');
+    const retry = getObjectArg(args, 'retry');
+    const platform = getStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform, deviceId });
     return wrapResponse(res);
 }
 async function handleFindElement(args) {
-    const { query, exact = false, timeoutMs = 3000, platform, deviceId } = args;
+    const query = requireStringArg(args, 'query');
+    const exact = getBooleanArg(args, 'exact') ?? false;
+    const timeoutMs = getNumberArg(args, 'timeoutMs') ?? 3000;
+    const platform = getStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await ToolsInteract.findElementHandler({ query, exact, timeoutMs, platform, deviceId });
     return wrapResponse(res);
 }
 async function handleTap(args) {
-    const { platform, x, y, deviceId } = args;
+    const platform = getStringArg(args, 'platform');
+    const x = requireNumberArg(args, 'x');
+    const y = requireNumberArg(args, 'y');
+    const deviceId = getStringArg(args, 'deviceId');
     const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId);
     ToolsNetwork.notifyActionStart();
     const res = await ToolsInteract.tapHandler({ platform, x, y, deviceId });
@@ -185,13 +248,19 @@ async function handleTap(args) {
     }));
 }
 async function handleTapElement(args) {
-    const { elementId } = args;
+    const elementId = requireStringArg(args, 'elementId');
     ToolsNetwork.notifyActionStart();
     const res = await ToolsInteract.tapElementHandler({ elementId });
     return wrapResponse(res);
 }
 async function handleSwipe(args) {
-    const { platform = 'android', x1, y1, x2, y2, duration, deviceId } = args;
+    const platform = getStringArg(args, 'platform') ?? 'android';
+    const x1 = requireNumberArg(args, 'x1');
+    const y1 = requireNumberArg(args, 'y1');
+    const x2 = requireNumberArg(args, 'x2');
+    const y2 = requireNumberArg(args, 'y2');
+    const duration = requireNumberArg(args, 'duration');
+    const deviceId = getStringArg(args, 'deviceId');
     const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId);
     ToolsNetwork.notifyActionStart();
     const res = await ToolsInteract.swipeHandler({ platform, x1, y1, x2, y2, duration, deviceId });
@@ -206,14 +275,19 @@ async function handleSwipe(args) {
     }));
 }
 async function handleScrollToElement(args) {
-    const { platform, selector, direction, maxScrolls, scrollAmount, deviceId } = args;
+    const platform = requireStringArg(args, 'platform');
+    const selector = requireObjectArg(args, 'selector');
+    const direction = getStringArg(args, 'direction');
+    const maxScrolls = getNumberArg(args, 'maxScrolls');
+    const scrollAmount = getNumberArg(args, 'scrollAmount');
+    const deviceId = getStringArg(args, 'deviceId');
     const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId);
     ToolsNetwork.notifyActionStart();
     const res = await ToolsInteract.scrollToElementHandler({ platform, selector, direction, maxScrolls, scrollAmount, deviceId });
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'scroll_to_element',
-        selector,
+        selector: selector ?? null,
         resolved: res?.success && res?.element ? {
             elementId: null,
             text: res.element.text ?? null,
@@ -230,7 +304,8 @@ async function handleScrollToElement(args) {
     }));
 }
 async function handleTypeText(args) {
-    const { text, deviceId } = args;
+    const text = requireStringArg(args, 'text');
+    const deviceId = getStringArg(args, 'deviceId');
     const uiFingerprintBefore = await captureActionFingerprint('android', deviceId);
     ToolsNetwork.notifyActionStart();
     const res = await ToolsInteract.typeTextHandler({ text, deviceId });
@@ -245,7 +320,7 @@ async function handleTypeText(args) {
     }));
 }
 async function handlePressBack(args) {
-    const { deviceId } = args;
+    const deviceId = getStringArg(args, 'deviceId');
     const uiFingerprintBefore = await captureActionFingerprint('android', deviceId);
     ToolsNetwork.notifyActionStart();
     const res = await ToolsInteract.pressBackHandler({ deviceId });
@@ -260,24 +335,35 @@ async function handlePressBack(args) {
     }));
 }
 async function handleStartLogStream(args) {
-    const { platform, packageName, level, sessionId, deviceId } = args;
+    const platform = getStringArg(args, 'platform') ?? 'android';
+    const packageName = requireStringArg(args, 'packageName');
+    const level = getStringArg(args, 'level') ?? 'error';
+    const sessionId = getStringArg(args, 'sessionId');
+    const deviceId = getStringArg(args, 'deviceId');
     const res = await ToolsObserve.startLogStreamHandler({ platform, packageName, level, sessionId, deviceId });
     return wrapResponse(res);
 }
 async function handleReadLogStream(args) {
-    const { platform, sessionId, limit, since } = args;
+    const platform = getStringArg(args, 'platform');
+    const sessionId = getStringArg(args, 'sessionId');
+    const limit = getNumberArg(args, 'limit');
+    const since = getStringArg(args, 'since');
     const res = await ToolsObserve.readLogStreamHandler({ platform, sessionId, limit, since });
     return wrapResponse(res);
 }
 async function handleStopLogStream(args) {
-    const { platform, sessionId } = args;
+    const platform = getStringArg(args, 'platform');
+    const sessionId = getStringArg(args, 'sessionId');
     const res = await ToolsObserve.stopLogStreamHandler({ platform, sessionId });
     return wrapResponse(res);
 }
 function handleClassifyActionOutcome(args) {
-    const { uiChanged, expectedElementVisible, networkRequests, hasLogErrors } = args;
+    const uiChanged = requireBooleanArg(args, 'uiChanged');
+    const expectedElementVisible = getBooleanArg(args, 'expectedElementVisible');
+    const networkRequests = getArrayArg(args, 'networkRequests');
+    const hasLogErrors = getBooleanArg(args, 'hasLogErrors');
     const result = classifyActionOutcome({
-        uiChanged: Boolean(uiChanged),
+        uiChanged,
         expectedElementVisible: expectedElementVisible ?? null,
         networkRequests: networkRequests ?? null,
         hasLogErrors: hasLogErrors ?? null
@@ -285,7 +371,8 @@ function handleClassifyActionOutcome(args) {
     return Promise.resolve(wrapResponse(result));
 }
 async function handleGetNetworkActivity(args) {
-    const { platform, deviceId } = args;
+    const platform = requireStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
     const result = await ToolsNetwork.getNetworkActivity({ platform, deviceId });
     return wrapResponse(result);
 }

package/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.7.0'
+    version: '0.24.7'
 };
 export function createServer() {
     const server = new Server(serverInfo, {