core

Electron Stagewright

実際の Electron アプリ向けのエージェント型 UX テストです。アプリに指示を出し、体験を検証して、MCP を通じて範囲を限定した証拠を返します。

Electron Stagewright は、Claude Code、Codex、Cursor、 Cline、Aider など、MCP 対応のあらゆるエージェントが実際の Electron アプリを操作できる Model Context Protocol（MCP）サーバーです。アプリを起動または接続し、アクセシビリティツリーを調べ、安定した参照を使って操作し、再試行するアサーションで動作を検証し、すべてのチェックでエージェントとの往復を増やすことなく診断情報を取得できます。

これが必要な理由

ブラウザー自動化には、すでに成熟したエージェントツールがあります。Electron には、メインプロセス、レンダラーサーフェス、ネイティブメニューとダイアログ、複数のウィンドウ、パッケージ化されたランタイム、署名済みリリースアーティファクトという別の境界があります。MCP 経由で公開されるブラウザー API では、製品全体をカバーできません。

Electron Stagewright は、基本要素の段階から エージェントファースト となるように設計されています。

• エラーにはヒント、推奨される次のアクション、類似する参照先の候補が含まれます — エージェントは状況を尋ねるための追加の往復なしに復旧できます。
• すべての応答で、その応答自身のトークンコストが報告されます — エージェントは事後ではなく、リアルタイムで予算を管理できます。
• get_state は 1 回の呼び出しで状態の完全なエンベロープを返します — 可視、操作可能、チェック済み、フォーカス済み、無効、aria-expanded、aria-busy、aria-invalid。ボタンをクリックできるか判断するのに 4 回呼び出す必要はありません。
• wait_for_state は複合条件を受け付けます — { visible: true, enabled: true, focused: false } をサーバーがアトミックに評価します。3 回の呼び出しを 1 回にまとめられます。
• スナップショットでは recently_changed 要素にフラグが付きます — エージェントはツリー全体を再処理する代わりに、直前の表示から変わった箇所に絞って推論できます。
• スナップショットの差分は独立したツールではなくパラメーターです — electron_snapshot({ since: 'last' }) は差分のみを返します。覚える API が少なくなります。
• 必要なときにコンパクトなテキスト形式でエンコードできます — electron_snapshot({ format: 'text' }) は各要素を 1 行（[3] textbox "Email" value="" focused）でレンダリングし、デフォルト以外の状態だけを含めます。エージェントが表示内容を確認するだけでよい場合、JSON 形式と比べてスナップショットのトークン数を 5〜10 分の 1 に削減できます。
• expect_* プリミティブで、読み取り、比較、再試行の連鎖を置き換えられます — electron_expect_text({ ref, equals: 'Welcome', timeoutMs: 5000 }) は 5 回ではなく、1 回の呼び出しです。
• electron_find はアクセシビリティツリーを意味的に検索します — { role: 'button', name_contains: 'Submit', visible: true }。CSS セレクターも XPath も、推測も必要ありません。
• ホットリロードに対応しています — スナップショットと検索の応答では、前回のベースライン以降にレンダラーが再読み込みされたかが報告されるため、エージェントは参照を更新する必要があるか判断できます。
• フレームワークに依存しないスナップショットです — フレームワーク内部のプロパティではなく、アクセシビリティロールと ARIA を基盤としています。現在のフィクスチャは vanilla、React、Vue、Angular をカバーしており、対応するレンダラーの範囲は引き続き拡大中です。

Electron 固有のワークフロー

このサーバーでは、Electron 固有の次の 3 つのワークフローを第一級の機能として扱います。

1. 再起動せずに、実行中の開発サーバーに接続します。 electron_attach はループバック CDP エンドポイントを公開するアプリに接続し、事前にデバッグフラグを設定していない場合でも、electron_inject は Node Inspector ハンドシェイクを介して実行中のメインプロセスに接続できます。
2. 決定論的なリプレイと、ツールごとのトークン予算を備えたセッショントレースです。 Playwright の trace.zip に着想を得つつ、LLM エージェントのセッション向けに設計されています。ツール呼び出し、引数、結果、所要時間、トークンの推定値を時系列で記録し、新しいアプリインスタンスに対してリプレイできます。また、予算を設定することで、エージェントの無限ループを抑制できます。
3. 署名、ノータライズ、パッケージ化された .app バンドルのエンドツーエンド検証です。 codesign、Gatekeeper による評価、autoUpdater フィードの検査、URL スキーム宣言の確認、クラッシュレポーターの仕組みを扱います。開発時だけでなく、本番環境の全機能を対象とします。

