devcdp

DevCDP

通过 MCP 为 AI 助手提供真实的 Chrome DevTools 访问能力。助手可以读取控制台、监视网络、查询 DOM、解析 source map、设置断点并检查实时变量——因此，它能告诉你问题为什么出现，而不是根据粘贴的错误信息猜测。

适用于任何支持 MCP 的助手和任何 Web 应用：没有内置任何特定框架、产品或公司的内容。

74 个工具——完整参考请参阅 docs/TOOLS.md，该文档由服务自身生成；关于测得的 token 成本及如何降低成本，请参阅 docs/PERFORMANCE.md。

---

它能做什么

控制台	日志、警告和未捕获的异常，附带文件、从 1 开始计数的行号和堆栈。
网络	从连接时起记录每个请求——方法、状态、耗时、大小、发起方，以及按需获取的响应正文。
DOM	选择器查询，提供真实的可见性和几何信息、具名的计算样式、变更历史、iframe 支持，以及结构化对话框检测。
源代码	已加载的脚本，以及通过 source map 还原的打包前原始文件——包括需要身份验证才能访问的外部 .map 文件。支持对两者进行全文搜索。
调试器	按原始行号在原始文件中设置断点、单步执行，以及展开嵌套对象进行作用域检查，而不是只打印 Object。
发现	向应用询问其自身信息：框架、路由、其按钮和字段可用的选择器、后端 API 接口，以及你项目自身的文档。
协作	你可以随时接管；你点击、选择和输入的内容都会被记录，供助手读取。

它谨慎处理的四件事

绝不伪造成功。 无法绑定的断点会显示 bound: false 并说明原因。Chrome 已丢弃的正文也会明确说明。已恢复的暂停所生成的捕获会标记为过期。每次失败都会返回 {ok: false, code, message, hint}，并指出下一步操作。

明确告知知识的边界。 Chrome 无法向稍后才连接的调试器重放控制台历史记录，因此连接时会准确报告这一点，而不会把空缓冲区说成“没有错误”。

不会让你陷入困境。 对页面的每次调用都会在我们这一侧设定时限——Runtime.evaluate 自身的超时由渲染器强制执行；如果卡住的正是渲染器，这就毫无用处。页面陷入无限循环时，会在几秒内失败并指出恢复方式；DevCDP 还会自行终止失控的脚本并重试。

绝不会让你的应用一直卡住。 断点会先捕获所需内容，然后自动恢复。即使是有意保持的暂停，也会在 maxPauseMs 后释放；断开连接时，所有内容都会清理干净。

---

安装

要求： Node 18+、Chrome，以及支持 MCP 的助手。

选择适合你客户端的方式。它们都在你的机器上运行同一个服务；不会托管在其他地方。

任意 MCP 客户端，通过 npm 安装。 将以下内容添加到客户端的 MCP 配置中：

{ "mcpServers": { "devcdp": { "command": "npx", "args": ["-y", "devcdp"] } } }

在原生 Windows 上，某些客户端需要 "command": "cmd", "args": ["/c", "npx", "-y", "devcdp"]。

Claude Code，通过插件安装（服务加上一项技能，用于告诉 Claude 何时使用哪个工具）：

/plugin marketplace add Dayananda-D/DevCDP
/plugin install devcdp@devcdp

Cursor： ， 或将上面的 JSON 添加到 ~/.cursor/mcp.json。

Gemini CLI，作为同时附带使用指南的扩展：

gemini extensions install https://github.com/Dayananda-D/DevCDP

opencode： 使用 opencode mcp add，或在 opencode.json 中添加：

{ "mcp": { "devcdp": { "type": "local", "command": ["npx", "-y", "devcdp"], "enabled": true } } }

Codex（CLI、桌面应用、VS Code 扩展），作为插件安装：

codex plugin marketplace add Dayananda-D/DevCDP

VS Code： 在 VS Code 中安装，或运行 MCP: Add Server，选择 NPM Package， 然后输入 devcdp。Copilot CLI： 使用命令 /mcp add，并指定 npx -y devcdp。DevCDP 已列入 官方 MCP Registry；VS Code 内的选择器展示的是 GitHub 从该注册表中精选的子集，这是单独的列表。

