mobile-debug-mcp 0.11.0 → 0.12.0

package/src/android/manage.ts

@@ -3,6 +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 { detectJavaHome } from '../utils/java.js'
 import { InstallAppResponse, StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from '../types.js'
 
@@ -35,8 +36,8 @@ export class AndroidManage {
     const metadata = await getAndroidDeviceMetadata('', deviceId)
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
+    let apkToInstall: string = apkPath
     try {
-      let apkToInstall = apkPath
       const stat = await fs.stat(apkPath).catch(() => null)
       if (stat && stat.isDirectory()) {
         const detectedJavaHome = await detectJavaHome().catch(() => undefined)
@@ -98,22 +99,38 @@ export class AndroidManage {
       try { await execAdb(['shell', 'rm', remotePath], deviceId) } catch {}
       return { device: deviceInfo, installed: true, output: pmOut }
     } catch (e) {
-      return { device: deviceInfo, installed: false, error: e instanceof Error ? e.message : String(e) }
+      // gather diagnostics for attempted adb operations
+      const basename = path.basename(apkToInstall)
+      const remotePath = `/data/local/tmp/${basename}`
+      const installDiag = execAdbWithDiagnostics(['install', '-r', apkToInstall], deviceId)
+      const pushDiag = execAdbWithDiagnostics(['push', apkToInstall, remotePath], deviceId)
+      const pmDiag = execAdbWithDiagnostics(['shell', 'pm', 'install', '-r', remotePath], deviceId)
+      return { device: deviceInfo, installed: false, error: e instanceof Error ? e.message : String(e), diagnostics: { installDiag, pushDiag, pmDiag } }
     }
   }
 
   async startApp(appId: string, deviceId?: string): Promise<StartAppResponse> {
     const metadata = await getAndroidDeviceMetadata(appId, deviceId)
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
-    await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId)
-    return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 }
+    try {
+      await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId)
+      return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 }
+    } catch (e:any) {
+      const diag = execAdbWithDiagnostics(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId)
+      return { device: deviceInfo, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
+    }
   }
 
   async terminateApp(appId: string, deviceId?: string): Promise<TerminateAppResponse> {
     const metadata = await getAndroidDeviceMetadata(appId, deviceId)
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
-    await execAdb(['shell', 'am', 'force-stop', appId], deviceId)
-    return { device: deviceInfo, appTerminated: true }
+    try {
+      await execAdb(['shell', 'am', 'force-stop', appId], deviceId)
+      return { device: deviceInfo, appTerminated: true }
+    } catch (e:any) {
+      const diag = execAdbWithDiagnostics(['shell', 'am', 'force-stop', appId], deviceId)
+      return { device: deviceInfo, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
+    }
   }
 
   async restartApp(appId: string, deviceId?: string): Promise<RestartAppResponse> {
@@ -129,7 +146,12 @@ export class AndroidManage {
   async resetAppData(appId: string, deviceId?: string): Promise<ResetAppDataResponse> {
     const metadata = await getAndroidDeviceMetadata(appId, deviceId)
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
-    const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId)
-    return { device: deviceInfo, dataCleared: output === 'Success' }
+    try {
+      const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId)
+      return { device: deviceInfo, dataCleared: output === 'Success' }
+    } catch (e:any) {
+      const diag = execAdbWithDiagnostics(['shell', 'pm', 'clear', appId], deviceId)
+      return { device: deviceInfo, dataCleared: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
+    }
   }
 }

package/src/android/observe.ts

@@ -1,7 +1,7 @@
 import { spawn } from "child_process"
 import { XMLParser } from "fast-xml-parser"
 import { GetLogsResponse, CaptureAndroidScreenResponse, GetUITreeResponse, GetCurrentScreenResponse, UIElement, DeviceInfo } from "../types.js"
-import { ADB, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, getScreenResolution, traverseNode, parseLogLine } from "./utils.js"
+import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, getScreenResolution, traverseNode, parseLogLine } from "./utils.js"
 import { createWriteStream } from "fs"
 import { promises as fsPromises } from "fs"
 import path from "path"
