mobile-debug-mcp 0.10.0 → 0.11.0

package/dist/tools/run.js

@@ -0,0 +1,180 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { resolveTargetDevice, listDevices } from '../resolve-device.js';
+import { AndroidManage } from '../android/manage.js';
+import { iOSManage } from '../ios/manage.js';
+export class ToolsRun {
+    static async buildAppHandler({ platform, projectPath, variant }) {
+        // delegate to platform-specific build implementations
+        const chosen = platform || 'android';
+        if (chosen === 'android') {
+            const android = new AndroidManage();
+            const artifact = await android.build(projectPath, variant);
+            return artifact;
+        }
+        else {
+            const ios = new iOSManage();
+            const artifact = await ios.build(projectPath, variant);
+            return artifact;
+        }
+    }
+    static async installAppHandler({ platform, appPath, deviceId }) {
+        let chosenPlatform = platform;
+        try {
+            const stat = await fs.stat(appPath).catch(() => null);
+            if (stat && stat.isDirectory()) {
+                // If the directory itself looks like an .app bundle, treat as iOS
+                if (appPath.endsWith('.app')) {
+                    chosenPlatform = 'ios';
+                }
+                else {
+                    const files = (await fs.readdir(appPath).catch(() => []));
+                    if (files.some(f => f.endsWith('.xcodeproj') || f.endsWith('.xcworkspace'))) {
+                        chosenPlatform = 'ios';
+                    }
+                    else if (files.includes('gradlew') || files.includes('build.gradle') || files.includes('settings.gradle') || (files.includes('app') && (await fs.stat(path.join(appPath, 'app')).catch(() => null)))) {
+                        chosenPlatform = 'android';
+                    }
+                    else {
+                        chosenPlatform = 'android';
+                    }
+                }
+            }
+            else if (typeof appPath === 'string') {
+                const ext = path.extname(appPath).toLowerCase();
+                if (ext === '.apk')
+                    chosenPlatform = 'android';
+                else if (ext === '.ipa' || ext === '.app')
+                    chosenPlatform = 'ios';
+                else
+                    chosenPlatform = 'android';
+            }
+        }
+        catch {
+            chosenPlatform = 'android';
+        }
+        if (chosenPlatform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
+            const androidRun = new AndroidManage();
+            const result = await androidRun.installApp(appPath, resolved.id);
+            return result;
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', deviceId });
+            const iosRun = new iOSManage();
+            const result = await iosRun.installApp(appPath, resolved.id);
+            return result;
+        }
+    }
+    static async startAppHandler({ platform, appId, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            return await new AndroidManage().startApp(appId, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            return await new iOSManage().startApp(appId, resolved.id);
+        }
+    }
+    static async terminateAppHandler({ platform, appId, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            return await new AndroidManage().terminateApp(appId, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            return await new iOSManage().terminateApp(appId, resolved.id);
+        }
+    }
+    static async restartAppHandler({ platform, appId, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            return await new AndroidManage().restartApp(appId, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            return await new iOSManage().restartApp(appId, resolved.id);
+        }
+    }
+    static async resetAppDataHandler({ platform, appId, deviceId }) {
+        if (platform === 'android') {
+            const resolved = await resolveTargetDevice({ platform: 'android', appId, deviceId });
+            return await new AndroidManage().resetAppData(appId, resolved.id);
+        }
+        else {
+            const resolved = await resolveTargetDevice({ platform: 'ios', appId, deviceId });
+            return await new iOSManage().resetAppData(appId, resolved.id);
+        }
+    }
+    static async buildAndInstallHandler({ platform, projectPath, deviceId, timeout }) {
+        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
+        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';
+                }
+                else {
+                    const ext = path.extname(projectPath).toLowerCase();
+                    if (ext === '.apk')
+                        chosenPlatform = 'android';
+                    else if (ext === '.ipa' || ext === '.app')
+                        chosenPlatform = 'ios';
+                    else
+                        chosenPlatform = 'android';
+                }
+            }
+        }
+        catch {
+            chosenPlatform = chosenPlatform || 'android';
+        }
+        pushEvent({ type: 'build', status: 'started', platform: chosenPlatform });
+        let buildRes;
+        try {
+            buildRes = await ToolsRun.buildAppHandler({ platform: chosenPlatform, projectPath });
+            if (buildRes && buildRes.error) {
+                pushEvent({ type: 'build', status: 'failed', error: buildRes.error });
+                return { ndjson: events.join('\n') + '\n', result: { success: false, error: buildRes.error } };
+            }
+            pushEvent({ type: 'build', status: 'finished', artifactPath: buildRes.artifactPath });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            pushEvent({ type: 'build', status: 'failed', error: msg });
+            return { ndjson: events.join('\n') + '\n', result: { success: false, error: msg } };
+        }
+        // Install phase
+        const artifact = buildRes.artifactPath || projectPath;
+        pushEvent({ type: 'install', status: 'started', artifactPath: artifact, deviceId });
+        let installRes;
+        try {
+            installRes = await ToolsRun.installAppHandler({ platform: chosenPlatform, appPath: artifact, deviceId });
+            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 } };
+            }
+            else {
+                pushEvent({ type: 'install', status: 'failed', error: installRes.error || 'unknown' });
+                return { ndjson: events.join('\n') + '\n', result: { success: false, error: installRes.error || 'install failed' } };
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            pushEvent({ type: 'install', status: 'failed', error: msg });
+            return { ndjson: events.join('\n') + '\n', result: { success: false, error: msg } };
+        }
+    }
+    static async listDevicesHandler({ platform, appId }) {
+        const devices = await listDevices(platform, appId);
+        return { devices };
+    }
+}

