mholecy/averi

averi is an MCP server that gives a coding agent hands on iOS Simulators and Android Emulators: launch the app, tap, type, read the screen, assert, screenshot. Its differentiator is ensure_state — the project checks in an averi.yaml describing app states (like logged in) and how to reach them, so the agent gets past login and deep into the app deterministically, instead of fumbling through it tap by tap on every task.
averi itself is project-independent: it ships only tools. Everything app-specific — states, flows, credentials — lives in your app repo.
## Installation
averi is on npm — nothing to clone or build. Setup is a job for your agent, not for you:
1. Register the MCP server (in your app repo):
bash
claude mcp add averi -- npx -y averi
2. Restart your agent session and paste this prompt:
> Set up the averi tool in this repo. Fetch https://raw.githubusercontent.com/mholecy/averi/main/SETUP.md and follow it step by step — run every check, and don't report done until the final verification passes.
The agent handles the rest: verifies prerequisites (adb, idb, a booted device), creates the gitignored .env.averi for test credentials, installs the agent skill, authors averi.yaml by driving your actual app, and proves the setup by logging in end to end — twice (once cold through the full flow, once warm in ~1 s).
Prefer to do it by hand, or setting up for a whole team (committed .mcp.json)? Everything is in SETUP.md — it reads fine for humans too.
Updating later is also an agent job — ask it to follow SETUP.md → Updating averi (bumps the version, re-syncs the copied skill so it can't drift, re-runs the login proof).
## What is averi
mermaid
flowchart LR
A(["AI agent"]) -- MCP --> S["averi server"]
S -- "adb / simctl + idb (opt-in WDA)" --> D["emulator / simulator"]
subgraph R["your app repo"]
Y["averi.yaml states, flows, selectors"]
E[".env.averi — gitignored credential values"]
end
S -. reads .-> Y
S -. reads .-> E
Your agent changes mobile code all day but can't see whether the app actually works. averi closes that loop: after a change, the agent builds the app, installs it, drives it to the changed screen, and verifies — on both platforms, on real simulators.
Three ideas make that reliable:
One tree, one selector language. Both platforms' accessibility trees are normalized into one model, so the same selectors (id:, text:"…", role:) — and usually one yaml — drive both OSes, with per-platform overrides only where they differ.
States over tap sequences. averi.yaml declares where the app can be and how to get there. The agent says ensure_state("logged_in") and averi does the rest, deterministically.
Credentials never in yaml. ${ENV_VAR} references resolve from a gitignored .env.averi (real env vars win, so CI works normally), and values are redacted () from every trace and error.
## How it works
### ensure_state — the core loop
mermaid
flowchart LR
A["ensure_state('logged_in')"] --> B{"screen matches the state's detect condition?"}
B -- yes --> C(["done — ~1 s"])
B -- no --> D["run the next reach: flow, e.g. login"]
D --> E{"detect: matches now?"}
E -- yes --> C
E -- no --> G{"another reach: flow?"}
G -- yes --> D