mcp-maestro-mobile-ai 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -23,6 +23,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Test results and screenshots now stored in `~/.maestro-mcp/output/`
 
 ### Added
+- **Automatic Prerequisites Check**: 
+  - Runs automatically after `npm install`
+  - Checks for Node.js 18+, Java 17+, Maestro CLI, Android SDK
+  - Shows clear error messages with installation hints
+  - Manual check available via `npm run check`
+- **Runtime Validation**: Server validates prerequisites on startup and exits gracefully if critical deps missing
 - **App Context Training System**: New tools to teach the AI about your app's UI
   - `register_elements` - Register testIDs, accessibilityLabels for app elements
   - `register_screen` - Define screen structures and available actions

package/docs/MCP_SETUP.md

@@ -1,18 +1,113 @@
 # MCP Server Setup Guide
 
-## Setting up Maestro MCP Server with AI Clients
+## Setting up MCP Maestro Mobile AI with AI Clients
 
-This guide explains how to configure the Maestro MCP Server with different AI clients.
+This guide explains how to configure the MCP Maestro Mobile AI server with different AI clients.
 
 ---
 
 ## Prerequisites
 
-1. **Node.js 18+** installed
-2. **Java 17+** installed  
-3. **Maestro CLI** installed
-4. **Android Emulator** running
-5. Dependencies installed: `npm install`
+### Required Dependencies
+
+| Prerequisite    | Version | Installation                          |
+| --------------- | ------- | ------------------------------------- |
+| **Node.js**     | 18+     | [nodejs.org](https://nodejs.org/)     |
+| **Java**        | 17+     | [adoptium.net](https://adoptium.net/) |
+| **Maestro CLI** | Latest  | See below                             |
+| **Android SDK** | Any     | Android Studio or standalone          |
+
+### Install Maestro CLI
+
+**macOS / Linux:**
+
+```bash
+curl -Ls https://get.maestro.mobile.dev | bash
+```
+
+**Windows (PowerShell):**
+
+```powershell
+iwr https://get.maestro.mobile.dev | iex
+```
+
+### Automatic Prerequisites Check ✨
+
+When you install the package, it **automatically checks** all prerequisites:
+
+```
+npm install -g mcp-maestro-mobile-ai
+
+╔════════════════════════════════════════════════════════╗
+║        MCP Maestro Mobile AI - Prerequisites          ║
+╚════════════════════════════════════════════════════════╝
+
+  ✅ Node.js v20.x
+  ✅ Java 17
+  ✅ Maestro 2.0.10
+  ✅ Android SDK configured
+
+✅ All prerequisites satisfied!
+```
+
+If any prerequisite is missing, you'll see:
+
+```
+  ❌ Java not found
+  ❌ Maestro CLI not found
+
+⚠️  Some required prerequisites are missing.
+
+💡 Installation hints:
+   → Install Java 17+ from https://adoptium.net/
+   → Install Maestro: curl -Ls https://get.maestro.mobile.dev | bash
+```
+
+### Manual Check
+
+You can manually check prerequisites anytime:
+
+```bash
+# If installed globally
+npm run check
+
+# Or run directly
+npx mcp-maestro-mobile-ai check
+```
+
+### Runtime Validation
+
+The server also validates prerequisites **when it starts**. If Java or Maestro is missing, the server will:
+
+1. Show clear error messages
+2. Provide installation hints
+3. Exit with code 2 (infrastructure error)
+
+---
+
+## Installation Options
+
+### Option 1: NPX (Recommended - No Install)
+
+```bash
+npx mcp-maestro-mobile-ai
+```
+
+### Option 2: Global Install
+
+```bash
+npm install -g mcp-maestro-mobile-ai
+maestro-mcp
+```
+
+### Option 3: Clone from GitHub
+
+```bash
+git clone https://github.com/krunal-mahera/mcp-maestro-mobile-ai.git
+cd mcp-maestro-mobile-ai
+npm install
+npm start
+```
 
 ---
 
@@ -21,29 +116,62 @@ This guide explains how to configure the Maestro MCP Server with different AI cl
 ### Step 1: Find your Cursor MCP config file
 
 The config file is located at:
+
 - **Windows**: `%USERPROFILE%\.cursor\mcp.json`
 - **macOS**: `~/.cursor/mcp.json`
 - **Linux**: `~/.cursor/mcp.json`
 
 ### Step 2: Add the Maestro server
 
-Edit the `mcp.json` file and add:
+**If installed via NPM (global):**
 
 ```json
 {
   "mcpServers": {
     "maestro": {
-      "command": "node",
-      "args": ["C:/path/to/ai-automation-mobile/src/mcp-server/index.js"],
+      "command": "maestro-mcp",
+      "env": {
+        "APP_ID": "com.your.app.package",
+        "ANDROID_HOME": "C:/Users/YourName/AppData/Local/Android/Sdk"
+      }
+    }
+  }
+}
+```
+
+**If using NPX:**
+
+```json
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "npx",
+      "args": ["mcp-maestro-mobile-ai"],
       "env": {
-        "APP_ID": "com.google.android.youtube"
+        "APP_ID": "com.your.app.package",
+        "ANDROID_HOME": "C:/Users/YourName/AppData/Local/Android/Sdk"
       }
     }
   }
 }
 ```
 
-**Important:** Replace the path with your actual project path.
+**If cloned from GitHub:**
+
+```json
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "node",
+      "args": ["C:/path/to/mcp-maestro-mobile-ai/src/mcp-server/index.js"],
+      "env": {
+        "APP_ID": "com.your.app.package",
+        "ANDROID_HOME": "C:/Users/YourName/AppData/Local/Android/Sdk"
+      }
+    }
+  }
+}
+```
 
 ### Step 3: Restart Cursor
 
@@ -52,6 +180,7 @@ Close and reopen Cursor for the changes to take effect.
 ### Step 4: Verify
 
 In Cursor's AI chat, type:
+
 ```
 List the available MCP tools
 ```
@@ -69,8 +198,9 @@ If there's an MCP extension for VS Code Copilot, configure it similarly to Curso
 ### Option 2: Run Server Manually
 
 1. Start the MCP server:
+
    ```bash
-   cd C:\Krunal\Practice\ai-automation-mobile
+   cd path/to/mcp-maestro-mobile-ai
    npm start
    ```
 
@@ -78,103 +208,178 @@ If there's an MCP extension for VS Code Copilot, configure it similarly to Curso
 
 ---
 
+## Claude Desktop Setup
+
+Edit `~/.claude/claude_desktop_config.json` (macOS/Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "npx",
+      "args": ["mcp-maestro-mobile-ai"],
+      "env": {
+        "APP_ID": "com.your.app.package"
+      }
+    }
+  }
+}
+```
+
+---
+
 ## Testing the Setup
 
-### 1. Check Configuration
+### 1. Check Prerequisites
+
+Ask the AI:
+
+```
+Check if maestro device is connected
+```
+
+### 2. Check Configuration
 
 Ask the AI:
+
 ```
 Get the app configuration
 ```
 
 Expected response:
+
 ```json
 {
   "success": true,
   "config": {
-    "appId": "com.google.android.youtube",
+    "appId": "com.your.app.package",
     "platform": "android"
   }
 }
 ```
 
-### 2. List Prompt Files
+### 3. List Prompt Files
 
 Ask the AI:
+
 ```
 List available prompt files
 ```
 
-### 3. Run a Test
+### 4. Run a Test
 
 Ask the AI:
+
 ```