从源代码安装，使用设置向导，它还会将使用指南写入助手的指令文件：请参阅下一节“设置”。

然后使用远程调试功能启动 Chrome（运行 debug-chrome.bat，或 chrome --remote-debugging-port=9222 --user-data-dir=<a separate profile>），打开你的 应用，并描述这个 Bug。

---

设置

1. node initialize_MCP.js      (or double-click initialize_MCP.bat)
2. Fully quit and reopen your assistant
3. Double-click debug-chrome.bat, open your app
4. Describe the bug

向导会检测已安装的编辑器，为每个编辑器写入合适格式的配置，并创建启动器。它绝不会覆盖无法解析的配置文件——而是打印出供你粘贴的代码片段——每次写入都是原子操作，并创建一份带时间戳的备份，同时移除旧安装留下的重复注册项。这部分有 23 项测试覆盖，因为这里出错会损坏你的机器，而不只是导致功能失效。

---

设置

所有设置均为可选项。让助手运行 devcdp_settings，即可查看生效值及每项设置的来源；也可以运行 devcdp_settings_init，生成一个带注释、可供编辑的文件。

配置文件会合并，后面的配置优先级更高，因此可按项目覆盖适用于整个安装的基线配置：

<install>/devcdp.settings.json   or  <install>/settings.json
<cwd>/.devcdp/settings.json
<cwd>/devcdp.settings.json

然后依次是 DEVCDP_* 环境变量和工具参数。支持注释和末尾逗号。

设置项	默认值
toasts	true	显示实时状态消息
toastMs · toastOpacity · toastMaxVisible	3500 · 0.78 · 3	消息显示时长、可见度和数量
badge · badgeCorner · edgePulse	true · "tc" · true	标签页指示器及其呼吸式边框
badgeCorner 位置	tc · bc · tl · tr · bl · br	浮层停靠的位置。拖动小标签即可将其移动到任意位置；该位置会按来源记住。消息会随它移动，因此 toastCorner 会跟随 badgeCorner
showCursor · highlightInspected	true · true	显示交互发生的位置，以及检查过的内容
ownerTimeoutMs	45000	指示器在未收到其会话消息的情况下保持显示的时长，超时后会自动移除
followNewTabs	true	标记并保留应用自行打开的标签页，避免弹出窗口成为未标记的盲区
chromeProfile	"isolated"	也可以设为 "default"，以复用已登录的 Chrome，或指定一个路径
disableWebSecurity	false	保持关闭：启用后会掩盖你本应调试的 CORS 问题
chromeFlags	[]	额外的 Chrome 标志
evalTimeoutMs · toolTimeoutMs	8000 · 30000	存活检测超时上限
autoResumeDefault · maxPauseMs	true · 30000	自主暂停控制
captureInputValues	false	始终捕获输入的值
docsRoot	自动	读取项目 README 和文档的位置
sharedMemoryDir	null	在团队中共享积累的修复方案
tabGroupMode	"session"	每个会话使用一个标签组；设为 "single" 则所有会话共用一个标签组

值得设置的有两项：docsRoot 可让助手学习你的领域词汇；sharedMemoryDir 则能真正实现“积累团队修复方案”。

---

同时运行多个会话

多个 Agent 可以在同一台机器上安全地调试。每个会话都会在 ~/.devcdp/registry/ 下的注册表中认领一个标签页；认领操作是原子的，因此两个进程不会获得同一个标签页。会话异常退出后会停止发送心跳，其认领记录会被清理，因此不会出现卡住的情况。

• 新会话会获得一个未被认领的标签页；如果全部已被占用，它会自行打开一个——打开的是你想要的页面，而不是空白页，并且会说明原因。
• 重新加载助手时，两个服务进程会短暂重叠，因此会留出一小段宽限时间，让即将退出的进程释放其标签页，新进程则直接重新连接。
• browser: 'new' 会启动一个独立的 Chrome，使用自己的端口和配置文件。
• window: 'new' 会为该会话创建独立的浏览器窗口。
• sessions_list 会显示每个会话占用的标签页。

了解当前使用的标签页

每个被认领的标签页都有一个 1px 边框和一个小型身份标签。边框会告诉你当前由谁操作：

