podium-mcp

One baton. Every instrument.

A single MCP stdio endpoint with 43 tools for iOS-simulator control, native UI automation, end-to-end flows, trustworthy assertions, React Native debugging, and WebView DOM + network inspection — one connection instead of half a dozen servers.

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 six capability sets behind a single stdio endpoint:

• Device & app management — simctl, with graceful adb detection.

• 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.

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.

What's new in v0.2.0

• Oracle ladder + trustworthy verdicts — assert_visible / assert_text / assert_not_visible / wait_for_element and validate_flow verify state through WebView-DOM › native a11y › Maestro, returning evidenced results that fail closed instead of guessing "looks ok".

• Batch & export — run_steps runs an ordered action batch in one call via the native backend; export_flow turns that batch into a reusable Maestro flow (the engineer→QA bridge).

• WebView network capture — webview_network records in-WebView fetch/XHR traffic and exports redacted JSON or HAR 1.2 (the network path metro_network can't see for WebView-hosted apps).

• Deeper RN introspection — metro_network (CDP Network domain) and metro_state (read the in-app Redux store) join metro_logs.

• Native-first gesture backend — idb/mobilecli cut tap_on ~14.7 s → ~0.6 s and inspect_screen ~8.9 s → ~0.9 s, with a Maestro fallback that preserves app state.

• Reliability hardening — explicit per-command timeouts with a timedOut flag, timestamped recordings + a duration watchdog, native-backend re-probe TTL, exact bundle-id matching, and transparent iOS-simulator scope.

• Registry-ready — server.json manifest + OIDC publish to the official MCP Registry, test-gated before every publish.

Related MCP server: mobile-device-mcp

Table of contents

• Why

• Requirements

• Install

• Usage

• Quick start

• The 43 tools

• The oracle ladder — trustworthy assertions

• Native-first gesture backend

• WebView & RN network introspection

• Documented limits

• Architecture

• Development & testing

• 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.

Requirements

• macOS with Xcode command-line tools (xcrun, simctl)

• Node.js ≥ 22 (uses native fetch and WebSocket; .npmrc sets engine-strict=true)

• mobilecli — bundled automatically as an npm dependency; the default native gesture + WebView backend (no separate install)

• (optional) idb (idb + idb_companion) — preferred native gesture backend when both are present; auto-detected

• (optional) Maestro on PATH (or at ~/.maestro/bin) — the run_flow engine and the gesture fallback path

• (optional) a running Metro bundler for the metro_* debugging tools

• (optional) Android SDK + adb — adb paths are detection-only and degrade gracefully when absent

Platform scope: podium's automation targets the iOS Simulator. Android devices are detected (device_list, podium_health) but not yet automatable — every adb-backed path returns an informative result instead of failing.

Install

Claude Code plugin (recommended)

No manual config — one-time marketplace setup, then install:

/plugin marketplace add github:hoainho/podium-mcp
/plugin install podium-mcp@podium

The plugin auto-starts the MCP server (all 43 tools) and ships four skills:

npx (zero install)

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

Manual (from source)

git clone git@github.com:hoainho/podium-mcp.git
cd podium-mcp
npm install
npm run build

Usage

Register the built server with any MCP client. Claude Code (.mcp.json):

{
  "mcpServers": {
    "podium": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/podium-mcp/dist/index.js"]
    }
  }
}

Quick manual smoke test over raw stdio (lists the 43 registered tools):

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node dist/index.js

Always call podium_health first to confirm which toolchain is available on the host.

Quick start (order of use)

1. podium_health — confirm xcrun / maestro / native backend availability.

2. device_list — pick a booted simulator udid.

3. Read state — app_list, app_state, screen_size, orientation_get.

4. Drive the device — app_launch, then tap_on / input_text / swipe / press_key, plus set_location and orientation_set. Batch several with run_steps.

5. Author & verify — inspect_screen to discover elements, run_flow for declarative checks, then assert_visible / validate_flow for an evidenced verdict.

6. Inspect WebViews — webview_inspect → tap coordinates, webview_eval, webview_navigate, webview_network.

7. Capture & debug — screenshot / record_start→record_stop; metro_logs / metro_network / metro_state; crash_list / crash_get.

