Artemis-Eapil/mcp_server/README.md

# 🔌 Universal MCP Server for ARTEMIS

This directory contains ARTEMIS's connection-only MCP bridge and the tools hosted by the user-started web service. Official automatic configuration and Skill installation currently support Codex.

## 🏗️ Architecture

```
mcp_server/
├── __init__.py           # Package exports (mcp, main)
├── base.py               # Shared FastMCP instance
├── server.py             # Compatibility entrypoint for the stdio bridge
├── bridge.py             # Connection-only, lightweight stdio -> local HTTP
├── shared.py             # Tools hosted in the user-started web process
├── catalog.json          # Offline schemas; regenerate with scripts/generate_mcp_catalog.py
├── rules.md              # Compatibility link to the official artemis-use Skill
├── 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 (with session sorting & caching)
│   ├── desktop.py        # Native OS toast notifier (macOS/Linux/Windows, enabled by default)
│   ├── script.py         # Universal Script / Command Hook notifier (ARTEMIS_NOTIFY_CMD)
│   ├── webhook.py        # OpenClaw / CI / Discord / Slack webhook notifier
│   ├── file.py           # File audit logger (notifications.jsonl)
│   └── 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
│   └── diagnose.py       # mobile_diagnose
└── utils/                # Environment and device utilities
    ├── device_utils.py   # Cross-platform ADB and emulator resolver
    └── env_utils.py      # Python interpreter and process manager
```

The trace status store (traces directory layout and `status.json` lifecycle)
lives in the neutral base package as `artemis/runtime/trace_store.py`, shared
by the MCP server, the admin console, and spawned worker processes.

## 🔔 Multi-Platform Notification & Wakeup Support

When you start an asynchronous mobile test via `mobile_run_task`, the user-started Artemis web service queues and runs the job so the AI agent is not blocked. Upon completion or failure, Artemis dispatches alerts across **all available notification channels** so that both human developers and AI agents are notified immediately across different platforms:

| Platform / Environment | Primary Notification Mechanism | How It Works & Configuration |
| :--- | :--- | :--- |
| **Antigravity / Jetski** | **Reactive Wakeup (`AgentApiNotifier`)** | Automatically detects and caches the active IDE session credentials (`ANTIGRAVITY_LS_ADDRESS`, `ANTIGRAVITY_CSRF_TOKEN`), sorting candidate processes by creation time to avoid stale PIDs, and calls `agentapi send-message` to wake up the agent directly in the conversation. |
| **Cursor / Windsurf / VS Code / Cline / Roo Code** | **Native Desktop Toast (`DesktopNotifier`) + File Audit (`FileNotifier`)** | Enabled **by default** across macOS (`osascript`), Linux (`notify-send`), and Windows (`powershell`). Pops up a system notification banner informing the developer whether the task completed or failed. The AI agent inspects `<trace_dir>/status.json` or uses `mobile_manage_task(action="status")`. Can be silenced via `ARTEMIS_DESKTOP_NOTIFY=false`. |
| **Claude Code / Desktop** | **Native Desktop Toast + File Audit** | Alerts the user via system desktop notification banner when background execution concludes, while maintaining a complete JSONL audit log in `notifications.jsonl`. |
| **OpenClaw / Slack / Discord / CI/CD** | **HTTP Webhook (`WebhookNotifier`)** | Sends structured JSON POST payloads to custom endpoints configured via `OPENCLAW_WEBHOOK_URL`, `MCP_NOTIFICATION_WEBHOOK`, or `ARTEMIS_WEBHOOK_URL`. |
| **Universal Custom IDE / CLI Hooks** | **Custom Script Hook (`ScriptNotifier`)** | Set `ARTEMIS_NOTIFY_CMD="my-script --title '{title}' --message '{message}' --trace-id '{trace_id}'"` in your environment to execute any custom command or script upon event completion. |

## Official Codex Skill

[`artemis-use`](../skills/artemis-use/SKILL.md) explains Flash, Pro and guided exploration, task diagnosis, evidence review, batching and plugin development. Detailed references load only when relevant. Its whole official directory is maintained by ARTEMIS; no global rule block is injected into AGENTS.md.

### How Global Rules & MCP are Installed
Only Codex configuration is installed: `uv run artemis mcp --install codex`. It preserves other clients and services. The user starts the web service with `start.bat`, `start-cn.bat`, or `uv run artemis ui`. The stdio bridge never starts a backend or standalone worker; all tool execution shares the web process. Offline initialization and tools/list still work, while tool calls explain how to start the service. Codex configuration is optional (`required = false`) so failures cannot block unrelated sessions. Reload both the web process and old MCP connections after upgrading.

