electron-stagewright

# Electron Stagewright

[![npm](https://img.shields.io/npm/v/@electron-stagewright/core?label=npm)](https://www.npmjs.com/package/@electron-stagewright/core)
[![CI](https://github.com/electron-stagewright/electron-stagewright/actions/workflows/ci.yml/badge.svg)](https://github.com/electron-stagewright/electron-stagewright/actions/workflows/ci.yml)
[![Real Electron E2E](https://github.com/electron-stagewright/electron-stagewright/actions/workflows/e2e-electron.yml/badge.svg)](https://github.com/electron-stagewright/electron-stagewright/actions/workflows/e2e-electron.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-1f6f5c)](LICENSE)

**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](https://github.com/microsoft/playwright-mcp/pull/1291) to support Electron ("you can release your own server for Electron" — Pavel Feldman, lead). This project takes the invitation seriously.

## Quick start

Requires **Node.js 24 or newer** (`node -v`). 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, prepare the same package set once in a terminal. Electron downloads
its binary the first time something loads it, not during install, and that download prints a
progress line to stdout; inside an MCP session the line would land in the protocol stream. Fetch the
binary with Electron's `install-electron` bin, then run `doctor`, which reports `"ok": true` and
exits 0 when every required check passes:

```bash
npx -y --package @electron-stagewright/core@0.6.1 --package playwright@1.63.0 \
  --package electron@42.11.10 install-electron
npx -y --package @electron-stagewright/core@0.6.1 --package playwright@1.63.0 \
  --package electron@42.11.10 electron-stagewright doctor --json
```

```bash
claude mcp add electron-stagewright -- \
  npx -y --package @electron-stagewright/core@0.6.1 --package playwright@1.63.0 \
  --package electron@42.11.10 electron-stagewright
```

`claude mcp list` should then show the server as connected (or run `/mcp` inside a session), and
its tools appear as `mcp__electron-stagewright__electron_launch` and so on. Keep the `--package`
list identical across all three commands: `npx` caches each list separately, so adding the demo or
a plugin package means running `install-electron` and `doctor` again with the new list.

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](https://code.claude.com/docs/en/mcp) 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](docs/guides/demo.md). 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:

```bash
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:

```json
{
  "mcpServers": {
    "electron-stagewright": {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "@electron-stagewright/core@0.6.1",
        "--package",
        "playwright@1.63.0",
        "--package",
        "electron@42.11.10",
        "electron-stagewright"
      ]
    }
  }
}
```

Then from any MCP-compatible agent:

```jsonc
// 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](TOOL-REFERENCE.md), generated from the live dispatcher manifest
(`pnpm docs:tools`).

## Documentation

- [Getting started](docs/guides/getting-started.md) — from a clean checkout to a complete driven
  session against the bundled example app.
- [Try the packaged demo](docs/guides/demo.md) — verify a published MCP host setup against a local,
  multi-window Electron task board without supplying your own app path.
- [Connect your MCP client](docs/guides/connect-your-mcp-client.md) — wire the published package
  into Claude Desktop, Cursor, or any MCP host, and confirm it connected.
- [Launch, attach, or inject](docs/guides/launch-or-attach.md) — getting a session against YOUR
  app, including apps that are already running.
- [Assert UI state](docs/guides/assert-ui-state.md) — refs vs selectors, the `expect_*` family,
  waits, and snapshot diffs.
- [Type into code editors](docs/guides/type-into-code-editors.md) — the reliable Monaco / EditContext
  typing path, `replace`, the auto-pairing caveat, and how to verify the text landed.
- [Capture diagnostics](docs/guides/capture-diagnostics.md) — screenshots, console, dialogs, and
  session traces.
- [Load, configure, and diagnose plugins](docs/guides/plugins.md) — explicitly load plugins, grant
  their narrowest gates, and inspect enabled tools and safe config with `electron_plugins`.
- [Migrate from electron-driver](docs/guides/migrate-from-electron-driver.md) — tool-by-tool
  mapping and the conceptual shifts.
- [Choose an Electron MCP server](docs/guides/choosing-an-electron-mcp-server.md) — compare
  Electron automation workflows by capability, trust boundary, recovery evidence, and