mobile-debug-mcp 0.12.3 → 0.12.4

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 {
@@ -74,28 +96,33 @@ export class iOSManage {
             }
             // 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 = process.env.MCP_DERIVED_DATA || path.join(projectRootDir, 'build', 'DerivedData');
-            const resultBundlePath = path.join(projectRootDir, 'build', 'xcresults', 'ResultBundle.xcresult');
+            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 = process.env.MCP_FORCE_CLEAN === '1';
+            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
+            // Insert clean if explicitly requested via env or opts
             if (forceClean) {
                 const idx = buildArgs.indexOf('build');
                 if (idx >= 0)

package/dist/server.js

@@ -115,30 +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." },
-                    projectType: { type: "string", enum: ["native", "kmp", "react-native", "flutter"], description: "Optional project type to guide build tool selection (e.g., kmp, react-native)." },
+                    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." },
-                    projectType: { type: "string", enum: ["native", "kmp", "react-native", "flutter"], description: "Optional project type to guide build tool selection (e.g., kmp, react-native)." },
+                    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"]
             }
         },
         {

package/dist/tools/manage.js

@@ -7,18 +7,52 @@ 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 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)));
+            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 {
@@ -50,10 +84,7 @@ export class ToolsManage {
     }
     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;
+        // 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')
@@ -62,7 +93,23 @@ export class ToolsManage {
             process.env.MCP_FORCE_CLEAN_IOS = '1';
         if (destinationUDID)
             process.env.MCP_XCODE_DESTINATION_UDID = destinationUDID;
-        const artifact = await ios.build(projectPath);
+        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 }) {
@@ -160,52 +207,11 @@ export class ToolsManage {
         }
     }
     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()) {
-                // 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';
+        // 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();
@@ -264,21 +270,36 @@ export class ToolsManage {
         const pushEvent = (obj) => events.push(JSON.stringify(obj));
         const effectiveTimeout = timeout ?? 180000; // reserved for future streaming/timeouts
         void effectiveTimeout;
+        // 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 {
             if (!chosenPlatform) {
-                // 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' });
+                // 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 {
+                    // 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;
@@ -318,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/docs/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.12.4]
+- Made projectType and platform mandatory
+
 ## [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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.12.3",
+  "version": "0.12.4",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/src/ios/manage.ts

@@ -5,11 +5,15 @@ import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validate
 import path from "path"
 
 export class iOSManage {
-  async build(projectPath: string, _variant?: string): Promise<{ artifactPath: string, output?: string } | { error: string, diagnostics?: any }> {
-    void _variant
+  async build(projectPath: string, optsOrVariant?: string | { workspace?: string, project?: string, scheme?: string, destinationUDID?: string, derivedDataPath?: string, forceClean?: boolean, xcodeCmd?: string }): Promise<{ artifactPath: string, output?: string } | { error: string, diagnostics?: any }> {
+    // Support legacy variant string as second arg
+    let opts: any = {}
+    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: string, maxDepth = 3): Promise<{ dir: string, workspace?: string, proj?: string } | null> {
+      async function findProject(root: string, maxDepth = 4): Promise<{ dir: string, workspace?: string, proj?: string } | null> {
         try {
           const ents = await fs.readdir(root, { withFileTypes: true }).catch(() => [])
           for (const e of ents) {
@@ -36,14 +40,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: string | undefined = opts.workspace
+      let proj: string | undefined = 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')
@@ -52,7 +73,7 @@ export class iOSManage {
       }
 
       // 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: string, workspacePath?: string, projectPathFull?: string, cwd?: string): Promise<string | null> {
@@ -73,31 +94,34 @@ export class iOSManage {
 
       // Prepare build flags and paths (support incremental builds)
       let buildArgs: string[]
-      let chosenScheme: string | null = null
+      let chosenScheme: string | null = opts.scheme || 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 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 = process.env.MCP_FORCE_CLEAN === '1'
+      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
+      // Insert clean if explicitly requested via env or opts
       if (forceClean) {
         const idx = buildArgs.indexOf('build')
         if (idx >= 0) buildArgs.splice(idx, 0, 'clean')

package/src/server.ts

@@ -134,30 +134,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." },
-          projectType: { type: "string", enum: ["native","kmp","react-native","flutter"], description: "Optional project type to guide build tool selection (e.g., kmp, react-native)." },
+          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." },
-          projectType: { type: "string", enum: ["native","kmp","react-native","flutter"], description: "Optional project type to guide build tool selection (e.g., kmp, react-native)." },
+          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"]
       }
     },
 

package/src/tools/manage.ts

@@ -9,15 +9,42 @@ import { execSync } from 'child_process'
 import type { InstallAppResponse, StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from '../types.js'
 
 export async function detectProjectPlatform(projectPath: string): Promise<'ios'|'android'|'ambiguous'|'unknown'> {
+  // Recursively scan up to a limited depth for platform markers to avoid mis-detection
+  async function scan(dir: string, depth = 3): Promise<{ ios: boolean, android: boolean }>{
+    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 files = (await fs.readdir(projectPath).catch(() => [])) as string[]
-      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)))
+      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()
@@ -44,13 +71,23 @@ export class ToolsManage {
 
   static async build_ios({ projectPath, workspace: _workspace, project: _project, scheme: _scheme, destinationUDID, derivedDataPath, buildJobs, forceClean }: { projectPath: string, workspace?: string, project?: string, scheme?: string, destinationUDID?: string, derivedDataPath?: string, buildJobs?: number, forceClean?: boolean }) {
     const ios = new iOSManage()
-    // silence unused param lints
-    void _workspace; void _project; void _scheme;
+    // 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 artifact = await (ios as any).build(projectPath)
+
+    const opts: any = {}
+    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 as any).build(projectPath, opts)
     return artifact
   }
 
@@ -147,45 +184,13 @@ export class ToolsManage {
     }
   }
 
-  static async installAppHandler({ platform, appPath, deviceId, projectType }: { platform?: 'android' | 'ios', appPath: string, deviceId?: string, projectType?: 'native' | 'kmp' | 'react-native' | 'flutter' }): Promise<InstallAppResponse> {
-    // Use projectType hint to influence platform detection when explicit platform is not provided
-    let chosenPlatform: 'android'|'ios'|undefined = 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)
-      }
+  static async installAppHandler({ platform, appPath, deviceId, projectType }: { platform: 'android' | 'ios', appPath: string, deviceId?: string, projectType: 'native' | 'kmp' | 'react-native' | 'flutter' }): Promise<InstallAppResponse> {
+    // 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).')
     }
 
-    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(() => [])) as string[]
-          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'
-    }
+    const chosenPlatform: 'android'|'ios' = platform
 
     if (chosenPlatform === 'android') {
       const resolved = await resolveTargetDevice({ platform: 'android', deviceId })
@@ -240,26 +245,41 @@ export class ToolsManage {
     }
   }
 
-  static async buildAndInstallHandler({ platform, projectPath, deviceId, timeout, projectType }: { platform?: 'android' | 'ios', projectPath: string, deviceId?: string, timeout?: number, projectType?: 'native' | 'kmp' | 'react-native' | 'flutter' }) {
+  static async buildAndInstallHandler({ platform, projectPath, deviceId, timeout, projectType }: { platform: 'android' | 'ios', projectPath: string, deviceId?: string, timeout?: number, projectType: 'native' | 'kmp' | 'react-native' | 'flutter' }) {
     const events: string[] = []
     const pushEvent = (obj: any) => events.push(JSON.stringify(obj))
     const effectiveTimeout = timeout ?? 180000 // reserved for future streaming/timeouts
     void effectiveTimeout
 
+    // 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 {
       if (!chosenPlatform) {
-        // 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' })
+        // 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 {
+          // 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
@@ -298,7 +318,7 @@ export class ToolsManage {
     pushEvent({ type: 'install', status: 'started', artifactPath: artifact, deviceId })
     let installRes: any
     try {
-      installRes = await ToolsManage.installAppHandler({ platform: chosenPlatform as any, appPath: artifact, deviceId })
+      installRes = await ToolsManage.installAppHandler({ platform: chosenPlatform as any, 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/test/unit/manage/mcp_disable_autodetect.test.ts

@@ -18,10 +18,11 @@ export async function run() {
     const { ToolsManage } = await import('../../../src/tools/manage.js')
 
     try {
+      // platform and projectType are now mandatory; calling without them should return a missing-params error
       const res = await ToolsManage.buildAndInstallHandler({ projectPath: both })
       console.log('result:', res.result)
       assert.strictEqual(res.result.success, false)
-      assert.ok(String(res.result.error).includes('MCP_DISABLE_AUTODETECT'), 'Expected error to mention MCP_DISABLE_AUTODETECT')
+      assert.ok(String(res.result.error).includes('Both platform and projectType parameters are required'), 'Expected missing-params error')
       console.log('mcp_disable_autodetect test passed')
     } finally {
       if (orig === undefined) delete process.env.MCP_DISABLE_AUTODETECT