Electron Stagewright

Drive, inspect, and assert on real Electron desktop apps from an AI agent — agent-native, Playwright-style automation with accessibility refs, stable error codes, and retrying assertions

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.

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 designedagent-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.
- get_statereturns 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.
- wait_for_stateaccepts composite predicates—{ visible: true, enabled: true, focused: false }evaluated atomically by the server. One call replaces three.
- Snapshots flagrecently_changedelements— 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—electron_expect_text({ ref, equals: 'Welcome', timeoutMs: 5000 })is one call, not five.
- electron_findqueries the accessibility tree semantically—{ role: 'button', name_contains: '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.

The server treats three Electron-specific workflows as first-class:
- Attach to a running dev server without restarting it.electron_attachconnects to apps exposing a loopback CDP endpoint, andelectron_injectcan attach to a running main process via the Node Inspector handshake when no debug flag was arranged up front.
- Session traces with deterministic replay and per-tool token budgets.Inspired by Playwright'strace.zipbut designed for LLM agent sessions: a timeline of tool calls, arguments, results, timings, and token estimates — replayable against a fresh app instance, with budgets so agents can cap runaway loops.
- End-to-end validation of signed, notarized, packaged.appbundles—codesign, Gatekeeper assessment, autoUpdater feed inspection, URL-scheme declaration checks, and crash reporter machinery. The full production surface, not just dev.

Microsoft's official Playwright MCP teamexplicitly declinedto support Electron ("you can release your own server for Electron" — Pavel Feldman, lead). This project takes the invitation seriously.

npx -y --package @electron-stagewright/core@0.5.0 --package playwright@1.61.1 \ --package electron@42.3.0 electron-stagewright doctor --json

claude mcp add electron-stagewright -- \ npx -y --package @electron-stagewright/core@0.5.0 --package playwright@1.61.1 \ --package electron@42.3.0 electron-stagewright

The default Claude Code scope is local: it is available only in the current project and stays out of unrelated workspaces. To share a reviewed configuration with a team, use--scope project, which writes the samemcpServersshape to.mcp.json. See theClaude Code MCP scopesfor the host-specific behavior.

To verify a host before pointing it at your app, add the pinned@electron-stagewright/demo@0.1.0package and use thedemo guide. The demo is opt-in, so a normal core installation neither loads nor depends on it.

pnpm install pnpm build claude mcp add electron-stagewright -- \ node /abs/path/to/electron-stagewright/packages/core/dist/cli.js

{ "mcpServers": { "electron-stagewright": { "command": "npx", "args": [ "-y", "--package", "@electron-stagewright/core@0.5.0", "--package", "playwright@1.61.1", "--package", "electron@42.3.0", "electron-stagewright" ] } } }

// Launch mcp__electron-stagewright__electron_launch({ main: "/abs/path/to/.vite/build/main.js", env: { MY_ENV_VAR: "value" } }) // Inspect with full state per ref mcp__electron-stagewright__electron_snapshot() // → [1] button "Open File" enabled=true visible=true // [2] button "Settings" enabled=true visible=true // [3] textbox "Email" value="" focused=false // [4] heading "Welcome" // Interact by ref mcp__electron-stagewright__electron_click({ ref: 2 }) // Wait for a composite state in one call mcp__electron-stagewright__electron_wait_for_state({ ref: 3, state: { focused: true, enabled: true }, timeoutMs: 2000 }) // Assert + retry in one call instead of read-compare-retry chain mcp__electron-stagewright__electron_expect_text({ ref: 4, equals: "Welcome back" }) // Stop mcp__electron-stagewright__electron_stop()

The full tool list — every tool, its parameters, and operation type — is in[TOOL-REFERENCE.md, generated from the live dispatcher manifest (pnpm docs:tools).

…