mcp-maestro-mobile-ai 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -16,6 +16,104 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.6.0] - 2025-01-07
+
+### Added
+
+- **YAML Caching System**: Intelligent caching for faster recurring test execution
+
+  - `save_to_cache` - Save successful test YAML for future reuse
+  - `lookup_cache` - Check if a cached YAML exists for a prompt
+  - `list_cache` - List all cached tests with usage statistics
+  - `clear_cache` - Clear all cached YAMLs
+  - `delete_from_cache` - Delete specific cached test
+  - `get_cache_stats` - Get cache statistics (total cached, execution counts)
+  - `run_test_with_cache` - Run test with automatic cache lookup
+
+- **Prompt-Based Hashing**: Unique identification of test prompts
+  - SHA-256 based hashing with normalization
+  - Handles minor formatting differences (whitespace, quotes)
+  - AppId included in hash for app-specific caching
+
+- **Hidden Cache Storage**: Internal cache location (`~/.maestro-mcp/cache/`)
+  - Index file for fast lookup
+  - YAML files stored with hash-based names
+  - Not visible to end users
+
+- **Usage Statistics**: Track cache effectiveness
+  - Execution count per cached test
+  - Last used timestamp
+  - Most used tests identification
+
+- **Auto-Cache on Success**: After successful test execution
+  - Automatically saves YAML to cache (no user prompt needed)
+  - Failed tests are NOT cached (fix and re-run to cache)
+  - Automatic reuse when same prompt is run again
+
+### Changed
+
+- **Server Version**: Updated to v1.6.0
+- **runTest function**: Now includes cache prompt for successful tests
+- **runTestSuiteWithReport**: Offers bulk caching for successful tests
+
+### Benefits
+
+| Feature | Benefit |
+|---------|---------|
+| Faster Execution | Skip YAML generation for recurring tests |
+| Reduced AI Calls | Cached YAML reused automatically |
+| Clean Separation | Cache hidden from user-facing directories |
+| Smart Invalidation | New YAML generated if prompt changes |
+
+---
+
+## [1.5.0] - 2025-01-07
+
+### Added
+
+- **Prompt Analysis System (Action-Element-Verification Model)**: Intelligent prompt parsing for reliable YAML generation
+
+  - `validate_prompt` - PRIMARY tool for converting natural language to Maestro YAML
+  - `analyze_prompt` - Analyze prompts without generating YAML (debugging/inspection)
+  - Extracts: Actions, Elements, Values, Verifications, Sequence
+
+- **Tiered Clarification System**: Smart handling of incomplete prompts
+
+  - **COMPLETE**: All required info present → generates clean YAML
+  - **GENERATABLE**: Missing some info → asks clarification OR generates with warnings
+  - **NEEDS_CLARIFICATION**: Missing important info → asks specific questions
+  - **INSUFFICIENT**: Missing critical info (app ID) → requests minimum required info
+
+- **Force Generate with Warnings**: Option to generate YAML with assumptions
+  - Automatically adds warning comments for assumed values
+  - Lists all assumptions made during generation
+  - Placeholder values clearly marked for user to replace
+
+- **New Utilities**:
+  - `src/mcp-server/utils/promptAnalyzer.js` - Action-Element-Verification parser
+  - `src/mcp-server/utils/yamlGenerator.js` - YAML generation with warnings support
+  - `validateAndGenerate()` - Orchestrator function in contextTools.js
+
+- **Intelligent Clarification Questions**: Context-aware questions based on what's missing
+  - Critical questions (blocking): App ID
+  - Important questions: Field labels, button text
+  - Recommended questions: Verification elements, dropdown options
+
+### Changed
+
+- **Server Version**: Updated to v1.5.0
+- **Description**: Updated to highlight prompt analysis and tiered clarification
+- **Keywords**: Added `prompt-analysis`, `natural-language`, `yaml-generator`
+
+### Developer Experience
+
+- Generic, framework-agnostic approach works for ANY mobile app
+- No hard-coded app-specific values
+- Interaction patterns automatically applied
+- Comprehensive test script for verification
+
+---
+
 ## [1.4.0] - 2025-01-07
 
 ### Security