Microsoft の公式 Playwright MCP チームは、Electron のサポートを明確に拒否しました（「Electron 用の独自サーバーをリリースできます」— Pavel Feldman、リード）。このプロジェクトは、その誘いを真剣に受け止めています。

クイックスタート

Node.js 24 以降（node -v）が必要です。Linux では、サーバーにディスプレイ（DISPLAY、WAYLAND_DISPLAY、または xvfb-run -a）も必要です。デフォルトの起動トランスポートでは、Playwright と Electron ランタイムを使用します。現在のプロジェクトで個人的にセットアップする場合は、サーバーをそのプロジェクト内に置き、リリーステスト済みのパッケージセットを固定してください。

MCP ホストを設定する前に、ターミナルで同じパッケージセットを一度準備してください。Electron はインストール時ではなく、何かが Electron を読み込む初回にバイナリをダウンロードします。このダウンロードでは stdout に進捗行が出力されます。MCP セッション内では、この行がプロトコルストリームに混入してしまいます。Electron の install-electron bin でバイナリを取得し、その後 doctor を実行してください。必要なチェックがすべて通ると、"ok": true が報告され、終了コード 0 で終了します。

npx -y --prefix ~/ --package @electron-stagewright/[email protected] \
  --package [email protected] --package [email protected] install-electron
npx -y --prefix ~/ --package @electron-stagewright/[email protected] \
  --package [email protected] --package [email protected] electron-stagewright doctor --json

claude mcp add electron-stagewright -- \
  npx -y --prefix ~/ --package @electron-stagewright/[email protected] \
  --package [email protected] --package [email protected] \
  electron-stagewright --tool-profile essential

その後、claude mcp list にサーバーが接続済みとして表示されます（または、セッション内で /mcp を実行してください）。ツールは mcp__electron-stagewright__electron_launch などの名前で表示されます。3 つのコマンドすべてで --package リストを同じにしてください。npx はリストごとに別々にキャッシュするため、デモやプラグインのパッケージを追加する場合は、新しいリストで install-electron と doctor を再実行してください。--prefix ~/ も指定してください。これがないと、npx は現在のプロジェクトに同じバージョンのパッケージがすでにある場合、そのパッケージのリストへの追加を省略します（Electron アプリには Playwright と Electron の両方が含まれていることがよくあります）。また、npx のキャッシュから実行されるサーバーは、そのパッケージを読み込めません。サーバーは引き続き現在のディレクトリで実行されます。後で新しいリリースに移行する場合は、新しいリリースへの更新に従ってください。

デフォルトの Claude Code スコープはローカルです。現在のプロジェクトでのみ利用でき、関係のないワークスペースには影響しません。レビュー済みの設定をチームで共有するには、--scope project を使用してください。同じ mcpServers 形式で .mcp.json が作成されます。ホスト固有の動作については、Claude Code の MCP スコープを参照してください。

アプリに接続する前にホストを確認するには、固定された @electron-stagewright/[email protected] パッケージを追加し、デモガイドを使用してください。デモはオプトイン方式のため、通常のコアインストールでは読み込まれず、依存関係にも含まれません。

ローカル開発では、チェックアウトをビルドし、ビルド済み CLI を MCP ホストに指定します。

pnpm install
pnpm build

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

共有プロジェクトの .mcp.json 形式：

{
  "mcpServers": {
    "electron-stagewright": {
      "command": "npx",
      "args": [
        "-y",
        "--prefix",
        "~/",
        "--package",
        "@electron-stagewright/[email protected]",
        "--package",
        "[email protected]",
        "--package",
        "[email protected]",
        "electron-stagewright",
        "--tool-profile",
        "essential"
      ]
    }
  }
}

その後、MCP 対応エージェントから実行します（ツール名は Claude Code での表示に基づいています。他のホストでは異なるプレフィックスが付加されます）。

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

全ツール、そのパラメーター、操作の種類を含む完全なツール一覧は、ライブディスパッチャーマニフェストから生成されるTOOL-REFERENCE.md（pnpm docs:tools）にあります。

ドキュメント

