electron-mcp-server

# electron-debug-mcp — LLM & Agent Usage Guide

Electron Debug MCP allows AI coding agents (Claude, Cursor, Antigravity, etc.) to launch, inspect, drive, and debug Electron applications over the Chrome DevTools Protocol (CDP) and Node inspect protocol.

## Connection & Setup
- Always start by checking the environment if unsure: `doctor`
- Start an app with remote debugging:
  ```json
  { "appPath": "/absolute/path/to/app", "inspectMain": true }
  ```
- If an Electron app is already running, find it with `find_apps` and attach using `attach_by_pid` or `attach`.
- **Note on processId**: If only one Electron app is running under this MCP server, `processId` is **optional** across all tools.

## High-Leverage Agent Recipes

### 1. Visual & Accessibility Inspection (See)
- One-shot check for layout, errors, and failed network calls:
  `vision` -> returns screenshot image + active URL + recent console errors + failed network requests.
- Inspect accessibility tree with stable element refs (`ref: "e1"`):
  `snapshot` -> returns accessibility tree with roles, names, and backend IDs.
- Set-of-Marks visual prompting:
  `vision({ markElements: true })` or `snapshot({ markElements: true })` -> injects high-contrast red numeric badges into the viewport image without modifying page styles permanently.
- Find DOM elements: `query_selector` or `get_dom`.
- Highlighting elements: `highlight({ selector: "#submit-btn" })`.

### 2. Driving Interactivity (Act)
- Ref-based actions (fast, robust, resistant to DOM shifts):
  `click({ ref: "e1" })`
  `type_text({ ref: "e2", text: "Hello desktop" })`
  `hover({ ref: "e3" })`
  `scroll({ ref: "e4" })`
- Prefer accessible interactions when elements have aria names:
  `click_ax({ name: "Save", role: "button" })`
  `type_ax({ name: "Email", text: "user@example.com" })`
- Or use CSS selectors:
  `click({ selector: "button.submit" })`
  `type_text({ text: "Hello", selector: "input#name" })`
  `select_option({ selector: "select#country", label: "Canada" })`
  `hover({ selector: ".menu-item" })`
  `scroll({ selector: "#footer" })`
  `drag({ fromSelector: "#draggable", toSelector: "#dropzone" })`
- Verify interactions without tool crashes:
  `assert_ui({ textIncludes: "Changes saved", maxConsoleErrors: 0 })` -> returns structured pass/fail.

### 3. Network Debugging & Interception
- Inspect recent network calls:
  `get_network_log({ tail: 20, failedOnly: true })`
- Read response body:
  `get_response_body({ requestId: "<id from get_network_log>" })`
- Mock an API endpoint:
  `network_stub({ urlPattern: "*api/users*", action: "fulfill", status: 200, body: JSON.stringify([{ id: 1 }]) })`
- Wait for all network calls to settle:
  `wait_network_idle({ idleMs: 500 })`
- Export HAR file:
  `export_har()` -> returns file path and `electron://artifact/{id}` URI.

### 4. Main Process & IPC Debugging (inspectMain: true)
- Window topology and target mapping: `webcontents_topology`
- Main process state (app paths, metrics, windows): `main_state`
- Record and observe IPC messages:
  `ipc_tap` -> then perform UI action -> `get_ipc_log({ tail: 50 })`
- Test deep linking: `open_deep_link({ url: "myapp://settings" })`
- Window bounds & focus: `focus_window`, `set_window_bounds`
- Clipboard interaction: `get_clipboard`, `set_clipboard`
- Permissions: `set_permission({ permission: "notifications", grant: true })`
- Main-process JS evaluation: `evaluate_main({ expression: "process.versions" })`

### 5. Native Electron API Mocking
Mock native dialogs, shell methods, or OS integrations without popups blocking execution:
- Mock `dialog.showOpenDialog`:
  `mock_electron_api({ module: "dialog", method: "showOpenDialog", returns: { canceled: false, filePaths: ["/test/file.png"] } })`
- Mock `shell.openExternal`:
  `mock_electron_api({ module: "shell", method: "openExternal", returns: true })`
- Inspect recorded calls:
  `get_mock_calls({ module: "shell", method: "openExternal" })`
- Restore original APIs:
  `restore_electron_mocks({ module: "shell", method: "openExternal" })`

### 6. Native Menus & Global Shortcuts
Drive native application menus and accelerators directly:
- Inspect menu tree: `get_application_menu()`
- Click menu item: `click_menu_item({ path: "File > Open File..." })`
- Trigger shortcut accelerator: `trigger_shortcut({ accelerator: "CommandOrControl+P" })`

### 7. Process Health Watchdog & Crash Diagnostics
Monitor Electron renderer terminations, window hangs, and memory pressure:
- Check health: `get_process_health()`
  Returns `status: "healthy" | "unresponsive" | "crashed"`, memory metrics (RSS, heap), window responsive states, and recent stderr crash tails.

### 8. Storage State Snapshot & Auth Replay
Export and restore cookies and local/session storage to bypass repeated logins:
- Export storage state: `save_storage_state()` -> returns Playwright-compatible JSON artifact.
- Restore storage state: `load_storage_state({ state: <payload> })` -> hydrates session instantly.

### 9. Performance & Artifacts
- CPU profiling: `start_cpu_profile` -> perform action -> `stop_cpu_profile`
- Memory leaks: `heap_snapshot`, `leak_check`
- Performance metrics & audit: `get_performance_metrics`, `perf_audit`
- Read exported artifacts directly via MCP:
  - List all artifacts: `electron://artifacts`
  - Read specific artifact: `electron://artifact/{id}`

### 10. Multi-Step Workflows & Codegen (`run_script`)
Execute multi-action sequences server-side with zero client roundtrip latency:
- Context variable interpolation: `{{vars.key}}`, `{{steps[id].result.path}}`, `{{env.KEY}}`, `{{secret:KEY}}`
- Conditional branching: `if: "{{steps.check.result.val}} == true"`
- Step retry: `retry: { retries: 3, delayMs: 250 }`
- Invariant assertions: `expect: { status: "success", contains: "Dashboard", js: "result.value.count > 0" }`
- Failure diagnostics: on step failure, auto-captures failure screenshot artifact (`electron://artifact/{id}`) and console/network error tails.
- Export as Playwright test: `exportAs: "playwright"` returns executable Playwright `_electron` test code.

### 11. Composite Workflows (v1.15.0)
High-leverage multi-step actions designed for autonomous agents:
- `repro_bundle({ notes })`: Packages screenshot, MHTML DOM archive, HAR network replay, source-mapped console errors, stderr log tail, health metrics, and a GitHub issue report into a zero-dependency PKZip archive (`electron://artifact/{id}`).
- `fill_form({ fields, submit, expect })`: Solves multi-field accessible forms (text, password, select, checkbox, radio, file), resolves `{{secret:VAR}}`, auto-submits, and verifies UI assertions in one turn.
- `offline_resilience_check({ faultType, durationMs, action })`: Chaos audit simulating offline / latency / HTTP 500 faults during interactions, measuring recovery, and computing Resilience Grade (A-F).
- `responsive_theme_matrix({ themes, viewports })`: Sweeps color schemes (`light`, `dark`) and viewport dimensions, catching horizontal scrollbar overflow (`scrollWidth > innerWidth`).
- `ipc_fuzz_and_verify({ iterations })`: Probes active IPC channels with boundary and malicious vectors (`__proto__`, path traversal, oversized buffers), monitoring main-process responsiveness and crash resistance.