Electron Stagewright

npm CI Real Electron E2E License: MIT

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.
• get_state 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.
• wait_for_state accepts composite predicates — { visible: true, enabled: true, focused: false } evaluated atomically by the server. One call replaces three.
• Snapshots flag recently_changed 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 — electron_expect_text({ ref, equals: 'Welcome', timeoutMs: 5000 }) is one call, not five.
• electron_find queries 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.

Electron-deep workflows

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

1. Attach to a running dev server without restarting it. electron_attach connects to apps exposing a loopback CDP endpoint, and electron_inject can attach to a running main process via the Node Inspector handshake when no debug flag was arranged up front.
2. Session traces with deterministic replay and per-tool token budgets. Inspired by Playwright's trace.zip but 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.
3. End-to-end validation of signed, notarized, packaged .app bundles — 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 team explicitly declined to support Electron ("you can release your own server for Electron" — Pavel Feldman, lead). This project takes the invitation seriously.

Quick start

The default launch transport uses Playwright and an Electron runtime. For a private setup in the current project, keep the server local to that project and pin the release-tested package set:

Before configuring an MCP host, run the same package set once in a terminal to prime a fresh npx cache. Electron may print binary-download progress to stdout during this first install, which would corrupt an MCP stdio session; the terminal bootstrap completes the install before the host starts it.

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 same mcpServers shape to .mcp.json. See the Claude Code MCP scopes for the host-specific behavior.

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

For local development, build the checkout and point your MCP host at the built CLI:

pnpm install
pnpm build

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

Shared project .mcp.json shape:

{
  "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"
      ]
    }
  }
}

Then from any MCP-compatible agent:

// 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).

Documentation

• Getting started — from a clean checkout to a complete driven session against the bundled example app.
• Try the packaged demo — verify a published MCP host setup against a local, multi-window Electron task board without supplying your own app path.
• Connect your MCP client — wire the published package into Claude Desktop, Cursor, or any MCP host, and confirm it connected.
• Launch, attach, or inject — getting a session against YOUR app, including apps that are already running.
• Assert UI state — refs vs selectors, the expect_* family, waits, and snapshot diffs.
• Type into code editors — the reliable Monaco / EditContext typing path, replace, the auto-pairing caveat, and how to verify the text landed.
• Capture diagnostics — screenshots, console, dialogs, and session traces.
• Load, configure, and diagnose plugins — explicitly load plugins, grant their narrowest gates, and inspect enabled tools and safe config with electron_plugins.
• Migrate from electron-driver — tool-by-tool mapping and the conceptual shifts.
• Choose an Electron MCP server — compare Electron automation workflows by capability, trust boundary, recovery evidence, and your own app.
• Compatibility — see which Node, Electron, operating-system, and transport combinations are verified by unit tests or real-runtime CI.
• Concepts — the agent-native model and why the server is shaped the way it is: the response envelope, refs, snapshots, retrying assertions, sessions, and the eval/plugin trust model, each linked to the decision that set it.
• Security model — the trust model, the controls behind --allow-eval, and a deployment checklist.
• Guides index · TOOL-REFERENCE.md · Architecture Decision Records.

Server flags

Pass these after the CLI path in your MCP host config (the args array). All default to the safe option; diagnostics go to stderr (stdout is reserved for the JSON-RPC protocol channel).

Security defaults worth knowing when wiring this into another project: arbitrary JS (the --allow-eval policy) and host-path launches (--app-root) are opt-in; electron_launch refuses runtime-altering env vars (ELECTRON_RUN_AS_NODE, NODE_OPTIONS, LD_*, DYLD_*); and user-supplied regex / text / key arguments are length- and complexity-bounded so a hostile tool call cannot wedge the server.

Use --tool-profile essential when an agent needs the common launch, snapshot, interaction, wait, and assertion workflow with a smaller initial manifest. Choose testing for the broader interaction, read, and screenshot-evidence surface, or debug for attach, discovery, window, console, screenshot, and dialog work. full stays the default until the profile benchmark demonstrates equivalent task success with a material context saving. See ADR-021 for the measured budget policy.

What each response looks like (the agent-UX detail)

Success, for example from electron_expect_text:

{
  "ok": true,
  "session_id": "pw-...",
  "matched": true,
  "actual": "Welcome back",
  "_meta": {
    "estimated_tokens": 24,
    "elapsed_ms": 142,
    "session_id": "pw-...",
  },
}

Error:

{
  "ok": false,
  "error": "ref 7 not found in current snapshot",
  "code": "REF_NOT_FOUND",
  "hint": "The DOM may have rerendered since the last snapshot.",
  "next_actions": ["electron_snapshot()", "electron_find({ role: \"button\" })"],
  "similar_refs": [
    { "ref": 9, "role": "button", "name": "Submit" },
    { "ref": 12, "role": "button", "name": "Cancel" },
  ],
  "retryable": false,
  "http": 404,
  "_meta": { "estimated_tokens": 89, "elapsed_ms": 23 },
}

The agent has everything to decide its next move without asking for context.

Architecture

Three transport implementations behind a single ITransport interface, so the project survives if Playwright's experimental _electron API changes or gets deprecated:

• PlaywrightElectronTransport — _electron.launch(), fast path (default).
• CDPTransport — Chrome DevTools Protocol direct, no Playwright dependency; launches packaged executables through a managed loopback endpoint or attaches to an existing one, with snapshot/find on the selected root page plus eval, observe, and interaction surfaces.
• InjectorTransport — Node Inspector handshake into a running process; supports main-process eval, window discovery, and console capture when an app was not started with a CDP endpoint.

Plugin model: a small core, with domain capabilities shipped as separate @electron-stagewright/plugin-* packages loaded explicitly via --plugin (the core never auto-scans). Shipped today: plugin-a11y (surface-scoped axe-core audits with bounded violations and incomplete checks; a fixed engine, not agent JavaScript, so no --allow-eval grant), plugin-visual (BrowserWindow visual baselines with explicit update confirmation, environment metadata, confined artifact roots, and actual/diff evidence), plugin-trace (session trace + deterministic replay + per-tool token budget), plugin-ipc (capture / invoke / stub Electron IPC, gated behind main eval: --allow-eval=main, or bare --allow-eval), plugin-production (validate packaged macOS, Windows, and Linux artifacts through MCP, a public library API, or a CI JSON CLI: bundle integrity, update/crash machinery, macOS signing/notarization/Gatekeeper, Windows Authenticode, and AppImage embedded signatures), plugin-network (renderer request/response capture, bodies, and stubbing via the transport seam), plugin-clock (deterministic renderer virtual time via the Playwright clock seam), plugin-storage (read, seed, and assert cookies plus storage snapshots through the no-eval transport seam, and per-key localStorage / sessionStorage plus IndexedDB records through a renderer-eval gate; cookie values are redacted by default, IndexedDB values can be redacted with config), and plugin-native-ui (read, assert, and invoke the application menu — the macOS menu bar — capture the notifications the app shows including startup ones, and read system-tray state plus fire tray events via launch-time instrumentation, all via the transport native-UI seam, no eval).

Dogfooding targets

The MCP is built against two real Electron applications maintained by the author, covering distinct verticals so the design doesn't accidentally bias to one shape:

• Code-editor shape — a code editor with runtime sandboxes, licensing, and IPC-heavy state. Stresses keyboard-driven flows, editor state, and license verification.
• POS shape — a multi-tenant Point of Sale desktop app with embedded Fastify server and SQLite. Stresses forms, large tables, embedded backend, auto-updater feeds.

If your Electron app has a shape these don't cover, open an issue — we'd love to add it as an example fixture.

Security

The server is a privileged local tool, not a sandbox: it drives a real app and, under an eval opt-in (--allow-eval or a target-specific variant), runs arbitrary JavaScript inside it, so only a trusted agent host should invoke it. The security model covers the trust boundaries, the controls (eval opt-in + blocklist, channel allowlists, launch confinement, structured redaction), and a deployment checklist; the posture is recorded in ADR-014. To report a vulnerability, see SECURITY.md.

Contributing

This project is in its earliest days. Issues and discussions welcome. See CONTRIBUTING.md for the workflow, and GOVERNANCE.md for how the project is run and the path to becoming a co-maintainer.

License

MIT — see LICENSE.