io.github.hoainho/podium-mcp

**One baton. Every instrument.**
A single MCP stdio endpoint with **51 tools** for **iOS (simulator + real) and Android** device control, native UI automation, end-to-end flows, trustworthy assertions, React Native debugging, **WebView DOM + network inspection**, and a **no-vision canvas/WebGL brain** for Pixi/Konva/Fabric/Phaser/Three/Babylon (validated live in WebKit) — plus an **experimental** engine bridge for instrumented Unity/GL builds (AltTester) — one connection instead of half a dozen servers.
-2ea44f.svg)
One prompt → podium drives Safari live → types the URL → explores the profile → opens a repo. Footage captured on a live iPhone 16 Pro simulator.
---
A podium is where a maestro stands — one place to conduct the whole orchestra. This MCP server unifies eight capability sets behind a single stdio endpoint:
- **Device & app management** — iOS simulators (simctl), real iPhones (devicectl), and Android (adb) behind one platform-tagged device model.
- **Native UI inspection & gestures** — route through idb/mobilecli with a Maestro fallback (no per-gesture JVM spin-up).
- **End-to-end flows & batch automation** — declarative Maestro flows, ordered action batches, and an engineer→QA flow exporter.
- **Trustworthy assertions** — an *oracle ladder* (WebView-DOM › native a11y › Maestro) that returns falsifiable, evidenced verdicts and **fails closed**.
- **WebView DOM + network** — resolve WKWebView DOM to tap coordinates, evaluate JS, drive navigation, and capture in-page HTTP traffic as JSON/HAR.
- **React Native debugging** — Metro console logs, network requests, and in-app state over CDP, plus host/simulator crash reports.
- **Real devices** — Android emulator/device via adb (gestures + uiautomator hierarchy); real iOS via devicectl lifecycle + an opt-in WebDriverAgent backend.
- **Canvas & game-engine automation, no vision** — a *canvas/WebGL brain* drives Pixi/Konva/Fabric/Phaser/Three/Babylon UIs as addressable objects (validated live in WebKit). An **experimental** engine bridge drives Unity/GL via an **AltTester-instrumented** build (or a window.__podiumEngine WebGL bridge) — code-complete + mock-tested, not yet run against a live Unity build.
Rather than wiring several MCP servers into every client config, podium-mcp exposes everything behind **one connection**, with a shared execFile layer (no shell), consistent structured errors, automatic retry around Maestro's iOS-driver flakiness, and a single health-check tool to confirm what's available on the host.
Table of contents
- Why
- Benchmarks
- Requirements
- Install
- Usage
- Quick start
- The 51 tools
- The oracle ladder — trustworthy assertions
- Native-first gesture backend
- WebView & RN network introspection
- Documented limits
- Architecture
- Development & testing
- Roadmap & contributing
- Releasing
- Prompt playbook & references
- Design ideas
- Contributing · Security · License
Why
Driving a React Native app end-to-end usually means juggling several MCP servers —
one for device/app control, one for UI flows, one for Metro/debugger logs, another
for WebView inspection — each with its own config entry, quirks, and failure modes.
podium-mcp collapses that into **one** server with:
- a single execFile-based command runner (no shell — arguments are passed verbatim),
- consistent structured errors (a tool never crashes the server),
- automatic retry around Maestro's known iOS-driver flakiness,
- graceful degradation when a toolchain (e.g. adb) is absent,
- **evidenced verdicts** so an agent knows when a flow *actually* worked.
Benchmarks
Podium is built on two choices that make it **fast** and **cheap**: it drives UIs
as *structured data* — never screenshots — and routes gestures through a *native
backend* with no per-action JVM spin-up.
Token economics — no-vision is ~5× cheaper
A screenshot-driven agent sends an image to a vision model on **every step**.
Podium returns a compact structured element list instead. On an equivalent 8-step
mobile flow (1179×2556 screenshots vs ~20-element lists):
| Approach | Per step | 8-step flow |
| --- | ---: | ---: |
| Screenshot / vision loop | ~2,070 tokens | **16,557 tokens** |
| Podium — no-vision, structured | ~390 tokens | **3,117 tokens** |
| **Savings** | **5.3×** | **−13,440 tokens (−81%)** |
The gap **compounds with every step** — a 30-step session runs roughly **62k vs
12k** input tokens. On top of per-step cost, the full **51-tool schema travels
with every request (~3,612 tokens, ~71/tool)**; Podium keeps tool descriptions