mcp-maestro-mobile-ai 1.1.0 → 1.3.0

package/scripts/check-prerequisites.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall Prerequisites Check
+ * 
+ * This script runs after npm install to warn users about missing prerequisites.
+ * It shows warnings but does NOT block installation.
+ */
+
+import { execSync } from "child_process";
+
+// ANSI color codes for terminal output
+const colors = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+};
+
+const icons = {
+  check: "✅",
+  cross: "❌",
+  warning: "⚠️",
+  info: "ℹ️",
+};
+
+/**
+ * Execute a command and return the output
+ */
+function execCommand(command) {
+  try {
+    return execSync(command, { 
+      encoding: "utf8", 
+      timeout: 10000,
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Parse version string to extract major version number
+ */
+function parseVersion(versionString) {
+  if (!versionString) return null;
+  const match = versionString.match(/(\d+)\.(\d+)/);
+  if (match) {
+    return {
+      major: parseInt(match[1], 10),
+      minor: parseInt(match[2], 10),
+      full: versionString,
+    };
+  }
+  return null;
+}
+
+/**
+ * Check Node.js version
+ */
+function checkNodeJs() {
+  const version = process.version;
+  const parsed = parseVersion(version);
+  
+  if (!parsed) {
+    return { 
+      installed: false, 
+      message: "Could not determine Node.js version" 
+    };
+  }
+
+  if (parsed.major >= 18) {
+    return { 
+      installed: true, 
+      version: version,
+      message: `Node.js ${version}` 
+    };
+  }
+
+  return { 
+    installed: true, 
+    version: version,
+    outdated: true,
+    message: `Node.js ${version} (requires 18+)` 
+  };
+}
+
+/**
+ * Check Java version
+ */
+function checkJava() {
+  // Try java --version first (Java 9+)
+  let output = execCommand("java --version");
+  
+  // Fall back to java -version (older format)
+  if (!output) {
+    output = execCommand("java -version 2>&1");
+  }
+
+  if (!output) {
+    return { 
+      installed: false, 
+      message: "Java not found",
+      hint: "Install Java 17+ from https://adoptium.net/"
+    };
+  }
+
+  // Parse Java version
+  const versionMatch = output.match(/(?:java|openjdk)\s+(?:version\s+)?["']?(\d+)(?:\.(\d+))?/i);
+  if (versionMatch) {
+    const major = parseInt(versionMatch[1], 10);
+    
+    if (major >= 17) {
+      return { 
+        installed: true, 
+        version: `${major}`,
+        message: `Java ${major}` 
+      };
+    }
+
+    return { 
+      installed: true, 
+      version: `${major}`,
+      outdated: true,
+      message: `Java ${major} (requires 17+)`,
+      hint: "Upgrade to Java 17+ from https://adoptium.net/"
+    };
+  }
+
+  return { 
+    installed: true, 
+    message: "Java (version unknown)" 
+  };
+}
+
+/**
+ * Check Maestro CLI
+ */
+function checkMaestro() {
+  const output = execCommand("maestro --version");
+
+  if (!output) {
+    return { 
+      installed: false, 
+      message: "Maestro CLI not found",
+      hint: "Install: curl -Ls https://get.maestro.mobile.dev | bash"
+    };
+  }
+
+  return { 
+    installed: true, 
+    version: output,
+    message: `Maestro ${output}` 
+  };
+}
+
+/**
+ * Check Android SDK / ADB
+ */
+function checkAndroidSdk() {
+  const androidHome = process.env.ANDROID_HOME;
+  
+  if (!androidHome) {
+    return { 
+      installed: false, 
+      message: "ANDROID_HOME not set",
+      hint: "Set ANDROID_HOME environment variable to your Android SDK path"
+    };
+  }
+
+  // Check if ADB exists
+  const adbOutput = execCommand("adb --version");
+  
+  if (!adbOutput) {
+    return { 
+      installed: true, 
+      message: "ANDROID_HOME set but ADB not in PATH",
+      hint: "Add Android SDK platform-tools to your PATH"
+    };
+  }
+
+  return { 
+    installed: true, 
+    message: `Android SDK (${androidHome.length > 40 ? "..." + androidHome.slice(-37) : androidHome})` 
+  };
+}
+
+/**
+ * Main check function
+ */
+function runChecks() {
+  console.log("");
+  console.log(`${colors.cyan}${colors.bright}╔════════════════════════════════════════════════════════╗${colors.reset}`);
+  console.log(`${colors.cyan}${colors.bright}║        MCP Maestro Mobile AI - Prerequisites          ║${colors.reset}`);
+  console.log(`${colors.cyan}${colors.bright}╚════════════════════════════════════════════════════════╝${colors.reset}`);
+  console.log("");
+
+  const checks = [
+    { name: "Node.js 18+", check: checkNodeJs, required: true },
+    { name: "Java 17+", check: checkJava, required: true },
+    { name: "Maestro CLI", check: checkMaestro, required: true },
+    { name: "Android SDK", check: checkAndroidSdk, required: false },
+  ];
+
+  const results = [];
+  let hasErrors = false;
+  let hasWarnings = false;
+
+  for (const item of checks) {
+    const result = item.check();
+    results.push({ ...item, result });
+
+    let icon, color;
+    
+    if (result.installed && !result.outdated) {
+      icon = icons.check;
+      color = colors.green;
+    } else if (result.outdated) {
+      icon = icons.warning;
+      color = colors.yellow;
+      hasWarnings = true;
+      if (item.required) hasErrors = true;
+    } else {
+      icon = item.required ? icons.cross : icons.warning;
+      color = item.required ? colors.red : colors.yellow;
+      if (item.required) {
+        hasErrors = true;
+      } else {
+        hasWarnings = true;
+      }
+    }
+
+    console.log(`  ${icon} ${color}${result.message}${colors.reset}`);
+  }
+
+  console.log("");
+
+  // Show hints for missing/outdated items
+  const hints = results
+    .filter(r => r.result.hint)
+    .map(r => r.result.hint);
+
+  if (hints.length > 0) {
+    console.log(`${colors.yellow}${icons.info} Installation hints:${colors.reset}`);
+    hints.forEach(hint => {
+      console.log(`   ${colors.yellow}→ ${hint}${colors.reset}`);
+    });
+    console.log("");
+  }
+
+  // Summary
+  if (hasErrors) {
+    console.log(`${colors.red}${colors.bright}⚠️  Some required prerequisites are missing.${colors.reset}`);
+    console.log(`${colors.red}   The server will not start without them.${colors.reset}`);
+    console.log("");
+  } else if (hasWarnings) {
+    console.log(`${colors.yellow}${colors.bright}${icons.warning} Some optional prerequisites are missing.${colors.reset}`);
+    console.log(`${colors.yellow}   The server may have limited functionality.${colors.reset}`);
+    console.log("");
+  } else {
+    console.log(`${colors.green}${colors.bright}${icons.check} All prerequisites satisfied!${colors.reset}`);
+    console.log("");
+  }
+
+  console.log(`${colors.cyan}Documentation: https://github.com/krunal-mahera/mcp-maestro-mobile-ai${colors.reset}`);
+  console.log("");
+
+  // Note: We do NOT exit with error code - this is just a warning
+  // The actual validation happens at runtime
+}
+
+// Run checks
+runChecks();
+

package/src/mcp-server/index.js

@@ -23,7 +23,7 @@ import { dirname, join } from "path";
 // Import tools
 import { readPromptFile, listPromptFiles } from "./tools/promptTools.js";
 import { validateMaestroYaml } from "./tools/validateTools.js";
-import { runTest, runTestSuite } from "./tools/runTools.js";
+import { runTest, runTestSuite, generateTestReport, listTestReports, runTestSuiteWithReport } from "./tools/runTools.js";
 import {
   getAppConfig,
   getTestResults,
@@ -45,8 +45,13 @@ import {
   getAppContext,
   clearContext,
   listContexts,
+  getYamlInstructions,
+  validateYamlBeforeRun,
+  getTestPattern,
+  getScreenAnalysis,
 } from "./tools/contextTools.js";
 import { logger } from "./utils/logger.js";
+import { validatePrerequisites } from "./utils/prerequisites.js";
 
 // Load environment variables
 const __filename = fileURLToPath(import.meta.url);
@@ -57,7 +62,7 @@ config({ path: join(__dirname, "../../.env") });
 const server = new Server(
   {
     name: "mcp-maestro-mobile-ai",
-    version: "1.1.0",
+    version: "1.2.0",
   },
   {
     capabilities: {
@@ -179,7 +184,7 @@ const TOOLS = [
   {
     name: "validate_maestro_yaml",
     description:
-      "Validate a Maestro YAML flow for syntax errors before running. Returns validation result with any errors found.",
+      "Validate Maestro YAML for syntax AND structure errors. Checks for: missing appId, missing clearState/launchApp, inputText without tapOn (which causes text to go to wrong fields). Always validate before running!",
     inputSchema: {
       type: "object",
       properties: {
@@ -195,14 +200,31 @@ const TOOLS = [
   // === Test Execution Tools ===
   {
     name: "run_test",
-    description:
-      "Run a single Maestro test. Provide the Maestro YAML content directly. The test will be executed on the selected device (or first available if none selected). Includes pre-flight checks and auto-retry.",
+    description: `Run a single Maestro test. IMPORTANT: The YAML MUST follow these rules or it will be REJECTED:
+
+1. STRUCTURE: Must start with appId, then clearState, then launchApp
+2. TEXT INPUT: ALWAYS use tapOn BEFORE inputText (or text goes to wrong field!)
+   CORRECT: - tapOn: "Username"  then  - inputText: "value"
+   WRONG: - inputText: "value" (missing tapOn!)
+3. Use visible text labels for elements when testIDs are unknown
+
+Example valid YAML:
+appId: com.example.app
+---
+- clearState
+- launchApp
+- tapOn: "Username"
+- inputText: "user@example.com"
+- tapOn: "Password"
+- inputText: "password123"
+- tapOn: "Sign In"
+- assertVisible: "Welcome"`,
     inputSchema: {
       type: "object",
       properties: {
         yaml: {
           type: "string",
-          description: "The Maestro YAML flow content to run",
+          description: "The Maestro YAML flow content. MUST use tapOn before inputText for each field!",
         },
         name: {
           type: "string",
@@ -220,7 +242,7 @@ const TOOLS = [
   {
     name: "run_test_suite",
     description:
-      "Run multiple Maestro tests in sequence. Provide an array of test objects with yaml and name properties. Tests run on selected device.",
+      "Run multiple Maestro tests in sequence. Each YAML must follow the rules: appId at top, clearState, launchApp, and ALWAYS tapOn before inputText!",
     inputSchema: {
       type: "object",
       properties: {
@@ -231,7 +253,7 @@ const TOOLS = [
             properties: {
               yaml: {
                 type: "string",
-                description: "The Maestro YAML flow content",
+                description: "The Maestro YAML. MUST use tapOn before inputText!",
               },
               name: {
                 type: "string",
@@ -252,7 +274,80 @@ const TOOLS = [
     },
   },
 
-  // === Results & Utility Tools ===
+  // === Results & Reporting Tools ===
+  {
+    name: "run_tests_with_report",
+    description:
+      "Run multiple tests and automatically generate HTML + JSON report. Use this when running tests from a prompt file. Returns report path that can be opened in browser.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tests: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              yaml: {
+                type: "string",
+                description: "The Maestro YAML. MUST use tapOn before inputText!",
+              },
+              name: {
+                type: "string",
+                description: "Name for this test",
+              },
+            },
+            required: ["yaml", "name"],
+          },
+          description: "Array of tests to run",
+        },
+        promptFile: {
+          type: "string",
+          description: "Name of the prompt file (for report metadata)",
+        },
+        appId: {
+          type: "string",
+          description: "App ID (for report metadata)",
+        },
+        retries: {
+          type: "number",
+          description: "Number of retries for failed tests",
+        },
+      },
+      required: ["tests"],
+    },
+  },
+  {
+    name: "generate_report",
+    description:
+      "Generate HTML and JSON report from test results. Call this after running tests to create a visual summary report.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        results: {
+          type: "array",
+          description: "Array of test results with name, success, duration, error fields",
+        },
+        promptFile: {
+          type: "string",
+          description: "Name of the prompt file",
+        },
+        appId: {
+          type: "string",
+          description: "App ID",
+        },
+      },
+      required: ["results"],
+    },
+  },
+  {
+    name: "list_reports",
+    description:
+      "List all generated test reports. Returns paths to HTML and JSON report files.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
   {
     name: "get_test_results",
     description: "Get the results from the last test run or a specific run by ID.",
@@ -457,6 +552,62 @@ const TOOLS = [
       properties: {},
     },
   },
+
+  // === YAML Generation Tools (CRITICAL) ===
+  {
+    name: "get_yaml_instructions",
+    description:
+      "CRITICAL: Call this BEFORE generating any Maestro YAML. Returns the exact rules and patterns for generating valid YAML that works consistently. Includes app-specific context if available.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: {
+          type: "string",
+          description: "App package ID to get app-specific context",
+        },
+      },
+    },
+  },
+  {
+    name: "validate_yaml_structure",
+    description:
+      "Validate YAML structure before running a test. Checks for common issues like missing 'tapOn' before 'inputText' which causes text to go to wrong fields.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        yamlContent: {
+          type: "string",
+          description: "The Maestro YAML content to validate",
+        },
+      },
+      required: ["yamlContent"],
+    },
+  },
+  {
+    name: "get_test_pattern",
+    description:
+      "Get a standard test pattern template. Available: login, form, search, navigation, list, settings, logout. Use these as starting points.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        patternName: {
+          type: "string",
+          description: "Pattern name: login, form, search, navigation, list, settings, or logout",
+          enum: ["login", "form", "search", "navigation", "list", "settings", "logout"],
+        },
+      },
+      required: ["patternName"],
+    },
+  },
+  {
+    name: "get_screen_analysis_help",
+    description:
+      "Get instructions on how to gather UI element information from the user. Call this when you don't know the exact element names/labels on a screen. Returns questions to ask the user.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
 ];
 
 // ============================================
@@ -514,7 +665,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case "run_test_suite":
         return await runTestSuite(args.tests, { retries: args.retries });
 
-      // Results & utility tools
+      // Results & reporting tools
+      case "run_tests_with_report":
+        return await runTestSuiteWithReport(args.tests, {
+          promptFile: args.promptFile,
+          appId: args.appId,
+          retries: args.retries,
+        });
+
+      case "generate_report":
+        return await generateTestReport(args.results, {
+          promptFile: args.promptFile,
+          appId: args.appId,
+        });
+
+      case "list_reports":
+        return await listTestReports();
+
       case "get_test_results":
         return await getTestResults(args.runId);
 
@@ -555,6 +722,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case "list_app_contexts":
         return await listContexts();
 
+      // YAML generation tools
+      case "get_yaml_instructions":
+        return await getYamlInstructions(args.appId);
+
+      case "validate_yaml_structure":
+        return await validateYamlBeforeRun(args.yamlContent);
+
+      case "get_test_pattern":
+        return await getTestPattern(args.patternName);
+
+      case "get_screen_analysis_help":
+        return await getScreenAnalysis();
+
       default:
         throw new Error(`Unknown tool: ${name}`);
     }
@@ -611,7 +791,18 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 // ============================================
 
 async function main() {
-  logger.info("Starting MCP Maestro Mobile AI v1.1.0...");
+  logger.info("Starting MCP Maestro Mobile AI v1.2.0...");
+  logger.info("");
+
+  // Validate prerequisites before starting
+  // This will exit with code 2 if critical prerequisites are missing
+  await validatePrerequisites({
+    exitOnError: true,
+    checkDevice: false, // Don't require device at startup
+  });
+
+  logger.info("");
+  logger.info("Prerequisites validated. Starting server...");
 
   const transport = new StdioServerTransport();
   await server.connect(transport);