更新记录

1.0.0（2026-11-04） 下载此版本

首个版本：

• 54 个 MCP 工具：编辑器、文件、项目、HBuilderX、浏览器、Electron、开发命令、后台服务、HTTP、代码智能
• 状态面板、复制客户端配置、重启桥接
• 支持 Claude Code、Claude Desktop、Cursor、OpenCode 等 MCP 客户端
• 浏览器自动化使用系统 Chrome / Edge，支持截图、控制台日志与 CDP 附加
• 通过 HBuilderX CLI 发行 uni-app / uni-app x 项目

平台兼容性

# Viry MCP

让 HBuilderX 直接接入 AI 编程客户端。

安装后，Claude Code、Cursor、Claude Desktop、OpenCode 等支持 MCP 的客户端就可以读取你正在编辑的文件、搜索项目、修改代码、执行 HBuilderX 命令，甚至触发 uni-app 发行构建。

当前版本：1.0.0 · 插件 ID：viry

功能一览

• 读取当前文件、选中文本和光标位置
• 在编辑器中插入、替换、批量修改代码
• 搜索项目内容、读写文件、列出目录
• 打开文件并跳转到指定行、保存、格式化
• 执行 HBuilderX 内置命令、触发 uni-app 发行
• 通过 cli.exe 导入 / 关闭项目
• 查找符号定义、引用，查看近似悬停信息和本地诊断
• 浏览器自动化：启动 Chrome/Edge、截图、点击、输入、读取控制台和网络请求
• Electron / Chromium 客户端：启动 Electron 或通过 CDP 附加到 Chrome、Edge、CEF、WebView2
• 测试与调试：运行 lint、typecheck、test、build（只允许测试/检查类脚本）
• 后台服务：启动/停止 npm run dev、npm run start，等待端口就绪并读取日志
• HTTP 接口测试：直接发 GET/POST/PUT 等请求，返回状态码、响应头和 JSON
• 内置 MCP 状态面板：查看连接、工具、日志，一键复制客户端配置

环境要求

Node.js 只用于运行 MCP 客户端进程；浏览器自动化引擎 playwright-core 已随插件打包，不需要额外安装。

浏览器与 Electron 自动化需要 HBuilderX 内置 Node 18 及以上；旧版本仍可使用文件、编辑器和命令类工具。

安装

方式一：插件市场安装（推荐）

1. 打开 HBuilderX：工具 → 插件安装
2. 搜索 Viry MCP，点击安装
3. 重启 HBuilderX

方式二：离线安装

把插件文件夹复制到以下目录，然后重启 HBuilderX：

<HBuilderX安装目录>/plugins/viry-mcp

通过插件市场安装的插件位于 %APPDATA%\HBuilder X\extensions\viry-mcp（macOS 为 ~/Library/Application Support/HBuilder X/extensions/viry-mcp），该目录由 HBuilderX 管理；手动离线安装建议使用上面的 plugins 目录。

确认安装成功

安装并重启后：

1. 状态栏右下角出现 MCP :27810
2. 菜单 工具 中出现 Viry MCP: 打开状态面板 等选项
3. 打开状态面板，能看到「运行中」和 54 个工具

如果状态栏没有出现，请检查 设置 → 插件配置 → Viry MCP 中的 viry.enabled 是否为开启状态。

连接 AI 客户端

MCP 客户端会启动插件自带的 mcp/stdio.js，由它自动读取端点文件并连接 HBuilderX，你不需要手动填写端口或 token。

最省事的方式：复制配置

在 HBuilderX 中任选一种：

• 状态面板 → 复制客户端配置
• 菜单 工具 → Viry MCP: 复制客户端配置
• 状态栏 MCP :端口 → 面板 → 复制

复制到的内容已经包含正确的绝对路径，直接粘到客户端配置里即可。

Claude Code

claude mcp add viry -- node "C:/Users/<你的用户名>/AppData/Roaming/HBuilder X/extensions/viry/mcp/stdio.js"

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "viry": {
      "command": "node",
      "args": ["C:/Users/<你的用户名>/AppData/Roaming/HBuilder X/extensions/viry/mcp/stdio.js"]
    }
  }
}

Cursor

编辑全局 ~/.cursor/mcp.json，或项目内的 .cursor/mcp.json：

{
  "mcpServers": {
    "viry": {
      "command": "node",
      "args": ["C:/Users/<你的用户名>/AppData/Roaming/HBuilder X/extensions/viry/mcp/stdio.js"]
    }
  }
}

OpenCode

编辑 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "viry": {
      "type": "local",
      "command": ["node", "C:/Users/<你的用户名>/AppData/Roaming/HBuilder X/extensions/viry/mcp/stdio.js"],
      "enabled": true
    }
  }
}

手动安装时的路径

如果你是把插件放在 HBuilderX 安装目录下，路径改为：

