mobile-debug-mcp 0.20.0 → 0.21.0

package/dist/scripts/press_and_wait_ui.mjs

@@ -0,0 +1,85 @@
+import { ToolsObserve } from '../observe/index.js'
+import { ToolsInteract } from '../interact/index.js'
+
+async function main() {
+  const bundle = 'com.ideamechanics.modul8'
+  const sessionId = 'press-ui-test'
+  console.log('Starting log stream for', bundle)
+  try {
+    const platform = process.argv.includes('--platform') ? process.argv[process.argv.indexOf('--platform')+1] : 'android'
+    const pkg = bundle
+    const sessionOpts = { platform, packageName: pkg, sessionId }
+    const start = await ToolsObserve.startLogStreamHandler(sessionOpts)
+    console.log('startLogStream result:', JSON.stringify(start))
+  } catch (e) {
+    console.error('startLogStream failed:', e instanceof Error ? e.message : String(e))
+  }
+
+  console.log('\nAttempting to find and tap Generate Session...')
+  let el = null
+  try {
+    const platform = process.argv.includes('--platform') ? process.argv[process.argv.indexOf('--platform')+1] : 'android'
+    const found = await ToolsInteract.findElementHandler({ query: 'Generate Session', exact: platform === 'android', timeoutMs: 3000, platform })
+    const foundFlag = found && typeof (found).found !== 'undefined' ? found.found : false
+    console.log('findElementHandler:', foundFlag ? 'found' : 'not found')
+    if (foundFlag) {
+      el = found.element
+      console.log('Matched element:', JSON.stringify(el))
+    }
+  } catch (e) { console.error('findElementHandler err:', e) }
+
+  try {
+    const platform = process.argv.includes('--platform') ? process.argv[process.argv.indexOf('--platform')+1] : 'android'
+    const device = process.argv.includes('--device') ? process.argv[process.argv.indexOf('--device')+1] : undefined
+
+    // Strict foreground check: ensure the package is in foreground before tapping
+    try {
+      const fg = await ToolsInteract.get_current_activity ? await ToolsInteract.get_current_activity({ platform, deviceId: device }) : null
+      console.log('Foreground activity info:', fg)
+      if (fg && fg.activity && !String(fg.activity).includes('modul8')) {
+        console.error('App is not foreground. Aborting tap.')
+        process.exit(2)
+      }
+    } catch (e) { console.warn('Foreground check failed:', e) }
+
+    if (el && el.tapCoordinates) {
+      console.log('Tapping matched element at', JSON.stringify(el.tapCoordinates))
+      await ToolsInteract.tapHandler({ platform, x: el.tapCoordinates.x, y: el.tapCoordinates.y, deviceId: device })
+    } else {
+      console.log('Element not found, tapping center fallback')
+      await ToolsInteract.tapHandler({ platform, x: 200, y: 400, deviceId: device })
+    }
+  } catch (e) { console.error('Tap failed:', e) }
+
+  console.log('\nNow waiting for "Generating session" to disappear (timeout 30s)')
+  const start = Date.now()
+  const deadline = start + (parseInt(process.argv.includes('--timeout') ? process.argv[process.argv.indexOf('--timeout')+1] : '30000'))
+  let poll = 0
+  let disappeared = false
+  const platformArg = process.argv.includes('--platform') ? process.argv[process.argv.indexOf('--platform')+1] : 'android'
+  const deviceArg = process.argv.includes('--device') ? process.argv[process.argv.indexOf('--device')+1] : undefined
+  while (Date.now() <= deadline) {
+    poll++
+    try {
+      const f = await ToolsInteract.findElementHandler({ query: 'Generating session', exact: false, timeoutMs: 1000, platform: platformArg, deviceId: deviceArg })
+      const exists = f && typeof f.found !== 'undefined' ? f.found : false
+      console.log(`poll ${poll}: generating exists=${exists}`)
+      if (!exists) { disappeared = true; break }
+    } catch (e) { console.error('findElement err:', e) }
+    await new Promise(r => setTimeout(r, 500))
+  }
+
+  const elapsed = Date.now()-start
+  console.log('Result: disappeared=', disappeared, 'polls=', poll, 'elapsedMs=', elapsed)
+
+  // Platform-specific post-conditions
+
+
+  console.log('\nFinal Result: success=', disappeared)
+
+  console.log('\nStopping log stream')
+  try { const stop = await ToolsObserve.stopLogStreamHandler({ platform: 'ios', sessionId }); console.log('stopLogStream', stop) } catch (e) { console.error('stop failed', e) }
+  process.exit(disappeared ? 0 : 2)
+}
+
+main().catch(e=>{ console.error(e); process.exit(1) })