• はじめに — クリーンなチェックアウトから、同梱のサンプルアプリでセッションを完全に実行するまでを説明します。
• パッケージ化されたデモを試す — 独自のアプリパスを指定せずに、ローカルの複数ウィンドウ対応 Electron タスクボードで公開済み MCP ホストのセットアップを検証します。
• MCP クライアントを接続する — 公開済みパッケージを Claude Code、Codex、Claude Desktop、Cursor、VS Code、opencode、または任意の MCP ホストに組み込み、接続を確認し、更新または削除する方法を説明します。
• 起動、アタッチ、またはインジェクト — すでに実行中のアプリも含め、あなたのアプリでセッションを開始する方法を説明します。
• UI の状態をアサートする — refs とセレクターの違い、expect_* ファミリー、待機、スナップショットの差分を説明します。
• コードエディターに入力する — 信頼性の高い Monaco / EditContext の入力方法、replace、自動ペアリングに関する注意点、テキストが正しく入力されたことを確認する方法を説明します。
• 診断情報を取得する — スクリーンショット、コンソール、ダイアログ、セッションのトレースを説明します。
• プラグインを読み込み、設定し、診断する — プラグインを明示的に読み込み、必要最小限のゲートを許可し、electron_plugins で有効なツールと安全な設定を確認します。
• electron-driver から移行する — ツールごとの対応関係と、概念上の変更点を説明します。
• Electron MCP サーバーを選ぶ — 機能、信頼境界、復旧時の根拠、独自アプリの観点から Electron 自動化のワークフローを比較します。
• 互換性 — Node、Electron、オペレーティングシステム、トランスポートのどの組み合わせが、ユニットテストまたは実ランタイム CI で検証済みかを確認できます。
• 概念 — エージェントネイティブのモデルと、サーバーが現在の形になった理由を説明します。レスポンスエンベロープ、refs、スナップショット、再試行するアサーション、セッション、eval／プラグインの信頼モデルをそれぞれ、決定の根拠とともに紹介します。
• セキュリティモデル — 信頼モデル、--allow-eval の背後にある制御、デプロイ時のチェックリストを説明します。
• ガイドの索引 · TOOL-REFERENCE.md · アーキテクチャ決定記録。

サーバーフラグ

MCP ホストの設定（args 配列）で、CLI パスの後にこれらを指定します。すべて安全なオプションがデフォルトです。診断情報は stderr に出力されます（stdout は JSON-RPC プロトコルチャネル用に予約されています）。

フラグ	効果
--allow-eval[=main|renderer]	任意の JavaScript をメイン／レンダラープロセスで実行する electron_eval_main／electron_eval_renderer ツールを登録します。デフォルトでは無効で、eval ツールは非表示になり、呼び出せません。--allow-eval のみを指定すると両方が有効になり、--allow-eval=renderer（または =main）を指定すると、最小権限の原則に従ってその対象のみが許可されます。また、IPC メインプロセスツール（main）や、キーごとの Web Storage／IndexedDB ツール（renderer）など、eval の接続点を直接呼び出すプラグインツールも制御します。
--app-root <dir>	ホストのパスを <dir> 内に制限します。対象は electron_launch の main、executablePath、cwd と、electron_set_files／electron_drop_file が読み取るファイルです。デフォルトは未設定（制限なし）です。アプリ／プロジェクトのルートに設定すると、ツール呼び出しによってホスト上の別の場所にあるバイナリが起動されたり、テスト対象のアプリにプロジェクト外のファイルが読み込まれたりするのを防げます。また、electron_launch({ main, runtime: "project" }) も有効になり、Electron はオペレーターが設定したルートからのみ解決されます。明示的に指定した executablePath が優先されます。
--screenshot-dir <dir>	呼び出し時に明示的なパスが指定されなかった場合に、electron_screenshot が書き込むデフォルトのディレクトリです。デフォルト：OS の一時ディレクトリ。
--operation-timeout-ms <n>	ディスパッチごとのタイムアウト（ミリ秒）です。処理が完了しないハンドラーは、アプリがフリーズした状態でエージェントを停止させる代わりに、再試行可能な OPERATION_TIMEOUT として解決されます。デフォルトは 120000 です。0 を指定すると無効になります。
--tool-profile <profile>	コアツールの範囲を選択します。essential（焦点を絞った起動／スナップショット／操作／アサーションの経路）、testing（より広範なテスト操作ツールとスクリーンショットによる証拠の取得）、debug（アタッチ／検査／診断）、または full を指定できます。デフォルトは full で、コアカタログ全体が維持されます。eval の許可設定と明示的に読み込まれたプラグインは、それぞれ独立して組み合わせられます。
--demo	インストール済みの @electron-stagewright/demo パッケージを解決し、electron_launch で main と executablePath の両方が省略された場合に、その Electron エントリを使用します。明示的に指定しない限り有効にならず、通常のコア依存関係になることもありません。公開された npx またはグローバル環境を設定する際は、コアの隣に固定バージョンのデモをインストールしてください。--app-root との併用はできません。
doctor [--json]	MCP stdio を起動せずに、Node、Playwright、Electron、Linux のディスプレイ、設定済みパス、eval ポリシー、プロジェクトランタイムの整合性、正確な serve 設定を事前チェックします。serve 時に使用する予定のプラグイン／設定／プロファイル／タイムアウト／デモの各フラグを同じように指定してください。doctor は、明示的に信頼したプラグインのみをインポートして短時間セットアップし、サーバーのオブジェクトグラフ全体を検証してから、後処理を行います。JSON モードには、範囲が制限されたランタイム／設定情報が含まれ、必須チェックに失敗するとゼロ以外の終了コードを返します。MCP サーバーの引数としてではなく、electron-stagewright doctor --json として実行してください。
production validate --app <path> [--json]	MCP stdio を起動せずに、パッケージ化された macOS の .app、Windows の .exe／.msi、または Linux の .AppImage を検証します。コアの隣に @electron-stagewright/plugin-production がインストールされている必要があります。アーティファクトに応じて、該当する信頼性チェックがデフォルトで選択されます。JSON モードではバージョン付きレポートを 1 つ出力します。失敗したチェックがなければ終了コード 0、検証済みの失敗があれば 1、使用法または入力が無効であれば 2 を返します。
--plugin <name|path>	パッケージ名、ファーストパーティの短縮名、またはファイルパスでプラグインを読み込みます。繰り返し指定でき、単一の値をカンマ区切りで指定することもできます。例：--plugin trace は @electron-stagewright/plugin-trace に展開されます。読み込み後に electron_plugins を呼び出すと、有効または無効なツールと、そのゲート要件を確認できます。
--plugin-config <name>=<json>	プラグインの設定をインライン JSON で指定し、そのスキーマに照らして検証します。プラグイン名をキーとして指定します。入力が無効な場合は、Zod のフィールドパスと修正用の入力が報告されます。electron_plugins が返すのは、プラグインが明示的に安全と指定したフィールドのみです。
サーバーは、正常にシャットダウンした場合（SIGINT、SIGTERM、またはホストが stdin を閉じた場合）は 0、起動時またはシャットダウンの後処理に失敗した場合は 1、不明なフラグなど使い方が無効な場合は 2 を返して終了します。

