autodevice-mcp

npx -y autodevice-mcp --doctor

autodevice-mcp is a local MCP server for repeatable abnormal API-response testing on Android, iOS, and HarmonyOS devices. It combines device automation, mitmproxy response mutation, evidence capture, cross-platform comparison, and auditable HTML/JSON reports behind one stdio MCP process.

The npm package bootstraps an isolated Python 3.12 runtime and keeps stdout reserved for MCP protocol frames. See npm installation for cache, bootstrap, proxy, and troubleshooting details.

Highlights

• Imports Markdown test cases and converts them into reusable mutation rules.
• Runs Android, iOS, and HarmonyOS lanes independently in one run_cases call.
• Reuses one bounded HDC shell worker per HarmonyOS device while isolating different serials.
• Reuses one HarmonyOS driver and recent verified page snapshot across adjacent MCP actions.
• Provides click_and_assert for one-call semantic click, adaptive wait, bounded empty-layout recovery, and any/all/absent page verification.
• Validates tools, devices, proxy reachability, and page anchors before formal execution.
• Discovers each device client IP from a fresh request instead of static configuration.
• Stores every modified response JSON with recursive sensitive-value redaction.
• Uses owner-only permissions (0700 directories and 0600 evidence files) for runtime data.
• Bounds each stored modified response; oversized bodies become size-and-SHA-256 audit markers.
• Captures screenshots, request hits, execution events, non-final visual prechecks, and final semantic reviews.
• Produces a fixed three-platform HTML report plus machine-readable artifacts.
• Persists scoped navigation and field-alias knowledge for later runs.

Safety model

preflight is read-only. A formal run_cases execution may configure the connected devices' Wi-Fi HTTP proxy after first taking a snapshot and verifying the new value. If readiness fails, partially applied settings are rolled back.

After a formal run, the verified phone proxy and mitmproxy process are intentionally retained for continued capture. Original proxy snapshots and owned-process evidence are persisted across MCP restarts. When capture is no longer required, call restore_retained_proxy; it restores every phone, verifies the readback, and stops only the project-owned mitmproxy process. A failed cleanup retains the recovery record for another attempt.

Only one run_cases call can mutate a workspace at a time. A concurrent call returns workspace_busy before preflight.

Do not run this project against devices, applications, or traffic you are not authorized to test.

Requirements

• Node.js 20 or newer
• Python 3.12 when available; otherwise the npm launcher downloads its pinned managed Python 3.12 runtime
• Android: adb and an authorized device
• iOS: Xcode command-line tools, iproxy, and a prepared WebDriverAgent
• HarmonyOS: hdc and an authorized device
• Phones and the host must have a routable network path for proxy-backed runs

Installation

No global install is required. Verify the launcher and runtime selection with:

npx -y autodevice-mcp --doctor

To prebuild the isolated runtime without starting an MCP server:

npx -y autodevice-mcp --bootstrap-only

The postinstall hook attempts the same bootstrap on a best-effort basis. A client launch retries it strictly and reports failures on stderr, never stdout.

MCP client configuration

Cursor configuration:

{
  "mcpServers": {
    "autodevice-mcp": {
      "command": "npx",
      "args": ["-y", "autodevice-mcp"]
    }
  }
}

Codex TOML example:

[mcp_servers.autodevice_mcp]
command = "npx"
args = ["-y", "autodevice-mcp"]
startup_timeout_sec = 120

For stricter data isolation, set AUTODEVICE_MCP_HOME in the client environment to a private absolute directory. Each operator should use a separate location because it contains rules, navigation knowledge, sessions, proxy events, modified responses, screenshots, and reports.

The bootstrap cache is separate from evidence: it defaults to ~/.cache/autodevice-mcp/<version>/<platform> and can be moved with AUTODEVICE_MCP_CACHE_HOME. Do not point multiple untrusted users at one cache.

AUTODEVICE_MCP_MAX_RESPONSE_BYTES controls the maximum serialized modified-response body retained per hit and defaults to 10 MiB. Explicit report output paths must remain inside the selected workspace data home.

First run

1. Call doctor to verify Python dependencies.
2. Call runtime_status to inspect devices, WDA/HDC, and proxy-port state.
3. Call the read-only preflight tool for the target platform.
4. Import a case containing a stable rule, exact API, and mutation/patch asset.
5. Execute it through one run_cases call.
6. Provide target_page or explicit target_page_assertions; missing anchors are a hard block.
7. Review index.html, modified_responses.json, and manifest.json, then submit final VLM or human decisions.
8. Call restore_retained_proxy when capture is no longer needed.

The proxy reminder is operationally important: a formal run deliberately retains the verified phone proxy and owned mitmproxy process for continued capture. Always call restore_retained_proxy before leaving the test network or returning a device.

proxy_host is an optional preference, not a bypass. The address must be a current local candidate, satisfy every device's advertised Wi-Fi prefix, and pass a source-bound route probe to every selected phone. If any device address is unavailable or any route cannot be proven, readiness stops before changing the proxy.

Every executable rule must contain an exact host, path-bearing api, HTTP method, and at least one non-empty mutation asset. Markdown such as GET https://api.example.test/v1/profile is imported end-to-end. For path-only source material, use apply_case_asset_overrides to supply host_override and method_override before running.

The report server binds to 127.0.0.1 by default. LAN sharing is explicit: pass a LAN bind host only when the report directory has been reviewed for sensitive evidence and the network is trusted.

Report bundle

Every archived report contains:

• summary.json
• runs.json
• modified_responses.json
• trace.json
• mitmproxy_events.jsonl
• execution_events.jsonl
• report.md
• index.html
• manifest.json
• copied screenshots

The integrity gate prevents the HTML report from claiming success when execution events, modified-response evidence, matching proxy hits, or verified proxy lifecycle evidence are missing.

Built-in Pillow comparison writes visual_precheck only. It never sets passed or failed. Successful execution returns awaiting_review; a Session becomes reviewed only after every lane has an explicit final pass.

See npm installation, architecture, device setup, report format, real-device regression, and troubleshooting for details.

Development and disclosure

• Contributions: CONTRIBUTING.md
• Security reports: SECURITY.md
• Conduct: CODE_OF_CONDUCT.md
• Changes: CHANGELOG.md

License

Licensed under the Apache License 2.0.