package/dist/scripts/test_generate_and_wait.mjs

@@ -0,0 +1,123 @@
+import fs from 'fs'
+import path from 'path'
+import { ToolsObserve } from '../observe/index.js'
+import { ToolsInteract } from '../interact/index.js'
+
+const argv = process.argv.slice(2)
+const opts = { platform: 'android', deviceId: undefined, timeoutMs: 180000, stabilityMs: 1000, pollIntervalMs: 500, saveDir: '/tmp' }
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '--platform') opts.platform = argv[++i]
+  else if (argv[i] === '--deviceId') opts.deviceId = argv[++i]
+  else if (argv[i] === '--timeout') opts.timeoutMs = Number(argv[++i])
+  else if (argv[i] === '--stabilityMs') opts.stabilityMs = Number(argv[++i])
+  else if (argv[i] === '--poll') opts.pollIntervalMs = Number(argv[++i])
+  else if (argv[i] === '--saveDir') opts.saveDir = argv[++i]
+}
+
+const platform = opts.platform
+const deviceId = opts.deviceId
+const timeoutMs = opts.timeoutMs
+const stabilityMs = opts.stabilityMs
+const poll = opts.pollIntervalMs
+const saveDir = opts.saveDir
+
+const ts = () => Date.now()
+
+async function findAndTapGenerate() {
+  try {
+    const found = await ToolsInteract.findElementHandler({ query: 'Generate Session', exact: false, timeoutMs: 3000, platform, deviceId })
+    const foundFlag = found && typeof found.found !== 'undefined' ? found.found : false
+    console.log('find Generate Session:', foundFlag)
+    if (foundFlag) {
+      const el = found.element
+      if (el && el.tapCoordinates) {
+        console.log('Tapping at', JSON.stringify(el.tapCoordinates))
+        await ToolsInteract.tapHandler({ platform, x: el.tapCoordinates.x, y: el.tapCoordinates.y, deviceId })
+        return true
+      } else {
+        // tap center of parent bounds if available
+        if (el && el.bounds) {
+          const b = el.bounds
+          const cx = Math.floor((b.left + b.right)/2)
+          const cy = Math.floor((b.top + b.bottom)/2)
+          console.log('Tapping parent center', cx, cy)
+          await ToolsInteract.tapHandler({ platform, x: cx, y: cy, deviceId })
+          return true
+        }
+      }
+    }
+  } catch (e) { console.error('error finding/tapping generate:', e) }
+  return false
+}
+
+async function captureUITree(savePrefix) {
+  try {
+    const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId })
+    const p = path.join(saveDir, `${savePrefix}_ui_${Date.now()}.json`)
+    fs.writeFileSync(p, JSON.stringify(tree, null, 2))
+    console.log('Wrote UI tree', p)
+    return tree
+  } catch (e) { console.error('failed getUITree:', e); return null }
+}
+
+async function tryCaptureScreenshot(savePrefix) {
+  try {
+    const res = await ToolsObserve.captureScreenshotHandler({ platform, deviceId })
+    // handler may return { image: 'data:image/png;base64,...' } or blocks; try to extract base64
+    let b64 = null
+    if (res && res.image && typeof res.image === 'string') b64 = res.image.replace(/^data:image\/png;base64,/, '')
+    else if (Array.isArray(res) && res.length) {
+      for (const blk of res) { if (blk && blk.mime === 'image/png' && blk.data) { b64 = blk.data; break } }
+    } else if (res && res.blocks) {
+      for (const blk of res.blocks) { if (blk && blk.mime === 'image/png' && blk.data) { b64 = blk.data; break } }
+    }
+    if (b64) {
+      const p = path.join(saveDir, `${savePrefix}_shot_${Date.now()}.png`)
+      fs.writeFileSync(p, Buffer.from(b64, 'base64'))
+      console.log('Wrote screenshot', p)
+      return p
+    }
+    console.log('No image returned from captureScreenshotHandler')
+  } catch (e) { console.error('screenshot error:', e) }
+  return null
+}
+
+async function main() {
+  console.log('Starting test: tap Generate Session and wait for Play session to appear stably')
+  const tapped = await findAndTapGenerate()
+  if (!tapped) console.log('Warning: generate tap not performed')
+
+  const start = ts()
+  const deadline = start + timeoutMs
+  let matchedAt = null
+  let pollCount = 0
+
+  while (Date.now() <= deadline) {
+    pollCount++
+    const savePrefix = `gen_wait_p${pollCount}`
+    const tree = await captureUITree(savePrefix)
+    try {
+      const f = await ToolsInteract.findElementHandler({ query: 'Play session', exact: false, timeoutMs: 500, platform, deviceId })
+      const exists = f && typeof f.found !== 'undefined' ? f.found : false
+      console.log(`poll ${pollCount}: play exists=${exists}`)
+      await tryCaptureScreenshot(savePrefix)
+      if (exists) {
+        if (matchedAt === null) matchedAt = Date.now()
+        const stable = Date.now() - matchedAt
+        if (stable >= stabilityMs) {
+          console.log('SUCCESS: Play session present and stable for', stable, 'ms after', Date.now()-start, 'ms and', pollCount, 'polls')
+          process.exit(0)
+        }
+      } else {
+        matchedAt = null
+      }
+    } catch (e) { console.error('error during poll:', e) }
+
+    await new Promise(r => setTimeout(r, poll))
+  }
+
+  console.error('FAIL: timeout waiting for Play session (polls=', pollCount, ')')
+  process.exit(2)
+}
+
+main().catch(e=>{ console.error('fatal', e); process.exit(1) })