これを別のプロジェクトに組み込む際に知っておくべきセキュリティ上のデフォルト設定：任意の JS（--allow-eval ポリシー）とホストパスからの起動（--app-root）はオプトインです。electron_launch は実行時の動作を変更する環境変数（ELECTRON_RUN_AS_NODE、NODE_OPTIONS、LD_*、DYLD_*）を拒否します。また、ユーザー指定の正規表現／テキスト／キー引数には長さと複雑さの上限が設けられているため、悪意のあるツール呼び出しによってサーバーが停止することはありません。

エージェントが一般的な起動、スナップショット、操作、待機、アサーションのワークフローを小さな初期マニフェストで使う場合は、--tool-profile essential を使用してください。より幅広い操作、読み取り、スクリーンショット証拠の機能には testing を、アタッチ、検出、ウィンドウ、コンソール、スクリーンショット、ダイアログの操作には debug を選んでください。 プロファイルのベンチマークで、同等のタスク成功率と大幅なコンテキスト削減が実証されるまでは、full が引き続きデフォルトです。測定に基づく予算ポリシーについては、ADR-021 を参照してください。

各レスポンスの形式（エージェント UX の詳細）

成功時の例（electron_expect_text の場合）：

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

エラー：

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

エージェントは、次の行動を決めるために必要な情報をすべて得られるため、コンテキストを尋ねる必要はありません。

アーキテクチャ

単一の ITransport インターフェースの背後に、3 つのトランスポート実装があります。Playwright の実験的な _electron API が変更または非推奨になった場合でも、プロジェクトを継続できます。

• PlaywrightElectronTransport — _electron.launch() を使用する高速パス（デフォルト）。
• CDPTransport — Playwright に依存しない Chrome DevTools Protocol の直接利用。管理されたループバックエンドポイント経由でパッケージ済み実行ファイルを起動するか、既存のエンドポイントにアタッチします。iframe、webview、WebContentsView のサーフェス指定に加え、選択したサーフェス上でのスナップショット／検索、eval、監視、操作に対応しています。
• InjectorTransport — Node Inspector のハンドシェイクを介して実行中のプロセスに接続します。CDP エンドポイントを指定して起動されていないアプリでも、メインプロセスでの eval、ウィンドウ検出、コンソールのキャプチャに対応しています。