@@ -81,7 +81,7 @@ export class AndroidObserve {
         elements
       };
     } catch (e) {
-      const errorMessage = `Failed to get UI tree. ADB Path: '${ADB}'. Error: ${e instanceof Error ? e.message : String(e)}`;
+      const errorMessage = `Failed to get UI tree. ADB Path: '${getAdbCmd()}'. Error: ${e instanceof Error ? e.message : String(e)}`;
       console.error(errorMessage);
       return {
           device: deviceInfo,
@@ -136,7 +136,7 @@ export class AndroidObserve {
       const args = deviceId ? ['-s', deviceId, 'exec-out', 'screencap', '-p'] : ['exec-out', 'screencap', '-p'];
       
       // Using spawn for screencap as well to ensure consistent process handling
-      const child = spawn(ADB, args)
+      const child = spawn(getAdbCmd(), args)
       
       const chunks: Buffer[] = []
       let stderr = ''
@@ -283,7 +283,7 @@ export class AndroidObserve {
       }
 
       const args = ['logcat', `--pid=${pid}`, filter]
-      const proc = spawn(ADB, args)
+      const proc = spawn(getAdbCmd(), args)
 
       const tmpDir = process.env.TMPDIR || '/tmp'
       const file = path.join(tmpDir, `mobile-debug-log-${sessionId}.ndjson`)

package/src/android/utils.ts

@@ -4,7 +4,7 @@ import { promises as fsPromises, existsSync } from 'fs'
 import path from 'path'
 import { detectJavaHome } from '../utils/java.js'
 
-export const ADB = process.env.ADB_PATH || 'adb'
+export function getAdbCmd() { return process.env.ADB_PATH || 'adb' }
 
 /**
  * Prepare Gradle execution options for building an Android project.
@@ -78,7 +78,7 @@ export function execAdb(args: string[], deviceId?: string, options: SpawnOptions
     const { timeout: customTimeout, ...spawnOptions } = options;
     
     // Use spawn instead of execFile for better stream control and to avoid potential buffering hangs
-    const child = spawn(ADB, adbArgs, spawnOptions)
+    const child = spawn(getAdbCmd(), adbArgs, spawnOptions)
     
     let stdout = ''
     let stderr = ''
@@ -126,7 +126,7 @@ export function spawnAdb(args: string[], deviceId?: string, options: SpawnOption
   const adbArgs = getAdbArgs(args, deviceId)
   return new Promise((resolve, reject) => {
     const { timeout: customTimeout, ...spawnOptions } = options
-    const child = spawn(ADB, adbArgs, spawnOptions)
+    const child = spawn(getAdbCmd(), adbArgs, spawnOptions)
 
     let stdout = ''
     let stderr = ''

package/src/ios/interact.ts

@@ -1,6 +1,6 @@
 import { spawn } from "child_process"
 import { WaitForElementResponse, TapResponse } from "../types.js"
-import { getIOSDeviceMetadata, IDB } from "./utils.js"
+import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "./utils.js"
 import { iOSObserve } from "./observe.js"
 
 export class iOSInteract {
@@ -39,12 +39,8 @@ export class iOSInteract {
   async tap(x: number, y: number, deviceId: string = "booted"): Promise<TapResponse> {
     const device = await getIOSDeviceMetadata(deviceId)
     
-    // Check for idb
-    const child = spawn(IDB, ['--version']);
-    const idbExists = await new Promise<boolean>((resolve) => {
-      child.on('error', () => resolve(false));
-      child.on('close', (code) => resolve(code === 0));
-    });
+    // Use shared helper to detect idb
+    const idbExists = await isIDBInstalled();
 
     if (!idbExists) {
         return {
@@ -64,7 +60,7 @@ export class iOSInteract {
       }
 
       await new Promise<void>((resolve, reject) => {
-        const proc = spawn(IDB, args);
+        const proc = spawn(getIdbCmd(), args);
         let stderr = '';
         proc.stderr.on('data', d => stderr += d.toString());
         proc.on('close', code => {

package/src/ios/manage.ts

@@ -1,7 +1,7 @@
 import { promises as fs } from "fs"
 import { spawn } from "child_process"
 import { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse, InstallAppResponse } from "../types.js"
-import { execCommand, getIOSDeviceMetadata, validateBundleId, IDB, findAppBundle } from "./utils.js"
+import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "./utils.js"
 import path from "path"
 
 export class iOSManage {
@@ -25,7 +25,8 @@ export class iOSManage {
       }
 
       await new Promise<void>((resolve, reject) => {
-        const proc = spawn('xcodebuild', buildArgs, { cwd: projectPath })
+        const xcodeCmd = process.env.XCODEBUILD_PATH || 'xcodebuild'
+        const proc = spawn(xcodeCmd, buildArgs, { cwd: projectPath })
         let stderr = ''
         proc.stderr?.on('data', d => stderr += d.toString())
         proc.on('close', code => {
@@ -67,31 +68,34 @@ export class iOSManage {
       }
 
       try {
-        const res = await execCommand(['simctl', 'install', deviceId, toInstall], deviceId)
-        return { device, installed: true, output: res.output }
-      } catch (e) {
-        try {
-          const child = spawn(IDB, ['--version'])
-          const idbExists = await new Promise<boolean>((resolve) => {
-            child.on('error', () => resolve(false));
-            child.on('close', (code) => resolve(code === 0));
-          });
-          if (idbExists) {
-            await new Promise<void>((resolve, reject) => {
-              const proc = spawn(IDB, ['install', toInstall, '--udid', device.id]);
-              let stderr = '';
-              proc.stderr.on('data', d => stderr += d.toString());
-              proc.on('close', code => {
-                if (code === 0) resolve();
-                else reject(new Error(stderr || `idb install failed with code ${code}`));
-              });
-              proc.on('error', err => reject(err));
+          const res = await execCommand(['simctl', 'install', deviceId, toInstall], deviceId)
+          return { device, installed: true, output: res.output }
+        } catch (e) {
+          // Gather diagnostics for simctl failure
+          const diag = execCommandWithDiagnostics(['simctl', 'install', deviceId, toInstall], deviceId)
+          try {
+            const child = spawn(getIdbCmd(), ['--version'])
+            const idbExists = await new Promise<boolean>((resolve) => {
+              child.on('error', () => resolve(false));
+              child.on('close', (code) => resolve(code === 0));
             });
-            return { device, installed: true }
-          }
-        } catch {}
-        return { device, installed: false, error: e instanceof Error ? e.message : String(e) }
-      }
+            if (idbExists) {
+              // attempt idb install via spawn but include diagnostics
+              await new Promise<void>((resolve, reject) => {
+                const proc = spawn(getIdbCmd(), ['install', toInstall, '--udid', device.id]);
+                let stderr = '';
+                proc.stderr.on('data', d => stderr += d.toString());
+                proc.on('close', code => {
+                  if (code === 0) resolve();
+                  else reject(new Error(stderr || `idb install failed with code ${code}`));
+                });
+                proc.on('error', err => reject(err));
+              });
+              return { device, installed: true }
+            }
+          } catch {}
+          return { device, installed: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
+        }
     } catch (e) {
       return { device, installed: false, error: e instanceof Error ? e.message : String(e) }
     }
@@ -99,16 +103,28 @@ export class iOSManage {
 
   async startApp(bundleId: string, deviceId: string = "booted"): Promise<StartAppResponse> {
     validateBundleId(bundleId)
-    const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId)
-    const device = await getIOSDeviceMetadata(deviceId)
-    return { device, appStarted: !!result.output, launchTimeMs: 1000 }
+    try {
+      const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId)
+      const device = await getIOSDeviceMetadata(deviceId)
+      return { device, appStarted: !!result.output, launchTimeMs: 1000 }
+    } catch (e:any) {
+      const diag = execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId)
+      const device = await getIOSDeviceMetadata(deviceId)
+      return { device, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag } as any
+    }
   }
 
   async terminateApp(bundleId: string, deviceId: string = "booted"): Promise<TerminateAppResponse> {
     validateBundleId(bundleId)
-    await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId)
-    const device = await getIOSDeviceMetadata(deviceId)
-    return { device, appTerminated: true }
+    try {
+      await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId)
+      const device = await getIOSDeviceMetadata(deviceId)
+      return { device, appTerminated: true }
+    } catch (e:any) {
+      const diag = execCommandWithDiagnostics(['simctl', 'terminate', deviceId, bundleId], deviceId)
+      const device = await getIOSDeviceMetadata(deviceId)
+      return { device, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag } as any
+    }
   }
 
   async restartApp(bundleId: string, deviceId: string = "booted"): Promise<RestartAppResponse> {
@@ -121,23 +137,28 @@ export class iOSManage {
     validateBundleId(bundleId)
     await this.terminateApp(bundleId, deviceId)
     const device = await getIOSDeviceMetadata(deviceId)
-    const containerResult = await execCommand(['simctl', 'get_app_container', deviceId, bundleId, 'data'], deviceId)
-    const dataPath = containerResult.output.trim()
-    if (!dataPath) throw new Error(`Could not find data container for ${bundleId}`)
-
     try {
-      const libraryPath = `${dataPath}/Library`
-      const documentsPath = `${dataPath}/Documents`
-      const tmpPath = `${dataPath}/tmp`
-      await fs.rm(libraryPath, { recursive: true, force: true }).catch(() => {})
-      await fs.rm(documentsPath, { recursive: true, force: true }).catch(() => {})
-      await fs.rm(tmpPath, { recursive: true, force: true }).catch(() => {})
-      await fs.mkdir(libraryPath, { recursive: true }).catch(() => {})
-      await fs.mkdir(documentsPath, { recursive: true }).catch(() => {})
-      await fs.mkdir(tmpPath, { recursive: true }).catch(() => {})
-      return { device, dataCleared: true }
-    } catch (e) {
-      throw new Error(`Failed to clear data for ${bundleId}: ${e instanceof Error ? e.message : String(e)}`)
+      const containerResult = await execCommand(['simctl', 'get_app_container', deviceId, bundleId, 'data'], deviceId)
+      const dataPath = containerResult.output.trim()
+      if (!dataPath) throw new Error(`Could not find data container for ${bundleId}`)
+
+      try {
+        const libraryPath = `${dataPath}/Library`
+        const documentsPath = `${dataPath}/Documents`
+        const tmpPath = `${dataPath}/tmp`
+        await fs.rm(libraryPath, { recursive: true, force: true }).catch(() => {})
+        await fs.rm(documentsPath, { recursive: true, force: true }).catch(() => {})
+        await fs.rm(tmpPath, { recursive: true, force: true }).catch(() => {})
+        await fs.mkdir(libraryPath, { recursive: true }).catch(() => {})
+        await fs.mkdir(documentsPath, { recursive: true }).catch(() => {})
+        await fs.mkdir(tmpPath, { recursive: true }).catch(() => {})
+        return { device, dataCleared: true }
+      } catch (e) {
+        throw new Error(`Failed to clear data for ${bundleId}: ${e instanceof Error ? e.message : String(e)}`)
+      }
+    } catch (e:any) {
+      const diag = execCommandWithDiagnostics(['simctl', 'get_app_container', deviceId, bundleId, 'data'], deviceId)
+      return { device, dataCleared: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag } as any
     }
   }
 }

package/src/ios/observe.ts

@@ -1,7 +1,7 @@
 import { spawn } from "child_process"
 import { promises as fs } from "fs"
 import { GetLogsResponse, CaptureIOSScreenshotResponse, GetUITreeResponse, UIElement, DeviceInfo } from "../types.js"
-import { execCommand, getIOSDeviceMetadata, validateBundleId, IDB, XCRUN } from "./utils.js"
+import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcrunCmd, isIDBInstalled } from "./utils.js"
 import { createWriteStream, promises as fsPromises } from 'fs'
 import path from 'path'
 import { parseLogLine } from '../android/utils.js'
@@ -25,6 +25,17 @@ interface IDBElement {
 
 function parseIDBFrame(frame: any): [number, number, number, number] {
   if (!frame) return [0, 0, 0, 0];
+  // Handle string frames like "{{0, 0}, {402, 874}}"
+  if (typeof frame === 'string') {
+    const nums = frame.match(/-?\d+(?:\.\d+)?/g);
+    if (!nums || nums.length < 4) return [0, 0, 0, 0];
+    const x = Number(nums[0]);
+    const y = Number(nums[1]);
+    const w = Number(nums[2]);
+    const h = Number(nums[3]);
+    return [Math.round(x), Math.round(y), Math.round(x + w), Math.round(y + h)];
+  }
+
   const x = Number(frame.x || 0);
   const y = Number(frame.y || 0);
   const w = Number(frame.width || frame.w || 0);
@@ -102,15 +113,7 @@ function traverseIDBNode(node: IDBElement, elements: UIElement[], parentIndex: n
   return currentIndex;
 }
 
-// Check if IDB is installed
-async function isIDBInstalled(): Promise<boolean> {
-  return new Promise((resolve) => {
-    // Check if 'idb' is in path by trying to run it
-    const child = spawn(IDB, ['--version']);
-    child.on('error', () => resolve(false));
-    child.on('close', (code) => resolve(code === 0));
-  });
-}
+
 
 // iOS live log stream support (moved from ios/utils to observe)
 const iosActiveLogStreams: Map<string, { proc: ReturnType<typeof import('child_process').spawn>, file: string }> = new Map()
@@ -207,13 +210,13 @@ export class iOSObserve {
          // Stabilization delay
          await delay(300 + (attempts * 100));
 
-         const args = ['ui', 'describe', '--json'];
+         const args = ['ui', 'describe-all', '--json'];
          if (targetUdid) {
             args.push('--udid', targetUdid);
          }
 
          const output = await new Promise<string>((resolve, reject) => {
-             const child = spawn(IDB, args);
+             const child = spawn(getIdbCmd(), args);
              let stdout = '';
              let stderr = '';
 
@@ -252,9 +255,14 @@ export class iOSObserve {
 
     try {
         const elements: UIElement[] = [];
-        const root = jsonContent;
-        
-        traverseIDBNode(root, elements);
+        // idb describe-all returns either a root object or an array of root nodes
+        if (Array.isArray(jsonContent)) {
+          for (const node of jsonContent) {
+            traverseIDBNode(node, elements);
+          }
+        } else {
+          traverseIDBNode(jsonContent, elements);
+        }
 
         // Infer resolution from root element if possible (usually the Window/Application frame)
         let width = 0;
@@ -293,7 +301,7 @@ export class iOSObserve {
       }
 
       const args = ['simctl', 'spawn', deviceId, 'log', 'stream', '--style', 'syslog', '--predicate', predicate]
-      const proc = spawn(XCRUN, args)
+      const proc = spawn(getXcrunCmd(), args)
 
       // Prepare output file
       const tmpDir = process.env.TMPDIR || '/tmp'

package/src/ios/utils.ts

@@ -1,10 +1,76 @@
-import { execFile, spawn } from "child_process"
+import { execFile, spawn, execSync, spawnSync } from "child_process"
 import { DeviceInfo } from "../types.js"
 import { promises as fsPromises } from 'fs'
 import path from 'path'
+import { makeEnvSnapshot } from '../utils/diagnostics.js'
 
-export const XCRUN = process.env.XCRUN_PATH || "xcrun"
-export const IDB = "idb"
+export function getXcrunCmd() { return process.env.XCRUN_PATH || 'xcrun' }
+
+export function getConfiguredIdbPath(): string | undefined {
+  if (process.env.MCP_IDB_PATH) return process.env.MCP_IDB_PATH
+  if (process.env.IDB_PATH) return process.env.IDB_PATH
+  const cfgPaths = [
+    process.env.MCP_CONFIG_PATH || (process.env.HOME ? `${process.env.HOME}/.mcp/config.json` : ''),
+    `${process.cwd()}/mcp.config.json`
+  ]
+  try {
+    const fs = require('fs')
+    for (const p of cfgPaths) {
+      if (!p) continue
+      try {
+        if (fs.existsSync(p)) {
+          const raw = fs.readFileSync(p, 'utf8')
+          const json = JSON.parse(raw)
+          if (json) {
+            if (json.idbPath) return json.idbPath
+            if (json.IDB_PATH) return json.IDB_PATH
+          }
+        }
+      } catch {}
+    }
+  } catch {}
+  return undefined
+}
+
+export function getIdbCmd() {
+  const cfg = getConfiguredIdbPath()
+  if (cfg) return cfg
+  if (process.env.IDB_PATH) return process.env.IDB_PATH
+  try {
+    const p = execSync('which idb', { stdio: ['ignore','pipe','ignore'] }).toString().trim()
+    if (p) return p
+  } catch {}
+  try {
+    const p2 = execSync('command -v idb', { stdio: ['ignore','pipe','ignore'] }).toString().trim()
+    if (p2) return p2
+  } catch {}
+  // check common user locations
+  const common = [
+    `${process.env.HOME}/Library/Python/3.9/bin/idb`,
+    `${process.env.HOME}/Library/Python/3.10/bin/idb`,
+    '/opt/homebrew/bin/idb',
+    '/usr/local/bin/idb',
+  ]
+  for (const c of common) {
+    try { execSync(`test -x ${c}`, { stdio: ['ignore','pipe','ignore'] }); return c } catch {}
+  }
+  return 'idb'
+}
+
+export async function isIDBInstalled(): Promise<boolean> {
+  const cmd = getIdbCmd()
+  try {
+    execSync(`command -v ${cmd}`, { stdio: ['ignore','pipe','ignore'] })
+    return true
+  } catch {
+    try {
+      execSync(`${cmd} list-targets --json`, { stdio: ['ignore','pipe','ignore'], timeout: 2000 })
+      return true
+    } catch {
+      return false
+    }
+  }
+}
 
 export interface IOSResult {
   output: string
@@ -23,7 +89,7 @@ export function validateBundleId(bundleId: string) {
 export function execCommand(args: string[], deviceId: string = "booted"): Promise<IOSResult> {
   return new Promise((resolve, reject) => {
     // Use spawn for better stream control and consistency with Android implementation
-    const child = spawn(XCRUN, args)
+    const child = spawn(getXcrunCmd(), args)
     
     let stdout = ''
     let stderr = ''
@@ -40,10 +106,12 @@ export function execCommand(args: string[], deviceId: string = "booted"): Promis
       })
     }
 
-    const timeoutMs = args.includes('log') ? 10000 : 5000 // 10s for logs, 5s for others
+    const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000 // env (ms) or default 30s
+  const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000 // env (ms) or default 60s
+  const timeoutMs = args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT // choose appropriate timeout
     const timeout = setTimeout(() => {
       child.kill()
-      reject(new Error(`Command timed out after ${timeoutMs}ms: ${XCRUN} ${args.join(' ')}`))
+      reject(new Error(`Command timed out after ${timeoutMs}ms: ${getXcrunCmd()} ${args.join(' ')}`))
     }, timeoutMs)
 
     child.on('close', (code) => {
@@ -62,6 +130,39 @@ export function execCommand(args: string[], deviceId: string = "booted"): Promis
   })
 }
 
+export function execCommandWithDiagnostics(args: string[], deviceId: string = "booted") {
+  // Run synchronously to capture stdout/stderr and exitCode reliably for diagnostics
+  const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000
+  const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000
+  const timeoutMs = args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT
+  const res = spawnSync(getXcrunCmd(), args, { encoding: 'utf8', timeout: timeoutMs }) as any
+  const runResult = {
+    exitCode: typeof res.status === 'number' ? res.status : null,
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+    envSnapshot: makeEnvSnapshot(['PATH','IDB_PATH','JAVA_HOME','HOME']),
+    command: getXcrunCmd(),
+    args,
+    deviceId
+  }
+
+  if (res.status !== 0) {
+    // include suggested fixes for common errors
+    const suggested: string[] = []
+    if ((runResult.stderr || '').includes('xcodebuild: error')) {
+      suggested.push('Ensure the project/workspace path is correct and xcodebuild is installed and accessible.')
+    }
+    if ((runResult.stderr || '').includes('No such file or directory') || (runResult.stderr || '').includes('not found')) {
+      suggested.push('Check that Xcode Command Line Tools are installed and XCRUN_PATH is set if using non-standard location.')
+    }
+
+    // Return diagnostics object
+    return { runResult: { ...runResult, suggestedFixes: suggested } }
+  }
+
+  return { runResult: { ...runResult, suggestedFixes: [] } }
+}
+
 function parseRuntimeName(runtime: string): string {
   // Example: com.apple.CoreSimulator.SimRuntime.iOS-17-0 -> iOS 17.0
   try {
@@ -99,7 +200,7 @@ export async function findAppBundle(dir: string): Promise<string | undefined> {
 export async function getIOSDeviceMetadata(deviceId: string = "booted"): Promise<DeviceInfo> {
   return new Promise((resolve) => {
     // If deviceId is provided (and not "booted"), attempt to find that device among booted simulators.
-    execFile(XCRUN, ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
+    execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
       const fallback: DeviceInfo = {
         platform: "ios",
         id: deviceId,
@@ -145,7 +246,7 @@ export async function getIOSDeviceMetadata(deviceId: string = "booted"): Promise
 
 export async function listIOSDevices(appId?: string): Promise<DeviceInfo[]> {
   return new Promise((resolve) => {
-    execFile(XCRUN, ['simctl', 'list', 'devices', '--json'], (err, stdout) => {
+    execFile(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], (err, stdout) => {
       if (err || !stdout) return resolve([])
       try {
         const data = JSON.parse(stdout)

package/src/server.ts

@@ -145,6 +145,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["appPath"]
       }
     },
+    {
+      name: "build_app",
+      description: "Build a project for Android or iOS and return the built artifact path. Does not install.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          platform: { type: "string", enum: ["android", "ios"], description: "Optional. If omitted the server will attempt to detect platform from projectPath files." },
+          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"]
+      }
+    },
     {
       name: "get_logs",
       description: "Get recent logs from Android or iOS simulator. Returns device metadata and the log output.",
@@ -438,6 +451,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return wrapResponse(response)
       }
 
+      if (name === "build_app") {
+        const { platform, projectPath, variant } = args as any
+        const res = await ToolsManage.buildAppHandler({ platform, projectPath, variant })
+        return wrapResponse(res)
+      }
+
       if (name === 'build_and_install') {
         const { platform, projectPath, deviceId, timeout } = args as any
         const res = await ToolsManage.buildAndInstallHandler({ platform, projectPath, deviceId, timeout })

package/src/types.ts

@@ -10,22 +10,30 @@ export interface StartAppResponse {
   device: DeviceInfo;
   appStarted: boolean;
   launchTimeMs: number;
+  error?: string;
+  diagnostics?: any;
 }
 
 export interface TerminateAppResponse {
   device: DeviceInfo;
   appTerminated: boolean;
+  error?: string;
+  diagnostics?: any;
 }
 
 export interface RestartAppResponse {
   device: DeviceInfo;
   appRestarted: boolean;
   launchTimeMs: number;
+  error?: string;
+  diagnostics?: any;
 }
 
 export interface ResetAppDataResponse {
   device: DeviceInfo;
   dataCleared: boolean;
+  error?: string;
+  diagnostics?: any;
 }
 
 export interface GetLogsResponse {
@@ -133,4 +141,5 @@ export interface InstallAppResponse {
   installed: boolean;
   output?: string;
   error?: string;
+  diagnostics?: any;
 }