mcp-maestro-mobile-ai 1.3.1 → 1.6.0

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

@@ -0,0 +1,820 @@
+/**
+ * Zod Schemas for MCP Tool Input Validation
+ *
+ * This module provides strict input validation for all MCP tools
+ * using Zod schemas. These schemas are used to validate inputs
+ * before tool execution for security and data integrity.
+ *
+ * @module toolSchemas
+ * @version 1.0.0
+ */
+
+import { z } from "zod";
+
+// ============================================
+// COMMON VALIDATION PATTERNS
+// ============================================
+
+/**
+ * Pattern for valid file paths (no path traversal)
+ */
+const safeFilePathPattern = /^[a-zA-Z0-9_\-./\\]+$/;
+
+/**
+ * Pattern for valid app IDs (e.g., com.example.app)
+ */
+const appIdPattern = /^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$/;
+
+/**
+ * Pattern for valid device IDs (emulator-5554, RF8M12345XY, 192.168.1.1:5555)
+ */
+const deviceIdPattern = /^[a-zA-Z0-9][a-zA-Z0-9_\-.:]*$/;
+
+/**
+ * Pattern for valid test/flow names
+ */
+const namePattern = /^[a-zA-Z0-9][a-zA-Z0-9_\-\s.]*$/;
+
+/**
+ * Pattern for valid screen names
+ */
+const screenNamePattern = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+
+// ============================================
+// CUSTOM REFINEMENTS
+// ============================================
+
+/**
+ * Refinement to check for path traversal attempts
+ */
+const noPathTraversal = (val) => !val.includes("..");
+
+/**
+ * Refinement to check for shell injection characters
+ */
+const noShellInjection = (val) => !/[;&|`$]/.test(val);
+
+/**
+ * Refinement to check for command substitution
+ */
+const noCommandSubstitution = (val) =>
+  !/\$\([^)]*\)/.test(val) && !/`[^`]*`/.test(val);
+
+// ============================================
+// REUSABLE SCHEMA COMPONENTS
+// ============================================
+
+/**
+ * Safe file path schema
+ */
+export const safeFilePath = z
+  .string()
+  .min(1, "File path is required")
+  .max(500, "File path too long")
+  .refine(noPathTraversal, "Path traversal not allowed (..)")
+  .refine(noShellInjection, "Invalid characters in path");
+
+/**
+ * App ID schema
+ */
+export const appIdSchema = z
+  .string()
+  .min(3, "App ID too short")
+  .max(150, "App ID too long")
+  .regex(appIdPattern, "Invalid app ID format (expected: com.example.app)");
+
+/**
+ * Optional App ID schema
+ */
+export const optionalAppIdSchema = z
+  .string()
+  .max(150, "App ID too long")
+  .regex(appIdPattern, "Invalid app ID format")
+  .optional();
+
+/**
+ * Device ID schema
+ */
+export const deviceIdSchema = z
+  .string()
+  .min(1, "Device ID is required")
+  .max(100, "Device ID too long")
+  .regex(deviceIdPattern, "Invalid device ID format");
+
+/**
+ * Test name schema
+ */
+export const testNameSchema = z
+  .string()
+  .min(1, "Test name is required")
+  .max(200, "Test name too long")
+  .refine(noShellInjection, "Invalid characters in test name")
+  .refine(noPathTraversal, "Invalid test name");
+
+/**
+ * YAML content schema
+ */
+export const yamlContentSchema = z
+  .string()
+  .min(10, "YAML content too short")
+  .max(50000, "YAML content too long")
+  .refine(noCommandSubstitution, "Command substitution not allowed in YAML");
+
+/**
+ * Retries schema
+ */
+export const retriesSchema = z
+  .number()
+  .int("Retries must be an integer")
+  .min(0, "Retries cannot be negative")
+  .max(10, "Maximum 10 retries allowed")
+  .optional();
+
+// ============================================
+// PROMPT TOOLS SCHEMAS
+// ============================================
+
+/**
+ * Schema for read_prompt_file tool
+ */
+export const readPromptFileSchema = z.object({
+  file: safeFilePath,
+});
+
+/**
+ * Schema for list_prompt_files tool
+ */
+export const listPromptFilesSchema = z.object({
+  directory: z
+    .string()
+    .max(200, "Directory path too long")
+    .refine(noPathTraversal, "Path traversal not allowed")
+    .optional(),
+});
+
+// ============================================
+// DEVICE MANAGEMENT SCHEMAS
+// ============================================
+
+/**
+ * Schema for list_devices tool (no params)
+ */
+export const listDevicesSchema = z.object({});
+
+/**
+ * Schema for select_device tool
+ */
+export const selectDeviceSchema = z.object({
+  deviceId: deviceIdSchema,
+});
+
+/**
+ * Schema for clear_device tool (no params)
+ */
+export const clearDeviceSchema = z.object({});
+
+/**
+ * Schema for check_device tool (no params)
+ */
+export const checkDeviceSchema = z.object({});
+
+/**
+ * Schema for check_app tool
+ */
+export const checkAppSchema = z.object({
+  appId: optionalAppIdSchema,
+});
+
+// ============================================
+// CONFIGURATION SCHEMAS
+// ============================================
+
+/**
+ * Schema for get_app_config tool (no params)
+ */
+export const getAppConfigSchema = z.object({});
+
+// ============================================
+// VALIDATION TOOL SCHEMAS
+// ============================================
+
+/**
+ * Schema for validate_maestro_yaml tool
+ */
+export const validateMaestroYamlSchema = z.object({
+  yaml: yamlContentSchema,
+});
+
+// ============================================
+// TEST EXECUTION SCHEMAS
+// ============================================
+
+/**
+ * Single test item schema (for arrays)
+ */
+export const testItemSchema = z.object({
+  yaml: yamlContentSchema,
+  name: testNameSchema,
+});
+
+/**
+ * Schema for run_test tool
+ */
+export const runTestSchema = z.object({
+  yaml: yamlContentSchema,
+  name: testNameSchema,
+  retries: retriesSchema,
+});
+
+/**
+ * Schema for run_test_suite tool
+ */
+export const runTestSuiteSchema = z.object({
+  tests: z
+    .array(testItemSchema)
+    .min(1, "At least one test is required")
+    .max(100, "Maximum 100 tests allowed"),
+  retries: retriesSchema,
+});
+
+/**
+ * Schema for run_tests_with_report tool
+ */
+export const runTestsWithReportSchema = z.object({
+  tests: z
+    .array(testItemSchema)
+    .min(1, "At least one test is required")
+    .max(100, "Maximum 100 tests allowed"),
+  promptFile: z.string().max(200).optional(),
+  appId: optionalAppIdSchema,
+  retries: retriesSchema,
+});
+
+// ============================================
+// RESULTS & REPORTING SCHEMAS
+// ============================================
+
+/**
+ * Test result item schema
+ */
+export const testResultItemSchema = z.object({
+  name: z.string().min(1).max(200),
+  success: z.boolean(),
+  duration: z.number().optional(),
+  error: z.string().max(5000).optional(),
+});
+
+/**
+ * Schema for generate_report tool
+ */
+export const generateReportSchema = z.object({
+  results: z
+    .array(testResultItemSchema)
+    .min(1, "At least one result is required")
+    .max(500, "Maximum 500 results allowed"),
+  promptFile: z.string().max(200).optional(),
+  appId: optionalAppIdSchema,
+});
+
+/**
+ * Schema for list_reports tool (no params)
+ */
+export const listReportsSchema = z.object({});
+
+/**
+ * Schema for get_test_results tool
+ */
+export const getTestResultsSchema = z.object({
+  runId: z
+    .string()
+    .max(100, "Run ID too long")
+    .refine(noShellInjection, "Invalid run ID")
+    .optional(),
+});
+
+/**
+ * Schema for take_screenshot tool
+ */
+export const takeScreenshotSchema = z.object({
+  name: z
+    .string()
+    .min(1, "Screenshot name is required")
+    .max(100, "Screenshot name too long")
+    .refine(noShellInjection, "Invalid characters in name")
+    .refine(noPathTraversal, "Invalid screenshot name"),
+});
+
+/**
+ * Schema for cleanup_results tool
+ */
+export const cleanupResultsSchema = z.object({
+  keepLast: z
+    .number()
+    .int()
+    .min(1, "Must keep at least 1 result")
+    .max(1000, "Maximum 1000 results")
+    .optional(),
+  deleteScreenshots: z.boolean().optional(),
+});
+
+// ============================================
+// APP CONTEXT/TRAINING SCHEMAS
+// ============================================
+
+/**
+ * Schema for register_elements tool
+ */
+export const registerElementsSchema = z.object({
+  appId: appIdSchema,
+  elements: z.record(
+    z.string(),
+    z.object({
+      testId: z.string().max(200).optional(),
+      accessibilityLabel: z.string().max(200).optional(),
+      text: z.string().max(500).optional(),
+      type: z.string().max(50).optional(),
+      description: z.string().max(500).optional(),
+    })
+  ),
+});
+
+/**
+ * Schema for register_screen tool
+ */
+export const registerScreenSchema = z.object({
+  appId: appIdSchema,
+  screenName: z
+    .string()
+    .min(1, "Screen name is required")
+    .max(100, "Screen name too long")
+    .regex(screenNamePattern, "Invalid screen name format"),
+  screenData: z.object({
+    description: z.string().max(500).optional(),
+    elements: z.array(z.string().max(100)).max(100).optional(),
+    actions: z.array(z.string().max(100)).max(50).optional(),
+  }),
+});
+
+/**
+ * Schema for save_successful_flow tool
+ */
+export const saveSuccessfulFlowSchema = z.object({
+  appId: appIdSchema,
+  flowName: z
+    .string()
+    .min(1, "Flow name is required")
+    .max(100, "Flow name too long")
+    .refine(noShellInjection, "Invalid characters in flow name"),
+  yamlContent: yamlContentSchema,
+  description: z.string().max(500).optional(),
+});
+
+/**
+ * Schema for get_saved_flows tool
+ */
+export const getSavedFlowsSchema = z.object({
+  appId: appIdSchema,
+});
+
+/**
+ * Schema for delete_flow tool
+ */
+export const deleteFlowSchema = z.object({
+  appId: appIdSchema,
+  flowName: z
+    .string()
+    .min(1, "Flow name is required")
+    .max(100, "Flow name too long"),
+});
+
+/**
+ * Schema for get_ai_context tool
+ */
+export const getAiContextSchema = z.object({
+  appId: appIdSchema,
+});
+
+/**
+ * Schema for get_full_context tool
+ */
+export const getFullContextSchema = z.object({
+  appId: appIdSchema,
+});
+
+/**
+ * Schema for clear_app_context tool
+ */
+export const clearAppContextSchema = z.object({
+  appId: appIdSchema,
+});
+
+/**
+ * Schema for list_app_contexts tool (no params)
+ */
+export const listAppContextsSchema = z.object({});
+
+// ============================================
+// YAML GENERATION TOOL SCHEMAS
+// ============================================
+
+/**
+ * Schema for get_yaml_instructions tool
+ */
+export const getYamlInstructionsSchema = z.object({
+  appId: optionalAppIdSchema,
+});
+
+/**
+ * Schema for validate_yaml_structure tool
+ */
+export const validateYamlStructureSchema = z.object({
+  yamlContent: yamlContentSchema,
+});
+
+/**
+ * Valid pattern names
+ */
+const validPatternNames = [
+  "login",
+  "form",
+  "search",
+  "navigation",
+  "list",
+  "settings",
+  "logout",
+  "dropdown",
+  "flutter_login_with_dropdown",
+  "flutter_multi_dropdown",
+];
+
+/**
+ * Schema for get_test_pattern tool
+ */
+export const getTestPatternSchema = z.object({
+  patternName: z.enum(validPatternNames, {
+    errorMap: () => ({
+      message: `Pattern must be one of: ${validPatternNames.join(", ")}`,
+    }),
+  }),
+});
+
+/**
+ * Schema for get_screen_analysis_help tool (no params)
+ */
+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
+// ============================================
+
+/**
+ * Map of tool names to their Zod schemas
+ */
+export const toolSchemas = {
+  // Prompt tools
+  read_prompt_file: readPromptFileSchema,
+  list_prompt_files: listPromptFilesSchema,
+
+  // Device management
+  list_devices: listDevicesSchema,
+  select_device: selectDeviceSchema,
+  clear_device: clearDeviceSchema,
+  check_device: checkDeviceSchema,
+  check_app: checkAppSchema,
+
+  // Configuration
+  get_app_config: getAppConfigSchema,
+
+  // Validation
+  validate_maestro_yaml: validateMaestroYamlSchema,
+
+  // Test execution
+  run_test: runTestSchema,
+  run_test_suite: runTestSuiteSchema,
+  run_tests_with_report: runTestsWithReportSchema,
+
+  // Results & reporting
+  generate_report: generateReportSchema,
+  list_reports: listReportsSchema,
+  get_test_results: getTestResultsSchema,
+  take_screenshot: takeScreenshotSchema,
+  cleanup_results: cleanupResultsSchema,
+
+  // App context/training
+  register_elements: registerElementsSchema,
+  register_screen: registerScreenSchema,
+  save_successful_flow: saveSuccessfulFlowSchema,
+  get_saved_flows: getSavedFlowsSchema,
+  delete_flow: deleteFlowSchema,
+  get_ai_context: getAiContextSchema,
+  get_full_context: getFullContextSchema,
+  clear_app_context: clearAppContextSchema,
+  list_app_contexts: listAppContextsSchema,
+
+  // YAML generation
+  get_yaml_instructions: getYamlInstructionsSchema,
+  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,
+};
+
+// ============================================
+// VALIDATION UTILITIES
+// ============================================
+
+/**
+ * Validate tool input against its schema
+ *
+ * @param {string} toolName - Name of the tool
+ * @param {object} input - Input to validate
+ * @returns {object} Validation result with success, data, and errors
+ */
+export function validateToolInput(toolName, input) {
+  const schema = toolSchemas[toolName];
+
+  if (!schema) {
+    return {
+      success: true,
+      data: input,
+      warning: `No schema defined for tool: ${toolName}`,
+    };
+  }
+
+  const result = schema.safeParse(input || {});
+
+  if (result.success) {
+    return {
+      success: true,
+      data: result.data,
+    };
+  }
+
+  // Format errors for better readability
+  const formattedErrors = result.error.issues.map((issue) => ({
+    field: issue.path.join(".") || "root",
+    message: issue.message,
+    code: issue.code,
+  }));
+
+  return {
+    success: false,
+    errors: formattedErrors,
+    message: `Validation failed: ${formattedErrors
+      .map((e) => e.message)
+      .join(", ")}`,
+  };
+}
+
+/**
+ * Get schema for a specific tool
+ *
+ * @param {string} toolName - Name of the tool
+ * @returns {z.ZodSchema|null} Zod schema or null if not found
+ */
+export function getSchemaForTool(toolName) {
+  return toolSchemas[toolName] || null;
+}
+
+/**
+ * List all tools with schemas
+ *
+ * @returns {string[]} Array of tool names
+ */
+export function listToolsWithSchemas() {
+  return Object.keys(toolSchemas);
+}
+
+// ============================================
+// EXPORTS
+// ============================================
+
+export default {
+  // Schema registry
+  toolSchemas,
+
+  // Utilities
+  validateToolInput,
+  getSchemaForTool,
+  listToolsWithSchemas,
+
+  // Common schemas
+  safeFilePath,
+  appIdSchema,
+  deviceIdSchema,
+  testNameSchema,
+  yamlContentSchema,
+  retriesSchema,
+
+  // Individual tool schemas (for direct imports)
+  readPromptFileSchema,
+  listPromptFilesSchema,
+  listDevicesSchema,
+  selectDeviceSchema,
+  clearDeviceSchema,
+  checkDeviceSchema,
+  checkAppSchema,
+  getAppConfigSchema,
+  validateMaestroYamlSchema,
+  runTestSchema,
+  runTestSuiteSchema,
+  runTestsWithReportSchema,
+  generateReportSchema,
+  listReportsSchema,
+  getTestResultsSchema,
+  takeScreenshotSchema,
+  cleanupResultsSchema,
+  registerElementsSchema,
+  registerScreenSchema,
+  saveSuccessfulFlowSchema,
+  getSavedFlowsSchema,
+  deleteFlowSchema,
+  getAiContextSchema,
+  getFullContextSchema,
+  clearAppContextSchema,
+  listAppContextsSchema,
+  getYamlInstructionsSchema,
+  validateYamlStructureSchema,
+  getTestPatternSchema,
+  getScreenAnalysisHelpSchema,
+  
+  // Prompt Analysis & Validation
+  validatePromptSchema,
+  analyzePromptSchema,
+  
+  // YAML Cache
+  saveToCacheSchema,
+  lookupCacheSchema,
+  deleteFromCacheSchema,
+  listCacheSchema,
+  clearCacheSchema,
+  getCacheStatsSchema,
+  runTestWithCacheSchema,
+};