mcp-maestro-mobile-ai 1.1.0

package/docs/MCP_SETUP.md

@@ -0,0 +1,180 @@
+# MCP Server Setup Guide
+
+## Setting up Maestro MCP Server with AI Clients
+
+This guide explains how to configure the Maestro MCP 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`
+
+---
+
+## Cursor Setup
+
+### 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:
+
+```json
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "node",
+      "args": ["C:/path/to/ai-automation-mobile/src/mcp-server/index.js"],
+      "env": {
+        "APP_ID": "com.google.android.youtube"
+      }
+    }
+  }
+}
+```
+
+**Important:** Replace the path with your actual project path.
+
+### Step 3: Restart Cursor
+
+Close and reopen Cursor for the changes to take effect.
+
+### Step 4: Verify
+
+In Cursor's AI chat, type:
+```
+List the available MCP tools
+```
+
+You should see the Maestro tools listed.
+
+---
+
+## VS Code with GitHub Copilot
+
+### Option 1: Copilot MCP Extension (if available)
+
+If there's an MCP extension for VS Code Copilot, configure it similarly to Cursor.
+
+### Option 2: Run Server Manually
+
+1. Start the MCP server:
+   ```bash
+   cd C:\Krunal\Practice\ai-automation-mobile
+   npm start
+   ```
+
+2. The server will run on stdio and can be connected to compatible clients.
+
+---
+
+## Testing the Setup
+
+### 1. Check Configuration
+
+Ask the AI:
+```
+Get the app configuration
+```
+
+Expected response:
+```json
+{
+  "success": true,
+  "config": {
+    "appId": "com.google.android.youtube",
+    "platform": "android"
+  }
+}
+```
+
+### 2. List Prompt Files
+
+Ask the AI:
+```
+List available prompt files
+```
+
+### 3. Run a Test
+
+Ask the AI:
+```
+Run a test: "Test that user can open YouTube and search for TechGuru"
+```
+
+---
+
+## Environment Variables
+
+You can pass environment variables in the MCP config:
+
+```json
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "node",
+      "args": ["path/to/src/mcp-server/index.js"],
+      "env": {
+        "APP_ID": "com.mycompany.myapp",
+        "ANDROID_HOME": "C:/Users/Me/Android/Sdk",
+        "LOG_LEVEL": "debug"
+      }
+    }
+  }
+}
+```
+
+Or create a `.env` file in the project root.
+
+---
+
+## Troubleshooting
+
+### 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`
+
+### Tools not appearing
+
+1. Restart your editor
+2. Check the MCP config path is correct
+3. Verify the server path in the config
+
+### Tests fail with "No emulator"
+
+1. Start an Android emulator
+2. Verify with `adb devices`
+
+### "APP_ID not configured"
+
+Set the `APP_ID` in either:
+- The MCP config's `env` section
+- A `.env` file in the project root
+
+---
+
+## 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 |
+

package/docs/PRIVACY.md

