feat: 新增 electron-mcp 条目 — Electron 桌面应用 CDP 自动化 (#1)

- entries/electron-mcp/manifest.json:4 工具、stdio 连接,截图密钥走 {{secrets.*}} 占位
- install.md:端口硬编码扫描范围、CDP 无鉴权风险、密钥强制校验
- usage.md:与 playwright/chrome-devtools MCP 的选型分工,以及 9 条实测限制与规避
- manifest.json:stats 20→21、mcpServices 7→8
This commit is contained in:
2026-07-29 16:04:02 +08:00
committed by GitHub
parent 53709bcb0f
commit e06a0b74d0
4 changed files with 301 additions and 3 deletions

View File

@@ -0,0 +1,82 @@
# 安装 Electron MCP
## 环境要求
- Node.js >= 18
- 目标 Electron 应用可以带 `--remote-debugging-port` 启动(见下方「让目标应用开放调试端口」)
- 首次拉包约 200MB+:该包依赖 `electron``playwright`(截图走 `chromium.connectOverCDP`
`npx` 冷启动可能需要数分钟。**不需要**额外执行 `npx playwright install`——它连接的是目标应用
自带的 Chromium不下载浏览器。
## 安装步骤
### 1. 生成截图加密密钥(必需)
`SCREENSHOT_ENCRYPTION_KEY` 是硬性前置:未设置、仍为默认值 `default-screenshot-key-change-me`
或长度不足 32 字符时,截图工具直接抛错。
```bash
openssl rand -hex 32
```
条目的连接配置里用 `{{secrets.SCREENSHOT_ENCRYPTION_KEY}}` 引用该值,因此需要把生成结果写入
`~/.desirecore/config/secrets.json`
```json
{
"SCREENSHOT_ENCRYPTION_KEY": "<上一步生成的 64 位十六进制字符串>"
}
```
未配置时连接会明确报错提示缺失的 secret不会静默降级。
### 2. 让目标应用开放调试端口
MCP 通过 Chrome DevTools Protocol (CDP) 连接,目标应用必须显式开放端口:
```bash
# 开发态:直接给 electron 传参
electron . --remote-debugging-port=9222
# 打包应用:多数框架同样接受该参数
/Applications/YourApp.app/Contents/MacOS/YourApp --remote-debugging-port=9222
```
如果应用在主进程里用 `app.commandLine.appendSwitch('remote-debugging-port', ...)` 控制,
就按该应用自身的开关(常见做法是仅在非打包态开启)来启用。
**端口不是任意的。** v1.5.0 的端口扫描列表在代码中硬编码,且**不读取任何环境变量**
```text
9222 9223 9224 9225
9200 9201 9202 9203 9204 9205
9300 9301 9302 9303 9304 9305
9400 9401 9402 9403 9404 9405
```
端口落在列表之外(例如自动分配到 9226MCP 完全发现不到该应用,四个工具全部不可用。
此时只能改用直连 CDP`usage.md`)。
### 3. 安全提示
CDP 协议**没有任何鉴权**,开放端口等于把渲染进程的完整控制权交给能访问该端口的任何人。
- 端口必须绑定 `127.0.0.1`Electron 默认行为),不要监听 `0.0.0.0`
- 生产/最终用户环境不要常开该端口
- 用 SSH 隧道远程调试时,本地转发端口必须先确认空闲——被占用时 `ssh -L` 可能只绑到 IPv6
`bind: Address already in use` 混在 stderr 里被忽略,后续请求会**静默打到本机的另一个
实例上**。动作前先 `curl http://127.0.0.1:<port>/json/version` 核对 `User-Agent` 是不是目标机器
## 验证
启动目标应用后:
```bash
# 1. 确认 CDP 端口活着,并核对连上的确实是目标应用
curl -s http://127.0.0.1:9222/json/version
# 2. 确认 MCP 本身可启动
npx -y electron-mcp-server@1.5.0 --help
```
接入 MCP 客户端后,调用 `get_electron_window_info` 应返回窗口标题与 URL。