package/docs/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.11.0]
+- Tools refactor - broke functions into 3 distinct class types; interact (for UI manipulation), manage (for build, installing etc) and observe (observing the app whilst running)
+- Add convenience method to build and install
+
 ## [0.10.0]
 
 ### Added / Changed

package/package.json

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

package/src/android/interact.ts

@@ -1,11 +1,6 @@
-import { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse, WaitForElementResponse, TapResponse, SwipeResponse, TypeTextResponse, PressBackResponse } from "../types.js"
-import { execAdb, getAndroidDeviceMetadata, getDeviceInfo, spawnAdb } from "./utils.js"
-import { detectJavaHome } from "../utils/java.js"
+import { WaitForElementResponse, TapResponse, SwipeResponse, TypeTextResponse, PressBackResponse } from "../types.js"
+import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js"
 import { AndroidObserve } from "./observe.js"
-import { promises as fs } from "fs"
-import { spawn } from "child_process"
-import path from "path"
-import { existsSync } from "fs"
 
 
 export class AndroidInteract {
@@ -93,152 +88,4 @@ export class AndroidInteract {
     }
   }
 
-  async installApp(apkPath: string, deviceId?: string): Promise<import("../types.js").InstallAppResponse> {
-    const metadata = await getAndroidDeviceMetadata("", deviceId)
-    const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
-
-    // Helper to recursively find first APK under a directory
-    async function findApk(dir: string): Promise<string | undefined> {
-      const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => [])
-      for (const e of entries) {
-        const full = path.join(dir, e.name)
-        if (e.isDirectory()) {
-          const found = await findApk(full)
-          if (found) return found
-        } else if (e.isFile() && full.endsWith('.apk')) {
-          return full
-        }
-      }
-      return undefined
-    }
-
-    try {
-      let apkToInstall = apkPath
-
-      // If a directory is provided, attempt to build via Gradle
-      const stat = await fs.stat(apkPath).catch(() => null)
-      if (stat && stat.isDirectory()) {
-        const gradlewPath = path.join(apkPath, 'gradlew')
-        const gradleCmd = existsSync(gradlewPath) ? './gradlew' : 'gradle'
-
-        await new Promise<void>(async (resolve, reject) => {
-          // Auto-detect and set JAVA_HOME (prefer JDK 17) so builds don't require manual environment setup
-          const detectedJavaHome = await detectJavaHome().catch(() => undefined)
-          const env = Object.assign({}, process.env)
-          if (detectedJavaHome) {
-            // Override existing JAVA_HOME if detection found a preferably compatible JDK (e.g., JDK 17).
-            if (env.JAVA_HOME !== detectedJavaHome) {
-              env.JAVA_HOME = detectedJavaHome
-              // Also ensure the JDK bin is on PATH so tools like jlink/javac are resolved from the detected JDK
-              env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`
-              console.debug('[android] Overriding JAVA_HOME with detected path:', detectedJavaHome)
-            }
-          }
-
-          // Sanitize environment so user shell init scripts are less likely to override our JAVA_HOME.
-          try {
-            // Remove obvious shell profile hints; avoid touching SDKMAN symlinks or on-disk state.
-            delete env.SHELL
-          } catch {}
-
-          // If we detected a compatible JDK, instruct Gradle to use it and avoid daemon reuse
-          // Prepare gradle invocation
-          const gradleArgs = ['assembleDebug']
-          if (detectedJavaHome) {
-            gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`)
-            gradleArgs.push('--no-daemon')
-            env.GRADLE_JAVA_HOME = detectedJavaHome
-          }
-
-          // Prefer invoking the wrapper directly without a shell to avoid user profile shims (sdkman) re-setting JAVA_HOME
-          const wrapperPath = path.join(apkPath, 'gradlew')
-          const useWrapper = existsSync(wrapperPath)
-          const execCmd = useWrapper ? wrapperPath : gradleCmd
-          const spawnOpts: any = { cwd: apkPath, env }
-          // When using wrapper, ensure it's executable and invoke directly (no shell)
-          if (useWrapper) {
-            // Ensure the wrapper is executable; swallow errors from chmod (best-effort).
-            await fs.chmod(wrapperPath, 0o755).catch(() => {})
-            spawnOpts.shell = false
-          } else {
-            // if using system 'gradle' allow shell to resolve platform PATH
-            spawnOpts.shell = true
-          }
-
-          const proc = spawn(execCmd, gradleArgs, spawnOpts)
-          let stderr = ''
-          proc.stderr?.on('data', d => stderr += d.toString())
-          proc.on('close', code => {
-            if (code === 0) resolve()
-            else reject(new Error(stderr || `Gradle build failed with code ${code}`))
-          })
-          proc.on('error', err => reject(err))
-        })
-
-        const built = await findApk(apkPath)
-        if (!built) throw new Error('Could not locate built APK after running Gradle')
-        apkToInstall = built
-      }
-
-      // Try normal adb install with streaming attempt
-      try {
-        const res = await spawnAdb(['install', '-r', apkToInstall], deviceId)
-        if (res.code === 0) {
-          return { device: deviceInfo, installed: true, output: res.stdout }
-        }
-        // fallthrough to fallback
-      } catch (e) {
-        // Log and continue to fallback
-        console.debug('[android] adb install failed, attempting push+pm fallback:', e instanceof Error ? e.message : String(e))
-      }
-
-      // Fallback: push APK to device and use pm install -r
-      const basename = path.basename(apkToInstall)
-      const remotePath = `/data/local/tmp/${basename}`
-      await execAdb(['push', apkToInstall, remotePath], deviceId)
-      const pmOut = await execAdb(['shell', 'pm', 'install', '-r', remotePath], deviceId)
-      // cleanup remote file
-      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) }
-    }
-  }
-
-  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 }
-  }
-
-  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 }
-  }
-
-  async restartApp(appId: string, deviceId?: string): Promise<RestartAppResponse> {
-    await this.terminateApp(appId, deviceId)
-    const startResult = await this.startApp(appId, deviceId)
-    return {
-      device: startResult.device,
-      appRestarted: startResult.appStarted,
-      launchTimeMs: startResult.launchTimeMs
-    }
-  }
-
-  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' }
-  }
 }

