mirror of
https://git.openapi.site/https://github.com/desirecore/registry.git
synced 2026-09-05 17:53:43 +08:00
Yige
e06a0b74d0
- 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
83 lines
2.9 KiB
Markdown
83 lines
2.9 KiB
Markdown
# 安装 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
|
||
```
|
||
|
||
端口落在列表之外（例如自动分配到 9226）时，MCP 完全发现不到该应用，四个工具全部不可用。
|
||
此时只能改用直连 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。
|