mcp-cdp

mcp-cdp

一个默认安全的 Model Context Protocol 服务，可通过 Chrome DevTools Protocol (CDP) 驱动 Electron 或 Chrome/Chromium 应用，而非使用像素级 GUI 自动化。将它指向应用的 --remote-debugging-port，Agent 就能访问 DOM、控制台、网络请求，执行真实输入操作（点击／输入／导航），以及（经授权后）执行 JavaScript。

它为何比桌面／网页应用的计算机操控方式更好：

• DOM，而非屏幕截图。 Agent 可以读取准确渲染的 HTML，并查询任意元素——获取的信息多得多，还能看到屏幕上未显示的内容。
• 控制台 + 网络。 测试失败时，未捕获的异常或失败的请求就在眼前——无需从图像中猜测。
• 互不冲突。 每个 Agent 都连接到自己的调试端口，因此并行运行的 Agent（例如每个 git worktree 一个）不会争用同一桌面。
• 跨操作系统。 CDP 在 macOS、Linux 和 Windows 上的工作方式完全一致——同一流程也能在无头 VPS 上运行。

这是 dockndevai MCP 服务套件的一部分——所有服务采用统一的治理模式。

它能为 Agent 提供什么

默认以只读模式启动（参见默认安全）；只有提高模式后，才会注册更高权限的工具。

工具	用途	所需模式
list_targets	列出页面／webview／Electron 窗口（id、type、title、url）	只读
dom_snapshot	页面或选择器子树的渲染后 HTML	只读
query_dom	所有匹配 CSS 选择器的元素的 outer HTML	只读
console_logs	最近的控制台输出 + 未捕获的异常	只读
network_requests	最近的请求（method、url、status、mime；不会捕获标头）	只读
screenshot	视口的 PNG 图像	只读
click	点击第一个匹配选择器的元素	读写
type_text	在页面中输入文本（先聚焦选择器）	读写
press_key	Enter / Tab / Escape / Backspace / Delete / 方向键	读写
navigate	将目标导航至某个 URL（需确认）	读写
evaluate	在页面中运行 JavaScript 表达式	管理员 + CDP_ALLOW_EVAL

安装

npx -y @dockndevai/mcp-cdp

暴露调试端口

启动应用（或 worktree 的开发构建）并指定端口——每个 Agent 使用一个端口：

• Electron 应用： your-app --remote-debugging-port=9222，或在主进程代码中，于 app.whenReady() 之前调用 app.commandLine.appendSwitch('remote-debugging-port', '9222')。
• 普通 Chrome/Chromium： chrome --headless=new --remote-debugging-port=9222 --user-data-dir=/tmp/p1 <url>。

检查服务是否已启动：curl http://127.0.0.1:9222/json/version。

配置

{
  "mcpServers": {
    "cdp": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-cdp"],
      "env": {
        "CDP_PORT": "9222",
        "CDP_MODE": "read-only"
      }
    }
  }
}

Claude Code / Cursor / Codex / VS Code / Windsurf 的配置请参阅 docs/CLIENTS.md，所有变量请参阅 .env.example。

默认安全

由 src/security.ts 强制执行。浏览器进程才是真正的边界——这能确保 Agent 仅在你指定的目标和操作范围内运行：

• CDP_MODE — read-only（默认）→ read-write → admin。高于当前模式的工具不会注册，因此在只读模式下，Agent 完全无法点击、输入或导航。
• CDP_TARGET_ALLOWLIST — 将交互限制在 URL 与你指定模式匹配的目标内（空值 = 全部）。读取（检查）始终允许。
• CDP_PROTECTED_TARGETS — 可以检查但绝不允许交互的目标。默认保护登录页面（accounts.google.com、login.microsoftonline.com、……）和浏览器内部页面（chrome://、devtools://、扩展程序）。
• CDP_ALLOW_EVAL — evaluate 会在渲染器中执行任意代码：需要管理员模式并且启用此标志，受保护的目标上会拒绝执行，且需要人工确认。
• CDP_DRY_RUN — 交互会记录其意图并直接返回，不会实际执行。
• 机密信息 — 请求/响应标头绝不会被捕获（Cookie/身份验证信息），敏感的 URL 查询参数值会被隐藏。evaluate 和 navigate 也会通过 MCP 征询请求人工确认。
• 仅限环回地址 — 端点必须是 127.0.0.1，除非设置了 CDP_ALLOW_REMOTE=true。

可选的 AI 风险防护。 设置 CDP_GUARD_MODE=monitor|enforce，让 evaluate 工具在执行前调用本地 laya-guard 守护进程，对 JS 表达式进行分类，决定允许、确认或阻止执行（pipx install laya-guard && laya-guard）。它会在 eval 安全检查之后运行，只能进一步收紧限制，不能授予权限；发生故障时会默认拒绝。

项目内置了一个技能 cdp-safe-operations，用于指导 Agent 如何开放端口、如何读取 DOM/控制台/网络而非使用截图、安全规则，以及“为什么失败了？”的工作流。另请参阅 SECURITY.md。

开发

npm install
npm run build
# list the tools:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | CDP_PORT=9222 node dist/index.js
npm test

许可证

MIT