mcp-maestro-mobile-ai 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -15,6 +15,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.2.0] - 2025-01-06
+
+### Added
+- **YAML Generation Instructions System**: Ensures consistent YAML generation across different environments
+  - `get_yaml_instructions` - AI MUST call this before generating YAML (provides exact rules)
+  - `validate_yaml_structure` - Validates YAML for common issues (like missing tapOn before inputText)
+  - `get_test_pattern` - Get standard patterns for login, search, navigation, form tests
+- **Critical Fix**: Input text pattern now enforced - prevents password going to username field issue
+- Standard test patterns for common scenarios (login, search, navigation, form)
+
+### Fixed
+- YAML generation inconsistency between different environments
+- Text input going to wrong fields due to missing tapOn commands
+
+---
+
+## [1.1.1] - 2025-01-06
+
+### Fixed
+- Version bump for npm publish
+
+---
+
 ## [1.1.0] - 2025-01-06
 
 ### Changed
@@ -23,6 +46,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.3.0",
     "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": [