mcp-maestro-mobile-ai 1.1.0

package/src/mcp-server/tools/utilityTools.js

@@ -0,0 +1,721 @@
+/**
+ * Utility Tools
+ * Helper tools for configuration, results, device management, and cleanup
+ */
+
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { logger } from "../utils/logger.js";
+import {
+  captureScreenshot as maestroScreenshot,
+  checkDeviceConnection,
+  checkAppInstalled,
+  listDevices as maestroListDevices,
+  selectDevice as maestroSelectDevice,
+  clearDeviceSelection as maestroClearDevice,
+  getSelectedDevice,
+  getConfig,
+} from "../utils/maestro.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = join(__dirname, "../../..");
+const RESULTS_DIR = join(PROJECT_ROOT, "output/results");
+const SCREENSHOTS_DIR = join(PROJECT_ROOT, "output/screenshots");
+
+/**
+ * Get app configuration
+ */
+export async function getAppConfig() {
+  try {
+    const maestroConfig = getConfig();
+
+    const config = {
+      appId: process.env.APP_ID || null,
+      platform: process.env.PLATFORM || "android",
+      emulatorName: process.env.EMULATOR_NAME || null,
+      androidHome: process.env.ANDROID_HOME || null,
+      promptsDir: "prompts",
+      outputDir: "output",
+      // Include configurable settings
+      settings: {
+        defaultWaitTimeout: maestroConfig.defaultTimeout,
+        defaultRetries: maestroConfig.defaultRetries,
+        maxResults: maestroConfig.maxResults,
+      },
+      // Include selected device
+      selectedDevice: maestroConfig.selectedDevice || null,
+    };
+
+    // Check if appId is configured
+    if (!config.appId) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              error: "APP_ID not configured",
+              hint: "Set APP_ID in the .env file or MCP config. Example: APP_ID=com.google.android.youtube",
+              config,
+            }),
+          },
+        ],
+      };
+    }
+
+    logger.info("App config retrieved", { appId: config.appId });
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            config,
+            usage: `Use appId "${config.appId}" at the top of your Maestro YAML files.`,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    logger.error("Error getting app config", { error: error.message });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: false,
+            error: error.message,
+          }),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * List all connected devices
+ */
+export async function listDevices() {
+  try {
+    logger.info("Listing connected devices...");
+
+    const result = await maestroListDevices();
+
+    if (!result.success) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              error: result.error,
+              devices: [],
+            }),
+          },
+        ],
+      };
+    }
+
+    if (result.devices.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: true,
+              devices: [],
+              count: 0,
+              message: "No devices connected. Start an emulator or connect a physical device via USB.",
+              hint: "Enable USB Debugging on your device: Settings → Developer Options → USB Debugging",
+            }),
+          },
+        ],
+      };
+    }
+
+    // Format devices for display
+    const formattedDevices = result.devices.map((device, index) => ({
+      index: index + 1,
+      id: device.id,
+      type: device.type,
+      model: device.model,
+      isSelected: device.isSelected,
+      displayName: `${device.type === "emulator" ? "📱" : "📲"} ${device.model} (${device.id})`,
+    }));
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            devices: formattedDevices,
+            count: result.devices.length,
+            selectedDevice: result.selectedDevice,
+            message: `Found ${result.devices.length} device(s). Use select_device with a device ID to choose which device to run tests on.`,
+            usage: "Example: select_device with deviceId='emulator-5554'",
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    logger.error("List devices error", { error: error.message });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: false,
+            error: error.message,
+          }),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Select a device for running tests
+ */
+export async function selectDevice(deviceId) {
+  try {
+    if (!deviceId) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              error: "Device ID is required",
+              hint: "Use list_devices to see available devices and their IDs",
+            }),
+          },
+        ],
+      };
+    }
+
+    logger.info(`Selecting device: ${deviceId}`);
+
+    // Verify the device exists
+    const deviceList = await maestroListDevices();
+    if (!deviceList.success) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              error: "Could not verify device. " + deviceList.error,
+            }),
+          },
+        ],
+      };
+    }
+
+    const deviceExists = deviceList.devices.some((d) => d.id === deviceId);
+    if (!deviceExists) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              error: `Device "${deviceId}" not found`,
+              availableDevices: deviceList.devices.map((d) => d.id),
+              hint: "Use list_devices to see available devices",
+            }),
+          },
+        ],
+      };
+    }
+
+    // Select the device
+    const result = maestroSelectDevice(deviceId);
+    const selectedDeviceInfo = deviceList.devices.find((d) => d.id === deviceId);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            selectedDevice: deviceId,
+            deviceInfo: selectedDeviceInfo,
+            message: `Device "${deviceId}" selected. All tests will now run on this device.`,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    logger.error("Select device error", { error: error.message });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: false,
+            error: error.message,
+          }),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Clear device selection
+ */
+export async function clearDevice() {
+  try {
+    logger.info("Clearing device selection...");
+
+    const result = maestroClearDevice();
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            message: "Device selection cleared. Tests will run on the first available device.",
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    logger.error("Clear device error", { error: error.message });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: false,
+            error: error.message,
+          }),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Check device connection
+ */
+export async function checkDevice() {
+  try {
+    logger.info("Checking device connection...");
+
+    const deviceStatus = await checkDeviceConnection();
+
+    if (!deviceStatus.connected) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              connected: false,
+              error: deviceStatus.error,
+              hint:
+                deviceStatus.hint ||
+                "Start an Android emulator from Android Studio or connect a physical device.",
+              troubleshooting: [
+                "1. Open Android Studio → Tools → Device Manager",
+                "2. Start an emulator or connect a physical device via USB",
+                "3. Enable USB Debugging: Settings → Developer Options → USB Debugging",
+                "4. Run 'adb devices' to verify connection",
+                "5. Try 'adb kill-server && adb start-server' if issues persist",
+              ],
+            }),
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            connected: true,
+            devices: deviceStatus.devices,
+            activeDevice: deviceStatus.activeDevice,
+            selectedDevice: deviceStatus.selectedDevice,
+            message: `Found ${deviceStatus.devices.length} connected device(s). ${
+              deviceStatus.selectedDevice
+                ? `Using selected device: ${deviceStatus.selectedDevice}`
+                : "Using first available device."
+            }`,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    logger.error("Device check error", { error: error.message });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: false,
+            error: error.message,
+          }),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Check if app is installed
+ */
+export async function checkApp(appId = null) {
+  try {
+    const targetAppId = appId || process.env.APP_ID;
+
+    if (!targetAppId) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              error: "No APP_ID provided or configured",
+              hint: "Set APP_ID in .env file or pass appId parameter",
+            }),
+          },
+        ],
+      };
+    }
+
+    logger.info(`Checking if app is installed: ${targetAppId}`);
+
+    // First check device connection
+    const deviceStatus = await checkDeviceConnection();
+    if (!deviceStatus.connected) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              error: "No device connected. Cannot check app installation.",
+              hint: "Start an emulator or connect a device first.",
+            }),
+          },
+        ],
+      };
+    }
+
+    // Check app installation
+    const appStatus = await checkAppInstalled(targetAppId);
+
+    if (!appStatus.installed) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              installed: false,
+              appId: targetAppId,
+              device: appStatus.device,
+              error: appStatus.error,
+              hint:
+                appStatus.hint ||
+                "Install the app on the device before running tests.",
+            }),
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            installed: true,
+            appId: targetAppId,
+            device: appStatus.device,
+            message: `App "${targetAppId}" is installed and ready for testing.`,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    logger.error("App check error", { error: error.message });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: false,
+            error: error.message,
+          }),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Get test results
+ */
+export async function getTestResults(runId = null) {
+  try {
+    let resultsPath;
+
+    if (runId) {
+      resultsPath = join(RESULTS_DIR, `${runId}.json`);
+    } else {
+      resultsPath = join(RESULTS_DIR, "latest.json");
+    }
+
+    // Check if results file exists
+    try {
+      await fs.access(resultsPath);
+    } catch {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              error: runId
+                ? `Results not found for run: ${runId}`
+                : "No test results available. Run some tests first.",
+            }),
+          },
+        ],
+      };
+    }
+
+    const content = await fs.readFile(resultsPath, "utf8");
+    const results = JSON.parse(content);
+
+    logger.info("Test results retrieved", { runId: results.runId });
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            ...results,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    logger.error("Error getting test results", { error: error.message });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: false,
+            error: error.message,
+          }),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Take a screenshot
+ */
+export async function takeScreenshot(name) {
+  try {
+    logger.info(`Taking screenshot: ${name}`);
+
+    // Check device first
+    const deviceStatus = await checkDeviceConnection();
+    if (!deviceStatus.connected) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              error: "No device connected. Cannot take screenshot.",
+              hint: "Start an emulator or connect a device first.",
+            }),
+          },
+        ],
+      };
+    }
+
+    const screenshotPath = await maestroScreenshot(name);
+
+    if (screenshotPath) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: true,
+              path: screenshotPath,
+              message: `Screenshot saved: ${screenshotPath}`,
+            }),
+          },
+        ],
+      };
+    } else {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              error: "Failed to capture screenshot.",
+            }),
+          },
+        ],
+      };
+    }
+  } catch (error) {
+    logger.error("Screenshot error", { error: error.message });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: false,
+            error: error.message,
+          }),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Clean up old test results
+ */
+export async function cleanupResults(options = {}) {
+  try {
+    const maxResults = options.keepLast || getConfig().maxResults || 50;
+    const deleteScreenshots = options.deleteScreenshots !== false;
+
+    logger.info(`Cleaning up results, keeping last ${maxResults}`);
+
+    // Ensure directories exist
+    await fs.mkdir(RESULTS_DIR, { recursive: true });
+
+    // Get all result files
+    const files = await fs.readdir(RESULTS_DIR);
+    const resultFiles = files
+      .filter((f) => f.endsWith(".json") && f !== "latest.json")
+      .map((f) => ({
+        name: f,
+        path: join(RESULTS_DIR, f),
+      }));
+
+    // Get file stats and sort by modification time
+    const filesWithStats = await Promise.all(
+      resultFiles.map(async (file) => {
+        const stats = await fs.stat(file.path);
+        return { ...file, mtime: stats.mtime };
+      })
+    );
+
+    filesWithStats.sort((a, b) => b.mtime - a.mtime);
+
+    // Files to delete (older than maxResults)
+    const filesToDelete = filesWithStats.slice(maxResults);
+
+    let deletedResults = 0;
+    let deletedScreenshots = 0;
+
+    // Delete old result files
+    for (const file of filesToDelete) {
+      try {
+        await fs.unlink(file.path);
+        deletedResults++;
+        logger.info(`Deleted old result: ${file.name}`);
+      } catch (e) {
+        logger.warn(`Failed to delete: ${file.name}`);
+      }
+    }
+
+    // Optionally clean up screenshots older than 7 days
+    if (deleteScreenshots) {
+      try {
+        const screenshotFiles = await fs.readdir(SCREENSHOTS_DIR);
+        const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
+
+        for (const file of screenshotFiles) {
+          const filePath = join(SCREENSHOTS_DIR, file);
+          const stats = await fs.stat(filePath);
+
+          if (stats.mtime.getTime() < sevenDaysAgo) {
+            await fs.unlink(filePath);
+            deletedScreenshots++;
+          }
+        }
+      } catch (e) {
+        // Ignore screenshot cleanup errors
+      }
+    }
+
+    const message = [
+      `Cleanup complete.`,
+      deletedResults > 0
+        ? `Deleted ${deletedResults} old result file(s).`
+        : "No old results to delete.",
+      deletedScreenshots > 0
+        ? `Deleted ${deletedScreenshots} old screenshot(s).`
+        : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            deletedResults,
+            deletedScreenshots,
+            keptResults: Math.min(filesWithStats.length, maxResults),
+            message,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    logger.error("Cleanup error", { error: error.message });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: false,
+            error: error.message,
+          }),
+        },
+      ],
+    };
+  }
+}
+
+export default {
+  getAppConfig,
+  listDevices,
+  selectDevice,
+  clearDevice,
+  checkDevice,
+  checkApp,
+  getTestResults,
+  takeScreenshot,
+  cleanupResults,
+};