「vConsole MCP🛠️」我让 AI 直接看见任何 H5 的日志和请求帮你 debug

嗨！这里是 JustHappy 🚀🚀 ,如果你是一个跨端 H5 开发者，就是在不同的端类型上开发 web 前端，跑在 webview 容器中的，那么在真机调试的时候一定很头疼、安卓 app、ios app、鸿蒙 app 、小程序（各家小程序在不同端上还有区别）...

跨端生态混乱在国内开发圈子个由来已久的"顽疾"，所以很早腾讯官方就开源了 vConsole，这也是我日常开发 debug 过程中必不可少的工具。但是这个工具在 AI 时代的使用方式有些原始了，如果在某一个端上发现了一个 bug，如果你想让 AI 分析，整个调试过程经常变成这样：

手机打开 vConsole
找到报错日志
截图或者复制到电脑
再给 AI 描述一遍刚才发生了什么
AI 分析后，我再回手机继续验证

AI 的分析能力已经很强了，但它没有连接到手机页面的"眼睛"。

所以我就在想：

能不能让 Codex 或 Claude Code 直接读取手机 vConsole 里的日志和网络请求？让它自动的去处理这些事情

我想要的东西其实很简单

不用 USB 调试。
不用每次截图。
不用手动复制错误信息。
也不用搭建一套复杂的云端调试平台。

于是就有了这个项目：

👉 vConsole-MCP

不过需要先说明一下：

vConsole 官方目前不提供 MCP 连接能力，请使用 Simonmie/vConsole 的 dev 分支进行尝试。

我在这个分支里为 vConsole 增加了一个 MCP 面板：

手机填写电脑的 IP、端口和配对 Token，点击 Connect，Agent 就可以开始读取页面信息了。

它现在能做什么？

目前 vConsole-MCP 一共向 Agent 提供了四个工具。

1. 发现手机页面

list_pages

列出所有连接到电脑的 H5 页面，包括：

页面 ID
页面 URL
页面标题
User-Agent
连接时间

如果同时打开了多个手机页面，Agent 可以先通过它找到需要调试的页面。

2. 读取 Console 日志

get_console_logs

可以读取 vConsole 捕获的：

Log
Info
Debug
Warn
Error

同时支持限制数量以及按日志级别筛选。

例如可以直接对 Codex 说：

go 复制代码

读取这个手机页面最近 20 条 warn 和 error 日志。

3. 读取网络请求

get_network_requests

可以读取 vConsole 捕获的 Fetch/XHR 请求，并支持：

只查看失败请求
按 URL 关键字筛选
查看状态码和请求耗时
查看请求与响应 Headers
按需读取请求体和响应体

例如：

bash 复制代码

找出最近失败的 /api 请求，并分析可能的失败原因。

需要注意，它读取的是 vConsole 已经捕获的 Fetch/XHR 记录，不是 Charles 或 mitmproxy 那种系统级抓包。

它不会捕获其他 App 的流量，也不是原始 TCP/TLS 数据包分析工具。

4. 执行 JavaScript

execute_javascript

在手机用户明确授权后，Agent 可以在目标页面中执行 JavaScript。

例如：

javascript 复制代码

读取当前页面的 document.title。

或者：

scss 复制代码

在页面中执行 alert('Hello JustHappy')。

因为 JavaScript 可以修改 DOM、Storage 和页面业务状态，所以这个能力默认是关闭的。

只读取日志和网络请求时，不需要打开 JavaScript 权限。

如何使用？也很简单

整个过程可以分成三步。

第一步：使用带 MCP 面板的 vConsole

先拉取我修改后的 vConsole：

bash 复制代码

git clone -b dev https://github.com/Simonmie/vConsole.git
cd vConsole
npm install
npm run build

构建完成后，将 dist/vconsole.min.js 引入需要调试的 H5 页面：

xml 复制代码

<script src="/path/to/vconsole.min.js"></script>

<script>
  const vConsole = new VConsole();
</script>

这时打开 vConsole，就可以看到新增的 MCP 面板。

第二步：构建 vConsole-MCP

目前项目还没有作为 npm 包发布，需要从源码安装：

bash 复制代码

git clone https://github.com/Simonmie/vConsole-MCP.git
cd vConsole-MCP
pnpm install
pnpm build

项目需要 Node.js 20 或更高版本。

然后把它添加到 Codex：

css 复制代码

codex mcp add vconsole \
  --env VCONSOLE_MCP_TOKEN=replace-with-a-random-token \
  -- node /absolute/path/to/vConsole-MCP/dist/index.js \
  --host 0.0.0.0 --port 8765

如果使用 Claude Code：

css 复制代码

claude mcp add \
  --transport stdio \
  --env VCONSOLE_MCP_TOKEN=replace-with-a-random-token \
  vconsole \
  -- node /absolute/path/to/vConsole-MCP/dist/index.js \
  --host 0.0.0.0 --port 8765

