🚀 Electron Debug MCP Server

Electron Debug MCP

为 AI 编码 Agent 注入真正的 Chrome DevTools Protocol 超能力。
让 Cursor、Claude 和自主 Agent 在 Electron 桌面应用中拥有观察、操作和深入检查运行时的能力。

快速开始 • 超能力 • 工具矩阵 • 使用示例 • 资源与提示词 • 更新日志 • 故障排除

---

🌟 为什么选择 Electron Debug MCP？

大多数 AI 编码 Agent 难以处理桌面应用：它们可以编辑源代码，却无法看到生成的窗口、点击按钮、读取控制台错误，或诊断无声无息的主进程崩溃。

Electron Debug MCP 通过 Chrome DevTools Protocol (CDP) 和 Node 检查器，将 Agent 直接接入 Electron 运行时，解锁全面的可视化、交互和诊断自主能力。

flowchart LR
    A["🤖 AI Agent (Cursor / Claude)"] <-->|"stdio JSON-RPC"| B["⚡ Electron Debug MCP"]
    B <-->|"CDP (WebSocket)"| C["🖼️ Renderer Windows\n(DOM · AXTree · Network · V8)"]
    B <-->|"Node Inspector / V8"| D["⚙️ Main Process\n(IPC · WebContents · Windows · Fuses)"]

✨ 核心超能力

⚡ 快速开始

1. 配置 MCP 客户端

🚀 在 Cursor 中（~/.cursor/mcp.json 或 .cursor/mcp.json）

{
  "mcpServers": {
    "electron-debug": {
      "command": "npx",
      "args": ["-y", "electron-debug-mcp@latest"]
    }
  }
}

💬 在 Claude Desktop 中（claude_desktop_config.json）

{
  "mcpServers": {
    "electron-debug": {
      "command": "npx",
      "args": ["-y", "electron-debug-mcp@latest"]
    }
  }
}

提示

在本地开发？ 运行 npm run build，并配置 "command": "node" 和 "args": ["/path/to/electron-mcp-server/build/index.js"]。

🛠️ 工具一览（111 个工具）

所有工具都接受可选的 processId。仅有一个应用运行时，会自动解析为活动进程。

🚀 生命周期与连接（8 个）

👁️ 查看与视觉检查（8 个）

🖱️ 操作与 UI 自动化（13）

📄 页面状态与导航（20）

🌐 网络与下载（12）

📈 性能、性能分析与调试器（16）

🛡️ 主进程、原生模拟、菜单与安全（23）

🩺 元信息与诊断（11）

📦 资源与提示词

📡 标准 MCP 资源

通过标准 MCP 资源直接公开实时状态和导出的产物：

• electron://server — 服务状态、版本和主机环境。
• electron://info — 活动进程 ID、目标明细和近期错误计数。
• electron://targets — 所有已连接进程中的实时 CDP 目标。
• electron://artifacts — 所有已导出截图、跟踪记录、堆快照和 HAR 文件的索引。
• electron://artifact/{id} — 根据 ID 获取已导出的产物。
• electron://process/{id} · electron://logs/{id} · electron://console/{id} · electron://cdp/{proc}/{target}

💬 内置 MCP 提示词

可一键调用的交互式调试方案：

• debug_blank_window — 系统化诊断白屏或空白渲染器。
• find_renderer_exception — 定位未处理的异常，检查审计结果并解析源代码堆栈。
• ui_smoke_check — 端到端 UI 验证：等待、交互并断言。
• attach_and_screenshot — 发现本地应用、连接并捕获视觉状态。
• vision_then_act — 视觉优先的 Agent 循环：观察、定位语义目标、执行操作并验证。
• ax_then_assert — 无障碍优先的操作循环：按无障碍名称定位并断言状态。

📚 Agent 方案

1. 视觉 → 操作 → 验证循环

// Step 1: Look at the screen and check for errors
{ "name": "vision", "arguments": {} }

// Step 2: Act and verify in a single turn (captures failure screenshot if assertion fails)
{
  "name": "act_and_verify",
  "arguments": {
    "action": { "type": "click_ax", "name": "Sign In" },
    "assertion": { "textIncludes": "Welcome back" }
  }
}

2. 自动化表单中的密钥脱敏

{
  "name": "type_text",
  "arguments": {
    "selector": "#api-key",
    "text": "{{secret:MY_APP_API_KEY}}"
  }
}

说明