-Run a test: "Test that user can open YouTube and search for TechGuru"
+Run a test: Open the app and verify the login screen is visible
 ```
 
 ---
 
 ## Environment Variables
 
-You can pass environment variables in the MCP config:
+| Variable               | Required    | Description                               |
+| ---------------------- | ----------- | ----------------------------------------- |
+| `APP_ID`               | Yes         | Target app package ID                     |
+| `ANDROID_HOME`         | Recommended | Android SDK path                          |
+| `DEFAULT_WAIT_TIMEOUT` | No          | Element wait timeout (ms, default: 10000) |
+| `DEFAULT_RETRIES`      | No          | Auto-retry count (default: 1)             |
+| `MAX_RESULTS`          | No          | Max result files to keep (default: 50)    |
+
+Example config with all options:
 
 ```json
 {
   "mcpServers": {
     "maestro": {
-      "command": "node",
-      "args": ["path/to/src/mcp-server/index.js"],
+      "command": "maestro-mcp",
       "env": {
         "APP_ID": "com.mycompany.myapp",
         "ANDROID_HOME": "C:/Users/Me/Android/Sdk",
-        "LOG_LEVEL": "debug"
+        "DEFAULT_WAIT_TIMEOUT": "15000",
+        "DEFAULT_RETRIES": "2",
+        "MAX_RESULTS": "100"
       }
     }
   }
 }
 ```
 
-Or create a `.env` file in the project root.
-
 ---
 
 ## Troubleshooting
 
+### Prerequisites Check Failed
+
+Run the manual check to see what's missing:
+
+```bash
+npm run check
+```
+
 ### Server doesn't start
 
-1. Check Node.js version: `node --version` (must be 18+)
-2. Check dependencies: `npm install`
-3. Check for errors in `output/logs/mcp-server.log`
+1. Check prerequisites: `npm run check`
+2. Check Node.js version: `node --version` (must be 18+)
+3. Check Java version: `java --version` (must be 17+)
+4. Check Maestro: `maestro --version`
 
-### Tools not appearing
+### Tools not appearing in AI chat
 
-1. Restart your editor
+1. Restart your editor completely
 2. Check the MCP config path is correct
-3. Verify the server path in the config
+3. Verify the command/args in the config
+4. Check for JSON syntax errors in config
 
 ### Tests fail with "No emulator"
 
 1. Start an Android emulator
 2. Verify with `adb devices`
+3. Make sure device shows as "device" not "offline"
 
 ### "APP_ID not configured"
 
 Set the `APP_ID` in either:
+
 - The MCP config's `env` section
 - A `.env` file in the project root
 
+### "ADB not found"
+
+Set `ANDROID_HOME` in your MCP config:
+
+```json
+"env": {
+  "ANDROID_HOME": "C:/Users/YourName/AppData/Local/Android/Sdk"
+}
+```
+
 ---
 
 ## Available Tools
 
-| Tool | Description |
-|------|-------------|
-| `read_prompt_file` | Read test prompts from a file |
-| `list_prompt_files` | List available prompt files |
-| `get_app_config` | Get app configuration |
-| `validate_maestro_yaml` | Validate Maestro YAML |
-| `run_test` | Run a single test |
-| `run_test_suite` | Run multiple tests |
-| `get_test_results` | Get test results |
-| `take_screenshot` | Take a screenshot |
-
+| Tool                    | Description                        |
+| ----------------------- | ---------------------------------- |
+| `read_prompt_file`      | Read test prompts from a file      |
+| `list_prompt_files`     | List available prompt files        |
+| `list_devices`          | List connected Android devices     |
+| `select_device`         | Select a specific device           |
+| `clear_device`          | Clear device selection             |
+| `check_device`          | Check device connection            |
+| `check_app`             | Check if app is installed          |
+| `get_app_config`        | Get app configuration              |
+| `validate_maestro_yaml` | Validate Maestro YAML              |
+| `run_test`              | Run a single test                  |
+| `run_test_suite`        | Run multiple tests                 |
+| `get_test_results`      | Get test results                   |
+| `take_screenshot`       | Take a screenshot                  |
+| `cleanup_results`       | Clean up old results               |
+| `register_elements`     | Register UI elements for better AI |
+| `register_screen`       | Register screen structure          |
+| `save_successful_flow`  | Save working flow pattern          |
+| `get_saved_flows`       | Get saved patterns                 |
+| `delete_flow`           | Delete a saved pattern             |
+| `get_ai_context`        | Get context for AI generation      |
+| `get_full_context`      | Get complete context data          |
+| `clear_app_context`     | Clear app context                  |
+| `list_app_contexts`     | List apps with context             |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mcp-maestro-mobile-ai",
-    "version": "1.1.0",
+    "version": "1.1.1",
     "private": false,
     "description": "MCP Server for AI-Assisted Mobile Automation using Maestro - Run mobile tests with natural language prompts",
     "main": "src/mcp-server/index.js",
@@ -10,6 +10,7 @@
     },
     "files": [
         "src/",
+        "scripts/",
         "prompts/",
         "templates/",
         "docs/",
@@ -32,6 +33,8 @@
         "dev": "node --watch src/mcp-server/index.js",
         "test:flow": "maestro test",
         "lint": "eslint src/",
+        "postinstall": "node scripts/check-prerequisites.js",
+        "check": "node scripts/check-prerequisites.js",
         "prepublishOnly": "npm run lint"
     },
     "keywords": [

package/scripts/check-prerequisites.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall Prerequisites Check
+ * 
+ * This script runs after npm install to warn users about missing prerequisites.
+ * It shows warnings but does NOT block installation.
+ */
+
+import { execSync } from "child_process";
+
+// ANSI color codes for terminal output
+const colors = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+};
+
+const icons = {
+  check: "✅",
+  cross: "❌",
+  warning: "⚠️",
+  info: "ℹ️",
+};
+
+/**
+ * Execute a command and return the output
+ */
+function execCommand(command) {
+  try {
+    return execSync(command, { 
+      encoding: "utf8", 
+      timeout: 10000,
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Parse version string to extract major version number
+ */
+function parseVersion(versionString) {
+  if (!versionString) return null;
+  const match = versionString.match(/(\d+)\.(\d+)/);
+  if (match) {
+    return {
+      major: parseInt(match[1], 10),
+      minor: parseInt(match[2], 10),
+      full: versionString,
+    };
+  }
+  return null;
+}
+
+/**
+ * Check Node.js version
+ */
+function checkNodeJs() {
+  const version = process.version;
+  const parsed = parseVersion(version);
+  
+  if (!parsed) {
+    return { 
+      installed: false, 
+      message: "Could not determine Node.js version" 
+    };
+  }
+
+  if (parsed.major >= 18) {
+    return { 
+      installed: true, 
+      version: version,
+      message: `Node.js ${version}` 
+    };
+  }
+
+  return { 
+    installed: true, 
+    version: version,
+    outdated: true,
+    message: `Node.js ${version} (requires 18+)` 
+  };
+}
+
+/**
+ * Check Java version
+ */
+function checkJava() {
+  // Try java --version first (Java 9+)
+  let output = execCommand("java --version");
+  
+  // Fall back to java -version (older format)
+  if (!output) {
+    output = execCommand("java -version 2>&1");
+  }
+
+  if (!output) {
+    return { 
+      installed: false, 
+      message: "Java not found",
+      hint: "Install Java 17+ from https://adoptium.net/"
+    };
+  }
+
+  // Parse Java version
+  const versionMatch = output.match(/(?:java|openjdk)\s+(?:version\s+)?["']?(\d+)(?:\.(\d+))?/i);
+  if (versionMatch) {
+    const major = parseInt(versionMatch[1], 10);
+    
+    if (major >= 17) {
+      return { 
+        installed: true, 
+        version: `${major}`,
+        message: `Java ${major}` 
+      };
+    }
+
+    return { 
+      installed: true, 
+      version: `${major}`,
+      outdated: true,
+      message: `Java ${major} (requires 17+)`,
+      hint: "Upgrade to Java 17+ from https://adoptium.net/"
+    };
+  }
+
+  return { 
+    installed: true, 
+    message: "Java (version unknown)" 
+  };
+}
+
+/**
+ * Check Maestro CLI
+ */
+function checkMaestro() {
+  const output = execCommand("maestro --version");
+
+  if (!output) {
+    return { 
+      installed: false, 
+      message: "Maestro CLI not found",
+      hint: "Install: curl -Ls https://get.maestro.mobile.dev | bash"
+    };
+  }
+
+  return { 
+    installed: true, 
+    version: output,
+    message: `Maestro ${output}` 
+  };
+}
+
+/**
+ * Check Android SDK / ADB
+ */
+function checkAndroidSdk() {
+  const androidHome = process.env.ANDROID_HOME;
+  
+  if (!androidHome) {
+    return { 
+      installed: false, 
+      message: "ANDROID_HOME not set",
+      hint: "Set ANDROID_HOME environment variable to your Android SDK path"
+    };
+  }
+
+  // Check if ADB exists
+  const adbOutput = execCommand("adb --version");
+  
+  if (!adbOutput) {
+    return { 
+      installed: true, 
+      message: "ANDROID_HOME set but ADB not in PATH",
+      hint: "Add Android SDK platform-tools to your PATH"
+    };
+  }
+
+  return { 
+    installed: true, 
+    message: `Android SDK (${androidHome.length > 40 ? "..." + androidHome.slice(-37) : androidHome})` 
+  };
+}
+
+/**
+ * Main check function
+ */
+function runChecks() {
+  console.log("");
+  console.log(`${colors.cyan}${colors.bright}╔════════════════════════════════════════════════════════╗${colors.reset}`);
+  console.log(`${colors.cyan}${colors.bright}║        MCP Maestro Mobile AI - Prerequisites          ║${colors.reset}`);
+  console.log(`${colors.cyan}${colors.bright}╚════════════════════════════════════════════════════════╝${colors.reset}`);
+  console.log("");
+
+  const checks = [
+    { name: "Node.js 18+", check: checkNodeJs, required: true },
+    { name: "Java 17+", check: checkJava, required: true },
+    { name: "Maestro CLI", check: checkMaestro, required: true },
+    { name: "Android SDK", check: checkAndroidSdk, required: false },
+  ];
+
+  const results = [];
+  let hasErrors = false;
+  let hasWarnings = false;
+
+  for (const item of checks) {
+    const result = item.check();
+    results.push({ ...item, result });
+
+    let icon, color;
+    
+    if (result.installed && !result.outdated) {
+      icon = icons.check;
+      color = colors.green;
+    } else if (result.outdated) {
+      icon = icons.warning;
+      color = colors.yellow;
+      hasWarnings = true;
+      if (item.required) hasErrors = true;
+    } else {
+      icon = item.required ? icons.cross : icons.warning;
+      color = item.required ? colors.red : colors.yellow;
+      if (item.required) {
+        hasErrors = true;
+      } else {
+        hasWarnings = true;
+      }
+    }
+
+    console.log(`  ${icon} ${color}${result.message}${colors.reset}`);
+  }
+
+  console.log("");
+
+  // Show hints for missing/outdated items
+  const hints = results
+    .filter(r => r.result.hint)
+    .map(r => r.result.hint);
+
+  if (hints.length > 0) {
+    console.log(`${colors.yellow}${icons.info} Installation hints:${colors.reset}`);
+    hints.forEach(hint => {
+      console.log(`   ${colors.yellow}→ ${hint}${colors.reset}`);
+    });
+    console.log("");
+  }
+
+  // Summary
+  if (hasErrors) {
+    console.log(`${colors.red}${colors.bright}⚠️  Some required prerequisites are missing.${colors.reset}`);
+    console.log(`${colors.red}   The server will not start without them.${colors.reset}`);
+    console.log("");
+  } else if (hasWarnings) {
+    console.log(`${colors.yellow}${colors.bright}${icons.warning} Some optional prerequisites are missing.${colors.reset}`);
+    console.log(`${colors.yellow}   The server may have limited functionality.${colors.reset}`);
+    console.log("");
+  } else {
+    console.log(`${colors.green}${colors.bright}${icons.check} All prerequisites satisfied!${colors.reset}`);
+    console.log("");
+  }
+
+  console.log(`${colors.cyan}Documentation: https://github.com/krunal-mahera/mcp-maestro-mobile-ai${colors.reset}`);
+  console.log("");
+
+  // Note: We do NOT exit with error code - this is just a warning
+  // The actual validation happens at runtime
+}
+
+// Run checks
+runChecks();
+