package/src/android/manage.ts

@@ -0,0 +1,135 @@
+import { promises as fs } from 'fs'
+import { spawn } from 'child_process'
+import path from 'path'
+import { existsSync } from 'fs'
+import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from './utils.js'
+import { detectJavaHome } from '../utils/java.js'
+import { InstallAppResponse, StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from '../types.js'
+
+export class AndroidManage {
+  async build(projectPath: string, _variant?: string): Promise<{ artifactPath: string, output?: string } | { error: string }> {
+    void _variant
+    try {
+      // Always use the shared prepareGradle utility for consistent env/setup
+      const { execCmd, gradleArgs, spawnOpts } = await (await import('./utils.js')).prepareGradle(projectPath)
+      await new Promise<void>((resolve, reject) => {
+        const proc = spawn(execCmd, gradleArgs, spawnOpts)
+        let stderr = ''
+        proc.stderr?.on('data', d => stderr += d.toString())
+        proc.on('close', code => {
+          if (code === 0) resolve()
+          else reject(new Error(stderr || `Gradle failed with code ${code}`))
+        })
+        proc.on('error', err => reject(err))
+      })
+    
+      const apk = await findApk(projectPath)
+      if (!apk) return { error: 'Could not find APK after build' }
+      return { artifactPath: apk }
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) }
+    }
+  }
+
+  async installApp(apkPath: string, deviceId?: string): Promise<InstallAppResponse> {
+    const metadata = await getAndroidDeviceMetadata('', deviceId)
+    const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
+
+    try {
+      let apkToInstall = apkPath
+      const stat = await fs.stat(apkPath).catch(() => null)
+      if (stat && stat.isDirectory()) {
+        const detectedJavaHome = await detectJavaHome().catch(() => undefined)
+        const env = Object.assign({}, process.env)
+        if (detectedJavaHome) {
+          if (env.JAVA_HOME !== detectedJavaHome) {
+            env.JAVA_HOME = detectedJavaHome
+            env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`
+            console.debug('[android-run] Overriding JAVA_HOME with detected path:', detectedJavaHome)
+          }
+        }
+        try { delete env.SHELL } catch {}
+
+        const gradleArgs = ['assembleDebug']
+        if (detectedJavaHome) {
+          gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`)
+          gradleArgs.push('--no-daemon')
+          env.GRADLE_JAVA_HOME = detectedJavaHome
+        }
+
+        const wrapperPath = path.join(apkPath, 'gradlew')
+        const useWrapper = existsSync(wrapperPath)
+        const execCmd = useWrapper ? wrapperPath : 'gradle'
+        const spawnOpts: any = { cwd: apkPath, env }
+        if (useWrapper) {
+          await fs.chmod(wrapperPath, 0o755).catch(() => {})
+          spawnOpts.shell = false
+        } else spawnOpts.shell = true
+
+        const proc = spawn(execCmd, gradleArgs, spawnOpts)
+        let stderr = ''
+        await new Promise<void>((resolve, reject) => {
+          proc.stderr?.on('data', d => stderr += d.toString())
+          proc.on('close', code => {
+            if (code === 0) resolve()
+            else reject(new Error(stderr || `Gradle build failed with code ${code}`))
+          })
+          proc.on('error', err => reject(err))
+        })
+
+        const built = await findApk(apkPath)
+        if (!built) throw new Error('Could not locate built APK after running Gradle')
+        apkToInstall = built
+      }
+
+      try {
+        const res = await spawnAdb(['install', '-r', apkToInstall], deviceId)
+        if (res.code === 0) {
+          return { device: deviceInfo, installed: true, output: res.stdout }
+        }
+      } catch (e) {
+        console.debug('[android-run] adb install failed, attempting push+pm fallback:', e instanceof Error ? e.message : String(e))
+      }
+
+      const basename = path.basename(apkToInstall)
+      const remotePath = `/data/local/tmp/${basename}`
+      await execAdb(['push', apkToInstall, remotePath], deviceId)
+      const pmOut = await execAdb(['shell', 'pm', 'install', '-r', remotePath], deviceId)
+      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) }
+    }
+  }
+
+  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 }
+  }
+
+  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 }
+  }
+
+  async restartApp(appId: string, deviceId?: string): Promise<RestartAppResponse> {
+    await this.terminateApp(appId, deviceId)
+    const startResult = await this.startApp(appId, deviceId)
+    return {
+      device: startResult.device,
+      appRestarted: startResult.appStarted,
+      launchTimeMs: startResult.launchTimeMs
+    }
+  }
+
+  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' }
+  }
+}