Web-DevHandler

将浏览器 DevTools 数据桥接给 Claude Code，实现 AI 编程调试闭环。

架构

Claude Code
  ↕ stdio (MCP)
mcp-server          ← TypeScript，注册所有 MCP 工具
  ↕ WebSocket :9229
ws-bridge           ← Node.js，消息路由 + 文件写入，常驻进程
  ↕ WebSocket :9229
chrome-extension    ← Manifest V3，采集 DevTools 数据
  ↕ chrome.devtools API
浏览器页面

快速开始

1. 安装

cd Web-DevHander
chmod +x install.sh
./install.sh

脚本会自动完成：安装依赖、编译 MCP Server、创建 logs 目录、清理旧 Native Messaging 配置。

2. 启动 ws-bridge（常驻进程，只需启动一次）

node ws-bridge/index.js

ws-bridge 监听 :9229，MCP Server 和 Chrome 扩展都连接到这个端口。

3. 配置 Claude Code

在 ~/.claude/settings.json 中添加：

{
  "mcpServers": {
    "web-devhandler": {
      "command": "node",
      "args": ["/path/to/Web-DevHander/mcp-server/dist/index.js"]
    }
  }
}

4. 加载 Chrome 扩展

1. 打开 chrome://extensions
2. 开启右上角"开发者模式"
3. 点击"加载已解压的扩展程序"，选择 chrome-extension/ 目录

5. 使用

1. 打开目标网页，按 F12 打开 DevTools
2. 切换到 Web-DevHandler 面板
3. Claude Code 即可调用所有工具

可用工具

控制台

工具	说明
get_console_logs	获取控制台日志，支持级别过滤（all/error/warn/log/info/debug）、条数限制、增量拉取（since 时间戳）
save_console_logs	全量保存控制台日志到 logs/tool-results/ 目录，返回文件路径
evaluate_javascript	在页面上下文中执行 JS 代码，相当于 DevTools Console

网络

工具	说明
get_network_requests	获取 XHR/Fetch 请求记录，支持 URL/状态码/方法过滤、分页、请求响应体、请求响应头
get_sse_events	获取 SSE（Server-Sent Events）流式请求的事件记录，支持 URL/事件类型/streamId 过滤
clear_sse_events	清空 SSE 事件缓冲区
get_iframe_info	获取页面所有 iframe 信息及 console hook 注入状态

DOM / 样式

工具	说明
get_dom_snapshot	获取指定 CSS 选择器对应元素的 outerHTML
get_computed_style	获取元素最终计算 CSS 样式，可指定属性列表

导航

工具	说明
navigate_to	跳转到指定 URL
reload_page	刷新页面，支持强制刷新（忽略缓存）
take_screenshot	截取页面截图，返回 base64 PNG
get_connection_status	查询连接状态

文件 I/O

工具	说明
create_log_file	在 logs/ 目录创建文件
write_to_file	写入数据到文件，支持 json / text / append 三种模式
read_log_file	读取文件内容，支持 tail N 行
clear_log_file	清空文件内容（保留文件）
delete_log_file	删除文件
list_log_files	列出 logs/ 目录下所有文件
parse_console_logs_to_md	将 save_console_logs 保存的 JSON 解析为 Markdown，自动剥除 ANSI 转义码、还原嵌套 JSON

项目结构

Web-DevHander/
├── mcp-server/              # MCP Server（TypeScript）
│   ├── src/
│   │   ├── index.ts         # 入口，注册所有工具
│   │   ├── connection/
│   │   │   ├── adapter-interface.ts  # 统一 Adapter 接口
│   │   │   └── adapter.ts            # WebSocket 连接实现（via ws-bridge）
│   │   └── tools/
│   │       ├── types.ts      # 公共类型定义与错误处理
│   │       ├── console.ts    # 控制台工具
│   │       ├── network.ts    # 网络工具
│   │       ├── elements.ts   # DOM / 样式工具
│   │       ├── navigation.ts # 导航 / 截图工具
│   │       └── file-io.ts    # 文件读写工具
│   ├── dist/                # 编译产物（不提交 git）
│   ├── package.json
│   └── tsconfig.json
│
├── ws-bridge/               # WebSocket 消息路由器（Node.js）
│   └── index.js             # 单文件，监听 :9229
│
├── chrome-extension/        # Chrome 扩展（Manifest V3）
│   ├── manifest.json
│   ├── devtools.html        # DevTools 入口页
│   ├── devtools.js          # 数据采集 + 请求处理
│   ├── panel.html           # DevTools 面板 UI
│   ├── panel.js             # 面板交互逻辑
│   ├── background.js        # Service Worker
│   ├── utils.js             # 公共工具函数
│   ├── popup.html
│   └── popup.js
│
├── scripts/
│   └── console-logs-to-md.js
│
├── logs/                    # 运行时日志（不提交 git）
│   ├── ws-bridge.log
│   └── tool-results/        # save_console_logs 写入目录
│
├── install.sh
└── README.md

修改 mcp-server 后重新编译

cd mcp-server
npm run build

修改 ws-bridge/index.js 或 chrome-extension/ 下的文件无需编译，重启 ws-bridge / 重新加载扩展即可生效。