Core MCP server

Electron Stagewright

Agentic UX testing for real Electron apps. Cue the app, prove the experience, and return bounded evidence through MCP.

Electron Stagewright is a Model Context Protocol (MCP) server that lets Claude Code, Codex, Cursor, Cline, Aider, and any MCP-compatible agent operate real Electron applications. Launch or attach, inspect the accessibility tree, interact through stable refs, assert behavior with retrying expectations, and capture diagnostics without turning every check into another agent round-trip.

Why this exists

Browser automation already has mature agent tooling. Electron adds a different boundary: the main process, renderer surfaces, native menus and dialogs, multiple windows, packaged runtimes, and signed release artifacts. A browser API exposed through MCP does not cover that whole product.

Electron Stagewright is designed agent-first from the primitive level up:

• Errors carry hints, suggested next actions, and similar-ref alternatives — agents recover without an extra round-trip asking for context.
• Every response reports its own token cost — agents budget in real time, not after the fact.
• getstate returns the full state envelope in one call** — visible, enabled, checked, focused, disabled, aria-expanded, aria-busy, aria-invalid. No 4-call chain to decide if a button is clickable.
• waitforstate accepts composite predicates — { visible: true, enabled: true, focused: false } evaluated atomically by the server. One call replaces three.
• Snapshots flag recentlychanged elements** — agents focus reasoning on what differs from the last view instead of reprocessing the whole tree.
• Snapshot diffs are a parameter, not a separate tool — electron_snapshot({ since: 'last' }) returns only deltas. Fewer APIs to remember.
• Compact text encoding on demand — electron_snapshot({ format: 'text' }) renders one line per element ([3] textbox "Email" value="" focused) with only non-default state, cutting snapshot tokens 5-10x versus the JSON shape when the agent just needs to look.
• expect primitives replace read-compare-retry chains — electronexpect_text({ ref, equals: 'Welcome', timeoutMs: 5000 }) is one call, not five.
• electronfind queries the accessibility tree semantically — { role: 'button', namecontains: 'Submit', visible: true } — no CSS selectors, no XPath, no guessing.
• Hot-reload-aware — snapshot and find responses report when the renderer reloaded since the previous baseline, so agents know refs may need refreshing.
• Framework-agnostic snapshot — built on accessibility roles and ARIA instead of framework-internal properties. Current fixtures cover vanilla, React, Vue, and Angular; the broader renderer matrix is still expanding.

Electron-deep workflows

The server treats three Electron-specific workflows as first-class:

Shortened. The full README is on GitHub.