quash-mcp 0.2.0__py3-none-any.whl

quash_mcp/tools/runsuite.py

@@ -0,0 +1,209 @@
+"""
+Run Suite tool - Execute multiple tasks in sequence like test suites.
+Mimics the Electron app's suite execution functionality.
+"""
+
+import asyncio
+import time
+from typing import Dict, Any, List, Optional, Callable
+from ..state import get_state
+from .execute import execute
+
+
+async def runsuite(
+    suite_name: str,
+    tasks: List[Dict[str, Any]],
+    progress_callback: Optional[Callable[[str], None]] = None
+) -> Dict[str, Any]:
+    """
+    Execute a suite of tasks in sequence.
+
+    Args:
+        suite_name: Name of the suite being executed
+        tasks: List of task definitions with:
+            - prompt (str): Task instruction
+            - type (str): 'setup', 'test', or 'teardown' (optional, default 'test')
+            - retries (int): Number of retry attempts (optional, default 0)
+            - continueOnFailure (bool): Continue suite if task fails (optional, default False)
+            - waitBefore (int): Seconds to wait before executing (optional, default 0)
+        progress_callback: Optional callback for progress updates
+
+    Returns:
+        Dict with suite execution results
+    """
+    state = get_state()
+
+    # Validate prerequisites
+    if not state.is_ready():
+        return {
+            "status": "error",
+            "message": "❌ Not ready to execute suite. Please connect device and configure first.",
+            "suite_name": suite_name,
+            "completed_tasks": 0,
+            "total_tasks": len(tasks)
+        }
+
+    # Validate tasks
+    if not tasks or len(tasks) == 0:
+        return {
+            "status": "error",
+            "message": "❌ Suite must have at least one task",
+            "suite_name": suite_name,
+            "completed_tasks": 0,
+            "total_tasks": 0
+        }
+
+    # Execution tracking
+    suite_start_time = time.time()
+    results = []
+    completed_tasks = 0
+    failed_tasks = 0
+    skipped_tasks = 0
+
+    def log_progress(message: str):
+        """Helper to log progress"""
+        if progress_callback:
+            progress_callback(message)
+
+    log_progress(f"🚀 Starting suite: {suite_name}")
+    log_progress(f"📋 Total tasks: {len(tasks)}")
+    log_progress("")
+
+    # Execute each task
+    for idx, task_def in enumerate(tasks, 1):
+        task_prompt = task_def.get('prompt')
+        task_type = task_def.get('type', 'test')
+        retries = task_def.get('retries', 0)
+        continue_on_failure = task_def.get('continueOnFailure', False)
+        wait_before = task_def.get('waitBefore', 0)
+
+        # Validate task has prompt
+        if not task_prompt:
+            log_progress(f"⚠️  Task {idx}: Skipped (no prompt)")
+            skipped_tasks += 1
+            results.append({
+                "task_number": idx,
+                "type": task_type,
+                "status": "skipped",
+                "message": "No prompt provided"
+            })
+            continue
+
+        # Wait before executing if specified
+        if wait_before > 0:
+            log_progress(f"⏳ Task {idx}: Waiting {wait_before}s before execution...")
+            await asyncio.sleep(wait_before)
+
+        # Task execution with retries
+        task_success = False
+        task_attempts = 0
+        max_attempts = retries + 1
+        task_result = None
+
+        log_progress(f"▶️  Task {idx}/{len(tasks)} [{task_type.upper()}]: {task_prompt[:60]}{'...' if len(task_prompt) > 60 else ''}")
+
+        while task_attempts < max_attempts and not task_success:
+            task_attempts += 1
+
+            if task_attempts > 1:
+                log_progress(f"   🔄 Retry {task_attempts - 1}/{retries}...")
+
+            try:
+                # Execute the task
+                task_result = await execute(
+                    task=task_prompt,
+                    progress_callback=lambda msg: log_progress(f"      {msg}")
+                )
+
+                if task_result.get('status') == 'success':
+                    task_success = True
+                    log_progress(f"   ✅ Task {idx} completed")
+                else:
+                    if task_attempts < max_attempts:
+                        log_progress(f"   ⚠️  Task {idx} failed, retrying...")
+                    else:
+                        log_progress(f"   ❌ Task {idx} failed after {task_attempts} attempt(s)")
+
+            except Exception as e:
+                log_progress(f"   ❌ Task {idx} error: {str(e)}")
+                task_result = {
+                    "status": "failed",
+                    "message": str(e)
+                }
+
+        # Record task result
+        if task_success:
+            completed_tasks += 1
+            results.append({
+                "task_number": idx,
+                "type": task_type,
+                "prompt": task_prompt[:100],
+                "status": "completed",
+                "attempts": task_attempts,
+                "message": task_result.get('message', 'Success')
+            })
+        else:
+            failed_tasks += 1
+            results.append({
+                "task_number": idx,
+                "type": task_type,
+                "prompt": task_prompt[:100],
+                "status": "failed",
+                "attempts": task_attempts,
+                "message": task_result.get('message', 'Failed') if task_result else 'Unknown error'
+            })
+
+            # Check if we should continue or stop
+            if not continue_on_failure:
+                log_progress("")
+                log_progress(f"⛔ Stopping suite execution (task {idx} failed and continueOnFailure=False)")
+                log_progress(f"📊 Remaining tasks: {len(tasks) - idx} (skipped)")
+                skipped_tasks = len(tasks) - idx
+                break
+
+        log_progress("")
+
+    # Calculate suite results
+    suite_duration = time.time() - suite_start_time
+    total_tasks = len(tasks)
+    pass_rate = (completed_tasks / total_tasks * 100) if total_tasks > 0 else 0
+
+    # Determine overall status
+    if completed_tasks == total_tasks:
+        status = "completed"
+        message = f"✅ Suite '{suite_name}' completed successfully"
+    elif completed_tasks > 0:
+        status = "partial"
+        message = f"⚠️  Suite '{suite_name}' partially completed"
+    else:
+        status = "failed"
+        message = f"❌ Suite '{suite_name}' failed"
+
+    # Final summary
+    log_progress("=" * 60)
+    log_progress(f"📊 Suite Execution Summary: {suite_name}")
+    log_progress("=" * 60)
+    log_progress(f"✅ Completed: {completed_tasks}/{total_tasks}")
+    log_progress(f"❌ Failed: {failed_tasks}")
+    log_progress(f"⏭️  Skipped: {skipped_tasks}")
+    log_progress(f"📈 Pass Rate: {pass_rate:.1f}%")
+    log_progress(f"⏱️  Duration: {suite_duration:.1f}s")
+    log_progress("=" * 60)
+
+    result = {
+        "status": status,
+        "message": message,
+        "suite_name": suite_name,
+        "total_tasks": total_tasks,
+        "completed_tasks": completed_tasks,
+        "failed_tasks": failed_tasks,
+        "skipped_tasks": skipped_tasks,
+        "pass_rate": round(pass_rate, 1),
+        "duration_seconds": round(suite_duration, 1),
+        "task_results": results
+    }
+
+    # Save latest suite execution to state
+    state.latest_suite = result
+
+    return result

