mcp-maestro-mobile-ai 1.1.1 → 1.3.1

package/CHANGELOG.md

@@ -15,6 +15,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.3.1] - 2025-01-06
+
+### Fixed
+- **MCP Schema Fix**: Fixed `generate_report` tool array parameter missing `items` definition
+  - This was causing "tool parameters array type must have items" validation error
+  - Now properly defines the structure of test result objects
+
+---
+
+## [1.2.0] - 2025-01-06
+
+### Added
+- **YAML Generation Instructions System**: Ensures consistent YAML generation across different environments
+  - `get_yaml_instructions` - AI MUST call this before generating YAML (provides exact rules)
+  - `validate_yaml_structure` - Validates YAML for common issues (like missing tapOn before inputText)
+  - `get_test_pattern` - Get standard patterns for login, search, navigation, form tests
+- **Critical Fix**: Input text pattern now enforced - prevents password going to username field issue
+- Standard test patterns for common scenarios (login, search, navigation, form)
+
+### Fixed
+- YAML generation inconsistency between different environments
+- Text input going to wrong fields due to missing tapOn commands
+
+---
+
+## [1.1.1] - 2025-01-06
+
+### Fixed
+- Version bump for npm publish
+
+---
+
 ## [1.1.0] - 2025-01-06
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mcp-maestro-mobile-ai",
-    "version": "1.1.1",
+    "version": "1.3.1",
     "private": false,
     "description": "MCP Server for AI-Assisted Mobile Automation using Maestro - Run mobile tests with natural language prompts",
     "main": "src/mcp-server/index.js",

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,6 +45,10 @@ import {
   getAppContext,
   clearContext,
   listContexts,
+  getYamlInstructions,
+  validateYamlBeforeRun,
+  getTestPattern,
+  getScreenAnalysis,
 } from "./tools/contextTools.js";
 import { logger } from "./utils/logger.js";
 import { validatePrerequisites } from "./utils/prerequisites.js";
@@ -58,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: {
@@ -180,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: {
@@ -196,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",
@@ -221,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: {
@@ -232,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",
@@ -253,7 +274,90 @@ 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",
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string", description: "Test name" },
+              success: { type: "boolean", description: "Whether the test passed" },
+              duration: { type: "number", description: "Test duration in milliseconds" },
+              error: { type: "string", description: "Error message if test failed" },
+            },
+            required: ["name", "success"],
+          },
+          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.",
@@ -458,6 +562,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: {},
+    },
+  },
 ];
 
 // ============================================
@@ -515,7 +675,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);
 
@@ -556,6 +732,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}`);
     }
@@ -612,7 +801,7 @@ 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

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

@@ -14,6 +14,13 @@ import {
   clearAppContext,
   listAppContexts,
 } from "../utils/appContext.js";
+import {
+  YAML_GENERATION_INSTRUCTIONS,
+  getYamlGenerationContext,
+  TEST_PATTERNS,
+  validateYamlStructure,
+  getScreenAnalysisInstructions,
+} from "../utils/yamlTemplate.js";
 
 /**
  * Format result as MCP response
@@ -180,6 +187,118 @@ export async function listContexts() {
   return formatResponse(result);
 }
 
+/**
+ * Get YAML generation instructions
+ * AI MUST call this before generating any Maestro YAML
+ */
+export async function getYamlInstructions(appId) {
+  if (!appId) {
+    // Return generic instructions without app context
+    return formatResponse({
+      success: true,
+      instructions: YAML_GENERATION_INSTRUCTIONS,
+      patterns: TEST_PATTERNS,
+      message: "Use these instructions when generating Maestro YAML. Always follow the tapOn → inputText pattern for text input.",
+    });
+  }
+
+  // Get app-specific context
+  const appContext = await loadAppContext(appId);
+  const instructions = getYamlGenerationContext(appId, appContext);
+
+  return formatResponse({
+    success: true,
+    appId,
+    instructions,
+    patterns: TEST_PATTERNS,
+    hasAppContext: Object.keys(appContext.elements || {}).length > 0,
+    message: "IMPORTANT: Follow these instructions EXACTLY when generating YAML. Always use tapOn before inputText.",
+  });
+}
+
+/**
+ * Validate YAML before running
+ * Checks for common issues like missing tapOn before inputText
+ */
+export async function validateYamlBeforeRun(yamlContent) {
+  if (!yamlContent) {
+    return formatResponse({
+      success: false,
+      error: "yamlContent is required",
+    });
+  }
+
+  const validation = validateYamlStructure(yamlContent);
+
+  if (!validation.valid) {
+    return formatResponse({
+      success: false,
+      valid: false,
+      issues: validation.issues,
+      message: "YAML has structural issues that may cause test failures. Please fix before running.",
+      fixedYaml: null, // Could auto-fix in future
+    });
+  }
+
+  return formatResponse({
+    success: true,
+    valid: true,
+    message: "YAML structure is valid.",
+  });
+}
+
+/**
+ * Get a test pattern template
+ */
+export async function getTestPattern(patternName) {
+  const patterns = {
+    login: TEST_PATTERNS.login,
+    search: TEST_PATTERNS.search,
+    navigation: TEST_PATTERNS.navigation,
+    form: TEST_PATTERNS.form,
+    list: TEST_PATTERNS.list,
+    settings: TEST_PATTERNS.settings,
+    logout: TEST_PATTERNS.logout,
+  };
+
+  const pattern = patterns[patternName?.toLowerCase()];
+
+  if (!pattern) {
+    return formatResponse({
+      success: false,
+      error: `Unknown pattern: ${patternName}`,
+      availablePatterns: Object.keys(patterns),
+      hint: "Use: login, form, search, navigation, list, settings, or logout",
+    });
+  }
+
+  return formatResponse({
+    success: true,
+    pattern: patternName,
+    template: pattern,
+    message: "Replace placeholders in {} with actual values. REMEMBER: Always use tapOn before inputText!",
+  });
+}
+
+/**
+ * Get screen analysis instructions
+ * Helps AI understand how to gather UI element information
+ */
+export async function getScreenAnalysis() {
+  const instructions = getScreenAnalysisInstructions();
+  
+  return formatResponse({
+    success: true,
+    instructions,
+    message: "Use these instructions to gather UI element information before generating YAML.",
+    requiredInfo: [
+      "Field labels/placeholders for text inputs",
+      "Button text for actions",
+      "Success/error indicators to verify results",
+    ],
+  });
+}
+
 export default {
   registerAppElements,
   registerAppScreen,
@@ -190,5 +309,9 @@ export default {
   getAppContext,
   clearContext,
   listContexts,
+  getYamlInstructions,
+  validateYamlBeforeRun,
+  getTestPattern,
+  getScreenAnalysis,
 };