解析 process.env.MY_APP_API_KEY，通过 CDP 填入该值，返回 typed: "[REDACTED]"，并自动从后续所有日志、控制台事件和 HAR 文件中清除该密钥。

3. 自动化安全审计

{ "name": "electron_security_audit", "arguments": {} }

返回检查清单得分（0–100）、字母等级（A–F），以及针对 webPreferences 和 Electron 二进制文件熔断器的可执行修复建议。

4. IPC 契约推断

// 1. Arm tap -> 2. Run app interactions -> 3. Infer TypeScript contracts
{ "name": "ipc_schema_inference", "arguments": {} }

根据观察到的运行时通信，直接为你的预加载 API 生成可直接使用的 TypeScript 定义。

5. 多步骤工作流引擎与 Playwright 代码生成（run_script）

在服务端执行复杂的多操作自动化，只需一次 MCP 往返；支持变量插值、条件分支、重试、断言检查和代码生成。

{
  "name": "run_script",
  "arguments": {
    "vars": {
      "targetWorkspace": "workspace-alpha",
      "expectedItems": 3
    },
    "steps": [
      {
        "id": "authenticate",
        "tool": "type_text",
        "args": {
          "selector": "input#token",
          "text": "{{secret:APP_API_TOKEN}}"
        },
        "expect": { "status": "success" }
      },
      {
        "id": "switch_workspace",
        "tool": "click",
        "args": { "selector": "button.workspace-switch" },
        "retry": { "retries": 3, "delayMs": 250 }
      },
      {
        "id": "check_banner",
        "tool": "eval_js",
        "args": { "expression": "Boolean(document.querySelector('.promo-modal'))" }
      },
      {
        "id": "dismiss_banner",
        "if": "{{steps.check_banner.result.value}} == true",
        "tool": "click",
        "args": { "selector": ".promo-modal .close-btn" }
      },
      {
        "id": "verify_workspace_state",
        "tool": "eval_js",
        "args": {
          "expression": "({ active: document.querySelector('#current-ws').textContent.trim(), count: document.querySelectorAll('.item').length })"
        },
        "expect": {
          "js": "result.value.active === 'workspace-alpha' && result.value.count >= 3"
        }
      }
    ],
    "exportAs": "playwright"
  }
}

功能与选项

import { test, expect, _electron as electron } from "@playwright/test";

test("executed script workflow", async () => {
  const electronApp = await electron.launch({ args: ["."] });
  const window = await electronApp.firstWindow();

  // Step: authenticate
  await window.locator("input#token").fill(process.env.APP_API_TOKEN || "");

  // Step: switch_workspace
  await window.locator("button.workspace-switch").click();

  // Step: dismiss_banner
  await window.locator(".promo-modal .close-btn").click();

  // Step: verify_workspace_state
  const evalResult = await window.evaluate("({ active: document.querySelector('#current-ws').textContent.trim(), count: document.querySelectorAll('.item').length })");
  expect(evalResult).toBeDefined();

  await electronApp.close();
});

6. Ref 定位器与 Set-of-Marks 视觉提示

使用紧凑的 ref（e1、e2）检查无障碍目标，并在不依赖脆弱 CSS 选择器的情况下执行交互：

// 1. Take snapshot with Set-of-Marks badges in the screenshot
{ "name": "vision", "arguments": { "markElements": true } }

// 2. Click directly by ref token
{ "name": "click", "arguments": { "ref": "e3" } }

// 3. Type text into ref
{ "name": "type_text", "arguments": { "ref": "e4", "text": "Hello Desktop!" } }

7. 原生 Electron API 模拟（对话框、Shell、剪贴板）

在自动化测试期间绕过 OS 文件对话框、外部 URL 打开操作或更新检查：

// 1. Mock dialog.showOpenDialog to return test fixtures
{
  "name": "mock_electron_api",
  "arguments": {
    "module": "dialog",
    "method": "showOpenDialog",
    "returns": { "canceled": false, "filePaths": ["/fixtures/document.pdf"] }
  }
}

// 2. Mock shell.openExternal
{
  "name": "mock_electron_api",
  "arguments": {
    "module": "shell",
    "method": "openExternal",
    "returns": true
  }
}

// 3. Inspect tracked invocations
{ "name": "get_mock_calls", "arguments": { "module": "shell", "method": "openExternal" } }

// 4. Restore original implementation
{ "name": "restore_electron_mocks", "arguments": { "module": "shell", "method": "openExternal" } }