• 蓝色呼吸光效 — DevCDP 正在工作
• 静止的绿色 — 控制权已交还给你
• 静止的红色 — 出现了问题

三种状态、三种颜色，无论运行多少个会话，每种颜色都只代表一种含义。会话通过身份标签上的文字和各自的 Chrome 标签页组来区分，而不是靠色调；否则，当你一眼只需知道标签页是否在等你时，边框就会变成一道谜题。

应用自行打开的标签页 — window.open、target="_blank"、在独立窗口中打开的详情页面 — 也会被标记并接管，标签为“已打开的标签页”。devtools_status 会在 tabsAppOpened 下列出这些标签页，以及切换到对应标签页的调用。

指示器不会比绘制它的会话存续得更久。 正常结束时 — 你关闭助手、断开连接或会话结束 — 边框会立即移除。如果服务被强制终止，来不及清理，覆盖层会发现已收不到该会话的消息，并在 ownerTimeoutMs（45s）内自行移除，同时将标签页移出所在组。无论哪种情况，屏幕上有边框就表示确实有会话存在。对于旧版本遗留的边框，运行 node scripts/sweep.mjs 即可清除所有不属于任何活动会话的边框（先用 --dry 查看）。

状态消息会以半透明、自动淡出的提示框显示。光标活动会有圆环跟随，每次点击都会出现涟漪效果，因此可以追踪 Agent 的操作。调试器暂停时，Chrome 自带的“Paused in debugger”横幅会出现 — 这是浏览器界面，不会给你的页面添加任何内容。

这一切都无法拦截点击：整个图层都设置为 pointer-events: none，交接时的确认按钮除外，该按钮尺寸为 91×24px。我们还编写了测试，通过该图层触发真实鼠标事件。

真正的 Chrome 标签页组由捆绑的扩展程序绘制，它会将每个会话的标签页放入带标题的蓝色组中。Chrome 不允许工具替你安装扩展程序 — 品牌版 Google Chrome 会忽略 --load-extension（其自身日志中显示“not allowed in Google Chrome”），而且不会通过调试端口公开 Extensions.loadUnpacked — 因此请选择以下一种方式：

• 无需手动操作： 将 chromePath 指向 Chromium 或 Chrome for Testing。这些版本允许启用该功能，因此扩展程序会自动加载，分组也会正常工作。如果你的机器上已有这类二进制文件，devtools_status 会告诉你它的位置。
• 品牌版 Chrome： 安装一次 — chrome://extensions → 开发者模式 → 加载已解压的扩展程序 → 选择 extension/。调试配置文件会持久保存，并由 debug-chrome.bat 和 DevCDP 自带的启动器共用，因此安装一次即可。

devtools_status.tabGrouping 会报告标签页是否确实位于某个组中；若不在组中，还会说明是因为未安装扩展程序，还是已安装的扩展程序运行失败 — 并提供错误信息。分组不会影响其他功能：没有扩展程序时，边框、身份标签和 window:'new' 仍可正常工作。

---

与助手协作

你不必等助手来询问。点击、输入、选择 — 这些操作都会被记录，助手会通过 session_get_user_actions 读取：操作了哪个元素、选择了哪个选项，以及你输入的值。

在标签页中按 Ctrl+Shift+D，即可明确将控制权交给你。这也会打开捕获输入值的窗口，因此你可以把“使用这个参考”传达给助手。在该窗口之外，输入值会保持私密；类似密码的字段无论如何都会经过脱敏处理。

当助手需要你亲自完成某项操作时，它会在页面上发出请求，并等待你点击 我已完成 ✓ 按钮。该按钮是唯一明确无误的信号 — Chrome 也会将自动化输入报告为可信输入，因此无法证明某项操作是由人完成的；工具会如实说明这一点，而不会假装能够证明。

---

一次典型的排查

"The save button does nothing. Find the exact line."

1. devtools_connect — 连接、认领标签页并标记它
2. source_search("save") — 按内容查找处理函数，无需路径
3. debugger_set_breakpoint(file, line) — 返回 bound: true
4. 触发点击
5. debugger_get_capture — 一次调用即可获取暂停时的作用域、控制台和网络信息
6. 答案是实际观察到的值，且所在行确实存在

断点会自动恢复执行，因此触发断点的点击仍会完成。

