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

• Extracts abnormal cases from plain text, Markdown, tables, numbered steps, and Gherkin without requiring one authoring format.
• Accepts URL/path-only request hints and resolves missing host or HTTP method from each device lane's current passive proxy traffic before mutation.
• Constrains semantic extraction to source-anchored candidate JSON; the model cannot submit proxy patches, commands, or device actions.
• Runs any single platform, any two-platform combination, or all Android, iOS, and HarmonyOS lanes independently in one run_cases call.
• Reuses one process-local device runtime per Android serial, iOS UDID/WDA endpoint, or HarmonyOS serial.
• Keeps the recoverable iOS WDA action session entirely inside the runtime boundary and reuses the HarmonyOS HDC worker/recent verified page snapshot across adjacent MCP actions.
• Returns explicit element-read states (available, empty, unavailable, timeout) so transport/parser failures cannot be mistaken for a real empty page.
• Uses non-blocking device-and-listener resource leases so disjoint tasks can run concurrently without sharing transient proxy state.
• 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 one dynamic single-, dual-, or triple-platform HTML report plus machine-readable artifacts.
• Persists scoped navigation and field-alias knowledge for later runs.
• Supports wildcard, slice, union, filter, negative-index, and recursive JSONPath field rules.

Safety model

preflight never changes a phone's Wi-Fi HTTP proxy. When explicitly requested, it may start or repair the iOS WDA/iproxy automation runtime, and Android proxy inspection may bring system Settings to the foreground. 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.

The MCP keeps one persistent multi-port mitmproxy runtime per workspace and reuses it across formal runs. A task never stops that runtime. If MCP actually changes a phone's Wi-Fi proxy, the original snapshot is persisted and restore_device_proxy restores and verifies the phone without touching mitmproxy. Use stop_proxy_runtime independently when the host runtime itself must be stopped.

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 installation and daily runs

1. Run doctor once after install or upgrade. Use runtime_status, preflight, and prepare_run only for troubleshooting, not before every task.
2. Provision and trust iOS WDA as a standalone maintenance action while the iPhone Wi-Fi proxy is off. Normal runs may recover iproxy and start one valid existing signed Runner with test-without-building; they stop immediately if strong readiness is still unavailable and never rebuild or resign WDA inline.
3. Submit testcase input through one run_cases call. Selected platforms prepare concurrently; any failed prerequisite stops the complete task before business navigation.
4. A fresh matching device/network/host/port proof skips Wi-Fi Settings. A direct-connect phone may receive one initial managed configuration; a retained mismatched manual Host or port fails with exact current/expected guidance and is never rewritten automatically.
5. Review index.html, modified_responses.json, and manifest.json, then submit final VLM or human decisions.
6. If the run changed a phone proxy, call restore_device_proxy when capture is no longer needed. Stop the host-level persistent listener only through stop_proxy_runtime.

Use targets for an explicit execution set. For example, ["android", "harmony"] and ["ios", "harmony"] both execute as one multi-lane Session and produce one comparison report. The target expression remains supported when it identifies an unambiguous platform set.

New callers should prefer one structured devices list. It can derive the selected lanes and keep each platform's serial, package, navigation, trigger, and iOS WDA settings together:

{
  "devices": [
    {
      "target": "android",
      "serial": "<android-serial>",
      "app_package": "<android-package>",
      "navigation_path": []
    },
    {
      "target": "ios",
      "udid": "<ios-udid>",
      "bundle_id": "<ios-bundle-id>",
      "wda_url": "http://127.0.0.1:8100",
      "navigation_path": []
    }
  ]
}

Flat android_serial, ios_udid, harmony_serial, platform maps, and global WDA fields remain available. If both input forms are supplied, conflicting values are rejected before device work.

The proxy reminder is evidence-based: it appears only when MCP changed a phone proxy. Call restore_device_proxy before leaving the test network or returning that device. The persistent host runtime is independent and can be inspected with proxy_runtime_status or explicitly stopped with stop_proxy_runtime.

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.

Case files may contain a full URL or only a path, and GET/POST is optional during extraction. A missing host or method is marked pending_capture; after navigation, each Android, iOS, or HarmonyOS lane independently observes the target request on its current Session and listener port. Only a unique resolved host + path + method contract can enter the strict response-mutation matcher. The runner never guesses GET, actively probes alternative methods, or falls back from an empty current import to historical rules. Manual apply_case_asset_overrides remains available for explicit operator-controlled corrections.

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, testcase extraction and execution, architecture, device setup, report format, real-device regression, and troubleshooting for details.

Field rules accept rootless dotted paths and a safe production JSONPath subset. See response field paths for selectors, filter operators, batch semantics, and evidence behavior.

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.