<HBuilderX安装目录>/plugins/viry-mcp/mcp/stdio.js

Windows 路径建议使用 /，或在 JSON 中使用 \\。

验证是否连接成功

1. 保持 HBuilderX 打开
2. 重启 AI 客户端（或重新加载 MCP 配置）
3. 打开状态面板，连接数 应该变成 1 或更多
4. 在 AI 客户端中问一句「调用 hbx_status 看看 HBuilderX 状态」，能返回版本和端口即成功

状态面板

状态面板以非模态弹窗的形式打开，不会占用侧边视图，也不会阻塞编辑。打开方式：

• 菜单 工具 → Viry MCP: 打开状态面板
• 点击状态栏 MCP :端口

再次点击会把已经打开的面板带到前台；关闭后再次打开会重新创建一个。

面板内容：

右上角 ◐ 可以切换明暗主题，默认会跟随 HBuilderX 的配色。

使用方式

安装并连接后，不需要记任何工具名，直接用自然语言告诉 AI 你想做什么即可。下面是常见场景。

读代码

读取我当前打开的文件，解释一下这个页面的数据流。

我选中了一段代码，帮我解释它做了什么。

改代码

把当前文件里所有 console.log 删掉。

在第 20 行下面加一个 onLoad 生命周期。

把当前选区替换成使用 async/await 的写法。

搜项目

在项目里搜索所有调用 uni.request 的地方，列出来。

找一下 useUserStore 是在哪里定义的，有哪些地方引用。

文件与项目

列出 pages 目录下的所有页面。

在 utils 目录下新建一个 format.js，写一个日期格式化函数。

帮我打开 pages/index/index.vue 并跳到第 50 行。

保存与格式化

保存当前文件并格式化。

AI 通过编辑器工具修改内容后默认会立即保存到磁盘（配置项 viry.autoSave，默认开启）。部分 HBuilderX 版本的单文件保存命令无效，插件会自动退化为“全部保存”，因此其它未保存文件也可能一起保存；关闭该配置后可用 hbx_save_file 手动保存。

HBuilderX 与发行

执行 HBuilderX 的关闭所有编辑器命令。

把 ViryUniApp 发行到 H5，等构建结束告诉我输出目录。

用 cli 把 E:/projects/demo 导入 HBuilderX。

弹出提示告诉我构建完成了。

网页与 Electron 测试

启动 Chrome 打开 http://localhost:5173，截一张图。

点击「登录」按钮，在用户名输入框填 admin，密码填 123456，再点击提交。

看一下浏览器控制台有没有报错，把错误列出来。

启动 ViryApp，截一张登录页，然后点击「设置」看看。

启动 ViryServer 后端，等 3001 端口就绪，然后调用登录接口测试 sun/123456。

看一下 ViryServer 最近的日志，有没有报错。

跑一下 npm run build，如果失败把错误贴出来。

跑一下 lint 和 typecheck，只看 error。

说明

• 编辑器修改类工具作用于 当前激活文件；要改其它文件，请先让 AI 打开它。
• 直接调用工具时，line / character 默认是 0 基（第一行是 0），需要 1 基时传 oneBased: true。
• 发行通过 HBuilderX CLI 执行并等待构建结束，返回输出目录；首次发行需要下载编译器时耗时可达数分钟，可用 timeout 调大。
• 浏览器自动化默认使用系统 Chrome，失败会自动尝试 Edge；默认无头模式，传 headless: false 可以看到真实窗口。
• Electron 自动化需要项目先构建（例如 npm run build），或对已经带 --remote-debugging-port 启动的客户端使用 hbx_web_attach。
• 测试/调试命令只允许 lint、test、typecheck、check、build 类脚本，以及 eslint / vue-tsc / tsc / vitest / jest。

工具清单

共 54 个工具，AI 会根据你的描述自动选择。你也可以在状态面板中查看完整列表。

状态

编辑器

文件与项目

HBuilderX 专有

浏览器与 Electron 自动化

测试与调试

服务与接口

命令执行只开放测试/检查类脚本和工具，不允许执行任意 shell 命令；后台服务只允许 dev / start 脚本。

代码智能

HBuilderX 目前没有公开语言服务的 hover / definition / references 查询接口，因此这四个工具是基于项目文本索引的近似实现，适合辅助定位，不能完全替代 IDE 的智能跳转。

配置项

打开 设置 → 插件配置 → Viry MCP：

修改端口等配置后，建议执行一次 工具 → Viry MCP: 重启桥接服务。

环境变量

一般不需要设置，高级场景可用：

常见问题

状态栏没有显示 MCP :端口

1. 确认插件已安装并启用：工具 → 插件安装
2. 检查 设置 → 插件 → Viry MCP → viry.enabled 是否开启
3. 菜单 工具 → Viry MCP: 查看状态，看是否提示启动失败
4. 端口被占用时会自动换端口，状态栏显示的是实际端口

