mcp-maestro-mobile-ai 1.4.0 → 1.6.0

package/src/mcp-server/schemas/toolSchemas.js

@@ -442,6 +442,9 @@ const validPatternNames = [
   "list",
   "settings",
   "logout",
+  "dropdown",
+  "flutter_login_with_dropdown",
+  "flutter_multi_dropdown",
 ];
 
 /**
@@ -460,6 +463,156 @@ export const getTestPatternSchema = z.object({
  */
 export const getScreenAnalysisHelpSchema = z.object({});
 
+/**
+ * Valid pattern categories
+ */
+const validPatternCategories = [
+  "keyboard_handling",
+  "element_interaction",
+  "timing_synchronization",
+  "input_handling",
+  "dropdown_picker",
+  "navigation",
+  "scroll_visibility",
+  "fallback_strategies",
+];
+
+/**
+ * Schema for get_interaction_patterns tool
+ */
+export const getKnownIssuesSchema = z.object({
+  category: z.enum(validPatternCategories).optional().describe("Filter patterns by category"),
+});
+
+/**
+ * Schema for get_patterns_by_category tool
+ */
+export const getPlatformRulesSchema = z.object({
+  category: z.enum(validPatternCategories, {
+    errorMap: () => ({
+      message: `Category must be one of: ${validPatternCategories.join(", ")}`,
+    }),
+  }),
+});
+
+/**
+ * Schema for get_generation_rules tool (no params)
+ */
+export const getGenerationRulesSchema = z.object({});
+
+// ============================================
+// PROMPT ANALYSIS & VALIDATION SCHEMAS
+// ============================================
+
+/**
+ * Schema for validate_prompt tool
+ * Analyzes user prompt using Action-Element-Verification model
+ */
+export const validatePromptSchema = z.object({
+  userPrompt: z
+    .string()
+    .min(5, "Prompt too short - provide a test description")
+    .max(5000, "Prompt too long"),
+  appId: z
+    .string()
+    .max(150, "App ID too long")
+    .regex(appIdPattern, "Invalid app ID format")
+    .optional()
+    .describe("Optional app package ID. If not in prompt, must be provided here."),
+  forceGenerate: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("If true, generate YAML with assumptions even if information is incomplete."),
+});
+
+/**
+ * Schema for analyze_prompt tool
+ * Analyzes prompt without generating YAML
+ */
+export const analyzePromptSchema = z.object({
+  userPrompt: z
+    .string()
+    .min(5, "Prompt too short")
+    .max(5000, "Prompt too long"),
+  appId: z
+    .string()
+    .max(150)
+    .regex(appIdPattern, "Invalid app ID format")
+    .optional(),
+});
+
+// ============================================
+// YAML CACHE SCHEMAS
+// ============================================
+
+/**
+ * Schema for save_to_cache tool
+ */
+export const saveToCacheSchema = z.object({
+  prompt: z
+    .string()
+    .min(5, "Prompt too short")
+    .max(5000, "Prompt too long")
+    .describe("The original test prompt/description"),
+  yaml: yamlContentSchema.describe("The YAML content to cache"),
+  testName: testNameSchema.describe("Name of the test"),
+  appId: optionalAppIdSchema,
+});
+
+/**
+ * Schema for lookup_cache tool
+ */
+export const lookupCacheSchema = z.object({
+  prompt: z
+    .string()
+    .min(5, "Prompt too short")
+    .max(5000, "Prompt too long")
+    .describe("The test prompt to look up in cache"),
+  appId: optionalAppIdSchema,
+});
+
+/**
+ * Schema for delete_from_cache tool
+ */
+export const deleteFromCacheSchema = z.object({
+  hash: z
+    .string()
+    .min(8, "Hash too short")
+    .max(64, "Hash too long")
+    .describe("The cache hash to delete (from list_cache output)"),
+});
+
+/**
+ * Schema for list_cache tool (no params)
+ */
+export const listCacheSchema = z.object({});
+
+/**
+ * Schema for clear_cache tool (no params)
+ */
+export const clearCacheSchema = z.object({});
+
+/**
+ * Schema for get_cache_stats tool (no params)
+ */
+export const getCacheStatsSchema = z.object({});
+
+/**
+ * Schema for run_test_with_cache tool
+ */
+export const runTestWithCacheSchema = z.object({
+  prompt: z
+    .string()
+    .min(5)
+    .max(5000)
+    .describe("The original test prompt - used for cache lookup"),
+  yaml: yamlContentSchema.describe("The YAML to use if not cached"),
+  name: testNameSchema,
+  appId: optionalAppIdSchema,
+  retries: retriesSchema,
+});
+
 // ============================================
 // SCHEMA REGISTRY
 // ============================================
