Mobile E2e Mcp

Mobile E2E MCP (2026)

[](https://github.com/shenyuexin/mobile-e2e-mcp/actions/workflows/ci.yml) [](https://github.com/shenyuexin/mobile-e2e-mcp/actions/workflows/platform-smoke.yml) [](https://github.com/shenyuexin/mobile-e2e-mcp/actions/workflows/real-device-acceptance.yml)

> AI-safe mobile device control via MCP: a policy-guarded, session-oriented mobile automation harness for AI agents, with deterministic-first Android/iOS execution, bounded visual fallback, and evidence-rich outcomes.

This repository is a pnpm monorepo that combines MCP tooling, adapter execution, and architecture docs for AI agents that need to inspect, act on, and debug mobile apps without turning raw device commands into ungoverned side effects.

Quick Start

{
  "mcpServers": {
    "mobile-e2e-mcp": {
      "command": "npx",
      "args": ["-y", "@shenyuexin/mobile-e2e-mcp@latest"]
    }
  }
}

Once installed, you get 66 MCP tools for governed mobile automation, plus a built-in Explorer for automatic page traversal.

Primary Product Surface: Explorer

Explorer is the main outward-facing product capability of this repository. It is not a standalone crawler bolted onto the side; it is the clearest product surface for the harness because broad app exploration requires the same core MCP capabilities a mobile AI agent needs in practice: device discovery, auditable sessions, UI inspection, bounded UI actions, rule-based risk gates, interruption/recovery handling, and structured evidence.

Use Explorer when you want to answer product questions such as:

• Which screens are reachable from this app entry point?
• Which flows are blocked by policy, external-app boundaries, risk gates, or repeated failures?
• What changed between two exploration runs?
• Which discovered paths should be promoted into deterministic replay or PR review evidence?

Explorer writes fixed, reviewable artifacts such as tree.txt, report.md, summary.json, config.json, and failure-review JSON/Markdown. Current local and tracked evidence includes large Settings explorations, including 100+ page runs, with rule decisions, interruption/failure context, and machine-consumable page metadata.

Core Wedge: Governed Agent Control

The strongest use case for this project is not "replace every mobile E2E framework." It is: give an AI agent a safer control plane for mobile devices.

Compared with a thin adb or platform-command wrapper, this harness adds:

• Policy boundaries: actions are checked against policy profiles before execution.
• Auditable sessions: actions run inside session, lease, audit, and evidence context.
• Capability disclosure: agents can query supported platforms and boundaries before acting.
• Structured outcomes: failures, denials, and evidence are machine-consumable instead of log-only.

Reproduce the dry-run proof:

pnpm run proof:governed-agent-mobile-control

The proof writes a timestamped bundle under output/showcase/governed-agent-mobile-control// and verifies that a read-only session blocks an interactive action with structured POLICY_DENIED. See [Governed Agent Mobile Control Proof](docs/showcase/governed-agent-mobile-control.md).

Explorer: Automatic Page Traversal

Explorer is a DFS-based automatic page traversal engine built into the MCP server. It systematically navigates through your app's screens, builds a state graph, and produces structured coverage reports without requiring manual flow definitions.

npx -y @shenyuexin/mobile-e2e-mcp@latest explore \
  --app-id com.example.app \
  --platform android \
  --output ./explore-report

Key features:

• DFS-based traversal: systematically explores every reachable screen from a starting point
• State graph tracking: records visited states and detects cycles to avoid infinite loops
• Circuit breaker: automatically stops when exploration hits diminishing returns or configured limits
• Structured coverage reports: outputs machine-consumable reports showing which screens and elements were discovered
• Rule-based gating: respects skip-page, skip-element, sampling, and risk-gating rules for safe exploration
• Interruption-aware evidence: records blocked, interrupted, skipped, and failed traversal decisions with reasons so a run can be reviewed instead of treated as a raw pass/fail crawl
• Experimental horizontal fallback: after vertical segments are exhausted, Explorer can probe horizontally scrollable content with bounded page-identity checks

Output

Explorer produces a directory of structured artifacts:

| File | Description | |------|-------------| | tree.txt | ASCII tree of all discovered pages and navigation paths | | report.md | Human-readable coverage report with module breakdown | | failure-review.md | Human-readable failure triage with grouped patterns and suggested next actions | | failure-review.json | Machine-consumable failure triage summary | | summary.json | Machine-consumable metrics and page metadata | | config.json | Runtime configuration and rule settings used for the run |

Example output from a real run against iOS Settings (181 pages, max depth 5):

• [tree.txt](docs/showcase/explorer/tree.txt) — full page hierarchy
• [report.md](docs/showcase/explorer/report.md) — module breakdown and paths
• [summary.json](docs/showcase/explorer/summary.json) — metrics and metadata

Local real-device runs are written under output/evidence/explorer/. These outputs are intentionally structured so they can be curated into public showcase evidence or consumed by follow-on tooling such as coverage diffing, PR summaries, and replay path extraction.

For architecture details and rule configuration:

• [Explorer hybrid traversal design](docs/architecture/explorer-hybrid-traversal-ascii.md)
• [Explorer rule registry](docs/engineering/explorer-rule-registry.zh-CN.md)

What This Repository Actually Is

This repo contains both:

1. Executable implementation (MCP server, adapters, contracts, core orchestration), and
2. Architecture and delivery knowledge base (design principles, capability model, phased rollout docs).

If you only remember one thing: this project is designed as an Explorer-led, governed mobile control layer for AI agents, not a single-framework test runner.

Mobile E2E Harness Positioning

This project is an AI mobile E2E harness: a policy-aware, session-oriented, deterministic-first execution harness for mobile automation where an AI agent needs controlled action, evidence, and support-boundary clarity.

If you're searching for terms like mobile test harness, real-device Android test harness, AI automation harness, or mobile CI harness, this repository is built for that exact workflow.

Why teams use this harness

• Deterministic-first harness: stable selectors and structured retries before OCR/CV fallback
• Failure-intelligence harness: reason codes, evidence artifacts, and remediation suggestions
• Governance-aware harness: policy profiles, auditable sessions, and controlled tool surfaces
• Explorer harness: the primary product surface, combining traversal, tool orchestration, risk gating, interruption handling, recovery, and structured coverage/failure evidence (available via CLI)
• Real-device evidence: Explorer/probe artifacts plus historical videos for happy path and interruption recovery

Capability Showcase

If you want a quick hands-on tour before diving into architecture details, start here:

• Happy path video (login -> scroll -> add to cart -> orders -> cart):
• docs/showcase/videos/m2e-happy-path-scroll-pause-40s.mp4
• Visible interruption + recovery video (HOME interruption -> recovertoknown_state -> continue action):
• docs/showcase/videos/m2e-interruption-home-recovery-35s.mp4
• Current real-device verification:
• Android Explorer evidence: docs/showcase/evidence/android-explorer-full-2026-04-28T03-38-20/
• Android probe entrypoint: pnpm run validate:android-tool-probe (latest Vivo V2405A run: 20/23 success, 0 partial, 3 expected diagnostic failures; core UI and interruption-resume paths passed)
• iOS probe entrypoint: pnpm run validate:ios-tool-probe
• Governed-control proof:
• pnpm run quickstart:governed-control (first-run readiness and next-command guide)
• pnpm run proof:governed-agent-mobile-control
• pnpm run proof:governed-agent-mobile-control:preflight (checks Android live-proof readiness)
• pnpm run proof:governed-agent-mobile-control:live (requires an Android device/emulator)
• pnpm run proof:governed-business-app-workflow (installs/launches the demo app, then switches to read-only governed agent observation)
• pnpm run proof:governed-policy-escalation (denies under read-only, then retries under interactive policy)
• pnpm run validate:governed-control-evidence
• pnpm run validate:governed-business-app-evidence
• pnpm run validate:governed-business-app-comparison
• pnpm run validate:governed-policy-escalation-evidence
• pnpm run validate:governed-evidence-brief
• pnpm run validate:governed-pr-evidence-summary
• pnpm run verify:mobile-change (one-command mobile change verification UX; use -- --live --contract=configs/readiness/mobile-change.android.json for contract-backed live mode)
• pnpm run generate:mobile-change-readiness-contract / pnpm run validate:mobile-change-readiness-contract
• pnpm run generate:mobile-change-repo-app-success-candidate / pnpm run validate:mobile-change-repo-app-success-candidate (repo-owned demo app success candidate; blocked output is not success evidence until a device/emulator run passes intake)
• pnpm run generate:mobile-change-ci-pr-evidence / pnpm run validate:mobile-change-ci-pr-evidence (compact PR/CI artifact with proof-level-safe blocked/failed/success labels)
• pnpm run generate:mobile-change-failure-memory / pnpm run validate:mobile-change-failure-memory (deterministic failure-pattern grouping and bounded next-action routing)
• pnpm run verify:react-native-change (experimental RN lane that runs readiness plus evidence-pack orchestration; live success still requires device, Metro, debug target, stable selectors, and intake-backed proof)
• pnpm run generate:react-native-readiness / pnpm run validate:react-native-readiness (RN preflight for device, Metro, JS debug target, readiness contract, and stable selectors)
• pnpm run generate:react-native-evidence-pack / pnpm run validate:react-native-evidence-pack (RN review artifact that keeps Metro signals supplemental)
• pnpm run proof:mobile-change-verification (fixture-backed mobile change verification bundle, failure packet, and scenario index)
• pnpm run generate:mobile-change-device-readiness / pnpm run validate:mobile-change-device-readiness (structured device/app/readiness preflight before attempting live mobile change proof)
• pnpm run proof:mobile-change-verification:live (optional live device/emulator proof; use M2E_LIVE_MOBILE_CHANGE_ALLOW_NO_DEVICE=1 for structured no-device output)
• pnpm run proof:mobile-change-verification:live-settings (runnable no-APK Android Settings success lane; requires 10AEA40Z3Y000R5 or editing the device id)
• pnpm run generate:mobile-change-live-settings-lane / pnpm run validate:mobile-change-live-settings-lane
• pnpm run proof:mobile-change-verification:readiness-failure (controlled live-runner-derived app readiness failure packet)
• pnpm run validate:mobile-change-verification
• pnpm run validate:mobile-change-live-android-evidence (tracked Android device 10AEA40Z3Y000R5 live app-readiness failure evidence)
• pnpm run validate:mobile-change-readiness-failure
• pnpm run generate:mobile-change-handoff / pnpm run validate:mobile-change-handoff
• pnpm run intake:mobile-change-live-proof / pnpm run validate:mobile-change-live-proof-intake (review live runner output before promoting it as tracked evidence)
• [docs/showcase/governed-agent-mobile-control.md](docs/showcase/governed-agent-mobile-control.md)
• [docs/showcase/governed-agent-mobile-control-live.md](docs/showcase/governed-agent-mobile-control-live.md)
• [docs/showcase/governed-business-app-workflow.md](docs/showcase/governed-business-app-workflow.md)
• [docs/showcase/governed-policy-escalation.md](docs/showcase/governed-policy-escalation.md)
• [docs/showcase/governed-quickstart.md](docs/showcase/governed-quickstart.md)
• [docs/showcase/evidence/governed-control-brief/brief.md](docs/showcase/evidence/governed-control-brief/brief.md)
• [docs/showcase/evidence/governed-control-brief/pr-comment.md](docs/showcase/evidence/governed-control-brief/pr-comment.md)
• [docs/showcase/evidence/governed-control-vivo-2026-05-23/report.md](docs/showcase/evidence/governed-control-vivo-2026-05-23/report.md)
• [docs/showcase/evidence/governed-business-app-vivo-2026-05-24/report.md](docs/showcase/evidence/governed-business-app-vivo-2026-05-24/report.md)
• [docs/showcase/evidence/governed-business-app-vivo-2026-05-24/comparison.md](docs/showcase/evidence/governed-business-app-vivo-2026-05-24/comparison.md)
• [docs/showcase/evidence/governed-policy-escalation-dry-run-2026-05-25/report.md](docs/showcase/evidence/governed-policy-escalation-dry-run-2026-05-25/report.md)
• [docs/showcase/evidence/mobile-change-verification-fixture/report.md](docs/showcase/evidence/mobile-change-verification-fixture/report.md)
• [docs/showcase/evidence/mobile-change-verification-fixture/failure-packet.md](docs/showcase/evidence/mobile-change-verification-fixture/failure-packet.md)
• [docs/showcase/evidence/mobile-change-verification-fixture/scenario-index.md](docs/showcase/evidence/mobile-change-verification-fixture/scenario-index.md)
• [docs/showcase/evidence/mobile-change-device-readiness/report.md](docs/showcase/evidence/mobile-change-device-readiness/report.md)
• [docs/showcase/evidence/mobile-change-live-android-10AEA40Z3Y000R5/report.md](docs/showcase/evidence/mobile-change-live-android-10AEA40Z3Y000R5/report.md)
• [docs/showcase/evidence/mobile-change-live-settings-lane/lane.md](docs/showcase/evidence/mobile-change-live-settings-lane/lane.md)
• [docs/showcase/evidence/mobile-change-live-proof-intake/intake.md](docs/showcase/evidence/mobile-change-live-proof-intake/intake.md)
• [docs/showcase/evidence/mobile-change-repo-app-success-candidate/candidate.md](docs/showcase/evidence/mobile-change-repo-app-success-candidate/candidate.md)
• [docs/showcase/evidence/mobile-change-ci-pr-evidence/pr-summary.md](docs/showcase/evidence/mobile-change-ci-pr-evidence/pr-summary.md)
• [docs/showcase/evidence/mobile-change-failure-memory/remediation.md](docs/showcase/evidence/mobile-change-failure-memory/remediation.md)
• [docs/showcase/evidence/mobile-change-readiness-failure/failure-packet.md](docs/showcase/evidence/mobile-change-readiness-failure/failure-packet.md)
• [docs/showcase/evidence/mobile-change-readiness-failure/handoff.md](docs/showcase/evidence/mobile-change-readiness-failure/handoff.md)
• Historical demo scripts:
• bash scripts/legacy/dev/record-demo-happy-path-android.sh
• bash scripts/legacy/dev/record-demo-interruption-home-recovery-android.sh
• bash scripts/legacy/dev/publish-showcase-assets-android.sh (record + curate videos + refresh snapshots/GIFs)
• Demo playbook and evidence index:
• [docs/showcase/README.md](docs/showcase/README.md)
• [docs/showcase/demo-playbook.zh-CN.md](docs/showcase/demo-playbook.zh-CN.md)
• [docs/showcase/failure-intelligence-demo.md](docs/showcase/failure-intelligence-demo.md)
• AI invocation and task guides:
• [docs/guides/ai-agent-invocation.zh-CN.md](docs/guides/ai-agent-invocation.zh-CN.md)
• [docs/guides/golden-path.md](docs/guides/golden-path.md)
• [docs/guides/flow-generation.md](docs/guides/flow-generation.md)
• CI evidence and bound

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shenyuexin
• Source: shenyuexin/mobile-e2e-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.