Skip to content
Back to search

electron-mcp-server

MCP server for debugging Electron apps via Chrome DevTools Protocol. Start/attach processes, capture screenshots, read console errors & network logs, inspect DOM, evaluate JS, and automate UI — built for Cursor and other MCP clients.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/amafjarkasi/electron-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/amafjarkasi/electron-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/amafjarkasi--electron-mcp-server/badge.svg)](/listings/amafjarkasi--electron-mcp-server)

HTML

<a href="/listings/amafjarkasi--electron-mcp-server"><img src="/api/listings/amafjarkasi--electron-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/amafjarkasi/electron-mcp-server.git
cd electron-mcp-server
npm install
npm run ensure-electron
npm run build
npm test

🪟 Windows binary missing?

If npm warns about `allowScripts` / Electron postinstall:

.\scripts\fix-electron.cmd

That reinstalls Electron, extracts `electron.exe` with system `tar`, then runs tests.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 636 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="assets/logo.svg" alt="Electron Debug MCP Logo" width="140" height="140" />
  3. # Electron Debug MCP
  4. **Real Chrome DevTools Protocol superpowers for AI coding agents.**<br/>
  5. *Give Cursor, Claude & autonomous agents eyes, hands, and deep runtime inspection inside Electron desktop applications.*
  6. <p align="center">
  7. <img alt="version" src="https://img.shields.io/badge/version-1.15.2-0F766E?style=flat-square" />
  8. <img alt="111 tools" src="https://img.shields.io/badge/111_tools-0F766E?style=flat-square" />
  9. <img alt="9 resources" src="https://img.shields.io/badge/9_resources-115E59?style=flat-square" />
  10. <img alt="6 prompts" src="https://img.shields.io/badge/6_prompts-134E4A?style=flat-square" />
  11. <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=nodedotjs&logoColor=white" />
  12. <img alt="Electron" src="https://img.shields.io/badge/Electron-CDP-47848F?style=flat-square&logo=electron&logoColor=white" />
  13. <img alt="license" src="https://img.shields.io/badge/license-ISC-F5A623?style=flat-square" />
  14. </p>
  15. <p align="center">
  16. <a href="#-quick-start"><b>Quick Start</b></a> •
  17. <a href="#-key-superpowers"><b>Superpowers</b></a> •
  18. <a href="#-tool-matrix-111-tools"><b>Tool Matrix</b></a> •
  19. <a href="#-agent-recipes"><b>Recipes</b></a> •
  20. <a href="#-resources--prompts"><b>Resources & Prompts</b></a> •
  21. <a href="#-changelog--releases"><b>Changelog</b></a> •
  22. <a href="#-troubleshooting"><b>Troubleshooting</b></a>
  23. </p>
  24. ---
  25. </div>
  26. ## 🌟 Why Electron Debug MCP?
  27. Most AI coding agents struggle with desktop applications: they can edit source code, but they cannot **see** the resulting window, **click** buttons, **read** console errors, or **diagnose** silent main-process crashes.
  28. **Electron Debug MCP** bridges your agent directly into your Electron runtime via the **Chrome DevTools Protocol (CDP)** and **Node inspector**, unlocking full visual, interactive, and diagnostic autonomy.
  29. ```mermaid
  30. flowchart LR
  31. A["🤖 AI Agent (Cursor / Claude)"] <-->|"stdio JSON-RPC"| B["⚡ Electron Debug MCP"]
  32. B <-->|"CDP (WebSocket)"| C["🖼️ Renderer Windows\n(DOM · AXTree · Network · V8)"]
  33. B <-->|"Node Inspector / V8"| D["⚙️ Main Process\n(IPC · WebContents · Windows · Fuses)"]
  34. ```
  35. ---
  36. ## ✨ Key Superpowers
  37. <table>
  38. <tr>
  39. <td width="50%">
  40. ### 🛡️ Runtime Security Audit
  41. `electron_security_audit` evaluates running windows against official Electron security guidelines. Flags `nodeIntegration`, missing `contextIsolation`, disabled sandbox, unsafe CSP, missing `setWindowOpenHandler`, unguarded `will-navigate`, and executable binary fuses.
  42. </td>
  43. <td width="50%">
  44. ### 🔒 Zero-Leak Secret Automation
  45. Automate logins and API forms without leaking credentials. `type_text({ text: "{{secret:VAR}}" })` resolves from `process.env` and automatically redacts the secret from return values, console logs, network entries, and HAR exports with `[REDACTED]`.
  46. </td>
  47. </tr>
  48. <tr>
  49. <td width="50%">
  50. ### 🧩 Autonomous Composite Workflows
  51. High-level single-turn workflows reduce round trips:
  52. - **`act_and_verify`**: Action → network idle → UI assertion → automatic failure screenshot if assertion fails.
  53. - **`triage`**: Instant health overview with page state, console errors, network failures, and resolved top exception stack.
  54. - **`network_failure_report`**: Aggregates failed HTTP calls with response bodies inline plus an exported HAR artifact.
  55. </td>
  56. <td width="50%">
  57. ### 🔌 Deep IPC Observability
  58. - **`ipc_tap`**: Intercepts main-process `ipcMain.handle` and `webContents.send` calls.
  59. - **`ipc_invoke`**: Call any registered main-process handle channel directly with custom arguments.
  60. - **`ipc_schema_inference`**: Analyzes traffic patterns and automatically emits inferred TypeScript interfaces for your preload bridge.
  61. </td>
  62. </tr>
  63. <tr>
  64. <td width="50%">
  65. ### 🗺️ Source-Mapped Stack Traces
  66. `resolve_stack` decodes inline base64 and external v3 source maps. When your bundled app throws an exception, the agent gets original `.ts` and `.tsx` file names, line numbers, and original source snippets rather than minified bundle noise.
  67. </td>
  68. <td width="50%">
  69. ### ⚡ Frictionless Agent Ergonomics
  70. - **Optional `processId`**: Automatically defaults to the single active app session.
  71. - **Tool Annotations**: Tools declare standard MCP hints (`readOnlyHint`, `destructiveHint`) so clients can auto-approve safe queries.
  72. - **Artifacts Resource**: Output files are indexed as `electron://artifact/{id}`.
  73. </td>
  74. </tr>
  75. </table>
  76. ---
  77. ## ⚡ Quick Start
  78. ### 1. Configure Your MCP Client
  79. #### 🚀 In Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)
  80. ```json
  81. {
  82. "mcpServers": {
  83. "electron-debug": {
  84. "command": "npx",
  85. "args": ["-y", "electron-debug-mcp@latest"]
  86. }
  87. }
  88. }
  89. ```
  90. #### 💬 In Claude Desktop (`claude_desktop_config.json`)
  91. ```json
  92. {
  93. "mcpServers": {
  94. "electron-debug": {
  95. "command": "npx",
  96. "args": ["-y", "electron-debug-mcp@latest"]
  97. }
  98. }
  99. }
  100. ```
  101. > [!TIP]
  102. > **Developing locally?** Run `npm run build` and configure `"command": "node"` with `"args": ["/path/to/electron-mcp-server/build/index.js"]`.
  103. ---
  104. ## 🛠️ Tool Matrix (111 Tools)
  105. All tools accept an optional `processId`. When only one app is running, it automatically resolves to the active process.
  106. ### 🚀 Lifecycle & Connection (8)
  107. | Tool | Description |
  108. | --- | --- |
  109. | `start_app` | Launch Electron app with remote debugging port. Set `inspectMain: true` to enable main-process debugging. |
  110. | `stop_app` | Terminate launched app or detach from an attached session. |
  111. | `attach` | Connect to a running Electron app via DevTools port or WebSocket URL. |
  112. | `attach_by_pid` | Detect DevTools port from an Electron OS PID's command line and attach. |
  113. | `find_apps` | Enumerate all running Electron processes on the host machine. |
  114. | `discover_apps` | Scan local TCP ports (default 9222–9322) to discover live CDP debug endpoints. |
  115. | `find_installed_apps` | Scan standard OS application directories for installed packaged Electron apps. |
  116. | `list_apps` | Enumerate all active and managed sessions with uptime, PID, and target counts. |
  117. ### 👁️ See & Visual Inspection (8)
  118. | Tool | Description |
  119. | --- | --- |
  120. | `vision` | Recommended one-shot snapshot: viewport screenshot, page URL/title, console errors, and network failures. Supports `markElements: true` for Set-of-Marks visual badges. |
  121. | `snapshot` | Complete semantic accessibility tree (`Accessibility.getFullAXTree`) with stable element refs (`ref: "e1"`), roles, names, and backend IDs. Supports `markElements: true`. |
  122. | `screenshot` | Capture viewport PNG or JPEG base64 payload. |
  123. | `save_screenshot` | Capture screenshot to disk (supports CSS selector clipping); registers an artifact. |
  124. | `diff_screenshot` | Visual regression comparison against a baseline screenshot. |
  125. | `start_screencast` | Stream live viewport frames into a bounded ring buffer. |
  126. | `stop_screencast` | Stop screencasting and optionally save the final frame to disk. |
  127. | `highlight` | Visually highlight a DOM element in the viewport with border and background overlays. |
  128. ### 🖱️ Act & UI Automation (13)
  129. | Tool | Description |
  130. | --- | --- |
  131. | `act_and_verify` | **Composite:** Executes an action (`click`, `type`, `click_ax`), waits for network idle, verifies assertion, and captures failure screenshot if failed. |
  132. | `click` | Click the center of an element matching a CSS `selector` or accessibility `ref` (e.g. `"e1"`). |
  133. | `click_ax` | Robust click locating an element by its accessibility name and optional role. |
  134. | `type_text` | Type text into focused element, `selector`, or `ref`. Supports `{{secret:VAR}}` resolution and redaction. |
  135. | `type_ax` | Focus an element by accessibility name and type text with secret placeholder support. |
  136. | `press_key` | Dispatch keypress or keyboard shortcut (Enter, Escape, Tab, Arrows, Ctrl+A, etc.). |
  137. | `hover` | Move mouse pointer over a CSS `selector` or `ref` without clicking. |
  138. | `scroll` | Scroll page or element by delta coordinates, or scroll a `selector` or `ref` into view. |
  139. | `drag` | Drag-and-drop between two selectors or refs with native HTML5 `dataTransfer` payload. |
  140. | `select_option` | Select an option in a `<select>` dropdown by value or label. |
  141. | `set_file_input` | Programmatically set files on an `<input type="file">`. |
  142. | `handle_dialog` | Automatically accept or dismiss JavaScript alerts, confirms, and prompts. |
  143. | `open_deep_link` | Dispatch a custom protocol deep link (e.g. `myapp://action`) into the application. |
  144. ### 📄 Page State & Navigation (20)
  145. | Tool | Description |
  146. | --- | --- |
  147. | `fill_form` | **Composite:** Smart multi-field form solver (text, select, checkbox, radio, file) with `{{secret:VAR}}` resolution, auto-submit, and UI assertion. |
  148. | `responsive_theme_matrix` | **Composite:** Multi-theme (`light`, `dark`) and viewport sweep detecting text clipping & horizontal overflow scrollbars. |
  149. | `repro_bundle` | **Composite:** Self-contained bug repro bundle (screenshot, MHTML DOM, HAR replay, console errors, logs, health) zipped into an artifact. |
  150. | `page_info` | Basic page details: URL, title, dimensions, readyState, and user agent. |
  151. | `navigate` | Navigate the active page target to a URL with configurable load-state waiting. |
  152. | `reload` | Reload the active page target (supports cache busting). |
  153. | `wait_for` | Wait for a CSS selector, page title, URL substring, or custom JS expression. |
  154. | `get_dom` | Retrieve page HTML markup (supports CSS selector root and `maxLength` token protection). |
  155. | `query_selector` | Evaluate CSS query and inspect matching elements' attributes and text content. |
  156. | `evaluate` | Evaluate arbitrary JavaScript in the renderer page context. |
  157. | `get_console_messages` | Retrieve buffered console messages and exceptions (supports level and tail filtering). |
  158. | `get_logs` | Retrieve captured process stdout and stderr logs. |
  159. | `get_cookies` | Inspect cookies for specified URLs or across all targets. |
  160. | `set_cookie` | Set browser cookies with domain, path, and security flags. |
  161. | `delete_cookie` | Delete a specific cookie by name. |
  162. | `get_storage` | Read items from `localStorage` or `sessionStorage`. |
  163. | `set_storage` | Write items to `localStorage` or `sessionStorage`. |
  164. | `assert_ui` | Verify page URL, title, element visibility, text matches, and absence of console errors. |
  165. | `save_storage_state` | Export cookies, `localStorage`, and `sessionStorage` into a Playwright-compatible JSON artifact (`electron://artifact/{id}`). |
  166. | `load_storage_state` | Restore cookies and origin storage state back into the live Electron session for instant auth bypass and state replay. |
  167. ### 🌐 Network & Downloads (12)
  168. | Tool | Description |
  169. | --- | --- |
  170. | `offline_resilience_check` | **Composite:** Network chaos and fault recovery audit (simulating offline, high latency, or HTTP 500 faults) and Resilience Grade (`A`–`F`). |
  171. | `network_failure_report` | **Composite:** Gathers failed HTTP requests (status ≥ 400 or network failure), inlines response bodies, and registers an exported HAR artifact. |
  172. | `get_network_log` | Buffered HTTP requests and responses. Supports status, failure, and URL pattern filters. |
  173. | `get_response_body` | Fetch raw response body for a completed `requestId` (text or base64). |
  174. | `export_har` | Export buffered network traffic to an official HAR 1.2 file and register artifact. |
  175. | `wait_network_idle` | Block until zero network requests are in flight and the network has been quiet. |
  176. | `network_stub` | Intercept and mock HTTP requests matching a pattern with custom status, headers, or body. |
  177. | `clear_network_stubs` | Remove all active network interception stubs. |
  178. | `block_urls` | Block network requests matching wildcard URL patterns. |
  179. | `set_extra_headers` | Inject custom HTTP headers into all subsequent requests. |
  180. | `emulate_network` | Emulate offline conditions, added round-trip latency, and download/upload throughput caps. |
  181. | `get_downloads` | Arm download listeners across all sessions and capture downloaded files without save dialogs. |
  182. ### 📈 Performance, Profiling & Debugger (16)
  183. | Tool | Description |
  184. | --- | --- |
  185. | `perf_snapshot` | **Composite:** Coordinates CDP tracing, CPU profiling, and code coverage over an interaction or reload, returning an aggregated performance bundle and artifact URIs. |
  186. | `leak_check` | **Composite:** Memory leak detector measuring DOM node, event listener, document, and heap growth across iterations post-GC. |
  187. | `get_performance_metrics` | Renderer performance counters (JS heap used/total, DOM node count, layout count, etc.). |
  188. | `perf_audit` | Lightweight performance audit analyzing LCP, CLS, paint timing, and audit issues. |
  189. | `get_audit_issues` | Buffered Chromium security, mixed content, and deprecation audit issues. |
  190. | `start_tracing` / `stop_tracing` | Record and export Perfetto/DevTools JSON timeline traces. |
  191. | `start_cpu_profile` / `stop_cpu_profile` | Record and export V8 `.cpuprofile` files. |
  192. | `heap_snapshot` | Capture complete V8 heap snapshot file artifact. |
  193. | `start_coverage` / `stop_coverage` | Track JavaScript and CSS code coverage and report unused code percentage. |
  194. | `resolve_stack` | Resolves stack frames back to source snippets; automatically decodes v3 source maps. |
  195. | `set_breakpoint` / `remove_breakpoint` | Set or clear JavaScript breakpoints by script URL and line number. |
  196. | `pause` / `resume` | Suspend or resume V8 JavaScript execution via Debugger domain. |
  197. ### 🛡️ Main Process, Native Mocks, Menus & Security (23)
  198. | Tool | Description |
  199. | --- | --- |
  200. | `ipc_fuzz_and_verify` | **Composite:** IPC security and crash hardening fuzzer probing active handlers with boundary & attack payloads (`null`, `__proto__`, path traversal, oversized buffers). |
  201. | `mock_electron_api` | Intercept and mock any Electron native module (`dialog`, `shell`, `app`, `clipboard`, `autoUpdater`) with custom return values or async implementations. |
  202. | `get_mock_calls` | Inspect recorded call history, argument signatures, and timestamps for mocked Electron APIs. |
  203. | `restore_electron_mocks` | Restore original native Electron implementations and purge mock call records. |
  204. | `get_application_menu` | Inspect the native `Menu.getApplicationMenu()` tree with roles, labels, enabled/checked states, and accelerator shortcuts. |
  205. | `click_menu_item` | Programmatically dispatch `.click()` on native application menu items by path (`"File > Save"`), role, or id. |
  206. | `trigger_shortcut` | Inspect and trigger native global accelerators (`globalShortcut`) in the Electron application. |
  207. | `get_process_health` | Watchdog monitoring process exits, crashes (`render-process-gone`), window hangs (`unresponsive`), memory RSS/heap, and stderr logs. |
  208. | `electron_security_audit` | Comprehensive security audit of webPreferences, context isolation, sandboxing, window handlers, navigation guards, and binary fuses. |
  209. | `ipc_invoke` | Directly invoke a main-process IPC handle channel or emit an IPC event with arguments. |
  210. | `ipc_schema_inference` | Infer IPC channel contracts, payload types, and auto-generate TypeScript definitions. |
  211. | `ipc_tap` / `get_ipc_log` | Hook main-process IPC to capture traffic between renderer and main. |
  212. | `evaluate_main` | Evaluate JavaScript inside the Electron main/Node context (requires `inspectMain`). |
  213. | `main_state` | Inspect Electron application state: open windows, metrics, versions, and system paths. |
  214. | `webcontents_topology` | Map BrowserWindows and webContents IDs to their respective CDP targets. |
  215. | `focus_window` | Show and bring a specific BrowserWindow to the foreground. |
  216. | `set_window_bounds` | Move or resize an Electron BrowserWindow. |
  217. | `set_permission` | Programmatically allow or deny permissions (notifications, media, geolocation, etc.). |
  218. | `get_clipboard` / `set_clipboard` | Read or write text and image data on the OS clipboard. |
  219. | `print_pdf` | Render the page to a PDF document artifact. |
  220. | `capture_mhtml` | Save the page DOM, stylesheets, and images into an MHTML archive artifact. |
  221. ### 🩺 Meta & Diagnostics (11)
  222. | Tool | Description |
  223. | --- | --- |
  224. | `run_script` | **Composite:** Server-side workflow engine with templating (`{{vars}}`, `{{steps[id].result}}`), conditional branching (`if`), step retries, assertions, failure diagnostics, and Playwright codegen. |
  225. | `triage` | **Composite:** One-shot diagnosis aggregating page state, console errors, network failures, audit issues, log tails, and resolved exception stacks. |
  226. | `doctor` | Verify environment health, Node/Electron binaries, and test ephemeral port binding. |
  227. | `diagnose` | Health check across all active sessions, target counts, and buffer sizes. |
  228. | `clear_buffers` | Reset buffered console messages, network requests, logs, or IPC entries. |
  229. | `list_targets` | Enumerate all CDP targets (pages, workers, iframes, node). |
  230. | `emulate` | Override viewport, user agent, geolocation, device scale factor, and color scheme. |
  231. | `virtual_clock` | Freeze or advance virtual time to test deterministic timers and animations. |
  232. | `set_console_live` | Stream live console and log messages directly as MCP notifications. |
  233. | `cdp_command` | Raw CDP escape hatch: execute any `Domain.method` with custom parameters. |
  234. ---
  235. ## 📦 Resources & Prompts
  236. ### 📡 Standard MCP Resources
  237. Expose real-time state and exported artifacts directly via standard MCP resources:
  238. - `electron://server` — Server status, version, and host environment.
  239. - `electron://info` — Active process IDs, target breakdown, and recent error counts.
  240. - `electron://targets` — Live CDP targets across all connected processes.
  241. - `electron://artifacts` — Index of all exported screenshots, traces, heap snapshots, and HARs.
  242. - `electron://artifact/{id}` — Fetch an exported artifact by its ID.
  243. - `electron://process/{id}` · `electron://logs/{id}` · `electron://console/{id}` · `electron://cdp/{proc}/{target}`
  244. ### 💬 Built-in MCP Prompts
  245. Interactive debugging recipes ready for one-click invocation:
  246. - `debug_blank_window` — Systematically diagnose white/blank renderers.
  247. - `find_renderer_exception` — Isolate unhandled exceptions, inspect audits, and resolve source stacks.
  248. - `ui_smoke_check` — End-to-end UI verification: wait, interact, and assert.
  249. - `attach_and_screenshot` — Discover local apps, attach, and capture visual status.
  250. - `vision_then_act` — Visual-first agent loop: see, locate semantic target, act, and verify.
  251. - `ax_then_assert` — Accessibility-first action loop: locate by accessible name and assert state.
  252. ---
  253. ## 📚 Agent Recipes
  254. ### 1. Vision → Act → Verify Loop
  255. ```json
  256. // Step 1: Look at the screen and check for errors
  257. { "name": "vision", "arguments": {} }
  258. // Step 2: Act and verify in a single turn (captures failure screenshot if assertion fails)
  259. {
  260. "name": "act_and_verify",
  261. "arguments": {
  262. "action": { "type": "click_ax", "name": "Sign In" },
  263. "assertion": { "textIncludes": "Welcome back" }
  264. }
  265. }
  266. ```
  267. ### 2. Secret Redaction in Automation Forms
  268. ```json
  269. {
  270. "name": "type_text",
  271. "arguments": {
  272. "selector": "#api-key",
  273. "text": "{{secret:MY_APP_API_KEY}}"
  274. }
  275. }
  276. ```
  277. > [!NOTE]
  278. > Resolves `process.env.MY_APP_API_KEY`, inserts it via CDP, returns `typed: "[REDACTED]"`, and automatically sanitizes the secret from all subsequent logs, console events, and HAR files.
  279. ### 3. Automated Security Audit
  280. ```json
  281. { "name": "electron_security_audit", "arguments": {} }
  282. ```
  283. Returns checklist score (0–100), letter grade (A–F), and actionable remediation guidance for `webPreferences` and Electron binary fuses.
  284. ### 4. IPC Contract Inference
  285. ```json
  286. // 1. Arm tap -> 2. Run app interactions -> 3. Infer TypeScript contracts
  287. { "name": "ipc_schema_inference", "arguments": {} }
  288. ```
  289. Generates ready-to-use TypeScript definitions for your preload APIs directly from observed runtime communication.
  290. ### 5. Multi-Step Workflow Engine & Playwright Codegen (`run_script`)
  291. Execute complex, multi-action automations server-side in a single MCP roundtrip with variable interpolation, conditional branching, retries, assertion checks, and code generation.
  292. ```json
  293. {
  294. "name": "run_script",
  295. "arguments": {
  296. "vars": {
  297. "targetWorkspace": "workspace-alpha",
  298. "expectedItems": 3
  299. },
  300. "steps": [
  301. {
  302. "id": "authenticate",
  303. "tool": "type_text",
  304. "args": {
  305. "selector": "input#token",
  306. "text": "{{secret:APP_API_TOKEN}}"
  307. },
  308. "expect": { "status": "success" }
  309. },
  310. {
  311. "id": "switch_workspace",
  312. "tool": "click",
  313. "args": { "selector": "button.workspace-switch" },
  314. "retry": { "retries": 3, "delayMs": 250 }
  315. },
  316. {
  317. "id": "check_banner",
  318. "tool": "eval_js",
  319. "args": { "expression": "Boolean(document.querySelector('.promo-modal'))" }
  320. },
  321. {
  322. "id": "dismiss_banner",
  323. "if": "{{steps.check_banner.result.value}} == true",
  324. "tool": "click",
  325. "args": { "selector": ".promo-modal .close-btn" }
  326. },
  327. {
  328. "id": "verify_workspace_state",
  329. "tool": "eval_js",
  330. "args": {
  331. "expression": "({ active: document.querySelector('#current-ws').textContent.trim(), count: document.querySelectorAll('.item').length })"
  332. },
  333. "expect": {
  334. "js": "result.value.active === 'workspace-alpha' && result.value.count >= 3"
  335. }
  336. }
  337. ],
  338. "exportAs": "playwright"
  339. }
  340. }
  341. ```
  342. #### Capabilities & Options
  343. | Feature | Syntax / Option | Purpose |
  344. | --- | --- | --- |
  345. | **Variables & Context** | `{{vars.key}}` | Reference values from the script's `vars` object with preserved primitive types (strings, numbers, booleans, objects). |
  346. | **Step Dependencies** | `{{steps.id.result.path}}` | Pass outputs, IDs, or tokens computed in earlier steps directly into subsequent tool arguments. |
  347. | **Environment & Secrets** | `{{env.KEY}}` · `{{secret:KEY}}` | Inject process environment variables; secrets are automatically masked in logs, console events, and outputs as `[REDACTED]`. |
  348. | **Conditional Branching** | `if: "{{steps.check.result.open}} == true"` | Skips step execution unless condition evaluates to true (`==`, `!=`, `<`, `>`, `&&`, `||`). |
  349. | **Expectation Assertions** | `expect: { contains, equals, status, js }` | Validates step outcome; custom `js` expressions evaluate against `result` to verify app invariants. |
  350. | **Automatic Retries** | `retry: { retries: 3, delayMs: 250 }` | Automatically retries flaky operations with exponential backoff before failing. |
  351. | **Failure Diagnostics** | *Automated* | If a step fails, captures viewport screenshot artifact (`electron://artifact/{id}`), console errors, and network errors. |
  352. | **Playwright Codegen** | `exportAs: "playwright"` | Generates a standalone, runnable Playwright `_electron` test script (`.spec.ts`) reflecting the executed sequence. |
  353. <details>
  354. <summary><b>View Generated Playwright Codegen Output</b></summary>
  355. ```typescript
  356. import { test, expect, _electron as electron } from "@playwright/test";
  357. test("executed script workflow", async () => {
  358. const electronApp = await electron.launch({ args: ["."] });
  359. const window = await electronApp.firstWindow();
  360. // Step: authenticate
  361. await window.locator("input#token").fill(process.env.APP_API_TOKEN || "");
  362. // Step: switch_workspace
  363. await window.locator("button.workspace-switch").click();
  364. // Step: dismiss_banner
  365. await window.locator(".promo-modal .close-btn").click();
  366. // Step: verify_workspace_state
  367. const evalResult = await window.evaluate("({ active: document.querySelector('#current-ws').textContent.trim(), count: document.querySelectorAll('.item').length })");
  368. expect(evalResult).toBeDefined();
  369. await electronApp.close();
  370. });
  371. ```
  372. </details>
  373. ### 6. Ref Locators & Set-of-Marks Visual Prompting
  374. Inspect accessibility targets with compact refs (`e1`, `e2`) and drive interactions without fragile CSS selectors:
  375. ```json
  376. // 1. Take snapshot with Set-of-Marks badges in the screenshot
  377. { "name": "vision", "arguments": { "markElements": true } }
  378. // 2. Click directly by ref token
  379. { "name": "click", "arguments": { "ref": "e3" } }
  380. // 3. Type text into ref
  381. { "name": "type_text", "arguments": { "ref": "e4", "text": "Hello Desktop!" } }
  382. ```
  383. ### 7. Native Electron API Mocking (Dialogs, Shell, Clipboard)
  384. Bypass OS file dialogs, external URL opens, or update checks during automated test runs:
  385. ```json
  386. // 1. Mock dialog.showOpenDialog to return test fixtures
  387. {
  388. "name": "mock_electron_api",
  389. "arguments": {
  390. "module": "dialog",
  391. "method": "showOpenDialog",
  392. "returns": { "canceled": false, "filePaths": ["/fixtures/document.pdf"] }
  393. }
  394. }
  395. // 2. Mock shell.openExternal
  396. {
  397. "name": "mock_electron_api",
  398. "arguments": {
  399. "module": "shell",
  400. "method": "openExternal",
  401. "returns": true
  402. }
  403. }
  404. // 3. Inspect tracked invocations
  405. { "name": "get_mock_calls", "arguments": { "module": "shell", "method": "openExternal" } }
  406. // 4. Restore original implementation
  407. { "name": "restore_electron_mocks", "arguments": { "module": "shell", "method": "openExternal" } }
  408. ```
  409. ### 8. Native Application Menu & Accelerator Trigger
  410. Automate native OS menus and global keyboard shortcuts:
  411. ```json
  412. // 1. Inspect the full native menu tree
  413. { "name": "get_application_menu", "arguments": {} }
  414. // 2. Click menu item by path or role
  415. { "name": "click_menu_item", "arguments": { "path": "File > Save" } }
  416. // 3. Dispatch an Electron accelerator directly
  417. { "name": "trigger_shortcut", "arguments": { "accelerator": "CommandOrControl+Shift+P" } }
  418. ```
  419. ### 9. Process Health Watchdog & Crash Diagnostics
  420. ```json
  421. { "name": "get_process_health", "arguments": {} }
  422. ```
  423. Returns real-time status (`"healthy"`, `"unresponsive"`, or `"crashed"`), tracking OOM terminations, child process failures, window hangs, and memory metrics.
  424. ### 10. Storage State Snapshot & Auth Replay
  425. Save full session state (cookies, localStorage, sessionStorage) into Playwright-compatible storage state artifacts to bypass repeated login flows across tests:
  426. ```json
  427. // 1. Export storage state to an artifact
  428. { "name": "save_storage_state", "arguments": {} }
  429. // 2. Restore state into any new Electron session
  430. {
  431. "name": "load_storage_state",
  432. "arguments": {
  433. "state": { "cookies": [...], "origins": [...] }
  434. }
  435. }
  436. ```
  437. ### 11. One-Shot Bug Repro Bundle & Issue Generator (`repro_bundle`)
  438. Package a complete, self-contained zip archive containing viewport screenshot, full MHTML DOM archive, HAR network replay, source-mapped console errors, stderr tail, health metrics, and a GitHub-ready Markdown issue report in one turn:
  439. ```json
  440. {
  441. "name": "repro_bundle",
  442. "arguments": {
  443. "notes": "Regression on checkout flow after OAuth upgrade"
  444. }
  445. }
  446. ```
  447. Returns `artifactUri: "electron://artifact/..."`, destination path, and the complete markdown summary ready to paste into GitHub issues or Jira.
  448. ### 12. Smart Multi-Field Accessible & Secret Form Solver (`fill_form`)
  449. Fill complete multi-input forms in a single tool call from either a key-value dictionary or structured field specs:
  450. ```json
  451. {
  452. "name": "fill_form",
  453. "arguments": {
  454. "fields": {
  455. "Username or Email": "developer@example.com",
  456. "Password": "{{secret:APP_PASSWORD}}",
  457. "Environment": "Staging",
  458. "Remember Me": true
  459. },
  460. "submit": true,
  461. "expect": {
  462. "textIncludes": "Welcome back"
  463. }
  464. }
  465. }
  466. ```
  467. Resolves fields via accessibility tree labels, ARIA attributes, placeholders, or refs (`e1`), resolves secrets securely, selects dropdown options, toggles checkboxes, clicks submit, and verifies post-submit UI assertions.
  468. ### 13. Network Chaos & Resilience Scorecard (`offline_resilience_check`)
  469. Simulate real-world network failure conditions (offline, latency, or HTTP 500) during interaction, monitor app health and error bursts, restore network, and compute an executive Resilience Grade (A–F):
  470. ```json
  471. {
  472. "name": "offline_resilience_check",
  473. "arguments": {
  474. "faultType": "offline",
  475. "durationMs": 1500,
  476. "action": { "type": "click", "selector": "#save-btn" }
  477. }
  478. }
  479. ```
  480. ### 14. Responsive Theme & Viewport Matrix Sweep (`responsive_theme_matrix`)
  481. Audit how layouts adapt across color schemes (`light`, `dark`) and viewport sizes, catching horizontal scrollbar leaks (`scrollWidth > innerWidth`):
  482. ```json
  483. {
  484. "name": "responsive_theme_matrix",
  485. "arguments": {
  486. "themes": ["light", "dark"],
  487. "viewports": [
  488. { "width": 800, "height": 600, "name": "compact" },
  489. { "width": 1280, "height": 800, "name": "desktop" }
  490. ]
  491. }
  492. }
  493. ```
  494. ### 15. IPC Security & Crash Hardening Fuzzer (`ipc_fuzz_and_verify`)
  495. Harden renderer-to-main IPC communication against malicious or malformed payloads (`null`, prototype pollution, path traversal, oversized buffers) and verify process crash resistance:
  496. ```json
  497. {
  498. "name": "ipc_fuzz_and_verify",
  499. "arguments": {
  500. "iterations": 6
  501. }
  502. }
  503. ```
  504. ---
  505. ## 📋 Changelog & Releases
  506. | Version | Release Highlights | Test Suite |
  507. | :--- | :--- | :--- |
  508. | **v1.15.1** | **Security & Client Startup Fixes**: Path validation for `run_script` / `save_storage_state` (`validateOutputPath`, prevents CWE-22 arbitrary file write), and removal of broken `postinstall` script fixing `npx` / Copilot / Cursor handshake exit code 1. **111 tools**. | 142 unit · 111 smoke |
  509. | **v1.15.0** | **Composite Superpowers & Resilience Workflows**: One-Shot Bug Repro Bundle (`repro_bundle`), Smart Accessible & Secret Form Solver (`fill_form`), Network Chaos Resilience Scorecard (`offline_resilience_check`), Responsive Theme Sweep (`responsive_theme_matrix`), IPC Security Fuzzer (`ipc_fuzz_and_verify`). Pure Node zero-dependency PKZip generator. **111 tools**. | 140 unit · 111 smoke |
  510. | **v1.14.0** | **Ref Locators & Set-of-Marks** (`ref: "e1"`, `markElements: true`), **Native Electron API Mocking** (`mock_electron_api`, `get_mock_calls`, `restore_electron_mocks`), **Native Application Menu Driver** (`get_application_menu`, `click_menu_item`, `trigger_shortcut`), **Process Health Watchdog** (`get_process_health`), **Storage State Save & Load** (`save_storage_state`, `load_storage_state`). **106 tools**. | 135 unit · 106 smoke |
  511. | **v1.13.0** | **Server-Side Workflow Engine & Codegen** (`run_script` with context variables, conditional branching, expectation assertions, retries, failure diagnostics, and Playwright test codegen). **97 tools**. | 130 unit · 97 smoke |
  512. | **v1.12.0** | **Runtime Security Audit** (`electron_security_audit`), **Zero-Leak Secret Redaction** (`{{secret:VAR}}`), **IPC Schema Inference** (`ipc_schema_inference`), **Memory Leak Hunter** (`leak_check`), **Source Maps** (`resolve_stack`), **Composite Workflows** (`act_and_verify`, `triage`, `network_failure_report`, `perf_snapshot`). **96 tools**. | 125 unit · 96 smoke |
  513. | **v1.11.0** | **Tool Annotations** (`readOnlyHint`, `destructiveHint`), **Optional `processId`**, **Artifacts System** (`electron://artifacts`), **Network Log Filtering**, **DOM Guard**, `llms.txt`. **88 tools**. | 120 unit · 88 smoke |
  514. > [!TIP]
  515. > Complete historical release notes, API migration notes, and dependency updates are tracked in [**`CHANGELOG.md`**](./CHANGELOG.md).
  516. ---
  517. ## 🧯 Troubleshooting
  518. | Symptom | Solution |
  519. | --- | --- |
  520. | `Electron failed to install correctly` | Run `npm run ensure-electron` to verify and download the platform binary. |
  521. | `Process not found` | Omit `processId` when debugging a single app; the server resolves it automatically. |
  522. | Terminal hangs on `node build/index.js` | Normal: the server communicates over stdio JSON-RPC. Spawn it from your MCP client. |
  523. | Main-process tools fail | Launch the app with `inspectMain: true` to open the Node inspector port. |
  524. | Port in use / WSAEACCES on Windows | The server dynamically probes and selects ephemeral bindable ports to avoid Hyper-V/WSL conflicts. |
  525. ---
  526. ## 📜 Development & Verification
  527. ```bash
  528. npm test # Run build, 140 unit tests, and full 111-tool smoke suite
  529. npm run doctor # Verify environment health and port binding
  530. npm run sync:readme # Automatically synchronize badge counts with registered tools
  531. ```
  532. ---
  533. ## 📄 License
  534. [ISC](./LICENSE) © Electron Debug MCP contributors
  535. <div align="center">
  536. <img src="assets/logo.svg" width="48" height="48" alt="Electron Debug MCP" /><br/>
  537. <sub>Built for autonomous agents that need eyes — and hands — inside Electron.</sub>
  538. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.