@@ -513,6 +666,24 @@ export const toolSchemas = {
   validate_yaml_structure: validateYamlStructureSchema,
   get_test_pattern: getTestPatternSchema,
   get_screen_analysis_help: getScreenAnalysisHelpSchema,
+  
+  // Known Issues & Platform Rules
+  get_known_issues: getKnownIssuesSchema,
+  get_platform_rules: getPlatformRulesSchema,
+  get_generation_rules: getGenerationRulesSchema,
+  
+  // Prompt Analysis & Validation
+  validate_prompt: validatePromptSchema,
+  analyze_prompt: analyzePromptSchema,
+  
+  // YAML Cache
+  save_to_cache: saveToCacheSchema,
+  lookup_cache: lookupCacheSchema,
+  delete_from_cache: deleteFromCacheSchema,
+  list_cache: listCacheSchema,
+  clear_cache: clearCacheSchema,
+  get_cache_stats: getCacheStatsSchema,
+  run_test_with_cache: runTestWithCacheSchema,
 };
 
 // ============================================
@@ -633,4 +804,17 @@ export default {
   validateYamlStructureSchema,
   getTestPatternSchema,
   getScreenAnalysisHelpSchema,
+  
+  // Prompt Analysis & Validation
+  validatePromptSchema,
+  analyzePromptSchema,
+  
+  // YAML Cache
+  saveToCacheSchema,
+  lookupCacheSchema,
+  deleteFromCacheSchema,
+  listCacheSchema,
+  clearCacheSchema,
+  getCacheStatsSchema,
+  runTestWithCacheSchema,
 };

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

@@ -20,7 +20,26 @@ import {
   TEST_PATTERNS,
   validateYamlStructure,
   getScreenAnalysisInstructions,
+  getInteractionPatternHints,
+  getYamlGenerationRules,
+  getBestPractices,
+  PatternCategory,
 } from "../utils/yamlTemplate.js";
