mcp-maestro-mobile-ai 1.1.0

package/src/mcp-server/index.js

@@ -0,0 +1,625 @@
+#!/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 } 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,
+} from "./tools/contextTools.js";
+import { logger } from "./utils/logger.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.1.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 a Maestro YAML flow for syntax errors before running. Returns validation result with any errors found.",
+    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. Provide the Maestro YAML content directly. The test will be executed on the selected device (or first available if none selected). Includes pre-flight checks and auto-retry.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        yaml: {
+          type: "string",
+          description: "The Maestro YAML flow content to run",
+        },
+        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. Provide an array of test objects with yaml and name properties. Tests run on selected device.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tests: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              yaml: {
+                type: "string",
+                description: "The Maestro YAML flow content",
+              },
+              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 & Utility Tools ===
+  {
+    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: {},
+    },
+  },
+];
+
+// ============================================
+// 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 & utility tools
+      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();
+
+      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.1.0...");
+
+  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);
+});