@@ -0,0 +1,198 @@
+# Privacy Policy
+
+> **Maestro MCP Server** - Data Privacy Statement
+
+---
+
+## Summary
+
+**Maestro MCP does not collect, transmit, or store any user data externally.**
+
+All operations are performed locally on your machine. No data is sent to external servers, cloud services, or third parties.
+
+---
+
+## Data Collection
+
+### What We DO NOT Collect
+
+| Data Type | Collected? | Notes |
+|-----------|------------|-------|
+| Personal information | ❌ No | Never collected |
+| Usage analytics | ❌ No | No tracking |
+| Crash reports | ❌ No | Not sent anywhere |
+| Test results | ❌ No | Stays local |
+| Screenshots | ❌ No | Stays local |
+| Device information | ❌ No | Not transmitted |
+| IP addresses | ❌ No | No network calls |
+
+### What Stays Local
+
+| Data Type | Location | Purpose |
+|-----------|----------|---------|
+| Test results | `output/results/` | Test history |
+| Screenshots | `output/screenshots/` | Failure debugging |
+| Logs | `output/logs/` | Troubleshooting |
+| Configuration | `.env` | Your settings |
+
+---
+
+## Network Activity
+
+### External Connections
+
+**Maestro MCP makes ZERO external network connections.**
+
+The only network activity is:
+
+1. **npm install** - When you install the package (npm registry)
+2. **ADB** - Local connection to Android device/emulator
+
+### No Telemetry
+
+- ❌ No usage statistics sent
+- ❌ No error reports sent
+- ❌ No heartbeats or pings
+- ❌ No update checks (beyond npm)
+- ❌ No analytics of any kind
+
+---
+
+## Third-Party Services
+
+### Dependencies
+
+Maestro MCP uses the following npm packages:
+
+| Package | Purpose | Privacy |
+|---------|---------|---------|
+| @modelcontextprotocol/sdk | MCP protocol | No telemetry |
+| winston | Logging | Local only |
+| js-yaml | YAML parsing | Local only |
+| zod | Validation | Local only |
+| dotenv | Config loading | Local only |
+
+None of these dependencies collect or transmit data.
+
+### External Tools
+
+| Tool | Privacy |
+|------|---------|
+| Maestro CLI | Local execution only |
+| ADB | Local device communication |
+| Android Emulator | Local execution |
+
+---
+
+## Your Data
+
+### Data Ownership
+
+- **You own all data** generated by Maestro MCP
+- Test results, screenshots, and logs are yours
+- You control retention and deletion
+
+### Data Location
+
+All data is stored in your project directory:
+
+```
+your-project/
+├── output/
+│   ├── results/      ← Your test results
+│   ├── screenshots/  ← Your screenshots
+│   └── logs/         ← Your logs
+└── .env              ← Your configuration
+```
+
+### Data Deletion
+
+You can delete all generated data at any time:
+
+```bash
+# Delete all results
+rm -rf output/
+
+# Or use the cleanup tool
+cleanup_results --keepLast 0 --deleteScreenshots true
+```
+
+---
+
+## Screenshots & Sensitive Data
+
+### Warning
+
+Screenshots captured during testing may contain:
+
+- Personal information visible on screen
+- Authentication credentials
+- Financial data
+- Health information
+- Business confidential information
+
+### Recommendations
+
+1. **Use test accounts** with fake data
+2. **Review screenshots** before sharing
+3. **Implement cleanup policies** for old screenshots
+4. **Do not commit** screenshots to version control
+5. **Mask sensitive data** in test applications
+
+---
+
+## Compliance
+
+### GDPR
+
+Maestro MCP is GDPR-friendly:
+
+- ✅ No personal data collection
+- ✅ No data processing
+- ✅ No data transfer
+- ✅ Full user control
+
+### CCPA
+
+Maestro MCP complies with CCPA:
+
+- ✅ No sale of personal information
+- ✅ No data collection to sell
+- ✅ Complete transparency
+
+### Other Regulations
+
+| Regulation | Status |
+|------------|--------|
+| GDPR | ✅ Compatible |
+| CCPA | ✅ Compatible |
+| HIPAA | ⚠️ User responsibility* |
+| PCI DSS | ⚠️ User responsibility* |
+| SOC 2 | ✅ Compatible (no cloud) |
+
+*Screenshots may contain regulated data - user must manage appropriately.
+
+---
+
+## Contact
+
+For privacy inquiries:
+
+- **GitHub Issues**: [Public questions](https://github.com/krunal-mahera/mcp-maestro-mobile-ai/issues)
+- **Email**: For sensitive privacy matters
+
+---
+
+## Changes to This Policy
+
+We will update this policy as needed. Changes will be:
+
+- Documented in CHANGELOG.md
+- Announced in release notes
+- Effective immediately upon publication
+
+---
+
+*Last Updated: January 2025*
+*Version: 1.0.0*
+