electron-stagewright/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.

Status: pre-alpha. Core server implementation is active; plugin packages and the first npm release are still ahead. Star the repo to follow releases.

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