io.github.hoainho/podium-mcp

Installs an app on an iOS simulator. Accepts a path to a .app directory or a .zip archive.

Launches an app on an iOS simulator by bundle ID.

Returns the list of installed apps on a booted iOS simulator. Includes bundle ID, display name, and application type (User/System).

Checks whether an app is installed and/or running on an iOS simulator. installed: exact bundle-id match against the parsed simctl listapps output; running: matches the launchctl UIKitApplication:<bundleId> label on a token boundary (no prefix false positives).

Terminates a running app on an iOS simulator by bundle ID.

Uninstalls an app from an iOS simulator by bundle ID.

Asserts an element/text is ABSENT. FAILS CLOSED: if absence cannot be verified (e.g. a WebView whose DOM is unreadable — native a11y is blind to web content), returns an 'unverifiable' error rather than a false pass. Passes only when a capable oracle confirms absence.

Asserts the given text is visible on screen (by-text shorthand for assert_visible). Same oracle ladder + unverifiable handling.

Asserts an element/text is visible, via the oracle ladder (WebView-DOM > native a11y > Maestro). Passes only when a capable oracle confirms presence; if the surface is a WebView whose DOM can't be read (isInspectable=false), returns an 'unverifiable' error instead of a false pass. Provide text (any surface) or selector (WebView).

