h5-devtools-mcp

h5-devtools-mcp

English | 简体中文

一个 MCP 服务，可让编码 Agent（Claude Code、Codex、Cursor……）调试在真实设备 Android WebView 中运行的 H5 页面——读取控制台输出和未捕获的异常，并在页面中运行 JavaScript，无需打开 chrome://inspect。

状态：v0.1，早期版本。仅支持 Android。

工作原理

Coding agent ──MCP (stdio)──▶ h5-devtools-mcp ──adb forward──▶ webview_devtools_remote_<pid> ──CDP──▶ WebView page

每个可调试的 WebView 都会在抽象 Unix 套接字上公开一个 Chrome DevTools Protocol 端点。该服务通过 adb 发现这些套接字（方式与 chrome://inspect 相同），将它们转发到本地端口，并通过 CDP 连接。

要求

• Node.js 18+
• PATH 中有 adb（或设置 ADB_PATH）
• 已启用 USB 调试的 Android 设备
• 应用必须启用 WebView 调试（调试构建通常已启用）：

WebView.setWebContentsDebuggingEnabled(true);

设置

# Claude Code
claude mcp add h5-devtools -- npx -y h5-devtools-mcp

其他 MCP 客户端（Cursor、Codex……）使用相同的命令：npx -y h5-devtools-mcp。

从源码构建

git clone https://github.com/xianguoGou/h5-devtools-mcp.git
cd h5-devtools-mcp
npm install && npm run build
claude mcp add h5-devtools -- node /absolute/path/to/h5-devtools-mcp/dist/index.js

工具

工具	功能
list_targets	列出可调试页面：应用包名、标题、URL、可见性
attach	连接到页面并开始缓冲控制台输出
get_console	按级别、关键词和 exclude_keywords 过滤缓冲条目，通过 since_seq 增量读取
evaluate_js	在页面中运行 JavaScript 表达式并返回结果（会等待 Promise 完成）
detach	断开与页面的连接

输出专为节省令牌而设计：条目紧凑且每条占一行，长消息会被截断，并提供 since_seq，让 Agent 只读取新增内容，而不必在每轮都重新读取整个缓冲区。

示例

> list_targets
- id: R5CT1234/webview_devtools_remote_8812/3A1F…
  app: com.example.app (pid 8812) on SM-S9180
  title: "Order"
  url: https://m.example.com/order

> get_console { "levels": ["error"] }
#41 10:32:01.123 [error exception] TypeError: Cannot read properties of undefined (reading 'price')
    at https://m.example.com/assets/index-8f2a.js:1:48213
next since_seq: 57

故障排除

• “no debuggable WebView found”——应用未启用 WebView 调试，或尚无运行中的 WebView。请先打开 H5 页面。
• “debugger in use”——每个页面只能连接一个调试器。请关闭 chrome://inspect DevTools 窗口。
• “unauthorized”——请在设备上接受 USB 调试提示。

已知限制

• **调试器占用检测仅尽力而为。**它依赖 /json/list 不返回 webSocketDebuggerUrl。较新的 Chromium 允许每个页面连接多个 CDP 客户端，因此即使 DevTools 窗口已打开，连接也可能成功；较旧的 WebView 仍可能拒绝连接。
• **list_targets 遇到无响应的应用时，每个应用可能耗时约 3 秒。**套接字会逐个查询，超时时间为 3 秒；而 Android 会冻结后台应用，导致其 WebView 套接字停止响应。attach 只会重新检查目标自己的套接字，因此速度较快。
• evaluate_js 以页面的完整权限运行——它可以读取 Cookie、存储内容和令牌，也可以更改页面状态。请确保它受 Agent 的工具权限提示约束。
• **端到端测试脚本要求端口 9333 处于空闲状态。**如果上次运行残留了无头 Chromium，脚本会连接到该进程；请先将其关闭。

开发

端到端测试使用模拟的 adb 和无头 Chromium 代替手机：

npm run build
CHROME=/path/to/chrome npm run test:e2e

路线图

• 发现设备和 WebView 页面
• 控制台消息、未捕获的异常、浏览器日志条目
• 网络请求和响应
• JSBridge 调用日志（可配置桥接形式）
• evaluate_js
• screenshot
• JSBridge 模拟
• iOS（通过 WebKit Inspector Protocol 调试 WKWebView）

许可证

MIT