8. 原生应用菜单与快捷键触发

自动操作原生 OS 菜单和全局键盘快捷键：

// 1. Inspect the full native menu tree
{ "name": "get_application_menu", "arguments": {} }

// 2. Click menu item by path or role
{ "name": "click_menu_item", "arguments": { "path": "File > Save" } }

// 3. Dispatch an Electron accelerator directly
{ "name": "trigger_shortcut", "arguments": { "accelerator": "CommandOrControl+Shift+P" } }

9. 进程运行状况监控与崩溃诊断

{ "name": "get_process_health", "arguments": {} }

返回实时状态（"healthy"、"unresponsive" 或 "crashed"），跟踪 OOM 终止、子进程故障、窗口挂起和内存指标。

10. 存储状态快照与身份验证重放

将完整会话状态（cookies、localStorage、sessionStorage）保存为与 Playwright 兼容的存储状态文件，以免在多个测试中重复登录：

// 1. Export storage state to an artifact
{ "name": "save_storage_state", "arguments": {} }

// 2. Restore state into any new Electron session
{
  "name": "load_storage_state",
  "arguments": {
    "state": { "cookies": [...], "origins": [...] }
  }
}

11. 一键 Bug 复现包与问题报告生成器（repro_bundle）

一次调用即可打包生成完整、自包含的 zip 存档，其中包含视口截图、完整 MHTML DOM 存档、HAR 网络重放数据、带源映射的控制台错误、stderr 尾部内容、运行状况指标，以及可直接用于 GitHub 的 Markdown 问题报告：

{
  "name": "repro_bundle",
  "arguments": {
    "notes": "Regression on checkout flow after OAuth upgrade"
  }
}

返回 artifactUri: "electron://artifact/..."、目标路径，以及可直接粘贴到 GitHub 问题或 Jira 中的完整 Markdown 摘要。

12. 智能多字段无障碍与机密表单填写器（fill_form）

通过一次工具调用，使用键值字典或结构化字段规格填写完整的多输入项表单：

{
  "name": "fill_form",
  "arguments": {
    "fields": {
      "Username or Email": "[email protected]",
      "Password": "{{secret:APP_PASSWORD}}",
      "Environment": "Staging",
      "Remember Me": true
    },
    "submit": true,
    "expect": {
      "textIncludes": "Welcome back"
    }
  }
}

通过无障碍树标签、ARIA 属性、占位符或引用（e1）解析字段，安全地解析机密信息，选择下拉选项，切换复选框，点击提交，并验证提交后的 UI 断言。

13. 网络混乱与恢复能力评分卡（offline_resilience_check）

在交互期间模拟真实网络故障情形（离线、延迟或 HTTP 500），监控应用运行状况和错误突发，恢复网络，并计算执行层面的恢复能力评级（A–F）：

{
  "name": "offline_resilience_check",
  "arguments": {
    "faultType": "offline",
    "durationMs": 1500,
    "action": { "type": "click", "selector": "#save-btn" }
  }
}

14. 响应式主题与视口矩阵扫描（responsive_theme_matrix）

检查布局在不同配色方案（light、dark）和视口大小下的适配情况，捕获水平滚动条溢出（scrollWidth > innerWidth）：

{
  "name": "responsive_theme_matrix",
  "arguments": {
    "themes": ["light", "dark"],
    "viewports": [
      { "width": 800, "height": 600, "name": "compact" },
      { "width": 1280, "height": 800, "name": "desktop" }
    ]
  }
}

15. IPC 安全与崩溃防护模糊测试器（ipc_fuzz_and_verify）

增强渲染进程到主进程的 IPC 通信防护，以抵御恶意或格式错误的负载（null、原型污染、路径遍历、超大缓冲区），并验证进程抵御崩溃的能力：

{
  "name": "ipc_fuzz_and_verify",
  "arguments": {
    "iterations": 6
  }
}

📋 更新日志与版本发布

提示

完整的历史版本说明、API 迁移说明和依赖更新记录均在 CHANGELOG.md 中维护。

🧯 故障排查

📜 开发与验证

npm test            # Run build, 140 unit tests, and full 111-tool smoke suite
npm run doctor      # Verify environment health and port binding
npm run sync:readme # Automatically synchronize badge counts with registered tools

📄 许可证

ISC © Electron Debug MCP 贡献者

_{为需要在 Electron 内部观察并操作的自主 Agent 而构建。}