The 43 tools

Every tool returns structured JSON and never throws — failures come back as MCP tool errors. See docs/tool-catalog.md for the authoritative per-parameter reference.

Health & toolchain (1)

Device & simulator (6)

Apps (6)

Capture (3)

UI inspection & gestures (8)

Flows & batch automation (4)

Assertions & verdicts — the oracle ladder (5)

WebView DOM & network (4)

React Native debugging — Metro CDP (4)

Crash diagnostics (2)

The oracle ladder — trustworthy assertions

"It works" is operationalized as a falsifiable, evidenced verdict — never "looks ok". Assertions and validate_flow resolve visibility through a three-rung ladder, using the strongest available signal:

1. WebView DOM — when an inspectable WKWebView is present, query the real DOM.

2. Native accessibility — the native AX element set (via idb/mobilecli).

3. Maestro — assertVisible/assertNotVisible as the fallback.

assert_not_visible fails closed: if absence can't be positively verified (e.g. a WebView is unreadable), it reports failure rather than a false pass. Every verdict names the oracle that produced it, so an agent can weight its confidence.

Native-first gesture backend

Imperative gestures (tap_on, input_text, swipe, press_key, orientation_set, run_steps) and inspect_screen route through the fastest available backend, probed once and cached (with a short negative-cache TTL so a backend that starts after launch is picked up):

1. idb — when both idb and idb_companion are installed (native, fastest).

2. mobilecli — the bundled npm dependency (prebuilt Go binary). Default; no install.

3. Maestro fallback — when no native backend resolves, or for actions it can't express (double/long-press, UPSIDE_DOWN). The gesture generates a minimal flow with launchApp: { stopApp: false }, foregrounding the app without restarting so state is preserved.

Each result reports the backend it used. Set PODIUM_DISABLE_NATIVE=1 to force Maestro. Eliminating the per-gesture JVM spin-up cut tap_on ~14.7 s → ~0.6 s and inspect_screen ~8.9 s → ~0.9 s on an iPhone 16 Pro simulator. Run npm run benchmark for a full pass/fail sweep.

Maestro flakiness retry: when the fallback runs, its iOS driver intermittently fails with Failed to connect to 127.0.0.1:<port>. Flows retry up to 2× with 2 s / 5 s backoff and report the retries count; a persistent failure returns the raw output with remediation hints.

WebView & RN network introspection

Two distinct network layers, two tools:

• metro_network captures requests on the RN/Hermes target via the CDP Network domain — the right tool for a native RN app's own fetch.

• webview_network captures traffic inside a WKWebView: it injects a fetch/XHR recorder (rich — method/status/headers/body for calls after capture starts) and reads the browser's Performance Resource Timing buffer (includeResources, default on) — every request since navigation, including pre-capture ones (URL/timing/size). The merge yields a near-complete request list, exported as redacted JSON or HAR 1.2.

For an RN shell that hosts its UI in a WebView, the app's API calls run in the web layer — so metro_network sees nothing and webview_network is the tool to reach for. WebView tools require WKWebView.isInspectable = true (default in debug/staging builds; off in production); when none is found they return an actionable error.

Documented limits (by design, not bugs)

• WebGL/Canvas content is un-automatable by selector — no DOM/hierarchy; use tap_with_fallback with screenshot-derived coordinates.

• WebView tools are dev/QA only — production App Store builds typically set isInspectable = false; tools return an actionable error and fall back to coordinate taps.

• WebView content-process memory is unreadable from the app sandbox (platform limit) — use indirect signals (memory warnings, process terminations).

• Maestro text: matcher is full-string regex (IGNORE_CASE) — partial strings don't match; copy hierarchy text verbatim or anchor with .*.

• Android is detection-only — every adb path degrades to a structured "adb not found" result.

• orientation_get is a screenshot-aspect heuristic when no native backend is present — iOS simulators expose no direct orientation query.