The bridge discovers a live service from the same installation; `ARTEMIS_DAEMON_PORT` selects between multiple data spaces. Disconnection never replays a request automatically. Regenerate `catalog.json` after changing tool schemas; tests compare it with the live registrations.

## 🛠️ MCP Tools Overview

* **`mobile_exploration`**: Guided exploration using the same queue and conversation as the web workspace. Create/start, exchange messages, pause/continue, record and analyze demonstrations, save immutable case versions, rerun with Flash/Pro, or add a batch draft. Writes use stable request IDs; reads never launch work. Defaults are independent (`gpt-6.1-sol / high`) and timeouts pause without marking the test failed. See the [exploration workflow](../docs/exploration-mode.md).
* **`mobile_run_task`**: Asynchronously launches an autonomous mobile automation task (`Flash` or `Pro` model) with optional `device_serial` targeting. Pro runs can be tuned with `verification_level` (`off` | `final` | `checkpoints` | `strict` — how much the Checker audits) and `explorer_mode` (`flash` | `pro` | `ultra` — the Operator's perception depth).
* **`mobile_manage_task`**: Manages task lifecycle (`status`, `stop`, `inject_instruction`), returning task state and assigned `device_serial`. Pass `release_loop=True` with `inject_instruction` to gracefully end a `[Loop:continuous]` monitoring task — this explicit signal (not "please stop" wording) is what unlocks the loop milestone's completion.
* **`mobile_get_device_state`**: Real-time observer (`screenshot` or OCR+XML `hierarchy`) with optional `device_serial`.
* **`mobile_inspect_trace`**: Granular trace inspection, visual action overlays, agent reasoning, and `device_serial` tracking.
* **`mobile_diagnose`**: Environment doctor for the IDE. Reuses the readiness probes behind `artemis doctor` and the web console's device wizard (Python runtime, config, LLM credentials, ADB / devices / RSA keys / emulators, video toolchain) plus an MCP-host probe (server interpreter vs project `.venv`, detected MCP client, `.env` location, traces directory, daemon port collisions). Returns a `verdict` (`ready` | `degraded` | `blocked`), an ordered `next_steps` fix list the AI agent can act on (`Run:` one-command lines vs `Guidance:` for the user), scrubbed per-check details, `tasks` holding or waiting for devices, log paths, and the most recent failed task with its `recent_errors`. Optional deep checks: `verify_credentials=true` (live API-key validation, ~12s, result in `credentials`), `probe_device=true` (end-to-end screenshot + UIAutomator hierarchy, ~20s, result in `device_probe`), `launch_avd="<name>"` (boots an installed AVD in the background; re-run after ~60s). `attempt_fix=true` applies the safe self-heals (regenerate corrupted ADB keys, restart the ADB server, clear stale device locks / queue tickets left by crashed runners).

### 📱 Device Selection & Multi-Device Execution
ARTEMIS supports parallel execution across multiple connected Android devices and emulators:
1. **Direct Device Specification**: Provide `device_serial` explicitly (e.g. `device_serial="63191FDKX00062"` or `device_serial="emulator-5554"`). Per-device execution locks allow distinct devices to run in parallel.
2. **Automatic Device Selection**: Omit `device_serial` to let ARTEMIS auto-select an available ready device from the device pool.
* **User Choice Priority**: When multiple devices/emulators are connected, AI agents should prioritize asking the user which device to run on.
* **Device Diagnosis**: Inspect connected hardware, authorization status, and serials anytime via `adb devices` or `adb devices -l`.

## 🚀 How to Run & Configure

### CLI Execution
```bash
# Start server over stdio
python -m mcp_server

# Or via Artemis CLI
uv run artemis mcp
```

### IDE Configuration

#### One-Click Auto Install (Recommended)
Start ARTEMIS normally to synchronize Codex, or repair the integration explicitly:
```bash
uv run artemis mcp --install codex
```

#### Manual JSON Config Generation
Run `uv run artemis mcp --generate-config codex` to output a configuration template with resolved Python and project paths.

## 完整 AI 自动化

工作区工具与网页共用后台服务，覆盖普通与探索任务、批次、历史、诊断、人工复验及报告导出。参见 [接入说明](../docs/ai-automation.md) 和 [Skill](../skills/artemis-use/SKILL.md)。网页启动时同步官方 Skill 与 MCP 接入；已有审批策略及工具白名单保留。更新后重新加载 MCP 才能使用新版工具定义。