@@ -234,7 +332,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-[Unreleased]: https://github.com/krunal-mahera/mcp-maestro-mobile-ai/compare/v1.4.0...HEAD
+[Unreleased]: https://github.com/krunal-mahera/mcp-maestro-mobile-ai/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/krunal-mahera/mcp-maestro-mobile-ai/releases/tag/v1.6.0
+[1.5.0]: https://github.com/krunal-mahera/mcp-maestro-mobile-ai/releases/tag/v1.5.0
 [1.4.0]: https://github.com/krunal-mahera/mcp-maestro-mobile-ai/releases/tag/v1.4.0
 [1.3.1]: https://github.com/krunal-mahera/mcp-maestro-mobile-ai/releases/tag/v1.3.1
 [1.2.0]: https://github.com/krunal-mahera/mcp-maestro-mobile-ai/releases/tag/v1.2.0

package/package.json

@@ -1,8 +1,8 @@
 {
     "name": "mcp-maestro-mobile-ai",
-    "version": "1.4.0",
+    "version": "1.6.0",
     "private": false,
-    "description": "MCP Server for AI-Assisted Mobile Automation using Maestro - Run mobile tests with natural language prompts. Features enterprise-grade security with Safe Mode and input validation.",
+    "description": "MCP Server for AI-Assisted Mobile Automation using Maestro - Run mobile tests with natural language prompts. Features prompt analysis, tiered clarification, and enterprise-grade security.",
     "main": "src/mcp-server/index.js",
     "type": "module",
     "bin": {
@@ -54,7 +54,10 @@
         "ai",
         "security",
         "validation",
-        "zod"
+        "zod",
+        "prompt-analysis",
+        "natural-language",
+        "yaml-generator"
     ],
     "author": "Krunal Mahera <krunal.mahera@gmail.com>",
     "license": "MIT",

package/src/mcp-server/index.js

@@ -32,6 +32,14 @@ import {
   generateTestReport,
   listTestReports,
   runTestSuiteWithReport,
+  // Cache management
+  runTestWithCache,
+  saveTestToCache,
+  listCachedTests,
+  clearTestCache,
+  deleteCachedTest,
+  getTestCacheStats,
+  lookupCachedTest,
 } from "./tools/runTools.js";
 import {
   getAppConfig,
@@ -58,6 +66,13 @@ import {
   validateYamlBeforeRun,
   getTestPattern,
   getScreenAnalysis,
+  // Known Issues Tools
+  getKnownIssues,
+  getPlatformRules,
+  getGenerationRules,
+  // Prompt Analysis & Generation
+  validateAndGenerate,
+  analyzeTestPrompt,
 } from "./tools/contextTools.js";
 import { logger } from "./utils/logger.js";
 import { validatePrerequisites } from "./utils/prerequisites.js";
@@ -76,8 +91,8 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 config({ path: join(__dirname, "../../.env") });
 
-// Server version - updated for security features
-const SERVER_VERSION = "1.4.0";
+// Server version - updated for YAML caching features
+const SERVER_VERSION = "1.6.0";
 
 // Create MCP Server
 const server = new Server(
@@ -633,14 +648,14 @@ appId: com.example.app
   {
     name: "get_test_pattern",
     description:
-      "Get a standard test pattern template. Available: login, form, search, navigation, list, settings, logout. Use these as starting points.",
+      "Get a standard test pattern template. Available: login, form, search, navigation, list, settings, logout, dropdown, flutter_login_with_dropdown, flutter_multi_dropdown. Use these as starting points.",
     inputSchema: {
       type: "object",
       properties: {
         patternName: {
           type: "string",
           description:
-            "Pattern name: login, form, search, navigation, list, settings, or logout",
+            "Pattern name: login, form, search, navigation, list, settings, logout, dropdown, flutter_login_with_dropdown, or flutter_multi_dropdown",
           enum: [
             "login",
             "form",
@@ -649,6 +664,9 @@ appId: com.example.app
             "list",
             "settings",
             "logout",
+            "dropdown",
+            "flutter_login_with_dropdown",
+            "flutter_multi_dropdown",
           ],
         },
       },
@@ -664,6 +682,247 @@ appId: com.example.app
       properties: {},
     },
   },
+
+  // === Interaction Patterns & Generation Rules ===
+  {
+    name: "get_known_issues",
+    description:
+      "Get generic interaction patterns for reliable mobile test automation. These patterns are framework-agnostic and improve test reliability across all mobile apps. Optionally filter by category.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          description:
+            "Filter by category: keyboard_handling, element_interaction, timing_synchronization, input_handling, dropdown_picker, navigation, scroll_visibility, fallback_strategies",
+          enum: [
+            "keyboard_handling",
+            "element_interaction",
+            "timing_synchronization",
+            "input_handling",
+            "dropdown_picker",
+            "navigation",
+            "scroll_visibility",
+            "fallback_strategies",
+          ],
+        },
+      },
+    },
+  },
+  {
+    name: "get_platform_rules",
+    description:
+      "Get interaction patterns for a specific category. Use this to understand how to handle specific interaction types (keyboard, dropdowns, timing, etc.).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          description:
+            "Pattern category: keyboard_handling, element_interaction, timing_synchronization, input_handling, dropdown_picker, navigation, scroll_visibility, fallback_strategies",
+          enum: [
+            "keyboard_handling",
+            "element_interaction",
+            "timing_synchronization",
+            "input_handling",
+            "dropdown_picker",
+            "navigation",
+            "scroll_visibility",
+            "fallback_strategies",
+          ],
+        },
+      },
+      required: ["category"],
+    },
+  },
+  {
+    name: "get_generation_rules",
+    description:
+      "Get all YAML generation rules and best practices. These are framework-agnostic rules that improve test reliability across any mobile application.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+
+  // === Prompt Analysis & YAML Generation ===
+  {
+    name: "validate_prompt",
+    description: `Analyze a user's test description using the Action-Element-Verification model and generate Maestro YAML.
+
+This tool:
+1. Extracts ACTIONS (tap, input, scroll, select, verify...)
+2. Identifies ELEMENTS (button, field, dropdown, list, chart...)
+3. Finds VALUES (credentials, search terms, selections...)
+4. Detects VERIFICATIONS (visible, contains, success...)
+5. Assesses completeness and either:
+   - Generates clean YAML (if complete)
+   - Asks clarifying questions (if incomplete)
+   - Generates YAML with warnings (if forceGenerate=true)
+
+Use this as the PRIMARY tool for converting natural language test descriptions to Maestro YAML.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        userPrompt: {
+          type: "string",
+          description:
+            "Natural language test description. Example: 'Test login with username abc and password 1234 on com.example.app'",
+        },
+        appId: {
+          type: "string",
+          description:
+            "Optional app package ID. Provide if not included in the prompt.",
+        },
+        forceGenerate: {
+          type: "boolean",
+          description:
+            "If true, generate YAML with assumptions even if information is incomplete. Default: false",
+        },
+      },
+      required: ["userPrompt"],
+    },
+  },
+  {
+    name: "analyze_prompt",
+    description:
+      "Analyze a test prompt WITHOUT generating YAML. Returns detailed breakdown of detected actions, elements, values, and verifications. Use this to understand what the system can extract from a prompt.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        userPrompt: {
+          type: "string",
+          description: "The test description to analyze",
+        },
+        appId: {
+          type: "string",
+          description: "Optional app package ID for context",
+        },
+      },
+      required: ["userPrompt"],
+    },
+  },
+
+  // === YAML Cache Tools ===
+  {
+    name: "save_to_cache",
+    description:
+      "Save a successful test's YAML to cache for faster future execution. After a test passes, call this to store the YAML. When the same prompt is used again, the cached YAML will be reused automatically.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: {
+          type: "string",
+          description: "The original test prompt/description",
+        },
+        yaml: {
+          type: "string",
+          description: "The YAML content to cache",
+        },
+        testName: {
+          type: "string",
+          description: "Name of the test",
+        },
+        appId: {
+          type: "string",
+          description: "Optional app package ID",
+        },
+      },
+      required: ["prompt", "yaml", "testName"],
+    },
+  },
+  {
+    name: "lookup_cache",
+    description:
+      "Check if a YAML is cached for a given prompt. Returns the cached YAML if found, or indicates no cache exists.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: {
+          type: "string",
+          description: "The test prompt to look up",
+        },
+        appId: {
+          type: "string",
+          description: "Optional app package ID",
+        },
+      },
+      required: ["prompt"],
+    },
+  },
+  {
+    name: "list_cache",
+    description:
+      "List all cached test YAMLs. Shows test names, prompts, and usage statistics.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "clear_cache",
+    description:
+      "Clear all cached test YAMLs. After clearing, all tests will generate fresh YAML.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "delete_from_cache",
+    description:
+      "Delete a specific cached test by its hash. Use list_cache to find the hash.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        hash: {
+          type: "string",
+          description: "The cache hash to delete (from list_cache output)",
+        },
+      },
+      required: ["hash"],
+    },
+  },
+  {
+    name: "get_cache_stats",
+    description:
+      "Get cache statistics including total cached tests, execution counts, and most used tests.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "run_test_with_cache",
+    description:
+      "Run a test with automatic cache lookup. If a cached YAML exists for the prompt, it will be used. Otherwise, the provided YAML will be executed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: {
+          type: "string",
+          description: "The original test prompt - used for cache lookup",
+        },
+        yaml: {
+          type: "string",
+          description: "The YAML to use if not cached",
+        },
+        name: {
+          type: "string",
+          description: "Test name",
+        },
+        appId: {
+          type: "string",
+          description: "Optional app package ID",
+        },
+        retries: {
+          type: "number",
+          description: "Number of retries if test fails",
+        },
+      },
+      required: ["prompt", "yaml", "name"],
+    },
+  },
 ];
 
 // ============================================
@@ -917,6 +1176,82 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         result = await getScreenAnalysis();
         break;
 
+      // Known Issues & Platform Rules
+      case "get_known_issues":
+        result = await getKnownIssues(
+          validatedArgs.platform,
+          validatedArgs.category
+        );
+        break;
+
+      case "get_platform_rules":
+        result = await getPlatformRules(validatedArgs.category);
+        break;
+
+      case "get_generation_rules":
+        result = await getGenerationRules();
+        break;
+
+      // Prompt Analysis & YAML Generation
+      case "validate_prompt":
+        result = await validateAndGenerate(validatedArgs.userPrompt, {
+          appId: validatedArgs.appId,
+          forceGenerate: validatedArgs.forceGenerate,
+        });
+        break;
+
+      case "analyze_prompt":
+        result = await analyzeTestPrompt(
+          validatedArgs.userPrompt,
+          validatedArgs.appId
+        );
+        break;
+
+      // YAML Cache tools
+      case "save_to_cache":
+        result = await saveTestToCache(
+          validatedArgs.prompt,
+          validatedArgs.yaml,
+          validatedArgs.testName,
+          validatedArgs.appId
+        );
+        break;
+
+      case "lookup_cache":
+        result = await lookupCachedTest(
+          validatedArgs.prompt,
+          validatedArgs.appId
+        );
+        break;
+
+      case "list_cache":
+        result = await listCachedTests();
+        break;
+
+      case "clear_cache":
+        result = await clearTestCache();
+        break;
+
+      case "delete_from_cache":
+        result = await deleteCachedTest(validatedArgs.hash);
+        break;
+
+      case "get_cache_stats":
+        result = await getTestCacheStats();
+        break;
+
+      case "run_test_with_cache":
+        result = await runTestWithCache(
+          validatedArgs.prompt,
+          validatedArgs.yaml,
+          validatedArgs.name,
+          {
+            appId: validatedArgs.appId,
+            retries: validatedArgs.retries,
+          }
+        );
+        break;
+
       default:
         throw new Error(`Unknown tool: ${name}`);
     }