mcp-maestro-mobile-ai 1.1.0

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

@@ -0,0 +1,220 @@
+/**
+ * Validation Tools
+ * Validate Maestro YAML flows before execution
+ */
+
+import yaml from 'js-yaml';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Validate Maestro YAML syntax and structure
+ */
+export async function validateMaestroYaml(yamlContent) {
+  const errors = [];
+  const warnings = [];
+
+  try {
+    // Check if content is empty
+    if (!yamlContent || yamlContent.trim().length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              valid: false,
+              errors: ['YAML content is empty'],
+              warnings: [],
+            }),
+          },
+        ],
+      };
+    }
+
+    // Split by document separator (---)
+    const parts = yamlContent.split(/^---$/m);
+    let configPart = '';
+    let flowPart = '';
+
+    if (parts.length >= 2) {
+      configPart = parts[0];
+      flowPart = parts.slice(1).join('---');
+    } else {
+      flowPart = yamlContent;
+    }
+
+    // Parse config section
+    let config = {};
+    if (configPart.trim()) {
+      try {
+        config = yaml.load(configPart) || {};
+      } catch (e) {
+        errors.push(`Invalid YAML in config section: ${e.message}`);
+      }
+    }
+
+    // Check for appId
+    if (!config.appId) {
+      errors.push('Missing required "appId" in config section. Example: appId: com.example.app');
+    }
+
+    // Parse flow section
+    let flow = [];
+    if (flowPart.trim()) {
+      try {
+        flow = yaml.load(flowPart) || [];
+      } catch (e) {
+        errors.push(`Invalid YAML in flow section: ${e.message}`);
+      }
+    }
+
+    // Validate flow is an array
+    if (!Array.isArray(flow)) {
+      errors.push('Flow section must be an array of steps');
+    } else if (flow.length === 0) {
+      errors.push('Flow has no steps defined');
+    } else {
+      // Validate each step
+      flow.forEach((step, index) => {
+        validateStep(step, index, errors, warnings);
+      });
+    }
+
+    const isValid = errors.length === 0;
+    
+    logger.info(`YAML validation: ${isValid ? 'passed' : 'failed'}`, {
+      errors: errors.length,
+      warnings: warnings.length,
+    });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            valid: isValid,
+            errors,
+            warnings,
+            config: isValid ? config : undefined,
+            stepCount: Array.isArray(flow) ? flow.length : 0,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    logger.error('Validation error', { error: error.message });
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            valid: false,
+            errors: [`Validation error: ${error.message}`],
+            warnings: [],
+          }),
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Validate a single Maestro step
+ */
+function validateStep(step, index, errors, warnings) {
+  if (typeof step === 'string') {
+    // Simple command like "launchApp" or "- back"
+    const validSimpleCommands = [
+      'launchApp',
+      'stopApp',
+      'clearState',
+      'clearKeychain',
+      'back',
+      'home',
+      'hideKeyboard',
+      'scroll',
+      'scrollUntilVisible',
+    ];
+    
+    if (!validSimpleCommands.includes(step)) {
+      warnings.push(`Step ${index + 1}: "${step}" may not be a valid simple command`);
+    }
+    return;
+  }
+
+  if (typeof step !== 'object' || step === null) {
+    errors.push(`Step ${index + 1}: Invalid step format`);
+    return;
+  }
+
+  // Get the command name (first key)
+  const keys = Object.keys(step);
+  if (keys.length === 0) {
+    errors.push(`Step ${index + 1}: Empty step object`);
+    return;
+  }
+
+  const command = keys[0];
+  const value = step[command];
+
+  // Validate known commands
+  const validCommands = [
+    'launchApp',
+    'stopApp',
+    'clearState',
+    'tapOn',
+    'longPressOn',
+    'doubleTapOn',
+    'inputText',
+    'eraseText',
+    'pressKey',
+    'swipe',
+    'scroll',
+    'scrollUntilVisible',
+    'assertVisible',
+    'assertNotVisible',
+    'waitForAnimationToEnd',
+    'extendedWaitUntil',
+    'takeScreenshot',
+    'runFlow',
+    'runScript',
+    'evalScript',
+    'assertTrue',
+    'back',
+    'home',
+    'hideKeyboard',
+    'openLink',
+    'repeat',
+    'copyTextFrom',
+    'pasteText',
+  ];
+
+  if (!validCommands.includes(command)) {
+    warnings.push(`Step ${index + 1}: "${command}" is not a recognized Maestro command`);
+  }
+
+  // Specific validations
+  if (command === 'tapOn' || command === 'assertVisible') {
+    if (typeof value !== 'string' && typeof value !== 'object') {
+      errors.push(`Step ${index + 1}: "${command}" requires a string or object selector`);
+    }
+  }
+
+  if (command === 'inputText') {
+    if (typeof value !== 'string') {
+      errors.push(`Step ${index + 1}: "inputText" requires a string value`);
+    }
+  }
+
+  if (command === 'extendedWaitUntil') {
+    if (typeof value !== 'object') {
+      errors.push(`Step ${index + 1}: "extendedWaitUntil" requires an object with "visible" and optional "timeout"`);
+    } else if (!value.visible) {
+      errors.push(`Step ${index + 1}: "extendedWaitUntil" requires a "visible" property`);
+    }
+  }
+}
+
+export default {
+  validateMaestroYaml,
+};
+

