mobile-debug-mcp 0.12.2 → 0.12.3

package/dist/android/utils.js

@@ -11,7 +11,17 @@ export async function prepareGradle(projectPath) {
     const gradlewPath = path.join(projectPath, 'gradlew');
     const gradleCmd = existsSync(gradlewPath) ? './gradlew' : 'gradle';
     const execCmd = existsSync(gradlewPath) ? gradlewPath : gradleCmd;
-    const gradleArgs = ['assembleDebug'];
+    // Start with a default task; callers may append/override via env flags
+    const gradleArgs = [process.env.MCP_GRADLE_TASK || 'assembleDebug'];
+    // Respect generic MCP_BUILD_JOBS and Android-specific MCP_GRADLE_WORKERS
+    const workers = process.env.MCP_GRADLE_WORKERS || process.env.MCP_BUILD_JOBS;
+    if (workers) {
+        gradleArgs.push(`--max-workers=${workers}`);
+    }
+    // Respect gradle cache env: default enabled; set MCP_GRADLE_CACHE=0 to disable
+    if (process.env.MCP_GRADLE_CACHE === '0') {
+        gradleArgs.push('-Dorg.gradle.caching=false');
+    }
     const detectedJavaHome = await detectJavaHome().catch(() => undefined);
     const env = Object.assign({}, process.env);
     if (detectedJavaHome) {

package/dist/ios/manage.js

@@ -72,8 +72,17 @@ export class iOSManage {
                 catch { }
                 return null;
             }
+            // Prepare build flags and paths (support incremental builds)
             let buildArgs;
             let chosenScheme = null;
+            // Derived data and result bundle (agent-configurable)
+            const derivedDataPath = process.env.MCP_DERIVED_DATA || path.join(projectRootDir, 'build', 'DerivedData');
+            const resultBundlePath = path.join(projectRootDir, 'build', 'xcresults', 'ResultBundle.xcresult');
+            const xcodeJobs = parseInt(process.env.MCP_XCODE_JOBS || '', 10) || 4;
+            const forceClean = process.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(() => { });
             if (workspace) {
                 const workspacePath = path.join(projectRootDir, workspace);
                 chosenScheme = await detectScheme(xcodeCmd, workspacePath, undefined, projectRootDir);
@@ -86,16 +95,27 @@ export class iOSManage {
                 const scheme = chosenScheme || proj.replace(/\.xcodeproj$/, '');
                 buildArgs = ['-project', projectPathFull, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build'];
             }
+            // Insert clean if explicitly requested via env
+            if (forceClean) {
+                const idx = buildArgs.indexOf('build');
+                if (idx >= 0)
+                    buildArgs.splice(idx, 0, 'clean');
+            }
             // If we have a destination UDID, add an explicit destination to avoid xcodebuild picking an ambiguous target
             if (destinationUDID) {
                 buildArgs.push('-destination', `platform=iOS Simulator,id=${destinationUDID}`);
             }
-            // Add result bundle path for diagnostics
+            // Add derived data and result bundle for diagnostics and faster incremental builds
+            buildArgs.push('-derivedDataPath', derivedDataPath);
+            buildArgs.push('-resultBundlePath', resultBundlePath);
+            // parallelisation and jobs
+            buildArgs.push('-parallelizeTargets');
+            buildArgs.push('-jobs', String(xcodeJobs));
+            // Prepare results directory for backwards-compatible logs
             const resultsDir = path.join(projectPath, 'build-results');
             // 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(() => { });
-            // Skip specifying -resultBundlePath to avoid platform-specific collisions; rely on stdout/stderr logs
             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 tries = MAX_RETRIES + 1;

package/dist/ios/utils.js

@@ -239,6 +239,7 @@ export async function getIOSDeviceMetadata(deviceId = "booted") {
 }
 export async function listIOSDevices(appId) {
     return new Promise((resolve) => {
+        // Query all devices and separately query booted devices to mark them
         execFile(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], (err, stdout) => {
             if (err || !stdout)
                 return resolve([]);
@@ -247,32 +248,50 @@ export async function listIOSDevices(appId) {
                 const devicesMap = data.devices || {};
                 const out = [];
                 const checks = [];
-                for (const runtime in devicesMap) {
-                    const devices = devicesMap[runtime];
-                    if (Array.isArray(devices)) {
-                        for (const device of devices) {
-                            const info = {
-                                platform: 'ios',
-                                id: device.udid,
-                                osVersion: parseRuntimeName(runtime),
-                                model: device.name,
-                                simulator: true
-                            };
-                            if (appId) {
-                                // check if installed
-                                const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
-                                    .then(() => { info.appInstalled = true; })
-                                    .catch(() => { info.appInstalled = false; })
-                                    .then(() => { out.push(info); });
-                                checks.push(p);
+                // Get booted devices set
+                execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err2, stdout2) => {
+                    const bootedSet = new Set();
+                    if (!err2 && stdout2) {
+                        try {
+                            const bdata = JSON.parse(stdout2);
+                            const bmap = bdata.devices || {};
+                            for (const rt in bmap) {
+                                const devs = bmap[rt];
+                                if (Array.isArray(devs))
+                                    for (const d of devs)
+                                        bootedSet.add(d.udid);
                             }
-                            else {
-                                out.push(info);
+                        }
+                        catch { }
+                    }
+                    for (const runtime in devicesMap) {
+                        const devices = devicesMap[runtime];
+                        if (Array.isArray(devices)) {
+                            for (const device of devices) {
+                                const info = {
+                                    platform: 'ios',
+                                    id: device.udid,
+                                    osVersion: parseRuntimeName(runtime),
+                                    model: device.name,
+                                    simulator: true,
+                                    booted: bootedSet.has(device.udid)
+                                };
+                                if (appId) {
+                                    // check if installed
+                                    const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
+                                        .then(() => { info.appInstalled = true; })
+                                        .catch(() => { info.appInstalled = false; })
+                                        .then(() => { out.push(info); });
+                                    checks.push(p);
+                                }
+                                else {
+                                    out.push(info);
+                                }
                             }
                         }
                     }
-                }
-                Promise.all(checks).then(() => resolve(out)).catch(() => resolve(out));
+                    Promise.all(checks).then(() => resolve(out)).catch(() => resolve(out));
+                });
             }
             catch {
                 resolve([]);

package/dist/server.js

@@ -120,6 +120,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 type: "object",
                 properties: {
                     platform: { type: "string", enum: ["android", "ios"], description: "Optional. If omitted the server will attempt to detect platform from appPath/project files." },
+                    projectType: { type: "string", enum: ["native", "kmp", "react-native", "flutter"], description: "Optional project type to guide build tool selection (e.g., kmp, react-native)." },
                     appPath: { type: "string", description: "Path to APK, .app, .ipa, or project directory" },
                     deviceId: { type: "string", description: "Device UDID (iOS) or Serial (Android). Defaults to booted/connected." }
                 },
@@ -133,6 +134,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 type: "object",
                 properties: {
                     platform: { type: "string", enum: ["android", "ios"], description: "Optional. If omitted the server will attempt to detect platform from projectPath files." },
+                    projectType: { type: "string", enum: ["native", "kmp", "react-native", "flutter"], description: "Optional project type to guide build tool selection (e.g., kmp, react-native)." },
                     projectPath: { type: "string", description: "Path to project directory (contains gradlew or xcodeproj/xcworkspace)" },
                     variant: { type: "string", description: "Optional build variant (e.g., Debug/Release)" }
                 },
@@ -414,8 +416,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return wrapResponse(response);
         }
         if (name === "install_app") {
-            const { platform, appPath, deviceId } = args;
-            const res = await ToolsManage.installAppHandler({ platform, appPath, deviceId });
+            const { platform, projectType, appPath, deviceId } = args;
+            const res = await ToolsManage.installAppHandler({ platform, appPath, deviceId, projectType });
             const response = {
                 device: res.device,
                 installed: res.installed,
@@ -425,13 +427,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return wrapResponse(response);
         }
         if (name === "build_app") {
-            const { platform, projectPath, variant } = args;
-            const res = await ToolsManage.buildAppHandler({ platform, projectPath, variant });
+            const { platform, projectType, projectPath, variant } = args;
+            const res = await ToolsManage.buildAppHandler({ platform, projectPath, variant, projectType });
             return wrapResponse(res);
         }
         if (name === 'build_and_install') {
-            const { platform, projectPath, deviceId, timeout } = args;
-            const res = await ToolsManage.buildAndInstallHandler({ platform, projectPath, deviceId, timeout });
+            const { platform, projectType, projectPath, deviceId, timeout } = args;
+            const res = await ToolsManage.buildAndInstallHandler({ platform, projectPath, deviceId, timeout, projectType });
             // res: { ndjson, result }
             return {
                 content: [

package/dist/tools/manage.js

@@ -3,8 +3,149 @@ import path from 'path';
 import { resolveTargetDevice, listDevices } from '../utils/resolve-device.js';
 import { AndroidManage } from '../android/manage.js';
 import { iOSManage } from '../ios/manage.js';
+import { findApk } from '../android/utils.js';
+import { findAppBundle } from '../ios/utils.js';
+import { execSync } from 'child_process';
+export async function detectProjectPlatform(projectPath) {
+    try {
+        const stat = await fs.stat(projectPath).catch(() => null);
+        if (stat && stat.isDirectory()) {
+            const files = (await fs.readdir(projectPath).catch(() => []));
+            const hasIos = files.some(f => f.endsWith('.xcodeproj') || f.endsWith('.xcworkspace'));
+            const hasAndroid = files.includes('gradlew') || files.includes('build.gradle') || files.includes('settings.gradle') || (files.includes('app') && (await fs.stat(path.join(projectPath, 'app')).catch(() => null)));
+            if (hasIos && !hasAndroid)
+                return 'ios';
+            if (hasAndroid && !hasIos)
+                return 'android';
+            if (hasIos && hasAndroid)
+                return 'ambiguous';
+            return 'unknown';
+        }
+        else {
+            const ext = path.extname(projectPath).toLowerCase();
+            if (ext === '.apk')
+                return 'android';
+            if (ext === '.ipa' || ext === '.app')
+                return 'ios';
+            return 'unknown';
+        }
+    }
+    catch {
+        return 'unknown';
+    }
+}
 export class ToolsManage {
-    static async buildAppHandler({ platform, projectPath, variant }) {
+    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;
+    }
+    static async build_ios({ projectPath, workspace: _workspace, project: _project, scheme: _scheme, destinationUDID, derivedDataPath, buildJobs, forceClean }) {
+        const ios = new iOSManage();
+        // silence unused param lints
+        void _workspace;
+        void _project;
+        void _scheme;
+        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 artifact = await ios.build(projectPath);
+        return artifact;
+    }
+    static async build_flutter({ projectPath, platform, buildMode, maxWorkers: _maxWorkers, forceClean: _forceClean }) {
+        // Prefer using flutter CLI when available; otherwise delegate to native subproject builders
+        const flutterCmd = process.env.FLUTTER_PATH || 'flutter';
+        // silence unused params
+        void _maxWorkers;
+        void _forceClean;
+        try {
+            // Check flutter presence without streaming output
+            execSync(`${flutterCmd} --version`, { stdio: 'ignore' });
+            if (!platform || platform === 'android') {
+                const mode = buildMode || 'debug';
+                try {
+                    const out = execSync(`${flutterCmd} build apk --${mode}`, { cwd: projectPath, encoding: 'utf8' });
+                    // Try to find built APK
+                    const apk = await findApk(path.join(projectPath));
+                    if (apk)
+                        return { artifactPath: apk, output: out };
+                }
+                catch (err) {
+                    const stdout = err && err.stdout ? String(err.stdout) : '';
+                    const stderr = err && err.stderr ? String(err.stderr) : '';
+                    throw new Error(`flutter build apk failed: ${stderr || stdout || err.message}`);
+                }
+            }
+            if (!platform || platform === 'ios') {
+                const mode = buildMode || 'debug';
+                try {
+                    const out = execSync(`${flutterCmd} build ios --${mode} --no-codesign`, { cwd: projectPath, encoding: 'utf8' });
+                    const app = await findAppBundle(path.join(projectPath));
+                    if (app)
+                        return { artifactPath: app, output: out };
+                }
+                catch (err) {
+                    const stdout = err && err.stdout ? String(err.stdout) : '';
+                    const stderr = err && err.stderr ? String(err.stderr) : '';
+                    throw new Error(`flutter build ios failed: ${stderr || stdout || err.message}`);
+                }
+            }
+        }
+        catch (e) {
+            // If flutter CLI not available or command fails, fall back to native subprojects
+            // Preserve error message for diagnostics if needed
+            void e;
+        }
+        // Fallback: try native subproject builds
+        if (!platform || platform === 'android') {
+            const androidDir = path.join(projectPath, 'android');
+            const android = new AndroidManage();
+            const artifact = await android.build(androidDir, _forceClean ? 'clean && assembleDebug' : 'assembleDebug');
+            return artifact;
+        }
+        if (!platform || platform === 'ios') {
+            const iosDir = path.join(projectPath, 'ios');
+            const ios = new iOSManage();
+            const artifact = await ios.build(iosDir);
+            return artifact;
+        }
+        return { error: 'Unable to build flutter project' };
+    }
+    static async build_react_native({ projectPath, platform, variant, maxWorkers: _maxWorkers, forceClean: _forceClean }) {
+        // silence unused params
+        void _maxWorkers;
+        void _forceClean;
+        // React Native typically uses native subprojects. Delegate to Android/iOS builders.
+        if (!platform || platform === 'android') {
+            const androidDir = path.join(projectPath, 'android');
+            const android = new AndroidManage();
+            const artifact = await android.build(androidDir, variant || 'assembleDebug');
+            return artifact;
+        }
+        if (!platform || platform === 'ios') {
+            const iosDir = path.join(projectPath, 'ios');
+            // Recommend running `pod install` prior to building in CI; not performed automatically here
+            const ios = new iOSManage();
+            const artifact = await ios.build(iosDir);
+            return artifact;
+        }
+        return { error: 'Unable to build react-native project' };
+    }
+    static async buildAppHandler({ platform, projectPath, variant, projectType: _projectType }) {
+        void _projectType;
         // delegate to platform-specific build implementations
         const chosen = platform || 'android';
         if (chosen === 'android') {
@@ -18,8 +159,20 @@ export class ToolsManage {
             return artifact;
         }
     }
-    static async installAppHandler({ platform, appPath, deviceId }) {
+    static async installAppHandler({ platform, appPath, deviceId, projectType }) {
+        // Use projectType hint to influence platform detection when explicit platform is not provided
         let chosenPlatform = platform;
+        if (!chosenPlatform && projectType) {
+            // Heuristic defaults: KMP, React Native and Flutter commonly target Android by default in CI
+            if (projectType === 'kmp' || projectType === 'react-native' || projectType === 'flutter') {
+                chosenPlatform = 'android';
+                console.debug('[manage] projectType hint -> selecting android by default for', projectType);
+            }
+            else if (projectType === 'native' || projectType === 'ios') {
+                chosenPlatform = 'ios';
+                console.debug('[manage] projectType hint -> selecting ios by default for', projectType);
+            }
+        }
         try {
             const stat = await fs.stat(appPath).catch(() => null);
             if (stat && stat.isDirectory()) {
@@ -106,36 +259,44 @@ export class ToolsManage {
             return await new iOSManage().resetAppData(appId, resolved.id);
         }
     }
-    static async buildAndInstallHandler({ platform, projectPath, deviceId, timeout }) {
+    static async buildAndInstallHandler({ platform, projectPath, deviceId, timeout, projectType }) {
         const events = [];
         const pushEvent = (obj) => events.push(JSON.stringify(obj));
         const effectiveTimeout = timeout ?? 180000; // reserved for future streaming/timeouts
         void effectiveTimeout;
-        // determine platform if not provided by inspecting path
+        // determine platform if not provided by inspecting path or projectType hint
         let chosenPlatform = platform;
         try {
-            const stat = await fs.stat(projectPath).catch(() => null);
             if (!chosenPlatform) {
-                if (stat && stat.isDirectory()) {
-                    const files = (await fs.readdir(projectPath).catch(() => []));
-                    if (files.some(f => f.endsWith('.xcodeproj') || f.endsWith('.xcworkspace')))
-                        chosenPlatform = 'ios';
-                    else
-                        chosenPlatform = 'android';
+                // If autodetect is disabled, require explicit platform or projectType
+                if (process.env.MCP_DISABLE_AUTODETECT === '1') {
+                    pushEvent({ type: 'build', status: 'failed', error: 'MCP_DISABLE_AUTODETECT=1 requires explicit platform or projectType' });
+                    return { ndjson: events.join('\n') + '\n', result: { success: false, error: 'MCP_DISABLE_AUTODETECT=1 requires explicit platform or projectType (ios|android).' } };
+                }
+                // If caller indicated KMP, prefer android by default (most KMP modul8 setups target Android)
+                if (projectType === 'kmp') {
+                    chosenPlatform = 'android';
+                    pushEvent({ type: 'build', status: 'info', message: 'projectType=kmp -> selecting android platform by default' });
                 }
                 else {
-                    const ext = path.extname(projectPath).toLowerCase();
-                    if (ext === '.apk')
-                        chosenPlatform = 'android';
-                    else if (ext === '.ipa' || ext === '.app')
-                        chosenPlatform = 'ios';
-                    else
-                        chosenPlatform = 'android';
+                    const det = await detectProjectPlatform(projectPath);
+                    if (det === 'ios' || det === 'android') {
+                        chosenPlatform = det;
+                    }
+                    else if (det === 'ambiguous') {
+                        pushEvent({ type: 'build', status: 'failed', error: 'Ambiguous project (contains both iOS and Android). Please provide platform: "ios" or "android".' });
+                        return { ndjson: events.join('\n') + '\n', result: { success: false, error: 'Ambiguous project - please provide explicit platform parameter (ios|android).' } };
+                    }
+                    else {
+                        // Unknown project type - do not guess. Request explicit platform.
+                        pushEvent({ type: 'build', status: 'failed', error: 'Unknown project type - unable to autodetect platform. Please provide platform or projectType.' });
+                        return { ndjson: events.join('\n') + '\n', result: { success: false, error: 'Unknown project type - please provide platform or projectType (ios|android).' } };
+                    }
                 }
             }
         }
         catch {
-            chosenPlatform = chosenPlatform || 'android';
+            // detection failed; avoid guessing a platform
         }
         pushEvent({ type: 'build', status: 'started', platform: chosenPlatform });
         let buildRes;

package/dist/utils/resolve-device.js

@@ -49,6 +49,14 @@ export async function resolveTargetDevice(opts) {
             if (physical.length > 1)
                 candidates = physical;
         }
+        // Prefer booted iOS simulators if present
+        if (platform === 'ios') {
+            const booted = candidates.filter((d) => !!d.booted);
+            if (booted.length === 1)
+                return booted[0];
+            if (booted.length > 1)
+                return booted[0]; // if multiple booted, pick the first
+        }
         candidates.sort((a, b) => parseNumericVersion(b.osVersion) - parseNumericVersion(a.osVersion));
         if (candidates.length > 1 && parseNumericVersion(candidates[0].osVersion) > parseNumericVersion(candidates[1].osVersion)) {
             return candidates[0];

package/docs/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.12.3]
+- Now supports native and cross platform development platforms for building
+- Add MCP_DISABLE_AUTODETECT env var to require explicit platform/projectType for deterministic agent runs. When set to 1, build/install handlers will fail if platform is not provided.
+- Add unit test covering MCP_DISABLE_AUTODETECT behaviour and ambiguous project detection (test/unit/manage/mcp_disable_autodetect.test.ts).
+- Improve build_and_install handler to emit a clear NDJSON event when autodetect is disabled and platform was not supplied.
+
+
 ## [0.12.1]
 - Improve iOS build/install reliability: project auto-scan, explicit simulator destination, configurable watchdog timeout (MCP_XCODEBUILD_TIMEOUT) and retries (MCP_XCODEBUILD_RETRIES), and DerivedData fallback for locating .app artifacts.
 - Make install_app capable of building iOS projects before installing so agents can autonomously fix, build, install and validate apps.