electron-stagewright

# Electron Stagewright

**Agent-native UX from line one. Drive Electron apps the way Playwright drives browsers — but designed for AI agents, not adapted for them.**

A Model Context Protocol (MCP) server that lets AI agents — Claude Code, Codex, Cursor, Cline, Aider, and any MCP-compatible host — operate real Electron desktop applications. The current core can launch Electron apps, inspect the renderer accessibility tree, click/type/select by stable refs or selectors, read state, wait on predicates, run opt-in eval, capture screenshots, read console logs, handle native dialogs, and assert expectations with retrying `expect_*` tools.

## Why this exists

Most MCP servers in the wild are Playwright APIs wrapped in an MCP transport. They work, but their UX is a human's API exposed to an agent — leaving the agent to do all the reasoning, comparisons, and recovery manually. Token budgets evaporate on round-trips that shouldn't need to exist.

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.

## What competitors don't cover (yet)

The MCP ecosystem for browser automation is mature. The MCP ecosystem for **desktop Electron apps** is fragmented and still missing three structural capabilities this project treats 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

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.

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

```bash
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](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.5.0",
        "--package",
        "playwright@1.61.1",
        "--package",
        "electron@42.3.0",
        "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 your own app.
- [Compatibility](docs/guides/compatibility.md) — see which Node, Electron, operating-system, and
  transport combinations are verified by unit tests or real-runtime CI.
- [Concepts](docs/guides/concepts.md) — 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](docs/guides/security-model.md) — the trust model, the controls behind
  `--allow-eval`, and a deployment checklist.
- [Guides index](docs/guides/README.md) · [TOOL-REFERENCE.md](TOOL-REFERENCE.md) ·
  [Architecture Decision Records](docs/adr/README.md).

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

| Flag                                        | Effect