当你知道函数但不知道文件时（使用框架时通常如此）， debugger_set_breakpoint_at_function("app.store.save") 会询问引擎该函数的定义位置， 并在它的第一条语句处暂停。通过源代码文本搜索名称并不可靠：通过 Foo.bar = function 赋值的函数无法通过搜索 "bar: function" 找到，而且该查询 很可能会返回其他类中不相关的方法。

即使面对框架对象图，捕获内容也会保持精简：会打印关键变量，而太大的内容会说明其信息（"constructor", 77747 bytes expanded）， 这样你就能通过 debugger_evaluate_at_frame 只读取所需部分。

---

安全性

启动器使用单独的 Chrome 配置文件，因此不会影响你日常的浏览；同时会启用网络安全——禁用它会掩盖你正在排查的跨源故障。

除非你启用了记录功能或正在协作，否则不会记录输入的值；类似密码的字段始终会被隐藏。

远程调试会让任何能够访问该端口的对象完全控制浏览器配置文件。开发时请使用调试配置文件，不要用于个人账户。

---

目录结构

index.js                 entry point
server.js                shim for older configs pointing here
src/
  core/      config, context, buffers, structured errors, tool registry
  cdp/       connection, target selection, session claim registry, launching
  browser/   the injected in-page agent
  debug/     source maps, scope expansion
  store/     learned-memory store
  tools/     one module per tool group
extension/               companion extension for Chrome tab groups
plugins/devcdp/          Claude Code plugin: manifest, launcher, skill (generated)
server.json              MCP Registry manifest; must agree with package.json
scripts/gen-docs.mjs     regenerates docs/TOOLS.md and the plugin skill
docs/TOOLS.md            full tool reference (generated)
docs/PUBLISHING.md       how each marketplace listing is made and kept current
test/
  validate.mjs           offline checks, no browser needed
  installer.test.mjs     the setup wizard, against real files
  integration.mjs        real Chrome against a fixture app
  fixture-app/           small app with a staged bug and a real source map
BACKLOG.md               every defect found, its fix, and what remains

开发 DevCDP

node scripts/call.mjs <tool> '<json>'   call one tool, see the exact response and its cost
node scripts/mcp-probe.mjs             the same thing over real MCP, raw JSON-RPC

关于断点、日志以及此代码库曾遇到的陷阱： docs/DEBUGGING.md。

测试

npm run validate          offline checks
npm run test:installer    the setup wizard
npm test                  all three suites
npm run docs              regenerate the tool reference

共有 199 项检查。集成测试套件会连接到一个已经完成加载的页面，因为先前版本恰好无法正确处理这种情况。如果 docs/TOOLS.md 已过时，npm run validate 就会失败，确保参考文档不会偏离。

故障排除

工具未显示 — 完全退出助手（通过托盘或菜单退出，而不只是关闭窗口），然后重新打开。如果仍然缺失，请重新运行向导。

“Chrome 无法访问” — 通过 debug-chrome.bat 启动，然后检查 http://localhost:9222/json/version。一个端口只能由一个 Chrome 占用。

断点始终未触发 — 运行 debugger_list_breakpoints 并查看 bound。未绑定的断点会说明原因。

支持项目

DevCDP 免费且采用 MIT 许可证，由一人开发和维护。如果它为你省下了一个下午的调试时间，在 GitHub 上赞助 可以帮助项目继续发展。希望使用托管配置、在工程师之间共享已学习知识或举办入职培训工作坊的团队，可以创建 issue 开始讨论。

隐私与许可证

DevCDP 在本地运行，除了发送给你连接的 MCP 客户端之外，不会向任何地方发送数据：PRIVACY.md。采用 MIT 许可证：LICENSE。

选择器未找到任何内容 — 运行 dom_list_frames；内容可能位于 iframe 中。 使用 frame: 'all' 重试。

刚连接后控制台或网络信息为空 — 这是预期行为。捕获从连接时开始；page_reload 会在 DevCDP 监视下重新加载页面。

页面停止响应 — 主线程被阻塞，通常是应用 JS 中存在循环。page_interrupt 会中止正在运行的脚本；重新加载无法解除阻塞。

标签页不可用 — sessions_list 会显示哪个会话占用了它。