mobile-debug-mcp 0.12.1 → 0.12.3

package/README.md

@@ -1,4 +1,4 @@
-# Mobile Dev MCP
+# Mobile Dev Tools
 
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, and inspect Android/iOS apps from an MCP-compatible client.
 

package/dist/android/diagnostics.js

@@ -1,24 +1 @@
-import { spawnSync } from 'child_process';
-import { getAdbCmd } from './utils.js';
-import { makeEnvSnapshot } from '../utils/diagnostics.js';
-export function execAdbWithDiagnostics(args, deviceId) {
-    const adbArgs = deviceId ? ['-s', deviceId, ...args] : args;
-    const timeout = 120000;
-    const res = spawnSync(getAdbCmd(), adbArgs, { encoding: 'utf8', timeout });
-    const runResult = {
-        exitCode: typeof res.status === 'number' ? res.status : null,
-        stdout: res.stdout || '',
-        stderr: res.stderr || '',
-        envSnapshot: makeEnvSnapshot(['PATH', 'ADB_PATH', 'HOME', 'JAVA_HOME']),
-        command: getAdbCmd(),
-        args: adbArgs,
-        suggestedFixes: []
-    };
-    if (res.status !== 0) {
-        if ((runResult.stderr || '').includes('device not found'))
-            runResult.suggestedFixes.push('Ensure device is connected and adb is authorized (adb devices)');
-        if ((runResult.stderr || '').includes('No such file or directory'))
-            runResult.suggestedFixes.push('Verify ADB_PATH or that adb is installed');
-    }
-    return { runResult };
-}
+export { execAdbWithDiagnostics } from '../utils/diagnostics.js';

package/dist/android/manage.js

@@ -3,7 +3,7 @@ import { spawn } from 'child_process';
 import path from 'path';
 import { existsSync } from 'fs';
 import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from './utils.js';
-import { execAdbWithDiagnostics } from './diagnostics.js';
+import { execAdbWithDiagnostics } from '../utils/diagnostics.js';
 import { detectJavaHome } from '../utils/java.js';
 export class AndroidManage {
     async build(projectPath, _variant) {

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

@@ -1,5 +1,5 @@
 import { promises as fs } from "fs";
-import { spawn } from "child_process";
+import { spawn, spawnSync } from "child_process";
 import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "./utils.js";
 import path from "path";
 export class iOSManage {
@@ -34,10 +34,12 @@ export class iOSManage {
                 catch { }
                 return null;
             }
-            const projectInfo = await findProject(projectPath, 3);
+            // 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 || projectPath;
+            const projectRootDir = projectInfo.dir || absProjectPath;
             const workspace = projectInfo.workspace;
             const proj = projectInfo.proj;
             // Determine destination: prefer explicit env var, otherwise use booted simulator UDID
@@ -50,28 +52,70 @@ export class iOSManage {
                 }
                 catch { }
             }
+            // Determine xcode command early so it can be used when detecting schemes
+            const xcodeCmd = process.env.XCODEBUILD_PATH || 'xcodebuild';
+            // Determine available schemes by querying xcodebuild -list rather than guessing
+            async function detectScheme(xcodeCmdInner, workspacePath, projectPathFull, cwd) {
+                try {
+                    const args = workspacePath ? ['-list', '-workspace', workspacePath] : ['-list', '-project', projectPathFull];
+                    // Run xcodebuild directly to list schemes
+                    const res = spawnSync(xcodeCmdInner, args, { cwd: cwd || projectRootDir, encoding: 'utf8', timeout: 20000 });
+                    const out = res.stdout || '';
+                    const schemesMatch = out.match(/Schemes:\s*\n([\s\S]*?)(?:\n\n|$)/m);
+                    if (schemesMatch) {
+                        const block = schemesMatch[1];
+                        const schemes = block.split(/\n/).map(s => s.trim()).filter(Boolean);
+                        if (schemes.length)
+                            return schemes[0];
+                    }
+                }
+                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);
-                const scheme = workspace.replace(/\.xcworkspace$/, '');
+                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);
-                const scheme = proj.replace(/\.xcodeproj$/, '');
+                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
+            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 xcodeCmd = process.env.XCODEBUILD_PATH || 'xcodebuild';
             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;
@@ -81,7 +125,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: projectPath });
+                    const proc = spawn(xcodeCmd, buildArgs, { cwd: projectRootDir });
                     let stdout = '';
                     let stderr = '';
                     proc.stdout?.on('data', d => stdout += d.toString());
@@ -112,6 +156,9 @@ export class iOSManage {
                 }
                 // record the failure for reporting
                 lastErr = new Error(res.stderr || `xcodebuild failed with code ${res.code}`);
+                lastErr.code = res.code;
+                lastErr.exitCode = res.code;
+                lastErr.killedByWatchdog = !!res.killedByWatchdog;
                 // write logs for diagnostics (helpful whether killed or not)
                 try {
                     await fs.writeFile(path.join(resultsDir, `xcodebuild-${attempt}.stdout.log`), res.stdout).catch(() => { });
@@ -127,8 +174,10 @@ export class iOSManage {
                     break;
             }
             if (lastErr) {
-                // Include diagnostics and result bundle path when available
-                return { error: `xcodebuild failed: ${lastErr.message}. See build-results for logs.`, output: `stdout:\n${lastStdout}\nstderr:\n${lastStderr}` };
+                // 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 };
+                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
             const built = await findAppBundle(projectPath);

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/interact.js

@@ -1,4 +1,4 @@
-import { resolveTargetDevice } from '../resolve-device.js';
+import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { AndroidInteract } from '../android/interact.js';
 import { iOSInteract } from '../ios/interact.js';
 export class ToolsInteract {

package/dist/tools/manage.js

@@ -1,10 +1,151 @@
 import { promises as fs } from 'fs';
 import path from 'path';
-import { resolveTargetDevice, listDevices } from '../resolve-device.js';
+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/tools/observe.js

@@ -1,4 +1,4 @@
-import { resolveTargetDevice } from '../resolve-device.js';
+import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { AndroidObserve } from '../android/observe.js';
 import { iOSObserve } from '../ios/observe.js';
 export class ToolsObserve {

package/dist/utils/diagnostics.js

@@ -23,3 +23,27 @@ export class DiagnosticError extends Error {
         this.runResult = runResult;
     }
 }
+// Exec ADB with diagnostics — moved from src/android/diagnostics.ts
+import { spawnSync } from 'child_process';
+import { getAdbCmd } from '../android/utils.js';
+export function execAdbWithDiagnostics(args, deviceId) {
+    const adbArgs = deviceId ? ['-s', deviceId, ...args] : args;
+    const timeout = 120000;
+    const res = spawnSync(getAdbCmd(), adbArgs, { encoding: 'utf8', timeout });
+    const runResult = {
+        exitCode: typeof res.status === 'number' ? res.status : null,
+        stdout: res.stdout || '',
+        stderr: res.stderr || '',
+        envSnapshot: makeEnvSnapshot(['PATH', 'ADB_PATH', 'HOME', 'JAVA_HOME']),
+        command: getAdbCmd(),
+        args: adbArgs,
+        suggestedFixes: []
+    };
+    if (res.status !== 0) {
+        if ((runResult.stderr || '').includes('device not found'))
+            runResult.suggestedFixes.push('Ensure device is connected and adb is authorized (adb devices)');
+        if ((runResult.stderr || '').includes('No such file or directory'))
+            runResult.suggestedFixes.push('Verify ADB_PATH or that adb is installed');
+    }
+    return { runResult };
+}