web-debug-mcp

web-debug-mcp 是一个面向 Codex 及其他 MCP 客户端的本地、代理原生 Web 调试服务器。它暴露了一个小型工具面，用于协调浏览器会话、JavaScript 调试器、有界运行时证据和可复现的流程验证。

当前增量支持框架无关的浏览器目标、Chromium/CDP、带 WebDriver BiDi 证据的 Safari WebDriver、自动注入的 React 开发桥、Vite 模块图/HMR 端点，以及 Next.js 开发服务器元数据，包括有界的服务器日志、路由编译、Server Action 查找和观察到的请求执行证据。浏览器特定限制仍然明确。这使框架特定上下文保持在同一个 MCP 门面之后，而不是添加单独的工具目录。

包含内容

• 无需启动进程即可进行项目能力检测。

• 通过显式 CDP 端点的本地 Chromium 附加模式。

• 仅当 allowRemote: true 时才支持显式远程 CDP 附加；目标被标记为非隔离且永远不会自动发现。

• 通过显式可执行路径的本地 Chromium 启动模式。

• 通过本地 safaridriver 或显式 WebDriver 端点的 Safari WebDriver 模式，当安装的 Safari 暴露 BiDi 控制台事件和网络事件时，支持这些事件。

• 同源浏览器操作：导航、点击、填写、等待和重新加载。

• JavaScript 断点、暂停控制、有界调用帧，以及默认只读求值。

• 控制台、网络元数据、DOM 摘要、截图和调试器证据，打包在一个经过编辑的捆绑包中。

• React 组件树、钩子值、源位置、渲染计数、有界提交摘要、分析器持续时间、扁平火焰图视图，以及当开发构建暴露 React 提交时推断的渲染原因。

• 通过 webDebugVitePlugin() 开发插件的 Vite 模块/导入者图、HMR 状态、转换代码差异和源映射摘要。

• 当日志保持在检测到的项目根目录内时，有界、经过编辑的 Next.js 开发日志尾部。

• 通过 web_next_inspect 进行显式 Next.js 路由编译和 Server Action 查找，以及当浏览器发送 Next-Action 请求时，提供规范化服务器请求跟踪和请求链接的执行证据。

• 捕获中的有界重放时间线和通过 web_replay_seek 的帧查找；restore: true 仅重放安全保留的操作，并拒绝经过消毒的表单输入。

• 具有简单修复后检查的可复现操作场景。

• 确定性香草夹具和项目原生工具检查。

• 实时 React/Vite 夹具、自动 React 桥和模块图/HMR 冒烟测试。

• 实时 Next.js App Router 夹具和 /_next/mcp 运行时冒烟测试。

Related MCP server: Kaboom Browser AI Devtools MCP

要求

• Node.js 20 或更高版本。Safari BiDi 需要 Node 20.10+ 并带有 --experimental-websocket 或 Node 21+；较旧的运行时保留 Safari WebDriver 操作和文档化的网络回退，但报告 BiDi 控制台限制。

• 运行实时会话时需要基于 Chromium 的浏览器。

• 要么显式设置 WEB_DEBUG_CHROME_EXECUTABLE_PATH，要么向 web_session_start 提供显式的 cdpEndpoint。

开发命令

npm install --no-audit --no-fund
npm test
npm run typecheck
npm run build
npm run harness:check
npm run smoke:live
npm run smoke:react-vite
npm run smoke:next
npm run smoke:safari

使用 npm run serve:fixture 运行夹具。服务器绑定到 127.0.0.1，默认端口为 4173；设置 WEB_DEBUG_FIXTURE_PORT 以使用其他端口。

当默认的 macOS Chrome 路径不可用时，在设置 WEB_DEBUG_CHROME_EXECUTABLE_PATH 后运行 npm run smoke:live。它会启动香草夹具，在 app.js 中设置断点，点击按钮，捕获暂停安全的证据路径，并清理拥有的浏览器和夹具进程。

运行 npm run smoke:react-vite 以启动 Vite 夹具，验证 React 组件/状态证据，在 fixtures/react-vite/src/App.jsx 处暂停，并重放已提交的支付流程。

对于 Vite 应用程序，将仅限开发的插件添加到 vite.config.ts：

import { webDebugVitePlugin } from "web-debug-mcp/vite";

export default {
  plugins: [webDebugVitePlugin()],
};

该插件提供调试会话期间使用的本地只读模块图端点。它不应在生产服务器中启用。

运行 npm run smoke:next 以启动 Next.js App Router 夹具，查询其内置的 /_next/mcp 端点，验证路由/项目/编译元数据和有界服务器日志尾部，并执行客户端路由处理程序流程。

运行 npm run smoke:safari 以通过 Safari WebDriver 执行香草夹具。首先启用 Safari 设置 → 开发 → 允许远程自动化；Safari 会可见地运行，捕获 BiDi 控制台证据，并报告网络证据是来自 BiDi 还是有界 Performance Resource Timing 回退。Safari 的 JavaScript 调试器通过此适配器仍然不可用。

Safari 27 和 Safari Technology Preview 247 包含 Apple 官方的 Safari MCP 服务器。当需要浏览器原生 DOM、网络、控制台和截图工具时，请使用该官方服务器；此仓库不会添加重复的公共 Safari MCP 目录。WebDriver 适配器仍然作为套件中针对旧版 Safari 以及共享会话/证据编排的单一门面兼容路径而有用。

在开发期间使用 npm run dev 运行 MCP 服务器，或在 npm run build 后使用 node dist/index.js。MCP 协议消息使用 stdout；诊断信息必须保留在 stderr 上。

MCP 工作流

1. 使用项目根目录调用 web_project_detect。

2. 使用回环 URL 和显式浏览器连接或可执行文件调用 web_session_start。

3. 使用 web_browser_action 和 web_breakpoint_set 重现问题。

4. 调用 web_issue_capture 获取一个有界证据捆绑包。

5. 对于 Next.js，调用 web_next_inspect 编译路由或解析 Server Action ID。

6. 使用 web_repro_record 存储流程，稍后使用 web_fix_verify 运行。

7. 使用 web_replay_seek 检查一个保留的捕获帧；仅当帧包含安全、非敏感操作时传递 restore: true。

8. 当会话不再需要时调用 web_session_close。

服务器在正常会话期间不会写入项目。截图存储在临时按会话工件目录中，并作为路径返回。

安全默认值

• 除非显式启用 allowRemote，否则浏览器 URL 仅限回环。

• 浏览器导航保持在会话源上。

• 外部 CDP 附加被标记为非隔离。

• 控制台、网络、调试器局部变量和求值值均经过编辑和有界。

• 核心适配器不收集原始响应体、cookie、授权值和浏览器存储。

• 除非显式设置 allowSideEffects 为 true，否则求值拒绝副作用。

当前边界

此仓库是本地开发工具，而非托管服务。它没有生产部署、CI 工作流、未经身份验证/自动发现的远程浏览器控制，或完整的 React DevTools 分析器/火焰图对等性。React 持续时间和渲染原因细节是有界的，并从 DevTools 钩子推断；Vite 来源和源映射是摘要，而非完整的源映射调试器；Next.js 执行证据仅限于请求链接的 Server Action 元数据、请求洞察和有界日志；Safari 调试器对等性不可用，Safari 26 可能需要 Performance Resource Timing 网络回退；重放恢复仅限于安全保留的操作，并非应用程序状态时间旅行。显式远程 CDP 附加、Safari WebDriver 操作/DOM/截图、显式能力警告和有界重放恢复可用。对于这些相应声明，仍需要经批准的外部远程主机和调用方提供的工具认证证据。