其中：

0.0.0.0 表示允许同一局域网内的手机连接
8765 是 WebSocket 服务端口
VCONSOLE_MCP_TOKEN 是电脑与手机之间的配对凭据

建议每次调试都使用随机 Token，不要把服务端口直接暴露到公网。

第三步：让手机连接电脑

确保手机和电脑处于同一个局域网，然后打开手机页面中的 vConsole。

进入 MCP 面板并填写：

Host：电脑的局域网 IP
Port：默认是 8765
Pairing Token：与电脑端设置的 Token 完全一致

这里的 Host 应该填写电脑 IP。

不是手机 IP，也不是 localhost。

点击 Connect，当 Status 变成 open，连接就建立成功了。

接下来直接告诉 Agent：

复制代码

列出当前连接的手机页面。

然后继续：

复制代码

读取这个页面最近的错误日志。

或者：

复制代码

检查最近失败的网络请求，并包含响应正文。

手机连接一次，Agent 就能直接获得页面现场信息。

不用截图。

不用复制日志。

也不用再向 AI 复述页面刚才发生了什么。

它到底是怎么连接起来的？

整个结构其实并不复杂：

flowchart LR Agent["Codex / Claude Code"] <-->|"MCP stdio"| MCP["vconsole-mcp"] MCP <-->|"WebSocket :8765"| Mobile["Mobile H5 + vConsole"] Mobile --> Data["Console / Network stores"]

简单理解：

MCP 是 Agent 调用工具的接口
WebSocket 是电脑和手机之间的传话筒
vConsole 是手机页面里的数据来源

Agent 调用 get_console_logs 时，vConsole-MCP 会通过 WebSocket 向指定页面发送读取请求。

手机页面收到请求后，从 vConsole 已有的数据中取出日志，再把结果返回给 Agent。

网络请求也是同样的过程。

Console 和 Network 数据依然保存在手机页面中，Agent 需要时才读取。

不需要额外数据库，也不会持续把所有日志同步到云端。

为什么读取和执行要分开？

既然 Agent 已经可以连接页面，为什么不直接允许它执行 JavaScript？

因为这两件事的风险完全不同。

读取日志和网络记录基本是观察行为，而执行 JavaScript 可以：

修改页面 DOM
修改 LocalStorage 和 SessionStorage
改变页面业务状态
发起新的网络请求
读取当前页面上下文中的数据

所以我把它们拆成了两层权限。

默认情况下，Agent 只能读取页面信息。

只有手机用户主动勾选 Allow JavaScript Execution 后，Agent 才能执行脚本。

页面刷新后，这项授权也会重新恢复为拒绝状态。

这样即使 MCP 已经连上了手机页面，真正具有修改能力的操作仍然掌握在手机用户手里。

一个真实的调试过程

假设手机上的登录接口突然报错。

以前可能需要：

打开 vConsole
找到报错日志
查看 Network
截图发给 AI
再补充请求地址、状态码和响应内容

使用 vConsole-MCP 后，可以直接告诉 Agent：

复制代码

帮我检查当前手机页面的错误日志和失败请求。

Agent 会：

调用 list_pages 找到连接的页面
调用 get_console_logs 读取错误日志
调用 get_network_requests 筛选失败请求
根据 URL、状态码、Headers 和响应内容分析问题

AI 拿到的是页面现场数据，而不是经过人工转述后的二手信息。

如果还需要进一步验证，再由手机用户打开 JavaScript 权限，让 Agent 执行一段最小的检查脚本。

这个体验会自然很多。

当前版本还有哪些限制？

这个项目目前还是一个很早期的版本，哈哈，如果大家感兴趣的话欢迎提交PR

当前主要面向可信局域网内的开发调试，并且还有一些边界：

官方 vConsole 暂时没有 MCP 面板，需要使用修改后的 dev 分支
网络能力仅覆盖 vConsole 捕获的 Fetch/XHR 请求
暂不支持系统级网络抓包
暂不读取原始 WebSocket 帧
HTTPS 页面通常不能直接连接明文 ws://
如果页面使用 HTTPS，需要额外配置可信的 wss:// 服务
JavaScript 执行能力应只在可信开发页面中开启
Codex 和 Claude Code 同时运行时，不能监听同一个端口

Pairing Token 可以防止局域网内的页面随意接入，但它并不等于完整的加密和身份认证方案。

所以现在这个版本最适合的定位是：

一个本地、轻量、由手机用户控制权限的 H5 调试桥梁。

最后

如果你也经常调试手机 H5，欢迎拉下来玩一下。

遇到问题可以提 Issue，也欢迎 PR。（当然也可以直接来骚扰我的 juejin 评论区）

当然，如果这个项目刚好解决了你的问题，也可以顺手给个 Star 😜🚀