feat: introduce MCP server, cross-platform runtime, and Showcase UI reorganization

- Showcase UI Reorganization:
  * Move web UI dashboard from root directory into apps/showcase_ui/ for cleaner project structure
  * Add 'artemis ui' CLI command (artemis/interfaces/cli/commands/ui.py) and launcher scripts for the interactive showcase console
- Standalone MCP Server & Notifiers (mcp_server/):
  * Implement dedicated MCP server package with mobile automation tools (device_state, inspect_trace, task_manager, task_runner)
  * Add multi-channel notifiers (AgentAPI, Desktop notifications, Webhooks, File output, and Composite routing)
  * Introduce background task runner and trace store for autonomous mobile execution monitoring
- Cross-Platform Runtime & Toolchain Support:
  * Add artemis/platform/ with OS-specific implementations for Linux, macOS (Darwin), and Windows
  * Add artemis/runtime/supervisor.py for resilient process and agent runtime supervision
  * Add artemis/toolchain/ with dependency resolution and SDK descriptors
  * Add cross-platform launcher scripts (start.sh, start.bat) and installer scripts (scripts/install_deps.*)
- Core Enhancements & Diagnostics:
  * Enhance coordinate normalization, OCR API fallback, and perception pipeline
  * Add credential validation (credentials_validator.py) and system diagnostics
  * Update bilingual documentation (README.md, README_CN.md) and architecture diagrams
- Test Suite Expansion:
  * Add integration tests for cloud gateway, remote ADB, and Artemis login
  * Add unit tests covering core diagnostics, platform detection, toolchain, credentials validator, optional OCR, and MCP tools
This commit is contained in:
somew1nd committed 2026-08-18 13:59:27 -07:00
1 parent 78e478f502
commit 9a5aaf99b7
249 files changed
+37226 -9339

No files matched your search

+68
View File
@@ -0,0 +1,68 @@
# πŸ”Œ Universal MCP Server for ARTEMIS
This directory contains the universal **Model Context Protocol (MCP)** server for **ARTEMIS**, enabling seamless mobile device automation inside AI IDEs and agents like **Cursor**, **Claude Code**, **OpenClaw**, **Windsurf**, and **Jetski**.
## πŸ—οΈ Architecture
```
mcp_server/
β”œβ”€β”€ __init__.py # Package exports (mcp, main)
β”œβ”€β”€ base.py # Shared FastMCP instance
β”œβ”€β”€ server.py # Server entrypoint (stdio / sse)
β”œβ”€β”€ rules.md # AI Agent Testing Mindset & system prompt rules for IDEs
β”œβ”€β”€ background/ # Background process execution
β”‚ └── task_runner.py # Subprocess runner for Artemis Agent
β”œβ”€β”€ notifiers/ # Multi-environment notification adapters
β”‚ β”œβ”€β”€ base.py # BaseNotifier abstract class
β”‚ β”œβ”€β”€ agentapi.py # Jetski / Antigravity AgentAPI notifier
β”‚ β”œβ”€β”€ webhook.py # OpenClaw / CI / Discord / Slack webhook notifier
β”‚ β”œβ”€β”€ desktop.py # Native OS toast notifier
β”‚ β”œβ”€β”€ file.py # File audit logger
β”‚ └── composite.py # Multi-channel notification dispatcher
β”œβ”€β”€ tools/ # Modular standard MCP tools
β”‚ β”œβ”€β”€ task_runner.py # mobile_run_task
β”‚ β”œβ”€β”€ task_manager.py # mobile_manage_task
β”‚ β”œβ”€β”€ device_state.py # mobile_get_device_state
β”‚ └── inspect_trace.py # mobile_inspect_trace
└── utils/ # Environment, device, and trace utilities
β”œβ”€β”€ device_utils.py # Cross-platform ADB and emulator resolver
β”œβ”€β”€ env_utils.py # Python interpreter and process manager
└── trace_store.py # Traces directory and status manager
```
## 🧠 AI Agent Behavioral Rules (`rules.md`)
When connecting ARTEMIS to AI coding assistants like **Claude Code**, **Cursor**, or **Windsurf**, providing the assistant with domain-specific testing discipline is critical for generating reliable test code.
The included [`rules.md`](./rules.md) file contains the **Mobile Testing Mindset (ARTEMIS Integration)** guideline. It teaches the AI agent how to properly collaborate with ARTEMIS:
1. **The Runnable Code Principle & Active Exploration**: Instructs the AI to never guess or hallucinate UI transitions. Instead, it must first explore the live app via ARTEMIS MCP tools (`mobile_run_task`, etc.) to discover and verify real-world interaction paths before writing test scripts.
2. **Flash vs. Pro Routing Strategy**: Guides the AI to choose **Flash** for rapid, straightforward UI actions (< 30 steps) and **Pro** for complex multi-agent planning, polling loops, or video/log diagnosis.
3. **Latency & Timing Compensation**: Clarifies the difference between AI exploratory latency (e.g., model decision intervals) and the deterministic timing requirements of final test code.
4. **"Dynamic-First, Coordinate-Fallback" Locator Pattern**: Teaches the AI to prioritize dynamic UI locators (Resource IDs, OCR text, semantics) for layout resilience, while implementing absolute coordinate fallbacks for maximum execution reliability.
### How to Apply `rules.md` in Your IDE
* **Claude Code**: Copy or include the contents of `rules.md` in your project's `CLAUDE.md` file (or reference it directly in your instructions).
* **Cursor**: Copy the contents of `rules.md` into your `.cursorrules` or create a new rule file in `.cursor/rules/artemis.mdc`.
* **Windsurf / OpenClaw**: Add the rules to your global/workspace rules or agent system prompts so the assistant always follows verified mobile testing principles.
## πŸ› οΈ MCP Tools Overview
* **`mobile_run_task`**: Asynchronously launches an autonomous mobile automation task (`Flash` or `Pro` model).
* **`mobile_manage_task`**: Manages task lifecycle (`status`, `stop`, `inject_instruction`).
* **`mobile_get_device_state`**: Real-time observer (`screenshot` or OCR+XML `hierarchy`).
* **`mobile_inspect_trace`**: Granular trace inspection, visual action overlays, and agent reasoning.
## πŸš€ How to Run & Configure
### CLI Execution
```bash
# Start server over stdio
python -m mcp_server
# Or via Artemis CLI
artemis mcp
```
### IDE Configuration
Run `artemis mcp --generate-config all` to generate ready-to-use configuration JSON for Cursor, Claude Code, OpenClaw, and Windsurf.