npm - mcp-maestro-mobile-ai - Versions diffs - 1.1.0 - Mend

mcp-maestro-mobile-ai 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/CHANGELOG.md +114 -0
package/CONTRIBUTING.md +417 -0
package/LICENSE +22 -0
package/README.md +719 -0
package/ROADMAP.md +239 -0
package/docs/ENTERPRISE_READINESS.md +545 -0
package/docs/MCP_SETUP.md +180 -0
package/docs/PRIVACY.md +198 -0
package/docs/REACT_NATIVE_AUTOMATION_GUIDELINES.md +584 -0
package/docs/SECURITY.md +573 -0
package/package.json +69 -0
package/prompts/example-login-tests.txt +9 -0
package/prompts/example-youtube-tests.txt +8 -0
package/src/mcp-server/index.js +625 -0
package/src/mcp-server/tools/contextTools.js +194 -0
package/src/mcp-server/tools/promptTools.js +191 -0
package/src/mcp-server/tools/runTools.js +357 -0
package/src/mcp-server/tools/utilityTools.js +721 -0
package/src/mcp-server/tools/validateTools.js +220 -0
package/src/mcp-server/utils/appContext.js +295 -0
package/src/mcp-server/utils/logger.js +52 -0
package/src/mcp-server/utils/maestro.js +508 -0
package/templates/mcp-config-claude-desktop.json +15 -0
package/templates/mcp-config-cursor.json +15 -0
package/templates/mcp-config-vscode.json +13 -0

package/docs/ENTERPRISE_READINESS.md ADDED Viewed

