mcp-maestro-mobile-ai 1.3.0 → 1.4.0

package/src/mcp-server/index.js

@@ -1,816 +1,1059 @@
-#!/usr/bin/env node
-
-/**
- * Maestro MCP Server
- * AI-Assisted Mobile Automation using Model Context Protocol
- *
- * This server exposes tools for running Maestro mobile tests
- * that can be called by AI clients (Cursor, Claude Desktop, VS Code Copilot)
- */
-
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-import { config } from "dotenv";
-import { fileURLToPath } from "url";
-import { dirname, join } from "path";
-
-// Import tools
-import { readPromptFile, listPromptFiles } from "./tools/promptTools.js";
-import { validateMaestroYaml } from "./tools/validateTools.js";
-import { runTest, runTestSuite, generateTestReport, listTestReports, runTestSuiteWithReport } from "./tools/runTools.js";
-import {
-  getAppConfig,
-  getTestResults,
-  takeScreenshot,
-  checkDevice,
-  checkApp,
-  cleanupResults,
-  listDevices,
-  selectDevice,
-  clearDevice,
-} from "./tools/utilityTools.js";
-import {
-  registerAppElements,
-  registerAppScreen,
-  saveFlow,
-  getFlows,
-  removeFlow,
-  getAIContext,
-  getAppContext,
-  clearContext,
-  listContexts,
-  getYamlInstructions,
-  validateYamlBeforeRun,
-  getTestPattern,
-  getScreenAnalysis,
-} from "./tools/contextTools.js";
-import { logger } from "./utils/logger.js";
-import { validatePrerequisites } from "./utils/prerequisites.js";
-
-// Load environment variables
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-config({ path: join(__dirname, "../../.env") });
-
-// Create MCP Server
-const server = new Server(
-  {
-    name: "mcp-maestro-mobile-ai",
-    version: "1.2.0",
-  },
-  {
-    capabilities: {
-      tools: {},
-      resources: {},
-    },
-  }
-);
-
-// ============================================
-// TOOL DEFINITIONS
-// ============================================
-
-const TOOLS = [
-  // === Prompt File Tools ===
-  {
-    name: "read_prompt_file",
-    description:
-      "Read test prompts from a .txt or .md file. Each line in the file is treated as a separate test case prompt.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        file: {
-          type: "string",
-          description:
-            'Path to the prompt file (e.g., "prompts/login-tests.txt")',
-        },
-      },
-      required: ["file"],
-    },
-  },
-  {
-    name: "list_prompt_files",
-    description: "List all available prompt files in the prompts directory.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        directory: {
-          type: "string",
-          description:
-            'Directory to search for prompt files (default: "prompts")',
-        },
-      },
-    },
-  },
-
-  // === Device Management Tools ===
-  {
-    name: "list_devices",
-    description:
-      "List all connected Android devices and emulators. Shows device ID, type (emulator/physical), and model name. Use this to see available devices before selecting one.",
-    inputSchema: {
-      type: "object",
-      properties: {},
-    },
-  },
-  {
-    name: "select_device",
-    description:
-      "Select a specific device to run tests on. All subsequent tests will run on this device until changed. Use list_devices first to see available device IDs.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        deviceId: {
-          type: "string",
-          description:
-            'Device ID to select (e.g., "emulator-5554" or "RF8M12345XY" for physical device)',
-        },
-      },
-      required: ["deviceId"],
-    },
-  },
-  {
-    name: "clear_device",
-    description:
-      "Clear the device selection. Tests will run on the first available device (default behavior).",
-    inputSchema: {
-      type: "object",
-      properties: {},
-    },
-  },
-  {
-    name: "check_device",
-    description:
-      "Check if an Android emulator or device is connected. Shows connection status and which device is selected.",
-    inputSchema: {
-      type: "object",
-      properties: {},
-    },
-  },
-  {
-    name: "check_app",
-    description:
-      "Check if the target app is installed on the connected device. Verifies the app is ready for testing.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        appId: {
-          type: "string",
-          description:
-            "Optional: App package ID to check. Uses configured APP_ID if not provided.",
-        },
-      },
-    },
-  },
-
-  // === Configuration Tools ===
-  {
-    name: "get_app_config",
-    description:
-      "Get the current app configuration including appId, platform, selected device, and other settings.",
-    inputSchema: {
-      type: "object",
-      properties: {},
-    },
-  },
-
-  // === Validation Tools ===
-  {
-    name: "validate_maestro_yaml",
-    description:
-      "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: {
-        yaml: {
-          type: "string",
-          description: "The Maestro YAML content to validate",
-        },
-      },
-      required: ["yaml"],
-    },
-  },
-
-  // === Test Execution Tools ===
-  {
-    name: "run_test",
-    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. MUST use tapOn before inputText for each field!",
-        },
-        name: {
-          type: "string",
-          description: "Name for this test (used for reporting and screenshots)",
-        },
-        retries: {
-          type: "number",
-          description:
-            "Optional: Number of retries if test fails (default: from config or 0)",
-        },
-      },
-      required: ["yaml", "name"],
-    },
-  },
-  {
-    name: "run_test_suite",
-    description:
-      "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: {
-        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",
-        },
-        retries: {
-          type: "number",
-          description:
-            "Optional: Number of retries for failed tests (default: from config or 0)",
-        },
-      },
-      required: ["tests"],
-    },
-  },
-
-  // === 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",
-          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.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        runId: {
-          type: "string",
-          description: "Optional: Specific run ID to get results for",
-        },
-      },
-    },
-  },
-  {
-    name: "take_screenshot",
-    description:
-      "Take a screenshot of the current device screen. Useful for debugging or verification.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        name: {
-          type: "string",
-          description: "Name for the screenshot file",
-        },
-      },
-      required: ["name"],
-    },
-  },
-  {
-    name: "cleanup_results",
-    description:
-      "Clean up old test results and screenshots to free up disk space. Keeps the most recent results.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        keepLast: {
-          type: "number",
-          description: "Number of recent results to keep (default: 50)",
-        },
-        deleteScreenshots: {
-          type: "boolean",
-          description: "Whether to delete old screenshots (default: true)",
-        },
-      },
-    },
-  },
-
-  // === App Context/Training Tools ===
-  {
-    name: "register_elements",
-    description:
-      "Register UI elements for an app to help AI generate better YAML. Provide testIDs, accessibilityLabels, and text values for app elements. This teaches the AI about your app's UI structure.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        appId: {
-          type: "string",
-          description: "App package ID (e.g., 'com.myapp')",
-        },
-        elements: {
-          type: "object",
-          description:
-            "Object containing element definitions. Each key is the element name, value contains: testId, accessibilityLabel, text, type, description",
-        },
-      },
-      required: ["appId", "elements"],
-    },
-  },
-  {
-    name: "register_screen",
-    description:
-      "Register a screen structure for an app. Define what elements and actions are available on each screen.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        appId: {
-          type: "string",
-          description: "App package ID",
-        },
-        screenName: {
-          type: "string",
-          description: "Name of the screen (e.g., 'LoginScreen', 'Dashboard')",
-        },
-        screenData: {
-          type: "object",
-          description:
-            "Screen data including: description, elements (array of element names), actions (array of possible actions)",
-        },
-      },
-      required: ["appId", "screenName", "screenData"],
-    },
-  },
-  {
-    name: "save_successful_flow",
-    description:
-      "Save a successful test flow as a pattern for future reference. Call this after a test passes to help AI learn from successful patterns.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        appId: {
-          type: "string",
-          description: "App package ID",
-        },
-        flowName: {
-          type: "string",
-          description: "Name for this flow pattern",
-        },
-        yamlContent: {
-          type: "string",
-          description: "The successful Maestro YAML content",
-        },
-        description: {
-          type: "string",
-          description: "Optional: Description of what this flow does",
-        },
-      },
-      required: ["appId", "flowName", "yamlContent"],
-    },
-  },
-  {
-    name: "get_saved_flows",
-    description:
-      "Get all saved successful flows for an app. Use these as patterns when generating new tests.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        appId: {
-          type: "string",
-          description: "App package ID",
-        },
-      },
-      required: ["appId"],
-    },
-  },
-  {
-    name: "delete_flow",
-    description: "Delete a saved flow pattern.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        appId: {
-          type: "string",
-          description: "App package ID",
-        },
-        flowName: {
-          type: "string",
-          description: "Name of the flow to delete",
-        },
-      },
-      required: ["appId", "flowName"],
-    },
-  },
-  {
-    name: "get_ai_context",
-    description:
-      "Get the formatted AI context for an app. This returns all registered elements, screens, and example flows in a format optimized for AI consumption. ALWAYS call this before generating Maestro YAML to get app-specific information.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        appId: {
-          type: "string",
-          description: "App package ID",
-        },
-      },
-      required: ["appId"],
-    },
-  },
-  {
-    name: "get_full_context",
-    description:
-      "Get the complete raw app context including all elements, screens, and flows.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        appId: {
-          type: "string",
-          description: "App package ID",
-        },
-      },
-      required: ["appId"],
-    },
-  },
-  {
-    name: "clear_app_context",
-    description: "Clear all saved context for an app (elements, screens, flows).",
-    inputSchema: {
-      type: "object",
-      properties: {
-        appId: {
-          type: "string",
-          description: "App package ID",
-        },
-      },
-      required: ["appId"],
-    },
-  },
-  {
-    name: "list_app_contexts",
-    description: "List all apps that have saved context data.",
-    inputSchema: {
-      type: "object",
-      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: {},
-    },
-  },
-];
-
-// ============================================
-// HANDLERS
-// ============================================
-
-// List available tools
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  logger.info("Listing available tools");
-  return { tools: TOOLS };
-});
-
-// Handle tool calls
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-  logger.info(`Tool called: ${name}`, { args });
-
-  try {
-    switch (name) {
-      // Prompt tools
-      case "read_prompt_file":
-        return await readPromptFile(args.file);
-
-      case "list_prompt_files":
-        return await listPromptFiles(args.directory);
-
-      // Device management tools
-      case "list_devices":
-        return await listDevices();
-
-      case "select_device":
-        return await selectDevice(args.deviceId);
-
-      case "clear_device":
-        return await clearDevice();
-
-      case "check_device":
-        return await checkDevice();
-
-      case "check_app":
-        return await checkApp(args.appId);
-
-      // Config tools
-      case "get_app_config":
-        return await getAppConfig();
-
-      // Validation tools
-      case "validate_maestro_yaml":
-        return await validateMaestroYaml(args.yaml);
-
-      // Execution tools
-      case "run_test":
-        return await runTest(args.yaml, args.name, { retries: args.retries });
-
-      case "run_test_suite":
-        return await runTestSuite(args.tests, { retries: args.retries });
-
-      // 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);
-
-      case "take_screenshot":
-        return await takeScreenshot(args.name);
-
-      case "cleanup_results":
-        return await cleanupResults({
-          keepLast: args.keepLast,
-          deleteScreenshots: args.deleteScreenshots,
-        });
-
-      // App context/training tools
-      case "register_elements":
-        return await registerAppElements(args.appId, args.elements);
-
-      case "register_screen":
-        return await registerAppScreen(args.appId, args.screenName, args.screenData);
-
-      case "save_successful_flow":
-        return await saveFlow(args.appId, args.flowName, args.yamlContent, args.description);
-
-      case "get_saved_flows":
-        return await getFlows(args.appId);
-
-      case "delete_flow":
-        return await removeFlow(args.appId, args.flowName);
-
-      case "get_ai_context":
-        return await getAIContext(args.appId);
-
-      case "get_full_context":
-        return await getAppContext(args.appId);
-
-      case "clear_app_context":
-        return await clearContext(args.appId);
-
-      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}`);
-    }
-  } catch (error) {
-    logger.error(`Tool error: ${name}`, { error: error.message });
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify({
-            success: false,
-            error: error.message,
-          }),
-        },
-      ],
-    };
-  }
-});
-
-// List available resources (prompt files)
-server.setRequestHandler(ListResourcesRequestSchema, async () => {
-  const result = await listPromptFiles("prompts");
-  const files = JSON.parse(result.content[0].text).files || [];
-
-  return {
-    resources: files.map((file) => ({
-      uri: `prompts://${file}`,
-      name: file,
-      mimeType: "text/plain",
-      description: `Prompt file: ${file}`,
-    })),
-  };
-});
-
-// Read a resource
-server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-  const uri = request.params.uri;
-  const file = uri.replace("prompts://", "");
-  const result = await readPromptFile(`prompts/${file}`);
-
-  return {
-    contents: [
-      {
-        uri,
-        mimeType: "text/plain",
-        text: result.content[0].text,
-      },
-    ],
-  };
-});
-
-// ============================================
-// START SERVER
-// ============================================
-
-async function main() {
-  logger.info("Starting MCP Maestro Mobile AI v1.2.0...");
-  logger.info("");
-
-  // Validate prerequisites before starting
-  // This will exit with code 2 if critical prerequisites are missing
-  await validatePrerequisites({
-    exitOnError: true,
-    checkDevice: false, // Don't require device at startup
-  });
-
-  logger.info("");
-  logger.info("Prerequisites validated. Starting server...");
-
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-
-  logger.info("MCP Maestro Mobile AI server running on stdio");
-}
-
-main().catch((error) => {
-  logger.error("Failed to start server", { error: error.message });
-  process.exit(1);
-});
+#!/usr/bin/env node
+
+/**
+ * Maestro MCP Server
+ * AI-Assisted Mobile Automation using Model Context Protocol
+ *
+ * This server exposes tools for running Maestro mobile tests
+ * that can be called by AI clients (Cursor, Claude Desktop, VS Code Copilot)
+ *
+ * Security: All tool inputs are validated using Zod schemas before execution.
+ * See schemas/toolSchemas.js for validation rules.
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { config } from "dotenv";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+// Import tools
+import { readPromptFile, listPromptFiles } from "./tools/promptTools.js";
+import { validateMaestroYaml } from "./tools/validateTools.js";
+import {
+  runTest,
+  runTestSuite,
+  generateTestReport,
+  listTestReports,
+  runTestSuiteWithReport,
+} from "./tools/runTools.js";
+import {
+  getAppConfig,
+  getTestResults,
+  takeScreenshot,
+  checkDevice,
+  checkApp,
+  cleanupResults,
+  listDevices,
+  selectDevice,
+  clearDevice,
+} from "./tools/utilityTools.js";
+import {
+  registerAppElements,
+  registerAppScreen,
+  saveFlow,
+  getFlows,
+  removeFlow,
+  getAIContext,
+  getAppContext,
+  clearContext,
+  listContexts,
+  getYamlInstructions,
+  validateYamlBeforeRun,
+  getTestPattern,
+  getScreenAnalysis,
+} from "./tools/contextTools.js";
+import { logger } from "./utils/logger.js";
+import { validatePrerequisites } from "./utils/prerequisites.js";
+
+// Import security and validation
+import {
+  SecurityError,
+  isSafeModeEnabled,
+  getSecurityConfig,
+  logSecurityEvent,
+} from "./utils/security.js";
+import { validateToolInput } from "./schemas/toolSchemas.js";
+
+// Load environment variables
+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";
+
+// Create MCP Server
+const server = new Server(
+  {
+    name: "mcp-maestro-mobile-ai",
+    version: SERVER_VERSION,
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  }
+);
+
+// ============================================
+// TOOL DEFINITIONS
+// ============================================
+
+const TOOLS = [
+  // === Prompt File Tools ===
+  {
+    name: "read_prompt_file",
+    description:
+      "Read test prompts from a .txt or .md file. Each line in the file is treated as a separate test case prompt.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file: {
+          type: "string",
+          description:
+            'Path to the prompt file (e.g., "prompts/login-tests.txt")',
+        },
+      },
+      required: ["file"],
+    },
+  },
+  {
+    name: "list_prompt_files",
+    description: "List all available prompt files in the prompts directory.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        directory: {
+          type: "string",
+          description:
+            'Directory to search for prompt files (default: "prompts")',
+        },
+      },
+    },
+  },
+
+  // === Device Management Tools ===
+  {
+    name: "list_devices",
+    description:
+      "List all connected Android devices and emulators. Shows device ID, type (emulator/physical), and model name. Use this to see available devices before selecting one.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "select_device",
+    description:
+      "Select a specific device to run tests on. All subsequent tests will run on this device until changed. Use list_devices first to see available device IDs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        deviceId: {
+          type: "string",
+          description:
+            'Device ID to select (e.g., "emulator-5554" or "RF8M12345XY" for physical device)',
+        },
+      },
+      required: ["deviceId"],
+    },
+  },
+  {
+    name: "clear_device",
+    description:
+      "Clear the device selection. Tests will run on the first available device (default behavior).",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "check_device",
+    description:
+      "Check if an Android emulator or device is connected. Shows connection status and which device is selected.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "check_app",
+    description:
+      "Check if the target app is installed on the connected device. Verifies the app is ready for testing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: {
+          type: "string",
+          description:
+            "Optional: App package ID to check. Uses configured APP_ID if not provided.",
+        },
+      },
+    },
+  },
+
+  // === Configuration Tools ===
+  {
+    name: "get_app_config",
+    description:
+      "Get the current app configuration including appId, platform, selected device, and other settings.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+
+  // === Validation Tools ===
+  {
+    name: "validate_maestro_yaml",
+    description:
+      "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: {
+        yaml: {
+          type: "string",
+          description: "The Maestro YAML content to validate",
+        },
+      },
+      required: ["yaml"],
+    },
+  },
+
+  // === Test Execution Tools ===
+  {
+    name: "run_test",
+    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. MUST use tapOn before inputText for each field!",
+        },
+        name: {
+          type: "string",
+          description:
+            "Name for this test (used for reporting and screenshots)",
+        },
+        retries: {
+          type: "number",
+          description:
+            "Optional: Number of retries if test fails (default: from config or 0)",
+        },
+      },
+      required: ["yaml", "name"],
+    },
+  },
+  {
+    name: "run_test_suite",
+    description:
+      "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: {
+        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",
+        },
+        retries: {
+          type: "number",
+          description:
+            "Optional: Number of retries for failed tests (default: from config or 0)",
+        },
+      },
+      required: ["tests"],
+    },
+  },
+
+  // === 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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        runId: {
+          type: "string",
+          description: "Optional: Specific run ID to get results for",
+        },
+      },
+    },
+  },
+  {
+    name: "take_screenshot",
+    description:
+      "Take a screenshot of the current device screen. Useful for debugging or verification.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Name for the screenshot file",
+        },
+      },
+      required: ["name"],
+    },
+  },
+  {
+    name: "cleanup_results",
+    description:
+      "Clean up old test results and screenshots to free up disk space. Keeps the most recent results.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        keepLast: {
+          type: "number",
+          description: "Number of recent results to keep (default: 50)",
+        },
+        deleteScreenshots: {
+          type: "boolean",
+          description: "Whether to delete old screenshots (default: true)",
+        },
+      },
+    },
+  },
+
+  // === App Context/Training Tools ===
+  {
+    name: "register_elements",
+    description:
+      "Register UI elements for an app to help AI generate better YAML. Provide testIDs, accessibilityLabels, and text values for app elements. This teaches the AI about your app's UI structure.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: {
+          type: "string",
+          description: "App package ID (e.g., 'com.myapp')",
+        },
+        elements: {
+          type: "object",
+          description:
+            "Object containing element definitions. Each key is the element name, value contains: testId, accessibilityLabel, text, type, description",
+        },
+      },
+      required: ["appId", "elements"],
+    },
+  },
+  {
+    name: "register_screen",
+    description:
+      "Register a screen structure for an app. Define what elements and actions are available on each screen.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: {
+          type: "string",
+          description: "App package ID",
+        },
+        screenName: {
+          type: "string",
+          description: "Name of the screen (e.g., 'LoginScreen', 'Dashboard')",
+        },
+        screenData: {
+          type: "object",
+          description:
+            "Screen data including: description, elements (array of element names), actions (array of possible actions)",
+        },
+      },
+      required: ["appId", "screenName", "screenData"],
+    },
+  },
+  {
+    name: "save_successful_flow",
+    description:
+      "Save a successful test flow as a pattern for future reference. Call this after a test passes to help AI learn from successful patterns.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: {
+          type: "string",
+          description: "App package ID",
+        },
+        flowName: {
+          type: "string",
+          description: "Name for this flow pattern",
+        },
+        yamlContent: {
+          type: "string",
+          description: "The successful Maestro YAML content",
+        },
+        description: {
+          type: "string",
+          description: "Optional: Description of what this flow does",
+        },
+      },
+      required: ["appId", "flowName", "yamlContent"],
+    },
+  },
+  {
+    name: "get_saved_flows",
+    description:
+      "Get all saved successful flows for an app. Use these as patterns when generating new tests.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: {
+          type: "string",
+          description: "App package ID",
+        },
+      },
+      required: ["appId"],
+    },
+  },
+  {
+    name: "delete_flow",
+    description: "Delete a saved flow pattern.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: {
+          type: "string",
+          description: "App package ID",
+        },
+        flowName: {
+          type: "string",
+          description: "Name of the flow to delete",
+        },
+      },
+      required: ["appId", "flowName"],
+    },
+  },
+  {
+    name: "get_ai_context",
+    description:
+      "Get the formatted AI context for an app. This returns all registered elements, screens, and example flows in a format optimized for AI consumption. ALWAYS call this before generating Maestro YAML to get app-specific information.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: {
+          type: "string",
+          description: "App package ID",
+        },
+      },
+      required: ["appId"],
+    },
+  },
+  {
+    name: "get_full_context",
+    description:
+      "Get the complete raw app context including all elements, screens, and flows.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: {
+          type: "string",
+          description: "App package ID",
+        },
+      },
+      required: ["appId"],
+    },
+  },
+  {
+    name: "clear_app_context",
+    description:
+      "Clear all saved context for an app (elements, screens, flows).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: {
+          type: "string",
+          description: "App package ID",
+        },
+      },
+      required: ["appId"],
+    },
+  },
+  {
+    name: "list_app_contexts",
+    description: "List all apps that have saved context data.",
+    inputSchema: {
+      type: "object",
+      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: {},
+    },
+  },
+];
+
+// ============================================
+// HANDLERS
+// ============================================
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  logger.info("Listing available tools");
+  return { tools: TOOLS };
+});
+
+// ============================================
+// VALIDATION MIDDLEWARE
+// ============================================
+
+/**
+ * Create a validation error response
+ */
+function createValidationErrorResponse(toolName, validationResult) {
+  logSecurityEvent("TOOL_VALIDATION_FAILED", {
+    tool: toolName,
+    errors: validationResult.errors,
+  });
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          success: false,
+          error: "Input validation failed",
+          validationErrors: validationResult.errors,
+          message: validationResult.message,
+          hint: "Please check the input parameters and try again.",
+        }),
+      },
+    ],
+  };
+}
+
+/**
+ * Create a security error response
+ */
+function createSecurityErrorResponse(error) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          success: false,
+          error: "Security violation",
+          code: error.code,
+          message: error.message,
+          details: error.details,
+        }),
+      },
+    ],
+  };
+}
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const startTime = Date.now();
+
+  logger.info(`Tool called: ${name}`, { args });
+
+  // ============================================
+  // STEP 1: Validate input with Zod schema
+  // ============================================
+  const validationResult = validateToolInput(name, args);
+
+  if (!validationResult.success) {
+    logger.warn(`Validation failed for tool: ${name}`, {
+      errors: validationResult.errors,
+    });
+    return createValidationErrorResponse(name, validationResult);
+  }
+
+  // Use validated/sanitized data
+  const validatedArgs = validationResult.data;
+
+  // ============================================
+  // STEP 2: Log security event for audit trail
+  // ============================================
+  logSecurityEvent("TOOL_EXECUTION_START", {
+    tool: name,
+    safeMode: isSafeModeEnabled(),
+    hasArgs: Object.keys(validatedArgs || {}).length > 0,
+  });
+
+  try {
+    // ============================================
+    // STEP 3: Execute tool with validated args
+    // ============================================
+    let result;
+
+    switch (name) {
+      // Prompt tools
+      case "read_prompt_file":
+        result = await readPromptFile(validatedArgs.file);
+        break;
+
+      case "list_prompt_files":
+        result = await listPromptFiles(validatedArgs.directory);
+        break;
+
+      // Device management tools
+      case "list_devices":
+        result = await listDevices();
+        break;
+
+      case "select_device":
+        result = await selectDevice(validatedArgs.deviceId);
+        break;
+
+      case "clear_device":
+        result = await clearDevice();
+        break;
+
+      case "check_device":
+        result = await checkDevice();
+        break;
+
+      case "check_app":
+        result = await checkApp(validatedArgs.appId);
+        break;
+
+      // Config tools
+      case "get_app_config":
+        result = await getAppConfig();
+        break;
+
+      // Validation tools
+      case "validate_maestro_yaml":
+        result = await validateMaestroYaml(validatedArgs.yaml);
+        break;
+
+      // Execution tools
+      case "run_test":
+        result = await runTest(validatedArgs.yaml, validatedArgs.name, {
+          retries: validatedArgs.retries,
+        });
+        break;
+
+      case "run_test_suite":
+        result = await runTestSuite(validatedArgs.tests, {
+          retries: validatedArgs.retries,
+        });
+        break;
+
+      // Results & reporting tools
+      case "run_tests_with_report":
+        result = await runTestSuiteWithReport(validatedArgs.tests, {
+          promptFile: validatedArgs.promptFile,
+          appId: validatedArgs.appId,
+          retries: validatedArgs.retries,
+        });
+        break;
+
+      case "generate_report":
+        result = await generateTestReport(validatedArgs.results, {
+          promptFile: validatedArgs.promptFile,
+          appId: validatedArgs.appId,
+        });
+        break;
+
+      case "list_reports":
+        result = await listTestReports();
+        break;
+
+      case "get_test_results":
+        result = await getTestResults(validatedArgs.runId);
+        break;
+
+      case "take_screenshot":
+        result = await takeScreenshot(validatedArgs.name);
+        break;
+
+      case "cleanup_results":
+        result = await cleanupResults({
+          keepLast: validatedArgs.keepLast,
+          deleteScreenshots: validatedArgs.deleteScreenshots,
+        });
+        break;
+
+      // App context/training tools
+      case "register_elements":
+        result = await registerAppElements(
+          validatedArgs.appId,
+          validatedArgs.elements
+        );
+        break;
+
+      case "register_screen":
+        result = await registerAppScreen(
+          validatedArgs.appId,
+          validatedArgs.screenName,
+          validatedArgs.screenData
+        );
+        break;
+
+      case "save_successful_flow":
+        result = await saveFlow(
+          validatedArgs.appId,
+          validatedArgs.flowName,
+          validatedArgs.yamlContent,
+          validatedArgs.description
+        );
+        break;
+
+      case "get_saved_flows":
+        result = await getFlows(validatedArgs.appId);
+        break;
+
+      case "delete_flow":
+        result = await removeFlow(validatedArgs.appId, validatedArgs.flowName);
+        break;
+
+      case "get_ai_context":
+        result = await getAIContext(validatedArgs.appId);
+        break;
+
+      case "get_full_context":
+        result = await getAppContext(validatedArgs.appId);
+        break;
+
+      case "clear_app_context":
+        result = await clearContext(validatedArgs.appId);
+        break;
+
+      case "list_app_contexts":
+        result = await listContexts();
+        break;
+
+      // YAML generation tools
+      case "get_yaml_instructions":
+        result = await getYamlInstructions(validatedArgs.appId);
+        break;
+
+      case "validate_yaml_structure":
+        result = await validateYamlBeforeRun(validatedArgs.yamlContent);
+        break;
+
+      case "get_test_pattern":
+        result = await getTestPattern(validatedArgs.patternName);
+        break;
+
+      case "get_screen_analysis_help":
+        result = await getScreenAnalysis();
+        break;
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+
+    // ============================================
+    // STEP 4: Log successful execution
+    // ============================================
+    const duration = Date.now() - startTime;
+    logSecurityEvent("TOOL_EXECUTION_SUCCESS", {
+      tool: name,
+      duration: `${duration}ms`,
+    });
+
+    return result;
+  } catch (error) {
+    // ============================================
+    // ERROR HANDLING
+    // ============================================
+    const duration = Date.now() - startTime;
+
+    // Handle SecurityError specifically
+    if (error instanceof SecurityError) {
+      logger.error(`Security error in tool: ${name}`, {
+        code: error.code,
+        message: error.message,
+      });
+
+      logSecurityEvent("TOOL_SECURITY_ERROR", {
+        tool: name,
+        code: error.code,
+        duration: `${duration}ms`,
+      });
+
+      return createSecurityErrorResponse(error);
+    }
+
+    // Handle general errors
+    logger.error(`Tool error: ${name}`, { error: error.message });
+
+    logSecurityEvent("TOOL_EXECUTION_ERROR", {
+      tool: name,
+      error: error.message,
+      duration: `${duration}ms`,
+    });
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            success: false,
+            error: error.message,
+          }),
+        },
+      ],
+    };
+  }
+});
+
+// List available resources (prompt files)
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  const result = await listPromptFiles("prompts");
+  const files = JSON.parse(result.content[0].text).files || [];
+
+  return {
+    resources: files.map((file) => ({
+      uri: `prompts://${file}`,
+      name: file,
+      mimeType: "text/plain",
+      description: `Prompt file: ${file}`,
+    })),
+  };
+});
+
+// Read a resource
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const uri = request.params.uri;
+  const file = uri.replace("prompts://", "");
+  const result = await readPromptFile(`prompts/${file}`);
+
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: "text/plain",
+        text: result.content[0].text,
+      },
+    ],
+  };
+});
+
+// ============================================
+// START SERVER
+// ============================================
+
+async function main() {
+  logger.info(`Starting MCP Maestro Mobile AI v${SERVER_VERSION}...`);
+  logger.info("");
+
+  // Log security configuration
+  const securityConfig = getSecurityConfig();
+  logger.info("Security Configuration:", securityConfig);
+  logger.info(
+    `  Safe Mode: ${securityConfig.safeMode ? "ENABLED ✓" : "DISABLED ⚠"}`
+  );
+  logger.info(`  Security Mode: ${securityConfig.mode}`);
+  logger.info(
+    `  Security Logging: ${
+      securityConfig.logSecurityEvents ? "ENABLED" : "DISABLED"
+    }`
+  );
+  logger.info("");
+
+  // Validate prerequisites before starting
+  // This will exit with code 2 if critical prerequisites are missing
+  await validatePrerequisites({
+    exitOnError: true,
+    checkDevice: false, // Don't require device at startup
+  });
+
+  logger.info("");
+  logger.info("Prerequisites validated. Starting server...");
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  logger.info(
+    `MCP Maestro Mobile AI server v${SERVER_VERSION} running on stdio`
+  );
+
+  logSecurityEvent("SERVER_STARTED", {
+    version: SERVER_VERSION,
+    safeMode: securityConfig.safeMode,
+  });
+}
+
+main().catch((error) => {
+  logger.error("Failed to start server", { error: error.message });
+  process.exit(1);
+});