mcp-maestro-mobile-ai 1.1.0

package/src/mcp-server/utils/maestro.js

@@ -0,0 +1,508 @@
+/**
+ * Maestro Utility Functions
+ * Execute Maestro CLI commands and handle results
+ */
+
+import { spawn, execSync } from "child_process";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { logger } from "./logger.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Directories - Use system-level hidden paths for temp files
+// This ensures YAML files are not visible in user's project
+const USER_HOME = os.homedir();
+const APP_DATA_DIR = join(USER_HOME, ".maestro-mcp");
+const TEMP_DIR = join(APP_DATA_DIR, "temp");
+const OUTPUT_DIR = join(APP_DATA_DIR, "output");
+const SCREENSHOTS_DIR = join(OUTPUT_DIR, "screenshots");
+const RESULTS_DIR = join(OUTPUT_DIR, "results");
+const CONTEXT_DIR = join(APP_DATA_DIR, "context");
+
+// Configuration from environment
+const DEFAULT_TIMEOUT = parseInt(process.env.DEFAULT_WAIT_TIMEOUT) || 10000;
+const DEFAULT_RETRIES = parseInt(process.env.DEFAULT_RETRIES) || 0;
+const MAX_RESULTS = parseInt(process.env.MAX_RESULTS) || 50;
+
+// Selected device (in-memory state)
+let selectedDeviceId = process.env.MAESTRO_DEVICE || null;
+
+/**
+ * Get ADB command path
+ * Uses ANDROID_HOME if set, otherwise falls back to 'adb' in PATH
+ */
+function getAdbPath() {
+  const androidHome = process.env.ANDROID_HOME;
+  if (androidHome) {
+    // Use path.join for cross-platform compatibility
+    return path.join(androidHome, "platform-tools", "adb");
+  }
+  return "adb";
+}
+
+/**
+ * Execute Maestro CLI command with optional device targeting
+ */
+export function executeMaestro(args, deviceId = null) {
+  return new Promise((resolve) => {
+    // Use specified device, selected device, or let Maestro choose
+    const targetDevice = deviceId || selectedDeviceId;
+    const finalArgs = targetDevice ? ["--device", targetDevice, ...args] : args;
+
+    const maestro = spawn("maestro", finalArgs, {
+      shell: true,
+      env: { ...process.env },
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    maestro.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+
+    maestro.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    maestro.on("close", (exitCode) => {
+      resolve({ exitCode, stdout, stderr });
+    });
+
+    maestro.on("error", (error) => {
+      resolve({ exitCode: 1, stdout, stderr: error.message });
+    });
+  });
+}
+
+/**
+ * List all connected devices with detailed information
+ */
+export async function listDevices() {
+  try {
+    const adbPath = getAdbPath();
+    let adbOutput;
+    try {
+      adbOutput = execSync(`"${adbPath}" devices -l`, {
+        encoding: "utf8",
+        timeout: 5000,
+      });
+    } catch (error) {
+      return {
+        success: false,
+        error:
+          "ADB not found. Make sure Android SDK is installed and ANDROID_HOME is set.",
+        devices: [],
+      };
+    }
+
+    // Parse ADB output with detailed info
+    const lines = adbOutput.split("\n").filter((line) => line.trim());
+    const devices = lines
+      .slice(1) // Skip header "List of devices attached"
+      .map((line) => {
+        // Format: "emulator-5554 device product:sdk_gphone64_x86_64 model:sdk_gphone64_x86_64 device:emu64xa transport_id:1"
+        // Or: "RF8M12345XY device usb:1-1 product:starqltesq model:SM_G965U device:starqltesq transport_id:2"
+        const parts = line.split(/\s+/);
+        if (parts.length >= 2 && parts[1] === "device") {
+          const id = parts[0];
+          const isEmulator = id.startsWith("emulator-");
+
+          // Extract model name if available
+          const modelMatch = line.match(/model:(\S+)/);
+          const model = modelMatch ? modelMatch[1].replace(/_/g, " ") : null;
+
+          // Extract product name
+          const productMatch = line.match(/product:(\S+)/);
+          const product = productMatch ? productMatch[1] : null;
+
+          return {
+            id,
+            type: isEmulator ? "emulator" : "physical",
+            model:
+              model || (isEmulator ? "Android Emulator" : "Unknown Device"),
+            product,
+            status: "connected",
+            isSelected: id === selectedDeviceId,
+          };
+        }
+        return null;
+      })
+      .filter((d) => d !== null);
+
+    logger.info(`Found ${devices.length} device(s)`);
+
+    return {
+      success: true,
+      devices,
+      count: devices.length,
+      selectedDevice: selectedDeviceId,
+    };
+  } catch (error) {
+    logger.error("List devices failed", { error: error.message });
+    return {
+      success: false,
+      error: error.message,
+      devices: [],
+    };
+  }
+}
+
+/**
+ * Select a device for running tests
+ */
+export function selectDevice(deviceId) {
+  selectedDeviceId = deviceId;
+  logger.info(`Device selected: ${deviceId}`);
+  return {
+    success: true,
+    selectedDevice: deviceId,
+  };
+}
+
+/**
+ * Get the currently selected device
+ */
+export function getSelectedDevice() {
+  return selectedDeviceId;
+}
+
+/**
+ * Clear device selection (use default)
+ */
+export function clearDeviceSelection() {
+  selectedDeviceId = null;
+  logger.info("Device selection cleared, will use default");
+  return {
+    success: true,
+    message:
+      "Device selection cleared. Maestro will use the first available device.",
+  };
+}
+
+/**
+ * Check if ADB is available and device is connected
+ */
+export async function checkDeviceConnection() {
+  try {
+    const adbPath = getAdbPath();
+    // Check if ADB is available
+    let adbOutput;
+    try {
+      adbOutput = execSync(`"${adbPath}" devices`, {
+        encoding: "utf8",
+        timeout: 5000,
+      });
+    } catch (error) {
+      return {
+        connected: false,
+        error:
+          "ADB not found. Make sure Android SDK is installed and ANDROID_HOME is set.",
+        devices: [],
+      };
+    }
+
+    // Parse ADB output
+    const lines = adbOutput.split("\n").filter((line) => line.trim());
+    const devices = lines
+      .slice(1) // Skip header
+      .map((line) => {
+        const parts = line.split("\t");
+        if (parts.length >= 2) {
+          return {
+            id: parts[0].trim(),
+            status: parts[1].trim(),
+          };
+        }
+        return null;
+      })
+      .filter((d) => d && d.status === "device");
+
+    if (devices.length === 0) {
+      return {
+        connected: false,
+        error:
+          "No Android device/emulator connected. Start an emulator or connect a device.",
+        devices: [],
+        hint: "Run: emulator -avd YOUR_AVD_NAME",
+      };
+    }
+
+    logger.info(`Found ${devices.length} connected device(s)`);
+
+    return {
+      connected: true,
+      devices,
+      activeDevice: selectedDeviceId || devices[0].id,
+      selectedDevice: selectedDeviceId,
+    };
+  } catch (error) {
+    logger.error("Device check failed", { error: error.message });
+    return {
+      connected: false,
+      error: error.message,
+      devices: [],
+    };
+  }
+}
+
+/**
+ * Check if app is installed on device (optionally on specific device)
+ */
+export async function checkAppInstalled(appId, deviceId = null) {
+  if (!appId) {
+    return {
+      installed: false,
+      error: "APP_ID not configured",
+      hint: "Set APP_ID in .env file or MCP config",
+    };
+  }
+
+  const targetDevice = deviceId || selectedDeviceId;
+  const adbPath = getAdbPath();
+  const adbPrefix = targetDevice
+    ? `"${adbPath}" -s ${targetDevice}`
+    : `"${adbPath}"`;
+
+  try {
+    const result = execSync(`${adbPrefix} shell pm list packages ${appId}`, {
+      encoding: "utf8",
+      timeout: 10000,
+    });
+
+    const isInstalled = result.includes(appId);
+
+    if (!isInstalled) {
+      return {
+        installed: false,
+        appId,
+        device: targetDevice,
+        error: `App "${appId}" is not installed on the device`,
+        hint: "Install the app on the device before running tests",
+      };
+    }
+
+    logger.info(
+      `App verified: ${appId} on device: ${targetDevice || "default"}`
+    );
+
+    return {
+      installed: true,
+      appId,
+      device: targetDevice,
+    };
+  } catch (error) {
+    // If command fails, try alternative approach
+    try {
+      const result = execSync(`${adbPrefix} shell pm list packages`, {
+        encoding: "utf8",
+        timeout: 15000,
+      });
+
+      const isInstalled = result.includes(appId);
+
+      return {
+        installed: isInstalled,
+        appId,
+        device: targetDevice,
+        error: isInstalled
+          ? null
+          : `App "${appId}" is not installed on the device`,
+      };
+    } catch (e) {
+      return {
+        installed: false,
+        appId,
+        error:
+          "Could not verify app installation. Make sure device is connected.",
+      };
+    }
+  }
+}
+
+/**
+ * Run a Maestro flow from YAML content with retry support
+ */
+export async function runMaestroFlow(yamlContent, testName, options = {}) {
+  const maxRetries = options.retries ?? DEFAULT_RETRIES;
+  const deviceId = options.deviceId || selectedDeviceId;
+  const startTime = Date.now();
+
+  // Ensure directories exist
+  await fs.mkdir(TEMP_DIR, { recursive: true });
+  await fs.mkdir(SCREENSHOTS_DIR, { recursive: true });
+
+  // Write YAML to temp file
+  const tempFile = join(TEMP_DIR, `${testName}-${Date.now()}.yaml`);
+  await fs.writeFile(tempFile, yamlContent, "utf8");
+
+  let lastResult = null;
+  let attempts = 0;
+
+  try {
+    // Retry loop
+    while (attempts <= maxRetries) {
+      attempts++;
+
+      if (attempts > 1) {
+        logger.info(
+          `Retry ${attempts - 1}/${maxRetries} for test: ${testName}`
+        );
+      }
+
+      // Execute Maestro with device targeting
+      const result = await executeMaestro(["test", tempFile], deviceId);
+      const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+
+      if (result.exitCode === 0) {
+        logger.info(
+          `Test passed: ${testName} in ${duration}s (attempt ${attempts})${
+            deviceId ? ` on device ${deviceId}` : ""
+          }`
+        );
+        return {
+          success: true,
+          name: testName,
+          duration,
+          attempts,
+          device: deviceId || "default",
+          output: result.stdout,
+        };
+      }
+
+      // Test failed
+      lastResult = {
+        success: false,
+        name: testName,
+        duration,
+        attempts,
+        device: deviceId || "default",
+        error: parseErrorMessage(result.stderr || result.stdout),
+        rawError: result.stderr || result.stdout,
+      };
+
+      // If we have more retries, continue
+      if (attempts <= maxRetries) {
+        logger.warn(`Test failed, will retry: ${testName}`);
+        // Small delay before retry
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+      }
+    }
+
+    // All retries exhausted
+    logger.error(`Test failed after ${attempts} attempts: ${testName}`);
+
+    // Capture failure screenshot
+    const screenshotPath = await captureScreenshot(
+      `${testName}-failure`,
+      deviceId
+    );
+
+    return {
+      ...lastResult,
+      screenshot: screenshotPath,
+      retriesExhausted: maxRetries > 0,
+    };
+  } finally {
+    // Clean up temp file
+    try {
+      await fs.unlink(tempFile);
+    } catch (e) {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Parse and improve error messages
+ */
+function parseErrorMessage(rawError) {
+  if (!rawError) return "Unknown error";
+
+  // Element not found
+  if (rawError.includes("Element not found")) {
+    const match = rawError.match(/Element not found: (.+)/);
+    const element = match ? match[1] : "unknown element";
+    return `Element not found: ${element}. The element may not exist, or the app may still be loading. Try adding more wait time or check if the selector is correct.`;
+  }
+
+  // Timeout
+  if (rawError.includes("timeout") || rawError.includes("Timeout")) {
+    return "Operation timed out. The app may be slow or the element took too long to appear. Consider increasing the timeout value.";
+  }
+
+  // App not installed
+  if (
+    rawError.includes("App not installed") ||
+    rawError.includes("could not be found")
+  ) {
+    return "App is not installed on the device. Install the app before running tests.";
+  }
+
+  // No device
+  if (rawError.includes("No device") || rawError.includes("no devices")) {
+    return "No Android device/emulator connected. Start an emulator or connect a device.";
+  }
+
+  // Truncate very long errors
+  if (rawError.length > 500) {
+    return rawError.substring(0, 500) + "... (truncated)";
+  }
+
+  return rawError;
+}
+
+/**
+ * Capture a screenshot (optionally on specific device)
+ */
+export async function captureScreenshot(name, deviceId = null) {
+  await fs.mkdir(SCREENSHOTS_DIR, { recursive: true });
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const screenshotPath = join(SCREENSHOTS_DIR, `${name}-${timestamp}.png`);
+
+  try {
+    const result = await executeMaestro(
+      ["screenshot", screenshotPath],
+      deviceId
+    );
+    if (result.exitCode === 0) {
+      logger.info(`Screenshot saved: ${screenshotPath}`);
+      return screenshotPath;
+    }
+    return null;
+  } catch (error) {
+    logger.warn("Failed to capture screenshot", { error: error.message });
+    return null;
+  }
+}
+
+/**
+ * Get configuration values
+ */
+export function getConfig() {
+  return {
+    defaultTimeout: DEFAULT_TIMEOUT,
+    defaultRetries: DEFAULT_RETRIES,
+    maxResults: MAX_RESULTS,
+    selectedDevice: selectedDeviceId,
+  };
+}
+
+export default {
+  executeMaestro,
+  runMaestroFlow,
+  captureScreenshot,
+  checkDeviceConnection,
+  checkAppInstalled,
+  listDevices,
+  selectDevice,
+  getSelectedDevice,
+  clearDeviceSelection,
+  getConfig,
+};

package/templates/mcp-config-claude-desktop.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "npx",
+      "args": ["mcp-maestro-mobile-ai"],
+      "env": {
+        "APP_ID": "com.your.app.package",
+        "ANDROID_HOME": "/path/to/android/sdk",
+        "DEFAULT_RETRIES": "1",
+        "MAX_RESULTS": "50"
+      }
+    }
+  }
+}
+

package/templates/mcp-config-cursor.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "npx",
+      "args": ["mcp-maestro-mobile-ai"],
+      "env": {
+        "APP_ID": "com.your.app.package",
+        "ANDROID_HOME": "/path/to/android/sdk",
+        "DEFAULT_RETRIES": "1",
+        "MAX_RESULTS": "50"
+      }
+    }
+  }
+}
+

package/templates/mcp-config-vscode.json

@@ -0,0 +1,13 @@
+{
+  "github.copilot.chat.mcpServers": {
+    "maestro": {
+      "command": "npx",
+      "args": ["mcp-maestro-mobile-ai"],
+      "env": {
+        "APP_ID": "com.your.app.package",
+        "ANDROID_HOME": "/path/to/android/sdk"
+      }
+    }
+  }
+}
+