@@ -0,0 +1,545 @@
+# Enterprise Readiness Guide
+> **Maestro MCP Server** - AI-Assisted Mobile Automation
+This document provides enterprise decision-makers with a comprehensive overview of Maestro MCP's architecture, security model, operational characteristics, and roadmap.
+---
+## Table of Contents
+1. [Executive Summary](#executive-summary)
+2. [Architecture Overview](#architecture-overview)
+3. [Security Model](#security-model)
+4. [Execution Model](#execution-model)
+5. [Data Handling](#data-handling)
+6. [Configuration & Governance](#configuration--governance)
+7. [Reliability & Stability](#reliability--stability)
+8. [CI/CD Integration](#cicd-integration)
+9. [Compliance & Legal](#compliance--legal)
+10. [Known Limitations](#known-limitations)
+11. [Support & Maintenance](#support--maintenance)
+12. [Roadmap](#roadmap)
+---
+## Executive Summary
+### What Is Maestro MCP?
+Maestro MCP is a **Model Context Protocol (MCP) server** that enables AI assistants (Claude, GitHub Copilot, Cursor) to execute mobile UI tests using the [Maestro](https://maestro.mobile.dev) framework.
+### Key Value Proposition
+| Traditional Approach                 | With Maestro MCP                   |
+| ------------------------------------ | ---------------------------------- |
+| Write detailed test scripts manually | Describe tests in natural language |
+| Learn Maestro YAML syntax            | AI generates valid YAML            |
+| Debug selector issues                | AI adapts selectors automatically  |
+| Maintain test suites                 | Prompts are maintainable English   |
+### Enterprise Suitability
+| Criteria              | Status | Notes                             |
+| --------------------- | ------ | --------------------------------- |
+| Local Execution       | ✅     | All operations run locally        |
+| No Cloud Dependencies | ✅     | No external API calls required    |
+| No Telemetry          | ✅     | Zero data collection              |
+| Open Source           | ✅     | MIT License                       |
+| Audit Trail           | ✅     | All runs logged with full context |
+| CI/CD Compatible      | ✅     | Exit codes, JSON/JUnit output     |
+---
+## Architecture Overview
+### High-Level Architecture
+```
+┌─────────────────────────────────────────────────────────┐
+│                    AI Client Layer                       │
+│  (Cursor / Claude Desktop / VS Code Copilot)            │
+└─────────────────────────┬───────────────────────────────┘
+                          │ MCP Protocol (stdio)
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                  Maestro MCP Server                      │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
+│  │ Prompt      │  │ Validation  │  │ Execution   │     │
+│  │ Tools       │  │ Tools       │  │ Tools       │     │
+│  └─────────────┘  └─────────────┘  └─────────────┘     │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
+│  │ Device      │  │ Config      │  │ Reporting   │     │
+│  │ Management  │  │ Management  │  │ Tools       │     │
+│  └─────────────┘  └─────────────┘  └─────────────┘     │
+└─────────────────────────┬───────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                   Maestro CLI                            │
+│              (Mobile UI Automation)                      │
+└─────────────────────────┬───────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│              Android Device / Emulator                   │
+│                  (via ADB)                              │
+└─────────────────────────────────────────────────────────┘
+```
+### Component Responsibilities
+| Component       | Responsibility                                       |
+| --------------- | ---------------------------------------------------- |
+| **AI Client**   | Natural language interpretation, YAML generation     |
+| **MCP Server**  | Tool orchestration, validation, execution management |
+| **Maestro CLI** | Mobile UI automation, device interaction             |
+| **ADB**         | Android device communication                         |
+### Data Flow
+```
+1. User → "Test that user can login"
+2. AI Client → Generates Maestro YAML
+3. MCP Server → Validates YAML syntax
+4. MCP Server → Checks device connection
+5. MCP Server → Checks app installation
+6. MCP Server → Executes via Maestro CLI
+7. MCP Server → Captures results & screenshots
+8. MCP Server → Returns structured response
+9. AI Client → Presents results to user
+```
+---
+## Security Model
+> **Detailed security information: See [SECURITY.md](./SECURITY.md)**
+### Execution Boundaries
+| Operation                 | Allowed            | Restricted     |
+| ------------------------- | ------------------ | -------------- |
+| Maestro test execution    | ✅                 | -              |
+| Screenshot capture        | ✅                 | -              |
+| Device listing            | ✅                 | -              |
+| App installation check    | ✅                 | -              |
+| System-level ADB commands | -                  | ✅ (Safe Mode) |
+| File system access        | Limited to output/ | ✅             |
+| Network access            | None               | ✅             |
+### Trust Model
+```
+┌────────────────────────────────────────┐
+│           Trust Boundary               │
+│  ┌──────────────────────────────────┐  │
+│  │     Local Machine Only           │  │
+│  │  • No external API calls         │  │
+│  │  • No cloud storage              │  │
+│  │  • No telemetry                  │  │
+│  └──────────────────────────────────┘  │
+└────────────────────────────────────────┘
+```
+### Authentication & Authorization
+| Feature             | Current State    | Roadmap          |
+| ------------------- | ---------------- | ---------------- |
+| User Authentication | N/A (local tool) | Planned for SaaS |
+| Role-Based Access   | Design ready     | Q2 2025          |
+| API Keys            | N/A              | Planned for SaaS |
+| SSO Integration     | N/A              | Planned for SaaS |
+---
+## Execution Model
+### Test Execution Flow
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Prompt    │────▶│  Validate   │────▶│   Execute   │
+│   Input     │     │   YAML      │     │   Test      │
+└─────────────┘     └─────────────┘     └─────────────┘
+                           │                   │
+                           ▼                   ▼
+                    ┌─────────────┐     ┌─────────────┐
+                    │   Reject    │     │   Retry     │
+                    │   Invalid   │     │   on Fail   │
+                    └─────────────┘     └─────────────┘
+```
+### Pre-Flight Checks
+Before every test execution:
+1. ✅ **Device Connection** - Verify Android device/emulator is connected
+2. ✅ **App Installation** - Verify target app is installed
+3. ✅ **YAML Validation** - Validate Maestro YAML syntax
+4. ✅ **Configuration Check** - Verify required settings
+### Retry Mechanism
+| Setting               | Default    | Description                     |
+| --------------------- | ---------- | ------------------------------- |
+| `DEFAULT_RETRIES`     | 1          | Automatic retries on failure    |
+| Retry Delay           | 2 seconds  | Wait between retries            |
+| Screenshot on Failure | ✅ Enabled | Capture screen on final failure |
+### Timeout Governance
+| Timeout          | Default    | Configurable           |
+| ---------------- | ---------- | ---------------------- |
+| Test execution   | 5 minutes  | Via Maestro config     |
+| Wait for element | 10 seconds | `DEFAULT_WAIT_TIMEOUT` |
+| ADB commands     | 10 seconds | Hardcoded              |
+---
+## Data Handling
+### Data Storage
+| Data Type    | Location              | Retention         | Sensitive |
+| ------------ | --------------------- | ----------------- | --------- |
+| Test results | `output/results/`     | Configurable      | No        |
+| Screenshots  | `output/screenshots/` | Configurable      | Possible  |
+| Logs         | `output/logs/`        | Session           | No        |
+| Temp YAML    | `.temp/`              | Deleted after run | No        |
+### Data Lifecycle
+```
+Test Run Started
+    │
+    ├── Temp YAML created (.temp/)
+    │
+    ├── Test executed
+    │
+    ├── Results saved (output/results/)
+    │
+    ├── Screenshot captured (if failed)
+    │
+    ├── Temp YAML deleted
+    │
+    └── Auto-cleanup of old results (MAX_RESULTS)
+```
+### Data Retention Policy
+| Setting              | Default         | Description                  |
+| -------------------- | --------------- | ---------------------------- |
+| `MAX_RESULTS`        | 50              | Maximum result files to keep |
+| Screenshot retention | Same as results | Cleaned with results         |
+| Log rotation         | Manual          | Logs grow unbounded          |
+### Data Privacy
+- ❌ **No telemetry** - Zero data sent externally
+- ❌ **No analytics** - No usage tracking
+- ❌ **No cloud sync** - All data stays local
+- ✅ **User control** - Full control over all data
+---
+## Configuration & Governance
+### Configuration Hierarchy
+```
+Priority (highest to lowest):
+1. Tool arguments (runtime)
+2. Environment variables
+3. .env file (project)
+4. Built-in defaults
+```
+### Required Configuration
+| Variable       | Required    | Description           |
+| -------------- | ----------- | --------------------- |
+| `APP_ID`       | ✅ Yes      | Target app package ID |
+| `ANDROID_HOME` | Recommended | Android SDK path      |
+### Optional Configuration
+| Variable               | Default | Description                   |
+| ---------------------- | ------- | ----------------------------- |
+| `DEFAULT_WAIT_TIMEOUT` | 10000   | Element wait timeout (ms)     |
+| `DEFAULT_RETRIES`      | 1       | Auto-retry count              |
+| `MAX_RESULTS`          | 50      | Result file limit             |
+| `SAFE_MODE`            | true    | Restrict dangerous operations |
+| `LOG_LEVEL`            | info    | Logging verbosity             |
+### Configuration Validation
+The server validates configuration at startup:
+- ✅ Required variables present
+- ✅ Valid format for known variables
+- ✅ Device connectivity
+- ⚠️ Warnings for recommended settings
+---
+## Reliability & Stability
+### Health Checks
+| Check                | Frequency | Action on Failure     |
+| -------------------- | --------- | --------------------- |
+| Device connection    | Per test  | Fail with clear error |
+| App installation     | Per test  | Fail with hint        |
+| Maestro availability | Startup   | Exit with error       |
+| ADB availability     | Startup   | Exit with error       |
+### Error Handling
+| Error Type           | Handling         | User Feedback           |
+| -------------------- | ---------------- | ----------------------- |
+| Device not connected | Fail fast        | "Start emulator" hint   |
+| App not installed    | Fail fast        | "Install app" hint      |
+| Element not found    | Retry, then fail | Screenshot + suggestion |
+| Timeout              | Retry, then fail | Increased timeout hint  |
+| YAML syntax error    | Reject           | Specific error location |
+### Stability Features
+- ✅ Graceful error handling (no crashes)
+- ✅ Automatic retry on transient failures
+- ✅ Resource cleanup (temp files)
+- ✅ Memory-efficient result storage
+---
+## CI/CD Integration
+### Supported CI Systems
+| CI System      | Support Level | Notes               |
+| -------------- | ------------- | ------------------- |
+| GitHub Actions | ✅ Full       | Native support      |
+| GitLab CI      | ✅ Full       | Standard Node.js    |
+| Jenkins        | ✅ Full       | Pipeline compatible |
+| Azure DevOps   | ✅ Full       | YAML pipelines      |
+| CircleCI       | ✅ Full       | Docker-based        |
+### Exit Codes
+| Code | Meaning                                |
+| ---- | -------------------------------------- |
+| 0    | All tests passed                       |
+| 1    | One or more tests failed               |
+| 2    | Infrastructure error (no device, etc.) |
+### Output Formats
+| Format    | Status       | Use Case               |
+| --------- | ------------ | ---------------------- |
+| JSON      | ✅ Available | Programmatic access    |
+| JUnit XML | 🔜 Roadmap   | CI test reporting      |
+| HTML      | 🔜 Roadmap   | Human-readable reports |
+### Example: GitHub Actions
+```yaml
+name: Mobile Tests
+on: [push]
+jobs:
+  test:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Android Emulator
+        uses: reactivecircus/android-emulator-runner@v2
+        with:
+          api-level: 33
+          script: |
+            npm install -g @anthropic/maestro-mcp
+            maestro-mcp run --ci --prompt-file tests.txt
+```
+---
+## Compliance & Legal
+### License
+**MIT License** - Full text in [LICENSE](../LICENSE)
+Key permissions:
+- ✅ Commercial use
+- ✅ Modification
+- ✅ Distribution
+- ✅ Private use
+### Data Compliance
+| Regulation | Applicability       | Notes                       |
+| ---------- | ------------------- | --------------------------- |
+| GDPR       | N/A                 | No personal data collected  |
+| SOC 2      | Local tool          | No cloud infrastructure     |
+| HIPAA      | User responsibility | Screenshots may contain PHI |
+| PCI DSS    | User responsibility | Screenshots may contain PAN |
+### Telemetry Statement
+> **Maestro MCP collects zero telemetry data.**
+>
+> - No usage statistics
+> - No crash reports
+> - No analytics
+> - No network calls to external services
+### Third-Party Dependencies
+| Dependency                | License      | Purpose            |
+| ------------------------- | ------------ | ------------------ |
+| @modelcontextprotocol/sdk | MIT          | MCP protocol       |
+| winston                   | MIT          | Logging            |
+| js-yaml                   | MIT          | YAML parsing       |
+| zod                       | MIT          | Schema validation  |
+| dotenv                    | BSD-2-Clause | Environment config |
+---
+## Known Limitations
+### Current Limitations
+| Limitation            | Impact           | Workaround               | Roadmap |
+| --------------------- | ---------------- | ------------------------ | ------- |
+| Android only          | No iOS testing   | Use iOS-specific tools   | Q2 2025 |
+| Single device         | Sequential tests | Multiple instances       | Q3 2025 |
+| No parallel execution | Slower suites    | External parallelization | Q3 2025 |
+| English prompts only  | Limited i18n     | Translate prompts        | Q4 2025 |
+### AI Limitations
+| Limitation        | Description                           | Mitigation               |
+| ----------------- | ------------------------------------- | ------------------------ |
+| Selector accuracy | AI may generate incorrect selectors   | Validation + retry       |
+| Complex flows     | Multi-step flows may require guidance | Break into smaller tests |
+| Dynamic content   | Handling dynamic data                 | Use wait strategies      |
+### Infrastructure Requirements
+| Requirement | Minimum | Recommended         |
+| ----------- | ------- | ------------------- |
+| Node.js     | 18.x    | 20.x LTS            |
+| Java        | 17      | 21 LTS              |
+| RAM         | 4 GB    | 8 GB                |
+| Storage     | 500 MB  | 2 GB (with results) |
+---
+## Support & Maintenance
+### Support Channels
+| Channel         | Response Time | Availability |
+| --------------- | ------------- | ------------ |
+| GitHub Issues   | 48-72 hours   | Public       |
+| Email Support   | 24-48 hours   | Enterprise   |
+| Slack Community | Best effort   | Public       |
+### Release Cadence
+| Release Type  | Frequency | Notes            |
+| ------------- | --------- | ---------------- |
+| Patch (x.x.X) | As needed | Bug fixes        |
+| Minor (x.X.0) | Monthly   | New features     |
+| Major (X.0.0) | Quarterly | Breaking changes |
+### Versioning
+Follows [Semantic Versioning 2.0.0](https://semver.org/):
+- **MAJOR**: Breaking API changes
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes, backward compatible
+---
+## Roadmap
+### Q1 2025 (Current)
+- [x] Core MCP server implementation
+- [x] Device management tools
+- [x] Result storage and cleanup
+- [x] Retry mechanism
+- [ ] Security boundaries (Safe Mode)
+- [ ] JUnit XML reports
+- [ ] CI headless mode
+### Q2 2025
+- [ ] iOS support
+- [ ] TypeScript migration
+- [ ] Enhanced audit trail
+- [ ] Configuration schema validation
+- [ ] Health check endpoint
+### Q3 2025
+- [ ] Parallel test execution
+- [ ] Plugin/hook system
+- [ ] HTML report generation
+- [ ] Slack/Teams integration
+### Q4 2025
+- [ ] Web dashboard (optional)
+- [ ] Multi-tenant support
+- [ ] RBAC implementation
+- [ ] Enterprise support tier
+---
+## Getting Started
+### Quick Evaluation
+```bash
+# Install
+npm install -g mcp-maestro-mobile-ai
+# Configure (add to your MCP client config)
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "maestro-mcp",
+      "env": {
+        "APP_ID": "com.your.app"
+      }
+    }
+  }
+}
+```
+### Enterprise Evaluation
+For enterprise evaluation, please:
+1. Review [SECURITY.md](./SECURITY.md)
+2. Test in isolated environment
+3. Validate against your security policies
+4. Contact for enterprise support options
+---
+## Contact
+- **GitHub**: [krunal-mahera/mcp-maestro-mobile-ai](https://github.com/krunal-mahera/mcp-maestro-mobile-ai)
+- **npm**: [mcp-maestro-mobile-ai](https://www.npmjs.com/package/mcp-maestro-mobile-ai)
+- **Issues**: [GitHub Issues](https://github.com/krunal-mahera/mcp-maestro-mobile-ai/issues)
+---
+_Last Updated: January 2025_
+_Version: 1.0.0_