mobile-debug-mcp 0.12.2 → 0.12.4

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

@@ -3,11 +3,16 @@ import { spawn, spawnSync } from "child_process";
 import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "./utils.js";
 import path from "path";
 export class iOSManage {
-    async build(projectPath, _variant) {
-        void _variant;
+    async build(projectPath, optsOrVariant) {
+        // Support legacy variant string as second arg
+        let opts = {};
+        if (typeof optsOrVariant === 'string')
+            opts.variant = optsOrVariant;
+        else
+            opts = optsOrVariant || {};
         try {
             // Look for an Xcode workspace or project at the provided path. If not present, scan subdirectories (limited depth)
-            async function findProject(root, maxDepth = 3) {
+            async function findProject(root, maxDepth = 4) {
                 try {
                     const ents = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
                     for (const e of ents) {
@@ -36,14 +41,31 @@ export class iOSManage {
             }
             // Resolve projectPath to an absolute path to avoid cwd-relative resolution issues
             const absProjectPath = path.resolve(projectPath);
-            const projectInfo = await findProject(absProjectPath, 3);
-            if (!projectInfo)
-                return { error: 'No Xcode project or workspace found' };
-            const projectRootDir = projectInfo.dir || absProjectPath;
-            const workspace = projectInfo.workspace;
-            const proj = projectInfo.proj;
-            // Determine destination: prefer explicit env var, otherwise use booted simulator UDID
-            let destinationUDID = process.env.MCP_XCODE_DESTINATION_UDID || process.env.MCP_XCODE_DESTINATION || '';
+            // If caller supplied explicit workspace/project, prefer those and set projectRootDir accordingly
+            let projectRootDir = absProjectPath;
+            let workspace = opts.workspace;
+            let proj = opts.project;
+            if (workspace) {
+                // normalize workspace path and set root to its parent
+                workspace = path.isAbsolute(workspace) ? workspace : path.join(absProjectPath, workspace);
+                projectRootDir = path.dirname(workspace);
+                workspace = path.basename(workspace);
+            }
+            else if (proj) {
+                proj = path.isAbsolute(proj) ? proj : path.join(absProjectPath, proj);
+                projectRootDir = path.dirname(proj);
+                proj = path.basename(proj);
+            }
+            else {
+                const projectInfo = await findProject(absProjectPath, 4);
+                if (!projectInfo)
+                    return { error: 'No Xcode project or workspace found' };
+                projectRootDir = projectInfo.dir || absProjectPath;
+                workspace = projectInfo.workspace;
+                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 || '';
             if (!destinationUDID) {
                 try {
                     const meta = await getIOSDeviceMetadata('booted');
@@ -53,7 +75,7 @@ export class iOSManage {
                 catch { }
             }
             // Determine xcode command early so it can be used when detecting schemes
-            const xcodeCmd = process.env.XCODEBUILD_PATH || 'xcodebuild';
+            const xcodeCmd = opts.xcodeCmd || process.env.XCODEBUILD_PATH || 'xcodebuild';
             // Determine available schemes by querying xcodebuild -list rather than guessing
             async function detectScheme(xcodeCmdInner, workspacePath, projectPathFull, cwd) {
                 try {
@@ -72,30 +94,55 @@ export class iOSManage {
                 catch { }
                 return null;
             }
+            // Prepare build flags and paths (support incremental builds)
             let buildArgs;
-            let chosenScheme = null;
+            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');
+            // 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';
+            // ensure result dirs exist
+            await fs.mkdir(path.dirname(resultBundlePath), { recursive: true }).catch(() => { });
+            await fs.mkdir(derivedDataPath, { recursive: true }).catch(() => { });
+            // remove any pre-existing result bundle path to avoid xcodebuild complaining
+            await fs.rm(resultBundlePath, { recursive: true, force: true }).catch(() => { });
             if (workspace) {
                 const workspacePath = path.join(projectRootDir, workspace);
-                chosenScheme = await detectScheme(xcodeCmd, workspacePath, undefined, projectRootDir);
+                if (!chosenScheme)
+                    chosenScheme = await detectScheme(xcodeCmd, workspacePath, undefined, projectRootDir);
                 const scheme = chosenScheme || workspace.replace(/\.xcworkspace$/, '');
                 buildArgs = ['-workspace', workspacePath, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build'];
             }
             else {
                 const projectPathFull = path.join(projectRootDir, proj);
-                chosenScheme = await detectScheme(xcodeCmd, undefined, projectPathFull, projectRootDir);
+                if (!chosenScheme)
+                    chosenScheme = await detectScheme(xcodeCmd, undefined, projectPathFull, projectRootDir);
                 const scheme = chosenScheme || proj.replace(/\.xcodeproj$/, '');
                 buildArgs = ['-project', projectPathFull, '-scheme', scheme, '-configuration', 'Debug', '-sdk', 'iphonesimulator', 'build'];
             }
+            // Insert clean if explicitly requested via env or opts
+            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

@@ -115,28 +115,30 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "install_app",
-            description: "Install an app on Android or iOS. Accepts a built binary (apk/.ipa/.app) or a project directory to build then install.",
+            description: "Install an app on Android or iOS. Accepts a built binary (apk/.ipa/.app) or a project directory to build then install. platform and projectType are required.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    platform: { type: "string", enum: ["android", "ios"], description: "Optional. If omitted the server will attempt to detect platform from appPath/project files." },
+                    platform: { type: "string", enum: ["android", "ios"], description: "Platform to install to (required)." },
+                    projectType: { type: "string", enum: ["native", "kmp", "react-native", "flutter"], description: "Project type to guide build/install tool selection (required)." },
                     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." }
                 },
-                required: ["appPath"]
+                required: ["platform", "projectType", "appPath"]
             }
         },
         {
             name: "build_app",
-            description: "Build a project for Android or iOS and return the built artifact path. Does not install.",
+            description: "Build a project for Android or iOS and return the built artifact path. Does not install. platform and projectType are required.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    platform: { type: "string", enum: ["android", "ios"], description: "Optional. If omitted the server will attempt to detect platform from projectPath files." },
+                    platform: { type: "string", enum: ["android", "ios"], description: "Platform to build for (required)." },
+                    projectType: { type: "string", enum: ["native", "kmp", "react-native", "flutter"], description: "Project type to guide build tool selection (required)." },
                     projectPath: { type: "string", description: "Path to project directory (contains gradlew or xcodeproj/xcworkspace)" },
                     variant: { type: "string", description: "Optional build variant (e.g., Debug/Release)" }
                 },
-                required: ["projectPath"]
+                required: ["platform", "projectType", "projectPath"]
             }
         },
         {
@@ -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,196 @@ 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) {
+    // Recursively scan up to a limited depth for platform markers to avoid mis-detection
+    async function scan(dir, depth = 3) {
+        const res = { ios: false, android: false };
+        try {
+            const ents = await fs.readdir(dir).catch(() => []);
+            for (const e of ents) {
+                if (e.endsWith('.xcworkspace') || e.endsWith('.xcodeproj'))
+                    res.ios = true;
+                if (e === 'gradlew' || e === 'build.gradle' || e === 'settings.gradle')
+                    res.android = true;
+                if (res.ios && res.android)
+                    return res;
+            }
+            if (depth <= 0)
+                return res;
+            for (const e of ents) {
+                try {
+                    const full = path.join(dir, e);
+                    const st = await fs.stat(full).catch(() => null);
+                    if (st && st.isDirectory()) {
+                        const child = await scan(full, depth - 1);
+                        if (child.ios)
+                            res.ios = true;
+                        if (child.android)
+                            res.android = true;
+                        if (res.ios && res.android)
+                            return res;
+                    }
+                }
+                catch { }
+            }
+        }
+        catch { }
+        return res;
+    }
+    try {
+        const stat = await fs.stat(projectPath).catch(() => null);
+        if (stat && stat.isDirectory()) {
+            const { ios: hasIos, android: hasAndroid } = await scan(projectPath, 3);
+            if (hasIos && !hasAndroid)
+                return 'ios';
+            if (hasAndroid && !hasIos)
+                return 'android';
+            if (hasIos && hasAndroid)
+                return 'ambiguous';
+            // no explicit markers found
+            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();
+        // 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;
+        if (_project)
+            opts.project = _project;
+        if (_scheme)
+            opts.scheme = _scheme;
+        if (destinationUDID)
+            opts.destinationUDID = destinationUDID;
+        if (derivedDataPath)
+            opts.derivedDataPath = derivedDataPath;
+        if (forceClean)
+            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;
+    }
+    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,41 +206,12 @@ export class ToolsManage {
             return artifact;
         }
     }
-    static async installAppHandler({ platform, appPath, deviceId }) {
-        let chosenPlatform = platform;
-        try {
-            const stat = await fs.stat(appPath).catch(() => null);
-            if (stat && stat.isDirectory()) {
-                // If the directory itself looks like an .app bundle, treat as iOS
-                if (appPath.endsWith('.app')) {
-                    chosenPlatform = 'ios';
-                }
-                else {
-                    const files = (await fs.readdir(appPath).catch(() => []));
-                    if (files.some(f => f.endsWith('.xcodeproj') || f.endsWith('.xcworkspace'))) {
-                        chosenPlatform = 'ios';
-                    }
-                    else if (files.includes('gradlew') || files.includes('build.gradle') || files.includes('settings.gradle') || (files.includes('app') && (await fs.stat(path.join(appPath, 'app')).catch(() => null)))) {
-                        chosenPlatform = 'android';
-                    }
-                    else {
-                        chosenPlatform = 'android';
-                    }
-                }
-            }
-            else if (typeof appPath === 'string') {
-                const ext = path.extname(appPath).toLowerCase();
-                if (ext === '.apk')
-                    chosenPlatform = 'android';
-                else if (ext === '.ipa' || ext === '.app')
-                    chosenPlatform = 'ios';
-                else
-                    chosenPlatform = 'android';
-            }
-        }
-        catch {
-            chosenPlatform = 'android';
+    static async installAppHandler({ platform, appPath, deviceId, projectType }) {
+        // Enforce explicit platform and projectType: both are mandatory to avoid ambiguity
+        if (!platform || !projectType) {
+            throw new Error('Both platform and projectType parameters are required (platform: ios|android, projectType: native|kmp|react-native|flutter).');
         }
+        const chosenPlatform = platform;
         if (chosenPlatform === 'android') {
             const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
             const androidRun = new AndroidManage();
@@ -106,36 +265,59 @@ 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
+        // Require explicit platform and projectType to avoid ambiguous autodetection
+        if (!platform || !projectType) {
+            pushEvent({ type: 'build', status: 'failed', error: 'Both platform and projectType parameters are required.' });
+            return { ndjson: events.join('\n') + '\n', result: { success: false, error: 'Both platform and projectType parameters are required (platform: ios|android, projectType: native|kmp|react-native|flutter).' } };
+        }
+        // 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
+                // If caller provided projectType, respect it as a hard override and map to platform
+                if (projectType) {
+                    if (projectType === 'kmp' || projectType === 'react-native' || projectType === 'flutter') {
                         chosenPlatform = 'android';
+                        pushEvent({ type: 'build', status: 'info', message: `projectType=${projectType} -> forcing android platform` });
+                    }
+                    else if (projectType === 'native' || projectType === 'ios') {
+                        chosenPlatform = 'ios';
+                        pushEvent({ type: 'build', status: 'info', message: `projectType=${projectType} -> forcing ios platform` });
+                    }
+                    else {
+                        pushEvent({ type: 'build', status: 'failed', error: `Unknown projectType: ${projectType}` });
+                        return { ndjson: events.join('\n') + '\n', result: { success: false, error: `Unknown projectType: ${projectType}` } };
+                    }
                 }
                 else {
-                    const ext = path.extname(projectPath).toLowerCase();
-                    if (ext === '.apk')
-                        chosenPlatform = 'android';
-                    else if (ext === '.ipa' || ext === '.app')
-                        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).' } };
+                    }
+                    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;
@@ -157,7 +339,7 @@ export class ToolsManage {
         pushEvent({ type: 'install', status: 'started', artifactPath: artifact, deviceId });
         let installRes;
         try {
-            installRes = await ToolsManage.installAppHandler({ platform: chosenPlatform, appPath: artifact, deviceId });
+            installRes = await ToolsManage.installAppHandler({ platform: chosenPlatform, appPath: artifact, deviceId, projectType });
             if (installRes && installRes.installed === true) {
                 pushEvent({ type: 'install', status: 'finished', artifactPath: artifact, device: installRes.device });
                 return { ndjson: events.join('\n') + '\n', result: { success: true, artifactPath: artifact, device: installRes.device, output: installRes.output } };

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];