Lists canvas/WebGL objects (Pixi/Konva/Fabric/Phaser/Three/Babylon) as DOM-like elements with tap-ready coordinates — NO screenshot/vision. Optionally filter by selector (name/id/text/type/role). Requires an inspectable WKWebView (isInspectable=true; debug/staging) hosting a canvas/WebGL framework (Pixi/Konva/Fabric/Phaser/Three/Babylon) with its root reachable (commonly on window, or Pixi's __PIXI_APP__). NO screenshots/vision — fails closed otherwise.

Resolves a fuzzy intent (e.g. "close", "settings", "✕") to a ranked, EVIDENCED canvas target without tapping — the 'close brain'. Returns the best match, all candidates with reasons, and a fail-closed confidentEnough flag (false when two targets tie). NO vision. Requires an inspectable WKWebView (isInspectable=true; debug/staging) hosting a canvas/WebGL framework (Pixi/Konva/Fabric/Phaser/Three/Babylon) with its root reachable (commonly on window, or Pixi's __PIXI_APP__). NO screenshots/vision — fails closed otherwise.

Resolves an intent to a single canvas target and TAPS it at absolute screen coordinates — the native-like 'close this' for canvas UIs. Fail-closed: if no confident, unambiguous match exists it does NOT tap and returns the candidates so you can disambiguate. NO vision. Requires an inspectable WKWebView (isInspectable=true; debug/staging) hosting a canvas/WebGL framework (Pixi/Konva/Fabric/Phaser/Three/Babylon) with its root reachable (commonly on window, or Pixi's __PIXI_APP__). NO screenshots/vision — fails closed otherwise.

Returns the bundled Maestro flow script cheat sheet (offline copy). Consult this before authoring unfamiliar Maestro commands, required args, nested properties, conditionals, or multi-screen flows.

Reads a crash report by its id (filename from crash_list). For .ips files returns a parsed JSON header and the report body (first ~8000 chars, truncated flag set if longer). Pass the same udid used for crash_list to also resolve sim-container reports. Path-traversal-safe.

Lists crash reports (.ips/.crash) from ~/Library/Logs/DiagnosticReports — plus the simulator's own container DiagnosticReports when udid is given — sorted newest first. Filter by processName (case-insensitive substring) and/or sinceHours.

Boots an iOS simulator by UDID. Waits up to 30 seconds for the boot command to complete. Idempotent: booting an already-booted device returns ok with alreadyBooted:true.

Returns a merged inventory of available iOS simulators (udid, name, state, runtime) plus any adb-detected Android devices. If adb is absent, the android section reports availability: false instead of failing. NOTE: Android entries are detection-only — podium's automation tools (tap/inspect/etc.) currently target iOS simulators.

Invokes a C# component method on a game-engine object by reflection — the engine analog of firing a DOM event handler. Requires an AltTester-instrumented build (dev/staging) with the in-app server running — production App Store builds are not instrumented. Uses no screenshots/vision.

Lists game-engine (Unity/GL) objects matching a selector, each with absolute screen coordinates for tapping — DOM-like addressing with NO vision. Requires an AltTester-instrumented build (dev/staging) with the in-app server running — production App Store builds are not instrumented. Uses no screenshots/vision.

Swipes between two screen coordinates inside a game-engine view. Requires an AltTester-instrumented build (dev/staging) with the in-app server running — production App Store builds are not instrumented. Uses no screenshots/vision.

Taps a game-engine object resolved by selector (engine-reported screen coords, no vision). Requires an AltTester-instrumented build (dev/staging) with the in-app server running — production App Store builds are not instrumented. Uses no screenshots/vision.

Exports a run_steps action sequence to a reusable Maestro flow (the engineer→QA bridge). Selector-based steps (tapText by id/text, key, swipe-by-direction, waitFor, assertVisible, screenshot) transpile cleanly. The lossy steps — coordinate tap/swipe, focused-field type, regex tapText — are emitted as commented '# TODO[unstable]' lines plus a warnings[] list, never as silently divergent YAML. Fix the TODOs to make the flow durable regression.

Types text into the currently-focused element via an ephemeral Maestro flow. Set submit:true to press Enter after typing. Note: Android does not support Unicode via inputText. WebView caveat: inputText injects at the native buffer level — React onChange/onChangeText never fires. For WebView forms use mobile-mcp mobile_type_keys (real keystroke simulation) instead.

Returns the current view hierarchy for a booted iOS simulator (podium's target platform). Uses idb's flat accessibility tree when idb is installed (fast), else maestro hierarchy. Defaults to compact:true — a flattened list of only the nodes that carry text / accessibility labels / resource-ids (dramatically smaller than the raw tree). Pass compact:false for the full nested hierarchy. LIMITATION: WebView (WKWebView/WebView) content is opaque — the hierarchy shows a single WebView node with no children. Web-rendered buttons, inputs, and labels are invisible to this tool. For WebView apps, identify elements visually via screenshot then calculate logical-point coordinates (screenshot pixels ÷ device scale factor, typically ÷3 on 3× Retina).

Lists React Native apps currently connected to a Metro bundler inspector. Returns CDP-style targets (id, title, webSocketDebuggerUrl). Returns a structured error if Metro is not running on the given port.

Reads console logs from a React Native app via the Metro CDP debugger. If webSocketDebuggerUrl is omitted, auto-discovers via metro_apps and uses the first connected app. Reports which app was chosen. Pass saveTo to also write the console timeline to a file for evidence (e.g. attach to a bug).

Captures network requests from a React Native app via the Metro CDP debugger (Network domain). If webSocketDebuggerUrl is omitted, auto-discovers via metro_apps and uses the first connected app. Pairs requestWillBeSent with responseReceived by requestId (method, url, status, headers, timing). format:'har' emits a valid HAR 1.2 log (HAR-lite — no response bodies yet) you can open in Chrome DevTools → Import HAR; pass saveTo to write the .har file. Sensitive headers (authorization/cookie/…) are REDACTED by default — set redact:false to keep them (don't commit unredacted HAR: it leaks tokens).

Reads app state from a React Native app by evaluating a JS expression in its runtime via the Metro CDP debugger (Runtime.evaluate, returnByValue). Default expression reads a globally-exposed Redux store; override `expression` to read any in-app value. The app must expose the value on a global the runtime can reach. Auto-discovers the ws via metro_apps when omitted.

Attempts to dismiss the React Native debug notification bar that sometimes appears at the bottom of the screen and intercepts taps. Taps the debug icons area at (50, 850) via the native backend (idb, else Maestro) and takes a before/after screenshot. NOTE: the (50,850) tap point is a device-specific heuristic, and 'cleared' is decided by a screenshot byte-size delta — a best-effort signal, not a guarantee (see tap_with_fallback caveat).

Opens a URL on an iOS simulator (deep-links, https:// etc.).

Returns the current orientation of a booted iOS simulator. Queries the native backend (mobilecli) when available for an exact answer; otherwise derives it from the screenshot aspect ratio.

Sets the screen orientation on an iOS simulator via an ephemeral Maestro flow. bundleId is required (Maestro needs it for the appId flow header). Valid values: PORTRAIT, LANDSCAPE_LEFT, LANDSCAPE_RIGHT, UPSIDE_DOWN

Returns health status of the podium-mcp server and toolchain availability. Scope: iOS (simulator + real device), Android (emulator + real via adb), game-engine (Unity/GL via AltTester), and no-vision canvas/WebGL automation. macOS + Xcode required; adb for Android, an instrumented build for engine tools.

Quantifies Podium's token savings: for an N-step flow, computes input tokens for Podium's no-vision structured flow vs a screenshot/vision loop, the savings ratio, and the fixed per-request tool-definition overhead. Heuristic estimates (~4 chars/token text, ~750 px/token image) — deterministic, no network.

Presses a hardware or system key via an ephemeral Maestro flow on the iOS simulator. Note: back/power/tab are Android key events and have no effect on iOS — they remain in the enum for a future Android backend. Valid keys: enter, home, lock, backspace, volume up, volume down, back, power, tab

Starts a screen recording on a booted iOS simulator. The recording runs in a detached background process. Call record_stop to finalize and retrieve the file.

Stops the active screen recording for an iOS simulator. Sends SIGINT to flush the video file, waits for the file size to stabilize, and returns the path and size.

Execute one or more Maestro flows on a device. Provide exactly one of: yaml (inline YAML string), files (array of flow file paths), or dir (directory path). includeTags and excludeTags are only applicable when using dir. When to use: run_flow gives the full Maestro vocabulary (assertions, conditionals, loops, retries); for a simple sequence of taps/types prefer run_steps, and for one gesture use the individual tools. TRUST BOUNDARY: Maestro flows can run arbitrary JS (evalScript) and local files (runScript/files/dir), so treat run_flow input as locally-executable code.

Execute an ordered batch of UI actions in ONE call via the native backend (idb/mobilecli, sub-second; Maestro fallback per step). Eliminates per-gesture MCP round-trips for fast continuous flows (login, navigation, form fill). Step actions: tap {x,y} · tapText {text|id} · type {text,submit} · key · swipe · waitFor {text,timeoutMs} · assertVisible {text} · waitMs · screenshot. Prefer `waitFor` over `waitMs` to act the instant the UI is ready instead of sleeping. WebView note: web-rendered text is invisible to tapText — use tap {x,y} for it; `type` uses real keystrokes so React onChange fires. Stops at the first failed step unless stopOnError:false. bundleId is only needed for the Maestro fallback (auto-detected otherwise). When to use: pick run_steps for >2 known sequential gestures (login, navigation, form fill); use run_flow for Maestro assertions/conditionals/loops/retries; use the individual gesture tools (tap_on, swipe, …) for a single exploratory action.

Returns the pixel dimensions of a booted iOS simulator screen by taking a temp screenshot and reading its pixel dimensions with sips.

Takes a screenshot of an iOS simulator. Returns the saved file path and byte size. Does NOT return base64 to keep payload small. saveTo defaults to a .png file in os.tmpdir().

Sets the simulated GPS location on a running iOS simulator. Codifies the QA geo-spinner fix: use this to unblock location-gated features during QA testing without moving the physical device.

Swipes in a direction or between two coordinates via an ephemeral Maestro flow. direction is always required; startX/startY/endX/endY are optional overrides expressed as percentage strings (e.g. '10%,50%') or pixel values.

Tap, double-tap, or long-press an element on screen via an ephemeral Maestro flow. Target by text (regex), accessibility id, or absolute x/y coordinates. bundleId is REQUIRED — Maestro needs it for the appId flow header. WebView caution: text/id selectors only resolve native accessibility nodes. Web-rendered elements inside WKWebView are invisible — tap_on will report COMPLETED but nothing is tapped. Use x+y coordinates instead for WebView content.

Sends a raw coordinate tap via the native backend (idb if installed, else a Maestro tapOn-point fallback). Useful for WKWebView game overlays where visual position differs from the DOM hit-test position. The Maestro fallback needs an app context: pass bundleId, or the foreground app is auto-detected. VERIFICATION: 'ok' is decided primarily by a change in the native accessibility element set before/after the tap (stable under animation/video). When no native backend is present it falls back to a screenshot byte-size delta (weak — animation can flip it). The result's `oracle` field reports which was used ('a11y-change' | 'screenshot-bytesize' | 'unverified'). For WebView-rendered targets the a11y tree won't change → oracle:'unverified'; confirm via webview_inspect. offsetStep defaults to 0 (tap the exact point); set it >0 only to deliberately probe nearby y-offsets on retry.

Returns a trustworthy, evidenced verdict on whether a just-implemented flow works. Runs your visibility assertions through the oracle ladder (WebView-DOM > native a11y > Maestro; fail-closed on unverifiable) AND auto-checks app health: no recent crash, no error-level Metro logs, no failed (≥400) network requests. ok=true only when ALL assertions pass AND all applicable auto-checks are clean — never a bare 'looks ok'. State the expected outcome as assertions; this tool makes the AI's 'it works' auditable.

Polls until an element/text is visible (via the oracle ladder), or fails on timeout. Use to act the instant the UI is ready instead of a blind sleep.

Evaluates a JavaScript expression in a WebView's page context and returns the result. Use it to read web-app state (location.href, store values, feature flags, on-screen balances) or to assert conditions against the live DOM. Requires the app's WKWebView to be inspectable (isInspectable=true) — on by default in debug/staging builds, frequently disabled in production App Store builds.

Lists embedded WebViews (WKWebView) on a booted simulator and, for the selected one, resolves a CSS selector to DOM elements WITH absolute on-screen tap coordinates. This is the answer to the 'WebView content is opaque' limitation of the coordinate tools: instead of eyeballing a screenshot, get tapX/tapY for a real DOM element and feed it straight into tap_on. Defaults to interactive elements when no selector is given. Requires the app's WKWebView to be inspectable (isInspectable=true) — on by default in debug/staging builds, frequently disabled in production App Store builds.

Drives a WebView's navigation: goto a URL, or back / forward / reload. Requires the app's WKWebView to be inspectable (isInspectable=true) — on by default in debug/staging builds, frequently disabled in production App Store builds.