• record_start/record_stop keep state in-process — serialize start → … → stop on one connection; one active recording per udid (a watchdog finalizes one that's never stopped).

Architecture

src/
  index.ts          # MCP server entry — registers every tool group, warms caches
  lib/
    exec.ts         # execFile-based runner (NO shell) + timeout/timedOut flag
    result.ts       # shared ok/error MCP content helpers
    simctl.ts       # xcrun simctl wrappers + device-list TTL cache
    native.ts       # gesture/inspect backend: idb → mobilecli → null (re-probe TTL)
    idb.ts          # idb gesture/inspect adapter
    gesture.ts      # unified native→Maestro executors (shared by screen + steps)
    oracle.ts       # the oracle ladder: WebView-DOM › a11y › Maestro
    maestro.ts      # Maestro engine: flow runner, idb retry, hierarchy
    export-maestro.ts # run_steps → reusable Maestro flow
    har.ts          # HAR 1.2 export for webview_network
    webview.ts      # mobilecli CDP — WebView list/inspect/eval/navigate/network
    metro.ts        # Metro CDP — app discovery, logs, network, state
    crash.ts        # DiagnosticReports crash listing/reading
    recording.ts    # detached screen recording lifecycle + watchdog
  tools/            # one file per group:
                    #   health, device, screen, steps, flow,
                    #   assert, validate, webview, debug
assets/             # bundled offline Maestro cheat sheet + demo.gif
scripts/            # benchmark.ts, compare-mcps.ts
e2e/                # real-simulator smoke suites (smoke / full-smoke / webview-network-live)
docs/               # tool catalog, e2e transcript, roadmap

Development & testing

npm run build       # tsc
npm run typecheck   # tsc --noEmit
npm test            # vitest run — 182 unit/integration tests (exec/network mocked, no sim needed)
npm run benchmark   # spawn a fresh server over stdio and sweep the tool suite
node e2e/smoke.e2e.mjs        # real E2E against a booted simulator (macOS + Xcode)
node e2e/full-smoke.e2e.mjs   # drives all 43 tool handlers (happy + structured-error paths)

182 tests across 16 files, all passing — including the oracle ladder (oracle, assert, validate), recording watchdog + timestamps, gesture-parity (screen ≡ steps), HAR export, WebView, and Metro paths.

Standards: TypeScript strict, no as any / @ts-ignore, no shell execution (all commands via lib/exec.ts), tools return structured errors instead of throwing. See CONTRIBUTING.md for the "add a new tool" checklist.

E2E on CI: the E2E (simulator) workflow boots a real iOS simulator on a macOS runner and runs the smoke suites nightly + on demand (not a PR gate — simulator runs are slow). full-smoke.e2e.mjs asserts the happy path where a target exists and the real structured-error path where a dependency is absent (a debug isInspectable app for WebView; a connected RN app for metro_*).

Releasing

server.json is the official MCP Registry manifest. Pushing a v* tag runs Publish to npm then Publish to MCP Registry (GitHub OIDC for the io.github.hoainho/* namespace — no long-lived token). Both workflows run typecheck → build → test as a gate first; the registry publish only succeeds once the matching npm version is live, and versions are immutable.

Prompt playbook & references

• prompts/ — copy-paste prompts for e2e flows, test cases, feature verification, bug fixing, and device control. Each names the podium tools it drives and was validated on a real simulator. Start with prompts/README.md.

• docs/tool-catalog.md — authoritative tool-by-tool reference.

• docs/e2e-demo.md — a real transcript against a booted iPhone 16 Pro simulator running a production RN app.

Design ideas

• One podium, one connection. A single server fronts every mobile capability so an agent configures one endpoint and discovers all 43 tools at once.

• Safe by construction. Every external command runs through an execFile layer with an explicit argument array — never a shell string.

• Never crash the conductor. Tools return structured results and errors instead of throwing; one bad call can't take the server down.

• Degrade, don't fail. A missing toolchain (e.g. Android's adb) yields an informative result rather than a hard error.

• Prove it, don't guess. Assertions return evidenced verdicts via the oracle ladder and fail closed when they can't verify.

Contributing

Contributions welcome — see CONTRIBUTING.md and the Code of Conduct. Use the issue templates for bugs and feature requests.

Security

Please report vulnerabilities privately per SECURITY.md — do not open a public issue. SECURITY.md also documents the webview_eval / run_flow trust boundary and the PII-in-transcript caveat.

License

MIT © 2026 hoainho