package/dist/server.js

@@ -314,6 +314,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["previousFingerprint"]
             }
         },
+        {
+            name: "observe_until",
+            description: "Wait for a UI condition (element present/absent) and require a stability window before returning success. Network-based waiting is not required; UI-only synchronization is the default and primary mode.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    type: { type: "string", enum: ["ui", "log", "screen", "idle"], description: "Condition type to observe", default: "ui" },
+                    query: { type: "string", description: "Optional query string for ui/log/screen types" },
+                    timeoutMs: { type: "number", description: "Timeout in ms to wait for condition (default 30000)", default: 30000 },
+                    pollIntervalMs: { type: "number", description: "Polling interval in ms (default 300, clamped to 250-500)", default: 300 },
+                    match: { type: "string", enum: ["present", "absent"], description: "Match mode for UI checks: 'present' or 'absent' (default 'present')", default: "present" },
+                    stability_ms: { type: "number", description: "Stability window in ms that the condition must hold before returning success (default 700)", default: 700 },
+                    includeSnapshotOnFailure: { type: "boolean", description: "Whether to include a debug snapshot on timeout (default true)", default: true },
+                    platform: { type: "string", enum: ["android", "ios"], description: "Optional platform override" },
+                    deviceId: { type: "string", description: "Optional device serial/udid" }
+                }
+            }
+        },
         {
             name: "wait_for_element",
             description: "Wait until a UI element with matching text appears on screen or timeout is reached.",

package/dist/system/gradle.js

@@ -0,0 +1,101 @@
+import { readFileSync, existsSync } from 'fs';
+import path from 'path';
+import os from 'os';
+function readPropertiesFile(p) {
+    try {
+        const txt = readFileSync(p, { encoding: 'utf8' });
+        const lines = String(txt).split(/\r?\n/);
+        const out = {};
+        for (const l of lines) {
+            const trimmed = l.trim();
+            if (!trimmed || trimmed.startsWith('#'))
+                continue;
+            const idx = trimmed.indexOf('=');
+            if (idx === -1)
+                continue;
+            const k = trimmed.substring(0, idx).trim();
+            const v = trimmed.substring(idx + 1).trim();
+            out[k] = v;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+function javaBinExists(p) {
+    if (!p)
+        return false;
+    try {
+        const javaPath = path.join(p, 'bin', 'java');
+        if (existsSync(javaPath))
+            return true;
+        const alt = path.join(p, 'Contents', 'Home', 'bin', 'java');
+        if (existsSync(alt))
+            return true;
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+export async function checkGradle() {
+    const issues = [];
+    const filesChecked = [];
+    const suggestedFixes = [];
+    let gradleJavaHome;
+    // 1) explicit env
+    if (process.env.GRADLE_JAVA_HOME) {
+        gradleJavaHome = process.env.GRADLE_JAVA_HOME;
+        if (!javaBinExists(gradleJavaHome)) {
+            issues.push(`GRADLE_JAVA_HOME is set to '${gradleJavaHome}' but no java binary was found there`);
+            suggestedFixes.push('Unset GRADLE_JAVA_HOME or point it to a valid JDK (e.g., /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home)');
+        }
+    }
+    // 2) user gradle.properties
+    const gradleUserHome = process.env.GRADLE_USER_HOME || path.join(os.homedir(), '.gradle');
+    const userProps = path.join(gradleUserHome, 'gradle.properties');
+    filesChecked.push(userProps);
+    try {
+        const props = readPropertiesFile(userProps);
+        if (props['org.gradle.java.home']) {
+            const p = props['org.gradle.java.home'];
+            gradleJavaHome = gradleJavaHome || p;
+            if (!javaBinExists(p)) {
+                issues.push(`org.gradle.java.home in ${userProps} points to '${p}' which does not look like a valid JDK`);
+                suggestedFixes.push(`Edit ${userProps} to remove or correct org.gradle.java.home`);
+            }
+        }
+    }
+    catch { }
+    // 3) system gradle.properties
+    const systemProps = '/etc/gradle/gradle.properties';
+    filesChecked.push(systemProps);
+    try {
+        const props = readPropertiesFile(systemProps);
+        if (props['org.gradle.java.home']) {
+            const p = props['org.gradle.java.home'];
+            gradleJavaHome = gradleJavaHome || p;
+            if (!javaBinExists(p)) {
+                issues.push(`org.gradle.java.home in ${systemProps} points to '${p}' which does not look like a valid JDK`);
+                suggestedFixes.push(`Edit ${systemProps} to remove or correct org.gradle.java.home`);
+            }
+        }
+    }
+    catch { }
+    // 4) GRADLE_HOME fallback
+    if (!gradleJavaHome && process.env.GRADLE_HOME) {
+        filesChecked.push(process.env.GRADLE_HOME);
+        if (javaBinExists(process.env.GRADLE_HOME)) {
+            gradleJavaHome = process.env.GRADLE_HOME;
+        }
+    }
+    const gradleValid = !!gradleJavaHome && javaBinExists(gradleJavaHome);
+    if (!gradleJavaHome) {
+        // no explicit gradle java home detected — not an issue
+    }
+    else if (!gradleValid) {
+        issues.push(`Detected org.gradle.java.home = '${gradleJavaHome}' but it is invalid`);
+    }
+    return { gradleJavaHome, gradleValid, filesChecked, issues, suggestedFixes };
+}

package/dist/system/index.js

@@ -1,10 +1,12 @@
 import { checkAndroid } from './android.js';
 import { checkIOS } from './ios.js';
+import { checkGradle } from './gradle.js';
 export async function getSystemStatus() {
     try {
         const android = await checkAndroid();
         const ios = await checkIOS();
-        const issues = [...android.issues, ...ios.issues];
+        const gradle = await checkGradle();
+        const issues = [...android.issues, ...ios.issues, ...(gradle.issues || [])];
         const success = issues.length === 0;
         return {
             success,
@@ -17,7 +19,11 @@ export async function getSystemStatus() {
             issues,
             appInstalled: android.appInstalled,
             iosAvailable: ios.iosAvailable,
-            iosDevices: ios.iosDevices
+            iosDevices: ios.iosDevices,
+            gradleJavaHome: gradle.gradleJavaHome,
+            gradleValid: gradle.gradleValid,
+            gradleFilesChecked: gradle.filesChecked,
+            gradleSuggestedFixes: gradle.suggestedFixes
         };
     }
     catch (e) {

package/dist/utils/android/utils.js

@@ -3,6 +3,7 @@ import path from 'path';
 import { detectJavaHome } from '../java.js';
 import { execCmd } from '../exec.js';
 import { spawnSync } from 'child_process';
+import { checkGradle } from '../../system/gradle.js';
 function findInPath(cmd) {
     try {
         // prefer command -v for POSIX
@@ -76,6 +77,14 @@ export async function prepareGradle(projectPath) {
         gradleArgs.push('-Dorg.gradle.caching=false');
     }
     const detectedJavaHome = await detectJavaHome().catch(() => undefined);
+    // Check for problematic org.gradle.java.home entries (env or properties) and avoid passing invalid values to Gradle
+    let gradleCheck;
+    try {
+        gradleCheck = await checkGradle();
+    }
+    catch {
+        gradleCheck = { gradleJavaHome: undefined, gradleValid: false, filesChecked: [], issues: [] };
+    }
     const env = Object.assign({}, process.env);
     // Ensure child processes can find Android platform-tools (adb, etc.) by
     // prepending the platform-tools directory to PATH for spawned processes.
@@ -90,6 +99,7 @@ export async function prepareGradle(projectPath) {
         console.debug(`[prepareGradle] error resolving adbPath: ${String(e)}`);
     }
     const pathParts = [];
+    // Prefer a detected (validated) Java home from the system/IDE
     if (detectedJavaHome) {
         if (env.JAVA_HOME !== detectedJavaHome) {
             env.JAVA_HOME = detectedJavaHome;
@@ -100,6 +110,26 @@ export async function prepareGradle(projectPath) {
         gradleArgs.push('--no-daemon');
         env.GRADLE_JAVA_HOME = detectedJavaHome;
     }
+    else if (gradleCheck && gradleCheck.gradleJavaHome) {
+        // There's an org.gradle.java.home configured somewhere (env or gradle.properties)
+        if (gradleCheck.gradleValid) {
+            const p = gradleCheck.gradleJavaHome;
+            const javaBin = path.join(p, 'bin');
+            if (!env.PATH || !env.PATH.includes(javaBin))
+                pathParts.push(javaBin);
+            gradleArgs.push(`-Dorg.gradle.java.home=${p}`);
+            gradleArgs.push('--no-daemon');
+            env.GRADLE_JAVA_HOME = p;
+        }
+        else {
+            // Invalid gradle java home detected: avoid passing it to Gradle and remove from spawn env
+            console.debug(`[prepareGradle] Invalid org.gradle.java.home detected (${gradleCheck.gradleJavaHome}); removing from spawn env to avoid Gradle error.`);
+            try {
+                delete env.GRADLE_JAVA_HOME;
+            }
+            catch { }
+        }
+    }
     if (platformToolsDir) {
         // Prepend platform-tools so gradle and child tools find adb without modifying global env
         if (!env.PATH || !env.PATH.includes(platformToolsDir)) {
@@ -138,10 +168,12 @@ export async function prepareGradle(projectPath) {
         catch (e) {
             console.debug('[prepareGradle] chmod failed for gradlew:', String(e));
         }
+        // Execute the wrapper directly without a shell to avoid shell tokenization of args (spaces in paths)
         spawnOpts.shell = false;
     }
     else {
-        spawnOpts.shell = true;
+        // Prefer executing gradle directly without invoking a shell to preserve argument boundaries
+        spawnOpts.shell = false;
     }
     return { execCmd, gradleArgs, spawnOpts };
 }

package/docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.21.0]
+- Added `observe_until` as a tool for agents to wait for things like API requests
+
+## [0.20.1]
+- Fixes gradle home issue for android
+
 ## [0.20.0]
 - Added `get_system_status` tool and refactored system health checks into `src/system`.
   - Provides a fast environment healthcheck (ADB availability/version, connected devices, log access, Android env vars, and basic iOS xcrun/simulator checks).

package/package.json

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