プラグインモデル：小規模なコアに、ドメイン機能を個別の @electron-stagewright/plugin-* パッケージとして同梱し、--plugin で明示的に読み込みます（コアが自動スキャンすることはありません）。現在同梱されているもの：plugin-a11y（サーフェス単位の axe-core 監査。違反と未完了のチェックには上限があります。固定のエンジンを使い、エージェントの JavaScript は使わないため、--allow-eval の許可は不要です）、plugin-visual（BrowserWindow のビジュアルベースライン。明示的な更新確認、環境メタデータ、制限された成果物ルート、実際の画像と差分の証拠を備えます）、plugin-trace（セッショントレース＋決定論的リプレイ＋ツールごとのトークン予算）、plugin-ipc（Electron IPC のキャプチャ／呼び出し／スタブ。メイン eval の許可が必要です：--allow-eval=main または --allow-eval のみ）、plugin-production（MCP、公開ライブラリ API、または CI JSON CLI を通じて、パッケージ済みの macOS、Windows、Linux 成果物を検証します。バンドルの完全性、アップデート／クラッシュ関連の仕組み、macOS の署名／公証／Gatekeeper、Windows Authenticode、AppImage に埋め込まれた署名に対応）、plugin-network（トランスポートの接点を介したレンダラーのリクエスト／レスポンスのキャプチャ、本文の取得、スタブ設定）、plugin-clock（Playwright のクロック接点を介した決定論的なレンダラーの仮想時間）、plugin-storage（eval を使わないトランスポートの接点を介した Cookie とストレージスナップショットの読み取り、初期値設定、アサーション。さらに、レンダラー eval の許可を介したキーごとの localStorage／sessionStorage と IndexedDB レコードへの対応。Cookie の値はデフォルトでマスキングされ、IndexedDB の値も設定によりマスキングできます）、plugin-native-ui（アプリケーションメニュー（macOS のメニューバー）の読み取り、アサーション、呼び出し、起動時の通知を含むアプリの通知のキャプチャ、システムトレイの状態の読み取りと起動時インストルメンテーションによるトレイイベントの発生。すべてトランスポートのネイティブ UI 接点を介し、eval は不要です）。

ドッグフーディング対象

この MCP は、作者が保守する 2 つの実際の Electron アプリを対象に構築されています。設計が特定の形状に偏らないよう、異なる分野のアプリを対象にしています。

• コードエディター型 — ランタイムサンドボックス、ライセンス、IPC を多用する状態管理を備えたコードエディターです。キーボード主体の操作フロー、エディターの状態、ライセンス認証を検証します。
• POS 型 — Fastify サーバーと SQLite を組み込んだ、マルチテナントの POS デスクトップアプリです。フォーム、大規模なテーブル、組み込みバックエンド、自動アップデーターのフィードを検証します。

お使いの Electron アプリがこれらではカバーできない形状の場合は、issue を作成してください。サンプル用フィクスチャとして追加できるとうれしいです。

セキュリティ

このサーバーは特権を持つローカルツールであり、サンドボックスではありません。実際のアプリを操作し、eval のオプトイン（--allow-eval またはターゲット固有のバリアント）を有効にすると、そのアプリ内で任意の JavaScript を実行するため、信頼できるエージェントホストのみが呼び出すようにしてください。セキュリティモデルでは、信頼境界、制御機能（eval のオプトインとブロックリスト、チャネルの許可リスト、起動の制限、構造化された機密情報の除去）、デプロイのチェックリストについて説明しています。セキュリティ方針は ADR-014 に記録されています。脆弱性の報告については、SECURITY.md を参照してください。

コントリビューション

このプロジェクトはまだ始まったばかりです。issue やディスカッションを歓迎します。ワークフローについては CONTRIBUTING.md を、プロジェクトの運営方法や共同メンテナーになるための手順については GOVERNANCE.md を参照してください。

テストプロジェクトの選択

pnpm test と pnpm test:coverage は、6 つすべての OS／Node CI セルで維持される通常の unit プロジェクトを選択します。pnpm test:real は、直列化された real-electron プロジェクトを選択し、実際の JSON 結果を scripts/real-test-inventory.json（レビュー済みファイル 25 件、シナリオ 36 件）と照合します。バイナリや必須のネイティブアドオン用フィクスチャ入力がない場合は実行を拒否し、すべてのプラットフォームで、欠落、スキップ、実行数ゼロを拒否します。ネイティブアドオン用の入力は node scripts/prepare-native-addon-fixture.mjs で準備し、出力された変数をエクスポートしてください（Windows では Electron の node.lib も取得し、MSVC が必要な npm 同梱の node-gyp を指定します）。 パッケージ化した CLI の適格性確認は別途行います。

ライセンス

MIT — LICENSE を参照してください。