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 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.
• 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

# 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:

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 自动化

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