quash_mcp/tools/usage.py

@@ -0,0 +1,31 @@
+"""
+Usage tool - View usage statistics and costs from backend.
+Queries the backend API for usage statistics instead of local tracking.
+"""
+
+from typing import Dict, Any, Optional
+
+
+async def usage(api_key: Optional[str] = None, show_recent: int = 5) -> Dict[str, Any]:
+    """
+    View usage statistics for Quash executions from backend.
+
+    Note: In v0.2.0, all usage tracking happens on the backend.
+    This tool would need backend API support to fetch usage stats.
+
+    Args:
+        api_key: Specific API key to query (optional - shows all if not provided)
+        show_recent: Number of recent executions to show (default: 5)
+
+    Returns:
+        Dict with usage statistics and execution history
+    """
+
+    # TODO: Implement backend API call to fetch usage stats
+    # For now, return a message directing users to the web portal
+
+    return {
+        "status": "info",
+        "message": "📊 Usage statistics are tracked on the backend. Please visit https://quashbugs.com/dashboard to view your usage, costs, and execution history.",
+        "note": "All usage tracking, token counts, and costs are now managed server-side for security."
+    }

quash_mcp-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+quash_mcp/__init__.py,sha256=LImiWCRgjAbb5DZXBq2DktUEAbftvnO61Vil4Ayun9A,39
+quash_mcp/__main__.py,sha256=WCg5OlnXhr6i0XJHAUGpbhliMy3qE2SJkFzVD4wO-lw,239
+quash_mcp/backend_client.py,sha256=FmwBVf_1nmWk18kXWuWXnDTYgL6x9kKqiNVULlW-x48,6844
+quash_mcp/server.py,sha256=scUGnplxjsvyYLK2q6hrjl-5Chkdnat9pODDtLzsQFY,15519
+quash_mcp/state.py,sha256=Tnt795GnZcas-h62Y6KYyIZVopeoWPM0TbRwOeVFYj4,4394
+quash_mcp/tools/__init__.py,sha256=r4fMAjHDjHUbimRwYW7VYUDkQHs12UVsG_IBmWpeX9s,249
+quash_mcp/tools/build.py,sha256=PAFx4YXXbJ_BFXrixZfHR593vN7WzrqW6J0Zg7Wwr2s,29326
+quash_mcp/tools/build_old.py,sha256=6M9gaqZ_dX4B7UFTxSMD8T1BX0zEwQUL7RJ8ItNfB54,6016
+quash_mcp/tools/configure.py,sha256=cv4RTolu6qae-XzyACSJUDrALfd0gYC-XE5s66_zfNk,4439
+quash_mcp/tools/connect.py,sha256=odrbxAYxLQNzdvlEX1XVLb4BXEZ276AG9wXOpLsOJ6Q,4783
+quash_mcp/tools/execute.py,sha256=waWnaD0dEVcOJgRBbqZo3HnxME1s6YUOn8aRbm4R3X4,6081
+quash_mcp/tools/runsuite.py,sha256=gohLk9FpN8v7F0a69fspqOqUexTcslpYf3qU-iIZZ3s,7220
+quash_mcp/tools/usage.py,sha256=g76A6FO36fThoyRFG7q92QmS3Kh1pIKOrhYOzUdIubA,1155
+quash_mcp-0.2.0.dist-info/METADATA,sha256=iNrSIhKB2rU5vlhHdJ4yunvnaf6B5GqkKV8XyTjnZcc,8097
+quash_mcp-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+quash_mcp-0.2.0.dist-info/entry_points.txt,sha256=9sbDxrx0ApGDVRS-IE3mQgSao3DwKnnV_k-_ipFn9QI,52
+quash_mcp-0.2.0.dist-info/RECORD,,

quash_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

quash_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+quash-mcp = quash_mcp.server:main