package/src/mcp-server/index.js

@@ -47,6 +47,7 @@ import {
   listContexts,
 } 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);
@@ -612,6 +613,17 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 
 async function main() {
   logger.info("Starting MCP Maestro Mobile AI v1.1.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);

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

@@ -0,0 +1,390 @@
+/**
+ * Runtime Prerequisites Validation
+ * 
+ * This module validates prerequisites when the MCP server starts.
+ * Critical missing dependencies will prevent server startup.
+ */
+
+import { execSync } from "child_process";
+import path from "path";
+import { logger } from "./logger.js";
+
+/**
+ * Execute a command safely and return result
+ */
+function execCommand(command, options = {}) {
+  try {
+    return {
+      success: true,
+      output: execSync(command, {
+        encoding: "utf8",
+        timeout: options.timeout || 10000,
+        stdio: ["pipe", "pipe", "pipe"],
+        ...options,
+      }).trim(),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Parse version string to extract major version number
+ */
+function parseVersion(versionString) {
+  if (!versionString) return null;
+  const match = versionString.match(/(\d+)(?:\.(\d+))?/);
+  if (match) {
+    return {
+      major: parseInt(match[1], 10),
+      minor: match[2] ? parseInt(match[2], 10) : 0,
+    };
+  }
+  return null;
+}
+
+/**
+ * Check Node.js version (should always pass since we're running in Node)
+ */
+function checkNodeJs() {
+  const version = process.version;
+  const parsed = parseVersion(version);
+
+  if (!parsed || parsed.major < 18) {
+    return {
+      name: "Node.js",
+      status: "error",
+      installed: true,
+      version: version,
+      required: "18+",
+      message: `Node.js ${version} is outdated. Requires 18+.`,
+      hint: "Upgrade Node.js from https://nodejs.org/",
+    };
+  }
+
+  return {
+    name: "Node.js",
+    status: "ok",
+    installed: true,
+    version: version,
+    message: `Node.js ${version}`,
+  };
+}
+
+/**
+ * Check Java version
+ */
+function checkJava() {
+  // Try java --version first (Java 9+)
+  let result = execCommand("java --version");
+
+  // Fall back to java -version
+  if (!result.success) {
+    result = execCommand("java -version 2>&1");
+  }
+
+  if (!result.success) {
+    return {
+      name: "Java",
+      status: "error",
+      installed: false,
+      required: "17+",
+      message: "Java is not installed or not in PATH.",
+      hint: "Install Java 17+ from https://adoptium.net/",
+    };
+  }
+
+  // Parse version
+  const versionMatch = result.output.match(
+    /(?:java|openjdk)\s+(?:version\s+)?["']?(\d+)/i
+  );
+
+  if (versionMatch) {
+    const major = parseInt(versionMatch[1], 10);
+
+    if (major < 17) {
+      return {
+        name: "Java",
+        status: "error",
+        installed: true,
+        version: `${major}`,
+        required: "17+",
+        message: `Java ${major} is outdated. Requires 17+.`,
+        hint: "Upgrade to Java 17+ from https://adoptium.net/",
+      };
+    }
+
+    return {
+      name: "Java",
+      status: "ok",
+      installed: true,
+      version: `${major}`,
+      message: `Java ${major}`,
+    };
+  }
+
+  // Can't determine version but Java is installed
+  return {
+    name: "Java",
+    status: "warning",
+    installed: true,
+    version: "unknown",
+    message: "Java installed (version unknown)",
+  };
+}
+
+/**
+ * Check Maestro CLI
+ */
+function checkMaestro() {
+  const result = execCommand("maestro --version");
+
+  if (!result.success) {
+    return {
+      name: "Maestro CLI",
+      status: "error",
+      installed: false,
+      message: "Maestro CLI is not installed or not in PATH.",
+      hint: "Install Maestro: curl -Ls https://get.maestro.mobile.dev | bash",
+      hintWindows: "Install Maestro: iwr https://get.maestro.mobile.dev | iex",
+    };
+  }
+
+  return {
+    name: "Maestro CLI",
+    status: "ok",
+    installed: true,
+    version: result.output,
+    message: `Maestro ${result.output}`,
+  };
+}
+
+/**
+ * Check Android SDK / ADB
+ */
+function checkAndroidSdk() {
+  const androidHome = process.env.ANDROID_HOME;
+
+  if (!androidHome) {
+    return {
+      name: "Android SDK",
+      status: "warning",
+      installed: false,
+      message: "ANDROID_HOME environment variable is not set.",
+      hint: "Set ANDROID_HOME to your Android SDK path for reliable ADB access.",
+    };
+  }
+
+  // Check if ADB is accessible
+  const adbPath = path.join(androidHome, "platform-tools", "adb");
+  const result = execCommand(`"${adbPath}" --version`);
+
+  if (!result.success) {
+    // Try system PATH
+    const pathResult = execCommand("adb --version");
+    if (pathResult.success) {
+      return {
+        name: "Android SDK",
+        status: "ok",
+        installed: true,
+        message: `Android SDK (ADB available via PATH)`,
+      };
+    }
+
+    return {
+      name: "Android SDK",
+      status: "warning",
+      installed: true,
+      message: "ANDROID_HOME set but ADB not accessible.",
+      hint: "Ensure platform-tools is installed in Android SDK.",
+    };
+  }
+
+  return {
+    name: "Android SDK",
+    status: "ok",
+    installed: true,
+    path: androidHome,
+    message: `Android SDK configured`,
+  };
+}
+
+/**
+ * Check for connected device/emulator
+ */
+function checkDevice() {
+  const androidHome = process.env.ANDROID_HOME;
+  let adbCmd = "adb";
+
+  if (androidHome) {
+    adbCmd = `"${path.join(androidHome, "platform-tools", "adb")}"`;
+  }
+
+  const result = execCommand(`${adbCmd} devices`);
+
+  if (!result.success) {
+    return {
+      name: "Device/Emulator",
+      status: "warning",
+      connected: false,
+      message: "Could not check for connected devices.",
+      hint: "Ensure ADB is properly configured.",
+    };
+  }
+
+  // Parse device list
+  const lines = result.output.split("\n").filter((l) => l.trim());
+  const devices = lines
+    .slice(1)
+    .filter((l) => l.includes("device") && !l.includes("offline"))
+    .map((l) => l.split("\t")[0]);
+
+  if (devices.length === 0) {
+    return {
+      name: "Device/Emulator",
+      status: "warning",
+      connected: false,
+      message: "No Android device or emulator connected.",
+      hint: "Start an emulator or connect a device via USB.",
+    };
+  }
+
+  return {
+    name: "Device/Emulator",
+    status: "ok",
+    connected: true,
+    devices: devices,
+    message: `${devices.length} device(s) connected`,
+  };
+}
+
+/**
+ * Run all prerequisite checks
+ * @param {Object} options - Options
+ * @param {boolean} options.exitOnError - Exit process if critical error found
+ * @param {boolean} options.checkDevice - Also check for connected device
+ * @returns {Object} Results object
+ */
+export async function validatePrerequisites(options = {}) {
+  const { exitOnError = true, checkDevice: shouldCheckDevice = false } = options;
+
+  logger.info("Validating prerequisites...");
+
+  const checks = [
+    { fn: checkNodeJs, critical: true },
+    { fn: checkJava, critical: true },
+    { fn: checkMaestro, critical: true },
+    { fn: checkAndroidSdk, critical: false },
+  ];
+
+  if (shouldCheckDevice) {
+    checks.push({ fn: checkDevice, critical: false });
+  }
+
+  const results = [];
+  let hasErrors = false;
+  let hasWarnings = false;
+
+  for (const { fn, critical } of checks) {
+    const result = fn();
+    results.push({ ...result, critical });
+
+    if (result.status === "error") {
+      if (critical) {
+        hasErrors = true;
+        logger.error(`❌ ${result.name}: ${result.message}`);
+      } else {
+        hasWarnings = true;
+        logger.warn(`⚠️ ${result.name}: ${result.message}`);
+      }
+    } else if (result.status === "warning") {
+      hasWarnings = true;
+      logger.warn(`⚠️ ${result.name}: ${result.message}`);
+    } else {
+      logger.info(`✅ ${result.name}: ${result.message}`);
+    }
+  }
+
+  // Collect hints for failed checks
+  const hints = results
+    .filter((r) => r.hint && (r.status === "error" || r.status === "warning"))
+    .map((r) => {
+      // Use Windows hint if available and on Windows
+      if (process.platform === "win32" && r.hintWindows) {
+        return r.hintWindows;
+      }
+      return r.hint;
+    });
+
+  if (hints.length > 0) {
+    logger.info("");
+    logger.info("💡 To fix issues:");
+    hints.forEach((hint) => {
+      logger.info(`   → ${hint}`);
+    });
+  }
+
+  // Handle critical errors
+  if (hasErrors && exitOnError) {
+    logger.error("");
+    logger.error("═══════════════════════════════════════════════════════");
+    logger.error("  CRITICAL: Required prerequisites are missing.");
+    logger.error("  The MCP server cannot start without them.");
+    logger.error("═══════════════════════════════════════════════════════");
+    logger.error("");
+    process.exit(2); // Exit code 2 for infrastructure errors
+  }
+
+  return {
+    success: !hasErrors,
+    hasWarnings,
+    results,
+    hints,
+  };
+}
+
+/**
+ * Quick check for critical prerequisites only
+ * Used for fast startup validation
+ */
+export function quickCheck() {
+  const java = checkJava();
+  const maestro = checkMaestro();
+
+  const errors = [];
+  
+  if (java.status === "error") {
+    errors.push({
+      name: "Java",
+      message: java.message,
+      hint: java.hint,
+    });
+  }
+
+  if (maestro.status === "error") {
+    errors.push({
+      name: "Maestro CLI",
+      message: maestro.message,
+      hint: process.platform === "win32" ? maestro.hintWindows : maestro.hint,
+    });
+  }
+
+  return {
+    success: errors.length === 0,
+    errors,
+  };
+}
+
+export default {
+  validatePrerequisites,
+  quickCheck,
+  checkNodeJs,
+  checkJava,
+  checkMaestro,
+  checkAndroidSdk,
+  checkDevice,
+};
+