+import {
+  INTERACTION_PATTERNS,
+  getPatternsByCategory,
+  getPatternCategories,
+} from "../utils/knownIssues.js";
+import {
+  analyzePrompt,
+  generateClarificationQuestions,
+  generateWarnings,
+  CompletenessLevel,
+} from "../utils/promptAnalyzer.js";
+import {
+  generateYamlFromAnalysis,
+  formatGenerationResponse,
+} from "../utils/yamlGenerator.js";
 
 /**
  * Format result as MCP response
@@ -259,6 +278,9 @@ export async function getTestPattern(patternName) {
     list: TEST_PATTERNS.list,
     settings: TEST_PATTERNS.settings,
     logout: TEST_PATTERNS.logout,
+    dropdown: TEST_PATTERNS.dropdown,
+    flutter_login_with_dropdown: TEST_PATTERNS.flutter_login_with_dropdown,
+    flutter_multi_dropdown: TEST_PATTERNS.flutter_multi_dropdown,
   };
 
   const pattern = patterns[patternName?.toLowerCase()];
@@ -268,7 +290,7 @@ export async function getTestPattern(patternName) {
       success: false,
       error: `Unknown pattern: ${patternName}`,
       availablePatterns: Object.keys(patterns),
-      hint: "Use: login, form, search, navigation, list, settings, or logout",
+      hint: "Use: login, form, search, navigation, list, settings, logout, dropdown, flutter_login_with_dropdown, or flutter_multi_dropdown",
     });
   }
 
@@ -276,7 +298,7 @@ export async function getTestPattern(patternName) {
     success: true,
     pattern: patternName,
     template: pattern,
-    message: "Replace placeholders in {} with actual values. REMEMBER: Always use tapOn before inputText!",
+    message: "Replace placeholders in {} with actual values. REMEMBER: Always use tapOn before inputText! For dropdowns: hideKeyboard -> tapCurrentValue -> waitForAnimationToEnd -> tapDesiredValue",
   });
 }
 
@@ -299,6 +321,284 @@ export async function getScreenAnalysis() {
   });
 }
 
+/**
+ * Get interaction patterns for reliable YAML generation
+ * These patterns are framework-agnostic and work across all mobile apps.
+ */
+export async function getKnownIssues(category = null) {
+  let patterns = INTERACTION_PATTERNS;
+  
+  if (category) {
+    patterns = getPatternsByCategory(category);
+  }
+  
+  // Format patterns for display
+  const formattedPatterns = Object.entries(patterns).map(([key, pattern]) => ({
+    name: key,
+    category: pattern.category,
+    situation: pattern.situation,
+    strategy: pattern.strategy,
+    rationale: pattern.rationale,
+  }));
+  
+  return formatResponse({
+    success: true,
+    count: formattedPatterns.length,
+    patterns: formattedPatterns,
+    availableCategories: getPatternCategories(),
+    message: "These patterns are automatically included in YAML generation. Apply them to create reliable tests.",
+  });
+}
+
+/**
+ * Get interaction patterns by category
+ */
+export async function getPlatformRules(category) {
+  const validCategories = getPatternCategories();
+  
+  if (!category || !validCategories.includes(category)) {
+    return formatResponse({
+      success: false,
+      error: `Invalid category: ${category}`,
+      validCategories,
+      hint: "Use: keyboard_handling, element_interaction, timing_synchronization, input_handling, dropdown_picker, navigation, scroll_visibility, or fallback_strategies",
+    });
+  }
+  
+  const patterns = getPatternsByCategory(category);
+  
+  return formatResponse({
+    success: true,
+    category,
+    patterns: Object.entries(patterns).map(([key, p]) => ({
+      name: key,
+      situation: p.situation,
+      strategy: p.strategy,
+      yamlPattern: p.yamlPattern,
+    })),
+    message: "Apply these patterns for the specified interaction type.",
+  });
+}
+
+/**
+ * Get all YAML generation rules and best practices
+ */
+export async function getGenerationRules() {
+  const rules = getYamlGenerationRules();
+  const hints = getInteractionPatternHints();
+  const bestPractices = getBestPractices();
+  
+  return formatResponse({
+    success: true,
+    rules,
+    hints,
+    bestPractices,
+    message: "These rules are automatically applied during YAML generation. They are framework-agnostic and improve test reliability.",
+  });
+}
+
+/**
+ * Validate and analyze user prompt for YAML generation
+ * Uses Action-Element-Verification model for generic prompt analysis
+ * 
+ * @param {string} userPrompt - The user's test description
+ * @param {object} options - Options: appId, forceGenerate
+ * @returns {object} Analysis result with YAML or clarification questions
+ */
+export async function validateAndGenerate(userPrompt, options = {}) {
+  const { appId = null, forceGenerate = false } = options;
+  
+  if (!userPrompt || typeof userPrompt !== 'string' || userPrompt.trim().length < 5) {
+    return formatResponse({
+      success: false,
+      error: "Prompt is too short or empty",
+      hint: "Provide a description of the test you want to create. Example: 'Test login with username abc and password 1234'",
+    });
+  }
+  
+  // Step 1: Analyze the prompt
+  const analysis = analyzePrompt(userPrompt, { appId });
+  
+  // Step 2: Check completeness level
+  const { assessment, extracted } = analysis;
+  
+  // INSUFFICIENT: Cannot proceed without critical info
+  if (assessment.level === CompletenessLevel.INSUFFICIENT) {
+    const questions = generateClarificationQuestions(analysis);
+    const criticalQuestions = questions.filter(q => q.priority === 'critical');
+    
+    return formatResponse({
+      success: false,
+      status: 'insufficient',
+      message: 'Cannot generate YAML: missing required information',
+      understood: {
+        appContext: extracted.appContext,
+        detectedActions: extracted.actions.map(a => a.type),
+        detectedElements: extracted.elements.map(e => e.type),
+        valuesFound: Object.keys(extracted.values),
+      },
+      requiredInfo: criticalQuestions.map(q => ({
+        field: q.field,
+        question: q.question,
+      })),
+      hint: 'Please provide at least the app ID (package name) to continue.',
+    });
+  }
+  
+  // NEEDS_CLARIFICATION: Should ask, but can force generate
+  if (assessment.level === CompletenessLevel.NEEDS_CLARIFICATION && !forceGenerate) {
+    const questions = generateClarificationQuestions(analysis);
+    
+    return formatResponse({
+      success: false,
+      status: 'needs_clarification',
+      message: 'Additional information recommended for reliable test generation',
+      completenessScore: assessment.score,
+      understood: {
+        appId: extracted.appContext.appId,
+        appName: extracted.appContext.appName,
+        detectedActions: extracted.actions.map(a => ({ type: a.type, context: a.context })),
+        detectedElements: extracted.elements.map(e => ({ type: e.type, label: e.label })),
+        valuesFound: extracted.values,
+        verifications: extracted.verifications.map(v => ({ type: v.type, target: v.target })),
+      },
+      questions: questions.map(q => ({
+        priority: q.priority,
+        field: q.field,
+        question: q.question,
+        required: q.required,
+        default: q.default,
+      })),
+      canForceGenerate: true,
+      hint: 'Answer the questions for better accuracy, or use forceGenerate: true to proceed with assumptions.',
+    });
+  }
+  
+  // GENERATABLE: Can generate with assumptions (if forceGenerate is true)
+  // or ask for clarification
+  if (assessment.level === CompletenessLevel.GENERATABLE && !forceGenerate) {
+    const questions = generateClarificationQuestions(analysis);
+    const recommendedQuestions = questions.filter(q => q.priority === 'recommended');
+    
+    return formatResponse({
+      success: false,
+      status: 'can_improve',
+      message: 'Prompt understood, but additional details would improve test reliability',
+      completenessScore: assessment.score,
+      understood: {
+        appId: extracted.appContext.appId,
+        detectedActions: extracted.actions.map(a => ({ type: a.type, context: a.context })),
+        detectedElements: extracted.elements.map(e => ({ type: e.type, label: e.label })),
+        valuesFound: extracted.values,
+      },
+      recommendations: recommendedQuestions.map(q => ({
+        field: q.field,
+        question: q.question,
+        default: q.default,
+      })),
+      assumptionsIfForced: assessment.assumptions,
+      canForceGenerate: true,
+      hint: 'Provide additional details or use forceGenerate: true to generate with assumptions.',
+    });
+  }
+  
+  // COMPLETE or forceGenerate: Generate YAML
+  const result = generateYamlFromAnalysis(analysis, {
+    forceGenerate,
+    includeComments: true,
+    appId: appId || extracted.appContext.appId,
+  });
+  
+  if (!result.success) {
+    return formatResponse({
+      success: false,
+      error: result.error,
+      missing: result.missing,
+    });
+  }
+  
+  // Generate warnings if force generated
+  const warnings = forceGenerate && assessment.level !== CompletenessLevel.COMPLETE
+    ? generateWarnings(analysis)
+    : [];
+  
+  return formatResponse({
+    success: true,
+    status: result.forceGenerated ? 'generated_with_warnings' : 'generated',
+    message: result.forceGenerated
+      ? 'YAML generated with assumptions. Review and update placeholders before running.'
+      : 'YAML generated successfully.',
+    yaml: result.yaml,
+    completenessScore: result.completenessScore,
+    forceGenerated: result.forceGenerated || false,
+    warnings: [
+      ...result.warnings,
+      ...warnings.map(w => w.message),
+    ],
+    assumptions: result.assumptions,
+    analysis: {
+      detectedActions: extracted.actions.length,
+      detectedElements: extracted.elements.length,
+      valuesFound: Object.keys(extracted.values).length,
+      verifications: extracted.verifications.length,
+    },
+  });
+}
+
+/**
+ * Analyze prompt without generating YAML
+ * Useful for understanding what the system detected
+ */
+export async function analyzeTestPrompt(userPrompt, appId = null) {
+  if (!userPrompt || typeof userPrompt !== 'string') {
+    return formatResponse({
+      success: false,
+      error: "Invalid prompt",
+    });
+  }
+  
+  const analysis = analyzePrompt(userPrompt, { appId });
+  const { extracted, assessment } = analysis;
+  const questions = generateClarificationQuestions(analysis);
+  
+  return formatResponse({
+    success: true,
+    analysis: {
+      appContext: extracted.appContext,
+      actions: extracted.actions.map(a => ({
+        type: a.type,
+        keyword: a.keyword,
+        context: a.context,
+      })),
+      elements: extracted.elements.map(e => ({
+        type: e.type,
+        label: e.label,
+        keyword: e.keyword,
+      })),
+      values: extracted.values,
+      verifications: extracted.verifications.map(v => ({
+        type: v.type,
+        target: v.target,
+      })),
+      sequence: extracted.sequence,
+    },
+    assessment: {
+      level: assessment.level,
+      score: assessment.score,
+      issues: assessment.issues,
+      missing: assessment.missing,
+      assumptions: assessment.assumptions,
+      canForceGenerate: assessment.canForceGenerate,
+    },
+    clarificationQuestions: questions.map(q => ({
+      priority: q.priority,
+      field: q.field,
+      question: q.question,
+      required: q.required,
+    })),
+  });
+}
+
 export default {
   registerAppElements,
   registerAppScreen,
@@ -313,5 +613,12 @@ export default {
   validateYamlBeforeRun,
   getTestPattern,
   getScreenAnalysis,
+  // Known Issues Tools
+  getKnownIssues,
+  getPlatformRules,
+  getGenerationRules,
+  // Prompt Analysis & Generation
+  validateAndGenerate,
+  analyzeTestPrompt,
 };