mcp-maestro-mobile-ai 1.1.0

package/README.md

@@ -0,0 +1,719 @@
+# MCP Maestro Mobile AI
+
+## AI-Assisted Mobile Automation using Model Context Protocol
+
+An MCP (Model Context Protocol) server that enables AI assistants like **Claude**, **Copilot**, and other LLMs to run mobile automation tests using **Maestro**. Features **app context training** for improved test generation accuracy.
+
+[![npm version](https://badge.fury.io/js/mcp-maestro-mobile-ai.svg)](https://www.npmjs.com/package/mcp-maestro-mobile-ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 📚 Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Enterprise Readiness](./docs/ENTERPRISE_READINESS.md) | Architecture, security model, compliance |
+| [Security Model](./docs/SECURITY.md) | Execution boundaries, threat model, best practices |
+| [Privacy Policy](./docs/PRIVACY.md) | Data handling, no telemetry statement |
+| [Changelog](./CHANGELOG.md) | Version history, release notes |
+| [Roadmap](./ROADMAP.md) | Future plans, feature timeline |
+| [Contributing](./CONTRIBUTING.md) | How to contribute |
+
+---
+
+## 🎯 What This Does
+
+**Testers write simple prompts → AI generates and runs tests automatically**
+
+```txt
+# prompts/my-tests.txt
+Test that user can login with valid credentials
+Test that search shows results for "TechGuru"
+Test that user can logout successfully
+```
+
+```
+You: "Run tests from prompts/my-tests.txt"
+
+AI: Reading prompts... Found 3 tests.
+    [1/3] Generating login test... ✅ PASSED
+    [2/3] Generating search test... ✅ PASSED
+    [3/3] Generating logout test... ❌ FAILED
+
+    Results: 2 passed, 1 failed
+```
+
+---
+
+## 🚀 Installation Options
+
+### Prerequisites (Required for all methods)
+
+- **Node.js 18+**
+- **Java 17+** (for Maestro)
+- **Maestro CLI** installed ([Installation Guide](https://maestro.mobile.dev/getting-started/installing-maestro))
+- **Android Emulator** or physical device connected via USB
+- **Cursor**, **Claude Desktop**, or **VS Code with GitHub Copilot**
+
+---
+
+### 📦 Option 1: NPX (Zero Install - Recommended)
+
+Run directly without installing:
+
+```bash
+npx mcp-maestro-mobile-ai
+```
+
+Then configure your AI client (see [MCP Configuration](#️-mcp-configuration) below).
+
+---
+
+### 📦 Option 2: Global Install via NPM
+
+```bash
+# Install globally
+npm install -g mcp-maestro-mobile-ai
+
+# Run the server
+maestro-mcp
+```
+
+---
+
+### 📦 Option 3: Clone from GitHub
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/krunal-mahera/mcp-maestro-mobile-ai.git
+cd mcp-maestro-mobile-ai
+
+# 2. Install dependencies
+npm install
+
+# 3. Run the server
+npm start
+```
+
+---
+
+## ⚙️ MCP Configuration
+
+Configure your AI client to use the Maestro MCP server.
+
+### 🔧 Cursor Setup
+
+#### Step 1: Locate Config File
+
+| OS          | Config File Location             |
+| ----------- | -------------------------------- |
+| **Windows** | `%USERPROFILE%\.cursor\mcp.json` |
+| **macOS**   | `~/.cursor/mcp.json`             |
+| **Linux**   | `~/.cursor/mcp.json`             |
+
+#### Step 2: Add Configuration
+
+**If installed via NPM (global):**
+
+```json
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "maestro-mcp",
+      "env": {
+        "APP_ID": "com.your.app.package"
+      }
+    }
+  }
+}
+```
+
+**If using NPX (no install):**
+
+```json
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "npx",
+      "args": ["mcp-maestro-mobile-ai"],
+      "env": {
+        "APP_ID": "com.your.app.package"
+      }
+    }
+  }
+}
+```
+
+**If cloned from GitHub:**
+
+```json
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "node",
+      "args": ["/path/to/mcp-maestro-mobile-ai/src/mcp-server/index.js"],
+      "env": {
+        "APP_ID": "com.your.app.package"
+      }
+    }
+  }
+}
+```
+
+#### Step 3: Restart Cursor
+
+Close and reopen Cursor completely for the changes to take effect.
+
+#### Step 4: Verify
+
+In Cursor's AI chat, type:
+
+```
+List the available MCP tools for maestro
+```
+
+---
+
+### 🔧 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"
+      }
+    }
+  }
+}
+```
+
+---
+
+### 🔧 VS Code with GitHub Copilot
+
+Add to VS Code settings (Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"):
+
+```json
+{
+  "github.copilot.chat.mcpServers": {
+    "maestro": {
+      "command": "npx",
+      "args": ["mcp-maestro-mobile-ai"],
+      "env": {
+        "APP_ID": "com.your.app.package"
+      }
+    }
+  }
+}
+```
+
+> 📝 **Note:** GitHub Copilot MCP support may vary by version.
+
+---
+
+## ✅ Verify Your Setup
+
+### Test 1: Check Configuration
+
+Ask the AI:
+
+```
+Get the maestro app configuration
+```
+
+Expected response:
+
+```json
+{
+  "success": true,
+  "config": {
+    "appId": "com.google.android.youtube",
+    "platform": "android"
+  }
+}
+```
+
+### Test 2: List Prompt Files
+
+Ask the AI:
+
+```
+List available prompt files in the maestro server
+```
+
+### Test 3: Run a Simple Test
+
+Make sure your Android emulator is running, then ask:
+
+```
+Run a test: Open YouTube and search for TechGuru
+```
+
+---
+
+## 📝 Usage Guide
+
+### For Testers - Creating Test Prompts
+
+1. **Create a prompt file** in the `prompts/` folder:
+
+```txt
+# prompts/my-app-tests.txt
+
+# Login Tests
+Test that user can login with valid email and password
+Test that login fails with incorrect password
+Test that forgot password link works
+
+# Dashboard Tests
+Test that dashboard shows user name after login
+Test that notifications icon is visible
+```
+
+2. **Ask the AI to run**:
+
+```
+Run tests from prompts/my-app-tests.txt
+```
+
+3. **AI handles everything**:
+   - ✅ Reads prompts
+   - ✅ Generates Maestro YAML
+   - ✅ Validates YAML
+   - ✅ Runs tests on emulator
+   - ✅ Reports results
+
+### 🧠 App Context Training (NEW!)
+
+The AI might not know your app's exact UI elements. **Train it** by registering your app's elements for much better test generation:
+
+**Step 1: Register UI Elements**
+
+Tell the AI:
+
+```
+Register these elements for app "com.myapp":
+{
+  "usernameInput": {
+    "testId": "login-username-input",
+    "accessibilityLabel": "Username",
+    "type": "textfield"
+  },
+  "passwordInput": {
+    "testId": "login-password-input", 
+    "accessibilityLabel": "Password",
+    "type": "textfield"
+  },
+  "loginButton": {
+    "testId": "login-submit-btn",
+    "text": "Sign In",
+    "type": "button"
+  }
+}
+```
+
+**Step 2: Register Screens (Optional)**
+
+```
+Register screen "LoginScreen" for app "com.myapp" with:
+- description: "Main login screen with email and password"
+- elements: ["usernameInput", "passwordInput", "loginButton"]
+- actions: ["login", "forgotPassword", "signUp"]
+```
+
+**Step 3: Save Successful Flows**
+
+After a test passes, save it as a pattern:
+
+```
+Save this successful flow for "com.myapp" as "login-flow"
+```
+
+The AI will use this pattern for similar tests in the future!
+
+**Step 4: Get Context Before Tests**
+
+Always get context before generating tests:
+
+```
+Get AI context for app "com.myapp", then run a login test
+```
+
+This gives the AI all the element names and patterns it needs.
+
+---
+
+### Tips for Writing Good Prompts
+
+✅ **Good prompts:**
+
+```
+Test that user can login with valid email "test@example.com" and password "Test123"
+Test that search results show products matching "shoes"
+Test that error message appears when password is less than 6 characters
+Test that user can navigate from home screen to settings
+```
+
+❌ **Bad prompts:**
+
+```
+Test login          (too vague)
+Click button        (not a test case)
+Check the app       (unclear expectation)
+```
+
+---
+
+## 🔧 Available MCP Tools (14 Tools)
+
+### Prompt Tools
+
+| Tool                | Description                            |
+| ------------------- | -------------------------------------- |
+| `read_prompt_file`  | Read test prompts from a .txt/.md file |
+| `list_prompt_files` | List available prompt files            |
+
+### Device Management Tools
+
+| Tool            | Description                                   |
+| --------------- | --------------------------------------------- |
+| `list_devices`  | List all connected Android devices/emulators  |
+| `select_device` | Select a specific device for test execution   |
+| `clear_device`  | Clear device selection (use first available)  |
+| `check_device`  | Check if Android emulator/device is connected |
+| `check_app`     | Verify app is installed on device             |
+
+### Test Execution Tools
+
+| Tool                    | Description                                 |
+| ----------------------- | ------------------------------------------- |
+| `validate_maestro_yaml` | Validate Maestro YAML syntax                |
+| `run_test`              | Run a single test (with auto-retry support) |
+| `run_test_suite`        | Run multiple tests in sequence              |
+
+### Configuration & Utility Tools
+
+| Tool               | Description                        |
+| ------------------ | ---------------------------------- |
+| `get_app_config`   | Get app configuration and settings |
+| `get_test_results` | Get results from last run          |
+| `take_screenshot`  | Capture device screen              |
+| `cleanup_results`  | Clean up old test results          |
+
+---
+
+## 📁 Project Structure
+
+```
+maestro-mcp-server/
+├── prompts/                      # ⭐ TESTERS CREATE FILES HERE
+│   ├── example-login-tests.txt
+│   └── example-youtube-tests.txt
+│
+├── src/mcp-server/               # MCP Server (don't modify)
+│   ├── index.js
+│   ├── tools/
+│   └── utils/
+│
+├── output/                       # Test outputs
+│   ├── logs/
+│   ├── screenshots/
+│   └── results/
+│
+├── config/
+│   └── maestro.config.yaml
+│
+├── docs/
+│   ├── MCP_SETUP.md
+│   └── REACT_NATIVE_AUTOMATION_GUIDELINES.md
+│
+├── mcp-config-cursor.json        # Ready-to-use Cursor config
+├── mcp-config-vscode.json        # Ready-to-use VS Code config
+├── env.example
+├── package.json
+└── README.md
+```
+
+---
+
+## ⚙️ Environment Configuration
+
+### Required Variables
+
+| Variable | Description                 | Example                      |
+| -------- | --------------------------- | ---------------------------- |
+| `APP_ID` | Package name of app to test | `com.google.android.youtube` |
+
+### Test Execution Settings
+
+| Variable               | Description                             | Default |
+| ---------------------- | --------------------------------------- | ------- |
+| `DEFAULT_WAIT_TIMEOUT` | Default wait timeout in ms              | `10000` |
+| `DEFAULT_RETRIES`      | Auto-retry count for failed tests       | `1`     |
+| `MAX_RESULTS`          | Max result files to keep (auto-cleanup) | `50`    |
+
+### Optional Variables
+
+| Variable        | Description         | Default          |
+| --------------- | ------------------- | ---------------- |
+| `ANDROID_HOME`  | Path to Android SDK | Auto-detected    |
+| `EMULATOR_NAME` | Preferred emulator  | Default emulator |
+| `PLATFORM`      | Target platform     | `android`        |
+| `LOG_LEVEL`     | Logging level       | `info`           |
+
+---
+
+## ✨ New Features (v2.1.0)
+
+### 🔌 Device Check
+
+Before running tests, verify your device is connected:
+
+```
+Check if my device is connected
+```
+
+### 📱 App Check
+
+Verify the app is installed before testing:
+
+```
+Check if YouTube app is installed
+```
+
+### 🔄 Auto-Retry
+
+Failed tests are automatically retried based on `DEFAULT_RETRIES` setting:
+
+- Set `DEFAULT_RETRIES=2` to retry failed tests twice
+- Reduces flaky test failures
+
+### 🧹 Result Cleanup
+
+Old results are automatically cleaned up:
+
+- Keeps last 50 results by default (configurable via `MAX_RESULTS`)
+- Use `cleanup_results` tool for manual cleanup
+
+### 💬 Improved Error Messages
+
+Errors now include:
+
+- Clear descriptions of what went wrong
+- Hints for how to fix the issue
+- Automatic screenshots on failure
+
+---
+
+## 🔍 Troubleshooting
+
+### "Tools not appearing in Cursor/VS Code"
+
+1. Verify the path in your MCP config is correct
+2. Restart your editor completely
+3. Check `output/logs/mcp-server.log` for errors
+
+### "APP_ID not configured"
+
+Set `APP_ID` in either:
+
+- The MCP config's `env` section, OR
+- A `.env` file in the project root
+
+### "No emulator connected"
+
+1. Start Android emulator from Android Studio
+2. Verify with: `adb devices`
+
+### "Element not found" during test
+
+The AI-generated selector might not match. Ask the AI to:
+
+- Use different selectors (text-based instead of ID-based)
+- Add more wait time with `extendedWaitUntil`
+- Use `maestro studio` to inspect elements
+
+### "Java version error"
+
+Maestro requires Java 17+. Check with:
+
+```bash
+java -version
+```
+
+---
+
+## 🧪 Example Session
+
+```
+You: List the prompt files
+
+AI: 📂 Found 2 prompt files:
+    - example-login-tests.txt (5 prompts)
+    - example-youtube-tests.txt (4 prompts)
+
+You: Run tests from prompts/example-youtube-tests.txt
+
+AI: 📂 Reading prompts...
+    Found 4 test prompts.
+
+    [1/4] "Test that user can open YouTube and search for TechGuru"
+          🔧 Generating Maestro YAML...
+          ✓ Validating YAML...
+          🚀 Running test...
+          ✅ PASSED (3.2s)
+
+    [2/4] "Test that user can play the first video"
+          🔧 Generating Maestro YAML...
+          ✓ Validating YAML...
+          🚀 Running test...
+          ✅ PASSED (5.1s)
+
+    [3/4] "Test that user can pause and resume"
+          🔧 Generating Maestro YAML...
+          ✓ Validating YAML...
+          🚀 Running test...
+          ✅ PASSED (4.3s)
+
+    [4/4] "Test that user can subscribe"
+          🔧 Generating Maestro YAML...
+          ✓ Validating YAML...
+          🚀 Running test...
+          ❌ FAILED (2.1s)
+          📸 Screenshot saved
+
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    📊 Results: 3 passed, 1 failed
+    📄 Report: output/results/latest.json
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+You: What failed in test 4?
+
+AI: Test 4 failed because the "Subscribe" button was not found.
+    The screenshot shows the video is still loading.
+
+    Would you like me to retry with more wait time?
+```
+
+---
+
+## 📚 Additional Resources
+
+- [Maestro Documentation](https://maestro.mobile.dev/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [React Native Automation Guidelines](./docs/REACT_NATIVE_AUTOMATION_GUIDELINES.md)
+- [MCP Setup Guide](./docs/MCP_SETUP.md)
+
+---
+
+## 🤝 For Other Projects
+
+To use this MCP server with a different app:
+
+1. Update `APP_ID` in your MCP config or `.env` file
+2. Create new prompt files in `prompts/` folder specific to your app
+3. The AI will generate tests based on your app's UI
+
+---
+
+## 📦 Publishing to NPM (For Maintainers)
+
+To publish this package to npm:
+
+### 1. Update Package Name
+
+Edit `package.json` and set your own npm scope:
+
+```json
+{
+  "name": "@your-org/maestro-mcp",
+  "version": "1.0.0"
+}
+```
+
+### 2. Login to NPM
+
+```bash
+npm login
+```
+
+### 3. Publish
+
+```bash
+# First time (create new package)
+npm publish --access public
+
+# Updates
+npm version patch  # or minor, major
+npm publish
+```
+
+### 4. Users Can Then Install Via
+
+```bash
+# Global install
+npm install -g @your-org/maestro-mcp
+
+# Or run directly
+npx @your-org/maestro-mcp
+```
+
+---
+
+## 🌟 GitHub Repository Setup
+
+### Recommended Repository Structure
+
+```
+your-org/maestro-mcp
+├── .github/
+│   ├── workflows/
+│   │   ├── publish.yml       # Auto-publish to npm on release
+│   │   └── test.yml          # CI tests
+│   └── ISSUE_TEMPLATE/
+├── src/
+├── prompts/
+├── README.md
+├── LICENSE
+└── package.json
+```
+
+### GitHub Actions: Auto-Publish to NPM
+
+Create `.github/workflows/publish.yml`:
+
+```yaml
+name: Publish to NPM
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+Then add `NPM_TOKEN` secret in your GitHub repository settings.
+
+---
+
+## 📜 License
+
+MIT License