mcp-maestro-mobile-ai 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned
+- Security boundaries (Safe Mode)
+- JUnit XML report generation
+- CI headless mode
+- iOS support
+
+---
+
+## [1.1.0] - 2025-01-06
+
+### Changed
+- **Package Renamed**: Changed from `@krunal.mahera/maestro-mcp` to `mcp-maestro-mobile-ai` for easier configuration
+- **YAML Storage**: Temp YAML files now stored in hidden system directory (`~/.maestro-mcp/`) instead of project folder
+- Test results and screenshots now stored in `~/.maestro-mcp/output/`
+
+### Added
+- **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
+  - `save_successful_flow` - Save working test patterns for AI reference
+  - `get_saved_flows` - Retrieve saved flow patterns
+  - `delete_flow` - Remove saved patterns
+  - `get_ai_context` - Get formatted context for AI (call before generating tests!)
+  - `get_full_context` - Get complete raw context data
+  - `clear_app_context` - Clear all context for an app
+  - `list_app_contexts` - List all apps with saved context
+
+### Improved
+- AI test generation accuracy when context is provided
+- Cleaner project directory (no temp files visible)
+
+---
+
+## [1.0.0] - 2025-01-05
+
+### Added
+- Initial public release on npm as `mcp-maestro-mobile-ai`
+- MCP server implementation with stdio transport
+- 14 MCP tools for mobile test automation:
+  - `read_prompt_file` - Read test prompts from files
+  - `list_prompt_files` - List available prompt files
+  - `list_devices` - List connected Android devices
+  - `select_device` - Select specific device for testing
+  - `clear_device` - Clear device selection
+  - `check_device` - Verify device connection
+  - `check_app` - Verify app installation
+  - `get_app_config` - Get server configuration
+  - `validate_maestro_yaml` - Validate YAML syntax
+  - `run_test` - Execute single test
+  - `run_test_suite` - Execute multiple tests
+  - `get_test_results` - Retrieve test results
+  - `take_screenshot` - Capture device screen
+  - `cleanup_results` - Clean up old results
+- Automatic retry mechanism for failed tests
+- Pre-flight checks (device, app) before test execution
+- Screenshot capture on test failure
+- Auto-cleanup of old results based on `MAX_RESULTS`
+- Improved error messages with hints
+- Support for physical devices via USB
+- Device selection for multi-device environments
+- Winston-based logging
+- Environment variable configuration
+- Example prompt files
+
+### Documentation
+- Comprehensive README with setup guides
+- MCP client configuration examples (Cursor, VS Code, Claude Desktop)
+- Template configuration files
+- React Native automation guidelines
+
+---
+
+## [0.1.0] - 2025-01-01
+
+### Added
+- Initial proof of concept
+- Basic Maestro CLI integration
+- Simple test execution
+
+---
+
+## Release Notes Format
+
+### Version Numbering
+
+- **MAJOR** (X.0.0): Breaking API changes
+- **MINOR** (0.X.0): New features, backward compatible
+- **PATCH** (0.0.X): Bug fixes, backward compatible
+
+### Change Categories
+
+- **Added**: New features
+- **Changed**: Changes in existing functionality
+- **Deprecated**: Features to be removed in future
+- **Removed**: Removed features
+- **Fixed**: Bug fixes
+- **Security**: Security-related changes
+
+---
+
+[Unreleased]: https://github.com/krunal-mahera/mcp-maestro-mobile-ai/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/krunal-mahera/mcp-maestro-mobile-ai/releases/tag/v1.1.0
+[1.0.0]: https://github.com/krunal-mahera/mcp-maestro-mobile-ai/releases/tag/v1.0.0
+[0.1.0]: https://github.com/krunal-mahera/mcp-maestro-mobile-ai/releases/tag/v0.1.0
+

package/CONTRIBUTING.md

