quash-mcp 0.2.0__tar.gz

quash_mcp-0.2.0/.gitignore

@@ -0,0 +1,43 @@
+node_modules/
+dist/
+release/
+.env
+.env.local
+.DS_Store
+# IDE and editor settings
+.idea/
+.vscode/
+
+# Build artifacts
+*.iml
+*.tsbuildinfo
+
+# Large local artifacts/binaries
+*.apk
+
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Python cache files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST

quash_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: quash-mcp
+Version: 0.2.0
+Summary: Model Context Protocol server for Quash - AI-powered mobile automation agent
+Project-URL: Homepage, https://quashbugs.com
+Project-URL: Repository, https://github.com/quash/quash-mcp
+Project-URL: Documentation, https://docs.quashbugs.com
+Project-URL: Issues, https://github.com/quash/quash-mcp/issues
+Author-email: Quash Team <hello@quashbugs.com>
+License: MIT
+Keywords: ai,android,mcp,mobile-automation,quash,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: adbutils==2.10.0
+Requires-Dist: apkutils==2.0.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=0.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Quash MCP - AI-Powered Mobile Automation
+
+A Model Context Protocol (MCP) server for mobile automation testing with Quash. Control Android devices and run automated tests from **any MCP-compatible host** using natural language.
+
+## Features
+
+- 🤖 **AI-Powered Automation**: Control your Android device using plain English
+- 📱 **Device Connection**: Works with emulators and physical devices
+- ⚙️ **Flexible Configuration**: Customize AI model, temperature, vision, reasoning, and more
+- 🔄 **Real-Time Execution**: Live progress streaming during task execution
+- 🎯 **Suite Execution**: Run multiple tasks in sequence with retry logic
+- 📊 **Usage Tracking**: Monitor API costs and token usage
+- 🔐 **Secure**: API key authentication via Quash platform
+
+## Installation
+
+```bash
+pip install quash-mcp
+```
+
+All dependencies (including ADB tools and device connectivity) are automatically installed. **AI execution happens on the Quash backend**, keeping the client lightweight and proprietary logic protected.
+
+## Quick Start
+
+### 1. Get Your API Key
+
+1. Visit [quashbugs.com](https://quashbugs.com) (or your deployment URL)
+2. Sign in with Google
+3. Go to Dashboard → API Keys
+4. Create a new API key
+
+### 2. Add to Your MCP Host
+
+Quash MCP works with any MCP-compatible host. Configure it to use `python3 -m quash_mcp` which works across all Python environments:
+
+#### Manual Configuration (Recommended)
+
+Add to your MCP host's config file:
+
+**Config file locations:**
+- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Claude Desktop (Linux)**: `~/.config/claude/claude_desktop_config.json`
+- **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Claude Code**: `~/.claude.json` (project-specific under `projects.<path>.mcpServers`)
+
+```json
+{
+  "mcpServers": {
+    "quash": {
+      "command": "python3",
+      "args": ["-m", "quash_mcp"]
+    }
+  }
+}
+```
+
+**Why `python3 -m quash_mcp`?**
+- Works in any Python environment (conda, venv, system)
+- No PATH configuration needed
+- Uses whichever Python has quash-mcp installed
+
+#### Alternative: Direct Command (if in PATH)
+
+If `quash-mcp` is in your PATH:
+
+```json
+{
+  "mcpServers": {
+    "quash": {
+      "command": "quash-mcp"
+    }
+  }
+}
+```
+
+Then restart your MCP host.
+
+### 3. Start Automating
+
+Ask your AI assistant (via your MCP host):
+
+```
+"Setup Quash and connect to my Android device"
+"Configure with my API key: mhg_xxxx..."
+"Execute task: Open Settings and enable WiFi"
+```
+
+## Available Tools
+
+### 1. `build`
+Setup and verify all dependencies.
+
+**Example:**
+```
+Can you run the build tool to setup my system for Quash?
+```
+
+### 2. `connect`
+Connect to an Android device or emulator.
+
+**Parameters:**
+- `device_serial` (optional): Device serial number
+
+**Example:**
+```
+Connect to my Android device
+```
+
+### 3. `configure`
+Configure agent execution parameters.
+
+**Parameters:**
+- `quash_api_key`: Your Quash API key from the web portal
+- `model`: LLM model (e.g., "anthropic/claude-sonnet-4", "openai/gpt-4o")
+- `temperature`: 0-2 (default: 0.2)
+- `max_steps`: Maximum execution steps (default: 15)
+- `vision`: Enable screenshots (default: false)
+- `reasoning`: Enable multi-step planning (default: false)
+- `reflection`: Enable self-improvement (default: false)
+- `debug`: Verbose logging (default: false)
+
+**Example:**
+```
+Configure Quash with my API key mhg_xxx, use Claude Sonnet 4, and enable vision
+```
+
+### 4. `execute`
+Run an automation task on the device.
+
+**Parameters:**
+- `task`: Natural language task description
+
+**Example:**
+```
+Execute task: Open Settings and navigate to WiFi settings
+```
+
+### 5. `runsuite`
+Execute multiple tasks in sequence with retry logic.
+
+**Parameters:**
+- `suite_name`: Name of the test suite
+- `tasks`: Array of tasks with retry and failure handling options
+
+**Example:**
+```
+Run a test suite with these tasks: [
+  {"prompt": "Open Settings", "type": "setup"},
+  {"prompt": "Enable WiFi", "type": "test", "retries": 2},
+  {"prompt": "Close Settings", "type": "teardown"}
+]
+```
+
+### 6. `usage`
+View API usage statistics and costs.
+
+**Example:**
+```
+Show me my Quash usage statistics
+```
+
+## Complete Workflow Example
+
+```
+User: "Setup Quash on my machine"
+→ Runs build tool
+→ Returns: All dependencies installed ✓
+
+User: "Connect to my Android emulator"
+→ Runs connect tool
+→ Returns: Connected to emulator-5554 ✓
+
+User: "Configure to use Claude Sonnet 4 with vision and my API key is mhg_xxx..."
+→ Runs configure tool
+→ Returns: Configuration set ✓
+
+User: "Execute task: Open Instagram and go to my profile"
+→ Runs execute tool with live streaming
+→ Returns: Task completed ✓
+
+User: "Show me my usage statistics"
+→ Runs usage tool
+→ Returns: Total cost: $0.15, 10 executions ✓
+```
+
+## Requirements
+
+- **Python 3.11+** - Required for the MCP server
+- **Android Device** - Emulator or physical device with USB debugging enabled
+- **Quash API Key** - Get from [quashbugs.com](https://quashbugs.com)
+
+Dependencies automatically installed:
+- Android Debug Bridge (ADB) - via `adbutils`
+- Quash Portal APK - via `apkutils`
+- MCP protocol support - via `mcp`
+- HTTP client - via `httpx`
+
+## Architecture
+
+**v0.2.0 uses a client-server architecture:**
+- **Client (quash-mcp)**: Lightweight MCP server handling device connections and API calls
+- **Server (Quash backend)**: Proprietary AI execution engine (LLMs, agents, pricing logic)
+
+```
+quash-mcp/
+├── quash_mcp/
+│   ├── __main__.py          # Module entry point for python -m
+│   ├── server.py            # Main MCP server entry point
+│   ├── backend_client.py    # API communication with Quash backend
+│   ├── state.py             # Session state management
+│   └── tools/
+│       ├── build.py         # Dependency checker and installer
+│       ├── connect.py       # Device connectivity
+│       ├── configure.py     # Agent configuration
+│       ├── execute.py       # Task execution (calls backend API)
+│       ├── runsuite.py      # Suite execution (calls backend API)
+│       └── usage.py         # Usage statistics (from backend)
+└── pyproject.toml
+```
+
+## Troubleshooting
+
+**"No devices found"**
+- Start Android emulator via Android Studio > AVD Manager
+- Connect physical device with USB debugging enabled
+- For WiFi debugging: `adb tcpip 5555 && adb connect <device-ip>:5555`
+
+**"Portal not ready"**
+- The `connect` tool automatically installs the Portal APK
+- If it fails, manually enable the Quash Portal accessibility service in Settings > Accessibility
+
+**"Invalid API key"**
+- Make sure you've run `configure` with a valid API key from quashbugs.com
+- API keys start with `mhg_` prefix
+- Check your API key hasn't been revoked in the web portal
+
+## License
+
+MIT

quash_mcp-0.2.0/README.md

@@ -0,0 +1,239 @@
+# Quash MCP - AI-Powered Mobile Automation
+
+A Model Context Protocol (MCP) server for mobile automation testing with Quash. Control Android devices and run automated tests from **any MCP-compatible host** using natural language.
+
+## Features
+
+- 🤖 **AI-Powered Automation**: Control your Android device using plain English
+- 📱 **Device Connection**: Works with emulators and physical devices
+- ⚙️ **Flexible Configuration**: Customize AI model, temperature, vision, reasoning, and more
+- 🔄 **Real-Time Execution**: Live progress streaming during task execution
+- 🎯 **Suite Execution**: Run multiple tasks in sequence with retry logic
+- 📊 **Usage Tracking**: Monitor API costs and token usage
+- 🔐 **Secure**: API key authentication via Quash platform
+
+## Installation
+
+```bash
+pip install quash-mcp
+```
+
+All dependencies (including ADB tools and device connectivity) are automatically installed. **AI execution happens on the Quash backend**, keeping the client lightweight and proprietary logic protected.
+
+## Quick Start
+
+### 1. Get Your API Key
+
+1. Visit [quashbugs.com](https://quashbugs.com) (or your deployment URL)
+2. Sign in with Google
+3. Go to Dashboard → API Keys
+4. Create a new API key
+
+### 2. Add to Your MCP Host
+
+Quash MCP works with any MCP-compatible host. Configure it to use `python3 -m quash_mcp` which works across all Python environments:
+
+#### Manual Configuration (Recommended)
+
+Add to your MCP host's config file:
+
+**Config file locations:**
+- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Claude Desktop (Linux)**: `~/.config/claude/claude_desktop_config.json`
+- **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Claude Code**: `~/.claude.json` (project-specific under `projects.<path>.mcpServers`)
+
+```json
+{
+  "mcpServers": {
+    "quash": {
+      "command": "python3",
+      "args": ["-m", "quash_mcp"]
+    }
+  }
+}
+```
+
+**Why `python3 -m quash_mcp`?**
+- Works in any Python environment (conda, venv, system)
+- No PATH configuration needed
+- Uses whichever Python has quash-mcp installed
+
+#### Alternative: Direct Command (if in PATH)
+
+If `quash-mcp` is in your PATH:
+
+```json
+{
+  "mcpServers": {
+    "quash": {
+      "command": "quash-mcp"
+    }
+  }
+}
+```
+
+Then restart your MCP host.
+
+### 3. Start Automating
+
+Ask your AI assistant (via your MCP host):
+
+```
+"Setup Quash and connect to my Android device"
+"Configure with my API key: mhg_xxxx..."
+"Execute task: Open Settings and enable WiFi"
+```
+
+## Available Tools
+
+### 1. `build`
+Setup and verify all dependencies.
+
+**Example:**
+```
+Can you run the build tool to setup my system for Quash?
+```
+
+### 2. `connect`
+Connect to an Android device or emulator.
+
+**Parameters:**
+- `device_serial` (optional): Device serial number
+
+**Example:**
+```
+Connect to my Android device
+```
+
+### 3. `configure`
+Configure agent execution parameters.
+
+**Parameters:**
+- `quash_api_key`: Your Quash API key from the web portal
+- `model`: LLM model (e.g., "anthropic/claude-sonnet-4", "openai/gpt-4o")
+- `temperature`: 0-2 (default: 0.2)
+- `max_steps`: Maximum execution steps (default: 15)
+- `vision`: Enable screenshots (default: false)
+- `reasoning`: Enable multi-step planning (default: false)
+- `reflection`: Enable self-improvement (default: false)
+- `debug`: Verbose logging (default: false)
+
+**Example:**
+```
+Configure Quash with my API key mhg_xxx, use Claude Sonnet 4, and enable vision
+```
+
+### 4. `execute`
+Run an automation task on the device.
+
+**Parameters:**
+- `task`: Natural language task description
+
+**Example:**
+```
+Execute task: Open Settings and navigate to WiFi settings
+```
+
+### 5. `runsuite`
+Execute multiple tasks in sequence with retry logic.
+
+**Parameters:**
+- `suite_name`: Name of the test suite
+- `tasks`: Array of tasks with retry and failure handling options
+
+**Example:**
+```
+Run a test suite with these tasks: [
+  {"prompt": "Open Settings", "type": "setup"},
+  {"prompt": "Enable WiFi", "type": "test", "retries": 2},
+  {"prompt": "Close Settings", "type": "teardown"}
+]
+```
+
+### 6. `usage`
+View API usage statistics and costs.
+
+**Example:**
+```
+Show me my Quash usage statistics
+```
+
+## Complete Workflow Example
+
+```
+User: "Setup Quash on my machine"
+→ Runs build tool
+→ Returns: All dependencies installed ✓
+
+User: "Connect to my Android emulator"
+→ Runs connect tool
+→ Returns: Connected to emulator-5554 ✓
+
+User: "Configure to use Claude Sonnet 4 with vision and my API key is mhg_xxx..."
+→ Runs configure tool
+→ Returns: Configuration set ✓
+
+User: "Execute task: Open Instagram and go to my profile"
+→ Runs execute tool with live streaming
+→ Returns: Task completed ✓
+
+User: "Show me my usage statistics"
+→ Runs usage tool
+→ Returns: Total cost: $0.15, 10 executions ✓
+```
+
+## Requirements
+
+- **Python 3.11+** - Required for the MCP server
+- **Android Device** - Emulator or physical device with USB debugging enabled
+- **Quash API Key** - Get from [quashbugs.com](https://quashbugs.com)
+
+Dependencies automatically installed:
+- Android Debug Bridge (ADB) - via `adbutils`
+- Quash Portal APK - via `apkutils`
+- MCP protocol support - via `mcp`
+- HTTP client - via `httpx`
+
+## Architecture
+
+**v0.2.0 uses a client-server architecture:**
+- **Client (quash-mcp)**: Lightweight MCP server handling device connections and API calls
+- **Server (Quash backend)**: Proprietary AI execution engine (LLMs, agents, pricing logic)
+
+```
+quash-mcp/
+├── quash_mcp/
+│   ├── __main__.py          # Module entry point for python -m
+│   ├── server.py            # Main MCP server entry point
+│   ├── backend_client.py    # API communication with Quash backend
+│   ├── state.py             # Session state management
+│   └── tools/
+│       ├── build.py         # Dependency checker and installer
+│       ├── connect.py       # Device connectivity
+│       ├── configure.py     # Agent configuration
+│       ├── execute.py       # Task execution (calls backend API)
+│       ├── runsuite.py      # Suite execution (calls backend API)
+│       └── usage.py         # Usage statistics (from backend)
+└── pyproject.toml
+```
+
+## Troubleshooting
+
+**"No devices found"**
+- Start Android emulator via Android Studio > AVD Manager
+- Connect physical device with USB debugging enabled
+- For WiFi debugging: `adb tcpip 5555 && adb connect <device-ip>:5555`
+
+**"Portal not ready"**
+- The `connect` tool automatically installs the Portal APK
+- If it fails, manually enable the Quash Portal accessibility service in Settings > Accessibility
+
+**"Invalid API key"**
+- Make sure you've run `configure` with a valid API key from quashbugs.com
+- API keys start with `mhg_` prefix
+- Check your API key hasn't been revoked in the web portal
+
+## License
+
+MIT

quash_mcp-0.2.0/SETUP_CLAUDE_CODE.md

@@ -0,0 +1,133 @@
+# Setting up Mahoraga MCP with Claude Code
+
+## Step 1: Install Dependencies
+
+```bash
+cd /Users/abhinavsai/POC/mahoraga-mac/mahoraga-mcp
+pip install -e .
+```
+
+## Step 2: Add MCP Server to Claude Code
+
+Run this command to add the Mahoraga MCP server:
+
+```bash
+claude mcp add mahoraga python3 /Users/abhinavsai/POC/mahoraga-mac/mahoraga-mcp/server.py
+```
+
+Verify it's connected:
+```bash
+claude mcp list
+```
+
+You should see: `mahoraga: ... - ✓ Connected`
+
+## Step 3: Verify Installation
+
+In Claude Code, you should now see 4 new tools available:
+- `mahoraga__build`
+- `mahoraga__connect`
+- `mahoraga__configure`
+- `mahoraga__execute`
+
+## Step 4: First Time Usage
+
+### 4.1 Setup Dependencies
+```
+Setup my system for Mahoraga mobile testing
+```
+This will:
+- Check Python version
+- Install ADB if missing
+- Install Mahoraga package
+- Verify Portal APK
+
+### 4.2 Connect Device
+Make sure you have an Android emulator running or device connected, then:
+```
+Connect to my Android device
+```
+
+### 4.3 Configure Agent
+```
+Configure Mahoraga with:
+- API key: sk-or-YOUR_KEY_HERE
+- Model: openai/gpt-4o
+- Enable vision
+- Enable reasoning
+```
+
+### 4.4 Run Your First Test
+```
+Execute this task: Open Settings and navigate to About Phone
+```
+
+## Example Session
+
+```
+You: "I want to test my Android app with Mahoraga"
+
+Claude: "I'll help you set up Mahoraga for mobile testing. Let me start by
+        checking if your system has all the required dependencies."
+        [calls mahoraga__build]
+
+You: "Great! Now connect to my emulator"
+
+Claude: [calls mahoraga__connect with no device_serial to auto-detect]
+
+You: "Configure it to use Claude 3.5 Sonnet with vision enabled.
+      My API key is sk-or-..."
+
+Claude: [calls mahoraga__configure with the settings]
+
+You: "Now open Instagram and navigate to the profile page"
+
+Claude: [calls mahoraga__execute with live streaming of the execution]
+```
+
+## Troubleshooting
+
+### Tools not showing up
+- Make sure you've restarted Claude Code completely
+- Check the config file path is correct for your OS
+- Verify the server.py path is absolute and correct
+
+### "No device found" error
+- Start Android Studio emulator
+- Or connect physical device with USB debugging enabled
+- Run `adb devices` in terminal to verify device is visible
+
+### "Portal not ready" error
+- The `connect` tool will automatically try to install it
+- If it fails, manually run: `mahoraga setup --device <serial>`
+
+### API key errors
+- Make sure you've run `configure` with a valid OpenRouter API key
+- Key should start with `sk-or-`
+
+## Advanced Usage
+
+### Using with multiple devices
+```
+Connect to device emulator-5556
+```
+
+### Adjusting execution parameters
+```
+Configure with max_steps: 25 and reasoning: true
+```
+
+### Debug mode
+```
+Configure with debug: true
+```
+
+This will show verbose logs during execution.
+
+## Next Steps
+
+Once you've verified everything works:
+1. Test with your own Android apps
+2. Create reusable test scenarios
+3. Explore reasoning and reflection modes for complex tasks
+4. Consider hosting the MCP server for team access