状态面板打不开

状态面板是弹窗，依赖 HBuilderX 3.0+ 的 createWebViewDialog：

1. 确认 HBuilderX 版本 ≥ 3.0
2. 如果提示「内置浏览器不存在」或弹出下载提示，请按提示安装内置浏览器插件
3. 尝试 工具 → Viry MCP: 重启桥接服务，再重新打开面板
4. 仍然不行时重启 HBuilderX，并查看 %APPDATA%\HBuilder X\.log 中的报错

AI 客户端提示「未找到 HBuilderX 桥接端点信息」

说明客户端进程找不到端点文件：

• HBuilderX 是否正在运行？
• Viry MCP 插件是否启用？
• ~/.viry-mcp/endpoint.json 是否存在？
• 如果刚刚重启过 HBuilderX，重启一下 AI 客户端

AI 客户端提示「无法连接 127.0.0.1:xxxx」

通常是端点文件指向了已经退出的实例：

1. 在 HBuilderX 执行 Viry MCP: 重启桥接服务
2. 重启 AI 客户端
3. 仍然不行时，删除 ~/.viry-mcp/endpoint.json 后重启 HBuilderX

同时开了多个 HBuilderX 窗口

每个窗口都会启动一个桥接服务，最后启动的实例会覆盖端点文件，客户端默认连接最后一个。建议只保留一个窗口；确需多窗口时，请分别在各个窗口执行 Viry MCP: 查看状态 确认端口，并让客户端连接你实际需要的那一个。

写入文件后编辑器内容没变

hbx_write_file 在文件已打开且没有未保存修改时，会自动同步编辑器缓冲区；如果编辑器里有未保存修改，则不会覆盖并给出提示。遇到编辑器仍显示旧内容，可调用 hbx_revert_file 用磁盘内容强制回填。要让 AI 改当前打开的文件，优先使用编辑器类工具（读取当前文件、替换选区等）。

发行构建没有输出

hbx_publish 通过 HBuilderX CLI 执行并等待构建结束，会返回退出码、输出末尾和输出目录（如 unpackage/dist/build/web）。首次发行需要下载编译器时可能耗时数分钟，可调大 timeout。

通过 CLI 操作项目时中文乱码

插件已对 cli.exe 的输出做 GBK 自动识别并去掉颜色控制符；如果仍有乱码，请反馈具体的 CLI 命令。

「运行到浏览器 / 手机」没有对应工具

HBuilderX 没有稳定公开的运行命令 ID。可以尝试让 AI 执行内置命令 workbench.toolbar.run 打开运行菜单，或直接在 HBuilderX 中操作。

浏览器启动失败

• 确认系统安装了 Chrome 或 Edge
• 可以传 browser: "msedge" 或 executablePath 指定浏览器
• 传 headless: false 可以看到真实窗口，方便排查
• 仍失败时检查 HBuilderX 内置 Node 是否为 18 及以上

截图过大或返回失败

截图默认 JPEG quality 80。整页截图或长页面建议：

{ "type": "jpeg", "quality": 60, "fullPage": false }

Electron 启动失败

• 先执行 npm run build，确保 package.json 的 main 指向已构建入口
• 确认 node_modules/electron/dist 存在
• 也可以手动启动 Electron 并加 --remote-debugging-port=9222，再用 hbx_web_attach 附加

命令被拒绝

测试/调试工具只允许检查类脚本和工具，npm run dev、npm run format 等会被拒绝，这是有意为之。需要运行开发服务器时，请使用终端或 hbx_open_terminal。

启动后端服务失败

• hbx_service_start 只允许 dev / start 脚本
• 日志文件在 ~/.viry-mcp/services/，可用 hbx_service_logs 查看
• 端口被占用时先停止旧服务，或换一个端口
• 服务记录保存在 ~/.viry-mcp/services/services.json，进程退出后状态会显示为已停止

HTTP 接口请求失败

• 确认 URL 和端口，例如 http://127.0.0.1:3001/api/login
• 跨域是否允许由目标服务决定
• 响应过大时会截断，可调整 maxBytes
• 需要 JSON 请求体时传 json 字段，会自动设置 Content-Type: application/json

安全提示

• 桥接服务只监听 127.0.0.1，不对外网开放。
• 每次启动都会生成新的随机 token，保存在用户目录的端点文件中。
• hbx_execute_command 可以执行任意 HBuilderX 命令，hbx_write_file 可以写任意路径，请只在可信的 AI 客户端中使用。
• 不需要使用 MCP 时，可以在设置中关闭 viry.enabled。

反馈

遇到问题时，请附上：

1. HBuilderX 版本
2. Viry MCP 版本（状态面板底部）
3. 状态面板的「最近日志」
4. AI 客户端的报错信息