@@ -0,0 +1,417 @@
+# Contributing to Maestro MCP
+
+Thank you for your interest in contributing to Maestro MCP! This document provides guidelines and information for contributors.
+
+---
+
+## Table of Contents
+
+1. [Code of Conduct](#code-of-conduct)
+2. [Getting Started](#getting-started)
+3. [Development Setup](#development-setup)
+4. [Making Changes](#making-changes)
+5. [Pull Request Process](#pull-request-process)
+6. [Coding Standards](#coding-standards)
+7. [Testing](#testing)
+8. [Documentation](#documentation)
+9. [Release Process](#release-process)
+
+---
+
+## Code of Conduct
+
+### Our Pledge
+
+We are committed to providing a welcoming and inclusive environment. All contributors are expected to:
+
+- Be respectful and constructive
+- Focus on the issue, not the person
+- Accept constructive criticism gracefully
+- Help others learn and grow
+
+### Unacceptable Behavior
+
+- Harassment, discrimination, or personal attacks
+- Trolling or inflammatory comments
+- Publishing others' private information
+- Any conduct inappropriate in a professional setting
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+Before contributing, ensure you have:
+
+- **Node.js 18+**
+- **Java 17+** (for Maestro)
+- **Maestro CLI** installed
+- **Android Emulator** or physical device
+- **Git** for version control
+
+### Finding Work
+
+1. **Good First Issues**: Look for `good first issue` label
+2. **Help Wanted**: Issues labeled `help wanted`
+3. **Roadmap Items**: Check [ROADMAP.md](./ROADMAP.md)
+4. **Bug Reports**: Fix reported issues
+5. **Feature Requests**: Implement requested features
+
+---
+
+## Development Setup
+
+### 1. Fork and Clone
+
+```bash
+# Fork the repository on GitHub, then:
+git clone https://github.com/YOUR-USERNAME/maestro-mcp.git
+cd maestro-mcp
+```
+
+### 2. Install Dependencies
+
+```bash
+npm install
+```
+
+### 3. Create Environment File
+
+```bash
+cp env.example .env
+# Edit .env with your settings
+```
+
+### 4. Run in Development Mode
+
+```bash
+npm run dev
+```
+
+### 5. Link for Local Testing
+
+```bash
+npm link
+# Now 'maestro-mcp' command is available globally
+```
+
+---
+
+## Making Changes
+
+### Branch Naming
+
+```
+feature/description    - New features
+fix/description        - Bug fixes
+docs/description       - Documentation
+refactor/description   - Code refactoring
+test/description       - Test additions
+```
+
+Examples:
+- `feature/ios-support`
+- `fix/device-detection`
+- `docs/security-update`
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation
+- `style`: Formatting, no code change
+- `refactor`: Code restructuring
+- `test`: Adding tests
+- `chore`: Maintenance tasks
+
+Examples:
+```
+feat(tools): add iOS device detection
+
+fix(maestro): handle timeout errors gracefully
+
+docs(security): update threat model
+```
+
+### Keep Commits Focused
+
+- One logical change per commit
+- Separate refactoring from feature changes
+- Include tests with feature commits
+
+---
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Sync with main**:
+   ```bash
+   git fetch origin
+   git rebase origin/main
+   ```
+
+2. **Run checks**:
+   ```bash
+   npm run lint
+   npm test
+   ```
+
+3. **Update documentation** if needed
+
+### PR Template
+
+```markdown
+## Description
+[What does this PR do?]
+
+## Motivation
+[Why is this change needed?]
+
+## Changes
+- [List of changes]
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Manual testing performed
+- [ ] Documentation updated
+
+## Screenshots (if applicable)
+[Add screenshots]
+
+## Related Issues
+Closes #[issue number]
+```
+
+### Review Process
+
+1. **Automated Checks**: Must pass CI
+2. **Code Review**: At least one approval required
+3. **Discussion**: Address all comments
+4. **Merge**: Squash and merge preferred
+
+---
+
+## Coding Standards
+
+### JavaScript/Node.js
+
+```javascript
+// Use ESM imports
+import { something } from 'module';
+
+// Use async/await over callbacks
+async function doSomething() {
+  const result = await fetchData();
+  return result;
+}
+
+// Use descriptive names
+const deviceConnectionStatus = await checkDeviceConnection();
+
+// Handle errors explicitly
+try {
+  await riskyOperation();
+} catch (error) {
+  logger.error('Operation failed', { error: error.message });
+  throw new Error('Clear error message');
+}
+```
+
+### Code Style
+
+- **ESLint**: Run `npm run lint` before committing
+- **Indentation**: 2 spaces
+- **Quotes**: Single quotes for strings
+- **Semicolons**: Required
+- **Line Length**: 100 characters max
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Variables | camelCase | `deviceId` |
+| Constants | UPPER_SNAKE | `MAX_RETRIES` |
+| Functions | camelCase | `runTest()` |
+| Classes | PascalCase | `TestRunner` |
+| Files | kebab-case | `run-tools.js` |
+
+### Error Handling
+
+```javascript
+// Provide actionable error messages
+throw new Error(
+  `App "${appId}" not installed. ` +
+  `Hint: Install the app before running tests.`
+);
+
+// Log with context
+logger.error('Test failed', {
+  testName,
+  error: error.message,
+  device: deviceId,
+});
+```
+
+---
+
+## Testing
+
+### Running Tests
+
+```bash
+# All tests
+npm test
+
+# With coverage
+npm run test:coverage
+
+# Watch mode
+npm run test:watch
+```
+
+### Test Structure
+
+```
+tests/
+├── unit/              # Unit tests
+│   ├── tools/
+│   └── utils/
+├── integration/       # Integration tests
+└── e2e/              # End-to-end tests
+```
+
+### Writing Tests
+
+```javascript
+import { describe, it, expect } from 'vitest';
+import { validateMaestroYaml } from '../src/tools/validateTools.js';
+
+describe('validateMaestroYaml', () => {
+  it('should accept valid YAML', async () => {
+    const yaml = `
+      appId: com.example.app
+      ---
+      - launchApp
+    `;
+    
+    const result = await validateMaestroYaml(yaml);
+    expect(result.valid).toBe(true);
+  });
+
+  it('should reject invalid YAML', async () => {
+    const yaml = 'invalid: [';
+    
+    const result = await validateMaestroYaml(yaml);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('syntax');
+  });
+});
+```
+
+### Test Requirements
+
+- Unit tests for all new functions
+- Integration tests for tool interactions
+- No decrease in coverage percentage
+- Tests must be deterministic
+
+---
+
+## Documentation
+
+### When to Update Docs
+
+- Adding new features
+- Changing existing behavior
+- Adding configuration options
+- Fixing user-facing bugs
+- Security-related changes
+
+### Documentation Files
+
+| File | Purpose |
+|------|---------|
+| README.md | Quick start, overview |
+| CHANGELOG.md | Version history |
+| ROADMAP.md | Future plans |
+| docs/ENTERPRISE_READINESS.md | Enterprise guide |
+| docs/SECURITY.md | Security model |
+| docs/PRIVACY.md | Privacy policy |
+
+### Documentation Style
+
+- Use clear, simple language
+- Include code examples
+- Keep examples working and tested
+- Use tables for comparisons
+- Add diagrams for complex concepts
+
+---
+
+## Release Process
+
+### Version Bumping
+
+```bash
+# Patch release (bug fixes)
+npm version patch
+
+# Minor release (new features)
+npm version minor
+
+# Major release (breaking changes)
+npm version major
+```
+
+### Release Checklist
+
+- [ ] All tests passing
+- [ ] CHANGELOG.md updated
+- [ ] Documentation updated
+- [ ] Version bumped in package.json
+- [ ] Git tag created
+- [ ] npm publish successful
+
+### Publishing
+
+```bash
+# Ensure logged in
+npm whoami
+
+# Publish (handled by maintainers)
+npm publish --access public
+```
+
+---
+
+## Questions?
+
+- **GitHub Issues**: For bugs and features
+- **Discussions**: For questions and ideas
+- **Email**: For private matters
+
+---
+
+## Recognition
+
+Contributors are recognized in:
+
+- GitHub contributors list
+- CHANGELOG.md for significant contributions
+- README.md for major contributors
+
+Thank you for contributing! 🎉
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+