package/src/mcp-server/utils/appContext.js

@@ -0,0 +1,295 @@
+/**
+ * App Context Manager
+ * 
+ * Provides context/training data to help AI generate better YAML.
+ * Stores information about app elements, successful flows, and patterns.
+ */
+
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { logger } from "./logger.js";
+
+// Context storage location
+const USER_HOME = os.homedir();
+const CONTEXT_DIR = path.join(USER_HOME, ".maestro-mcp", "context");
+
+/**
+ * Initialize context directory
+ */
+async function ensureContextDir() {
+  await fs.mkdir(CONTEXT_DIR, { recursive: true });
+}
+
+/**
+ * Get the context file path for an app
+ */
+function getContextPath(appId) {
+  // Sanitize appId for filename
+  const safeAppId = appId.replace(/[^a-zA-Z0-9.-]/g, "_");
+  return path.join(CONTEXT_DIR, `${safeAppId}.json`);
+}
+
+/**
+ * Load app context
+ */
+export async function loadAppContext(appId) {
+  if (!appId) {
+    return { elements: {}, flows: [], patterns: [] };
+  }
+
+  try {
+    await ensureContextDir();
+    const contextPath = getContextPath(appId);
+    const content = await fs.readFile(contextPath, "utf8");
+    return JSON.parse(content);
+  } catch (error) {
+    // No context exists yet
+    return {
+      appId,
+      elements: {},
+      screens: {},
+      flows: [],
+      patterns: [],
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+  }
+}
+
+/**
+ * Save app context
+ */
+export async function saveAppContext(appId, context) {
+  await ensureContextDir();
+  const contextPath = getContextPath(appId);
+  context.updatedAt = new Date().toISOString();
+  await fs.writeFile(contextPath, JSON.stringify(context, null, 2), "utf8");
+  logger.info(`App context saved: ${appId}`);
+  return { success: true, path: contextPath };
+}
+
+/**
+ * Register UI elements for an app
+ * These are the testIDs, accessibilityLabels, and text that can be used
+ */
+export async function registerElements(appId, elements) {
+  const context = await loadAppContext(appId);
+  
+  // Merge new elements
+  context.elements = {
+    ...context.elements,
+    ...elements,
+  };
+
+  await saveAppContext(appId, context);
+  
+  return {
+    success: true,
+    elementsCount: Object.keys(context.elements).length,
+  };
+}
+
+/**
+ * Register screen structure
+ * Defines what elements exist on each screen
+ */
+export async function registerScreen(appId, screenName, screenData) {
+  const context = await loadAppContext(appId);
+  
+  context.screens = context.screens || {};
+  context.screens[screenName] = {
+    ...screenData,
+    updatedAt: new Date().toISOString(),
+  };
+
+  await saveAppContext(appId, context);
+  
+  return {
+    success: true,
+    screen: screenName,
+    screensCount: Object.keys(context.screens).length,
+  };
+}
+
+/**
+ * Save a successful flow as a pattern for future reference
+ */
+export async function saveSuccessfulFlow(appId, flowName, yamlContent, description) {
+  const context = await loadAppContext(appId);
+  
+  context.flows = context.flows || [];
+  
+  // Remove existing flow with same name
+  context.flows = context.flows.filter(f => f.name !== flowName);
+  
+  // Add new flow
+  context.flows.push({
+    name: flowName,
+    description: description || "",
+    yaml: yamlContent,
+    savedAt: new Date().toISOString(),
+  });
+
+  // Keep only last 50 flows
+  if (context.flows.length > 50) {
+    context.flows = context.flows.slice(-50);
+  }
+
+  await saveAppContext(appId, context);
+  
+  return {
+    success: true,
+    flowName,
+    totalFlows: context.flows.length,
+  };
+}
+
+/**
+ * Get all saved flows for an app
+ */
+export async function getSavedFlows(appId) {
+  const context = await loadAppContext(appId);
+  return {
+    success: true,
+    flows: context.flows || [],
+    count: (context.flows || []).length,
+  };
+}
+
+/**
+ * Delete a saved flow
+ */
+export async function deleteFlow(appId, flowName) {
+  const context = await loadAppContext(appId);
+  
+  const before = (context.flows || []).length;
+  context.flows = (context.flows || []).filter(f => f.name !== flowName);
+  const after = context.flows.length;
+
+  await saveAppContext(appId, context);
+  
+  return {
+    success: before !== after,
+    deleted: before !== after,
+    message: before !== after ? `Flow "${flowName}" deleted` : `Flow "${flowName}" not found`,
+  };
+}
+
+/**
+ * Generate AI prompt context from app context
+ * This is the key function that provides training data to AI
+ */
+export async function generateAIPromptContext(appId) {
+  const context = await loadAppContext(appId);
+  
+  let promptContext = `## App Context for ${appId}\n\n`;
+  
+  // Add elements information
+  if (Object.keys(context.elements || {}).length > 0) {
+    promptContext += `### Available UI Elements (use these exact IDs/labels):\n\n`;
+    for (const [key, element] of Object.entries(context.elements)) {
+      promptContext += `- **${key}**: `;
+      if (element.testId) promptContext += `testID="${element.testId}" `;
+      if (element.accessibilityLabel) promptContext += `accessibilityLabel="${element.accessibilityLabel}" `;
+      if (element.text) promptContext += `text="${element.text}" `;
+      if (element.type) promptContext += `(${element.type})`;
+      if (element.description) promptContext += ` - ${element.description}`;
+      promptContext += `\n`;
+    }
+    promptContext += `\n`;
+  }
+
+  // Add screen information
+  if (Object.keys(context.screens || {}).length > 0) {
+    promptContext += `### Screen Structure:\n\n`;
+    for (const [screenName, screen] of Object.entries(context.screens)) {
+      promptContext += `#### ${screenName}\n`;
+      if (screen.description) promptContext += `${screen.description}\n`;
+      if (screen.elements && screen.elements.length > 0) {
+        promptContext += `Elements: ${screen.elements.join(", ")}\n`;
+      }
+      if (screen.actions && screen.actions.length > 0) {
+        promptContext += `Available actions: ${screen.actions.join(", ")}\n`;
+      }
+      promptContext += `\n`;
+    }
+  }
+
+  // Add example flows (patterns)
+  if ((context.flows || []).length > 0) {
+    promptContext += `### Example Flows (reference these patterns):\n\n`;
+    // Show last 5 flows as examples
+    const recentFlows = context.flows.slice(-5);
+    for (const flow of recentFlows) {
+      promptContext += `#### ${flow.name}\n`;
+      if (flow.description) promptContext += `${flow.description}\n`;
+      promptContext += `\`\`\`yaml\n${flow.yaml}\n\`\`\`\n\n`;
+    }
+  }
+
+  // Add general instructions
+  promptContext += `### Generation Instructions:\n`;
+  promptContext += `- Use the exact testID or accessibilityLabel values shown above\n`;
+  promptContext += `- Follow the patterns from example flows\n`;
+  promptContext += `- Add appropriate waits between actions\n`;
+  promptContext += `- Use assertVisible to verify screens before interacting\n`;
+  
+  return {
+    success: true,
+    context: promptContext,
+    hasElements: Object.keys(context.elements || {}).length > 0,
+    hasScreens: Object.keys(context.screens || {}).length > 0,
+    hasFlows: (context.flows || []).length > 0,
+  };
+}
+
+/**
+ * Clear all context for an app
+ */
+export async function clearAppContext(appId) {
+  try {
+    await ensureContextDir();
+    const contextPath = getContextPath(appId);
+    await fs.unlink(contextPath);
+    logger.info(`App context cleared: ${appId}`);
+    return { success: true, message: `Context for ${appId} cleared` };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * List all apps with saved context
+ */
+export async function listAppContexts() {
+  try {
+    await ensureContextDir();
+    const files = await fs.readdir(CONTEXT_DIR);
+    const contexts = files
+      .filter(f => f.endsWith(".json"))
+      .map(f => f.replace(".json", "").replace(/_/g, "."));
+    
+    return {
+      success: true,
+      apps: contexts,
+      count: contexts.length,
+    };
+  } catch (error) {
+    return { success: true, apps: [], count: 0 };
+  }
+}
+
+export default {
+  loadAppContext,
+  saveAppContext,
+  registerElements,
+  registerScreen,
+  saveSuccessfulFlow,
+  getSavedFlows,
+  deleteFlow,
+  generateAIPromptContext,
+  clearAppContext,
+  listAppContexts,
+};
+

package/src/mcp-server/utils/logger.js

@@ -0,0 +1,52 @@
+/**
+ * Logger Utility for MCP Server
+ * Logs to file only (stderr is used by MCP protocol)
+ */
+
+import winston from 'winston';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Ensure logs directory exists
+const logsDir = process.env.LOGS_DIR || join(__dirname, '../../../output/logs');
+if (!fs.existsSync(logsDir)) {
+  fs.mkdirSync(logsDir, { recursive: true });
+}
+
+// File format for logs
+const fileFormat = winston.format.combine(
+  winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
+  winston.format.errors({ stack: true }),
+  winston.format.json()
+);
+
+// Create logger instance - FILE ONLY (MCP uses stdio)
+export const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  transports: [
+    // File transport for all logs
+    new winston.transports.File({
+      filename: path.join(logsDir, 'mcp-server.log'),
+      format: fileFormat,
+      maxsize: 5242880, // 5MB
+      maxFiles: 5,
+    }),
+    
+    // Separate file for errors
+    new winston.transports.File({
+      filename: path.join(logsDir, 'error.log'),
+      format: fileFormat,
+      level: 'error',
+      maxsize: 5242880,
+      maxFiles: 5,
+    }),
+  ],
+});
+
+export default logger;
+