调试桥

调试桥

将 MCP 客户端和本地工具连接到正在运行的 Minecraft 客户端,以实现实时 Groovy 脚本编写、游戏状态检查以及内置的 Web UI。面向模组开发者和 AI 辅助调试。

管理

DebugBridge

一个 Fabric 客户端模组,适用于 Minecraft(1.19、1.21.11、精确版本 26.1 以及稳定版 26.2),通过本地 WebSocket 服务器暴露游戏状态,并提供 Vue Web UI 用于可视化查看。专为 AI 辅助的 Minecraft 开发和调试而构建。

2.1.0 中的新内容

v2.1.0 为每个维护目标提供相同的稳定功能线:Minecraft 1.19.x、1.21.11、精确版本 26.1 以及稳定版 26.2。原 26.2 开发模块现在成为稳定版 26.2 线;源目录仍为 mod/fabric-26.2-dev/。

相对于 2.0.0,此版本还强化了现有桥接:

  • record_video 默认使用临时存储,具有 24 小时 TTL 和自动清理(storage: "persistent" 会将文件保留在游戏目录下)
  • runCommand 保持相同的选择性启用线路协议,但现在使用原生的按版本提供程序,而不是 Groovy 往返
  • 配置值经过范围验证,对象引用有界,脚本执行复用其工作线程,录制/断开连接/纹理/实体刷新竞争得到更防御性的处理
  • 精确版本 26.1 可以在标题屏幕上渲染物品纹理(getItemTextureById 不再失败并提示 Components not bound yet)
  • Web UI 库存槽位、实体颜色和存储刷新行为更加可靠

Groovy 5 脚本模型和端点集与 v2.0.0 保持兼容。从 v2.1.0 发布版 获取匹配的 jar。

功能说明

DebugBridge 在 Minecraft 内部运行一个仅限本地的 WebSocket 服务器(默认端口 9876,扫描 9876–9886)。外部工具——CLI 脚本、捆绑的 Vue Web UI 或像 Claude Code 这样的 MCP 客户端——可以通过两个互补的 API 检查和与运行中的游戏交互:

原生端点(快速、高层)

专门构建的 Java 端点,在单次往返中返回结构化 JSON——无需脚本开销:

端点 返回内容
snapshot 玩家位置、生命值、饥饿值、维度、游戏模式、时间、天气
nearbyEntities 范围内的实体:类型、位置、装备、距离(可选 includeIcons 以获取物品纹理)
entityDetails 完整实体信息:带有伤害/自定义名称的装备槽位、载具、乘客、属性、物品展示框内容
lookedAtEntity 玩家正瞄准的实体(射线检测)
nearbyBlocks 范围内的方块实体:告示牌、箱子、旗帜、信标、熔炉等
blockDetails 方块实体内容:告示牌文字行、箱子库存、头颅档案、信标等级
screenInspect 当前打开的屏幕/GUI:类型、标题、带有物品堆叠的容器槽位(可选 includeIcons)
chatHistory 最近的客户端聊天消息(可选 includeJson 以获取带样式的组件)
screenshot 将帧缓冲捕获为 JPEG
record_video 将 N 帧帧缓冲捕获为默认临时存储的 JPEG 网格或逐帧文件
getItemTexture / getItemTextureById / getEntityItemTexture 将物品图标渲染为 PNG(遵循伤害、自定义模型数据、染色皮革、玩家头颅)
setEntityGlow / setBlockGlow / clearBlockGlow 用世界内轮廓高亮实体或方块
search 按名称模式搜索已加载的类
status 服务器健康状态和连接信息

两个端点系列在 config/debugbridge.json 中默认关闭:runCommand(run_command_enabled)通过原生的按版本提供程序以玩家身份发送命令,而会话控制三件套 disconnect / joinServer / quit(session_control_enabled)允许自动化循环离开世界、加入服务器或关闭客户端。joinServer 预先接受服务器资源包,并将连接推迟到客户端准备就绪后(没有加载覆盖层——在启动资源重载期间加入会静默丢弃服务器资源包),仅在连接尝试实际开始后才进行确认;在启动后桥接端口响应的那一刻即可安全触发。

Groovy 执行(execute 端点)

在 Minecraft JVM 内运行 Groovy 脚本,通过映射感知的 Java 桥接完全访问 Minecraft API——编写 Mojang 名称,它们会自动解析为运行时(intermediary)名称,即使在混淆构建上也是如此。便捷全局变量 mc、player 和 level 已预先绑定。沙箱允许文件 I/O 用于读写数据。每个请求具有可配置的超时(默认 10 秒,最大 5 分钟)。

// Convenience globals already available
println "Player at: " + player.blockPosition().toShortString()
println "Dimension: " + mc.level.dimension().location()

// Load anything else by Mojang name (works on obfuscated builds too).
// Prefer single quotes: double-quoted GStrings interpolate the $ in
// inner-class names like Display$TextDisplay.
def Vec3 = java.type('net.minecraft.world.phys.Vec3')

// Iterate Java collections. Wrap a bulk loop in sync { } so the per-call
// reflective dispatch batches into a single game-thread hop.
sync {
    java.list(level.entitiesForRendering()).each { entity ->
        if (entity.distanceTo(player) < 10) {
            println "Nearby: " + java.typeName(entity)
        }
    }
}

Vue Web UI

web-ui/ 目录包含一个 Vue 3 + Pinia + Tailwind 应用,用于可视化检查游戏状态:

  • 仪表盘 — 玩家快照概览
  • 实体面板 — 附近实体列表,带详情下钻、装备图标、发光切换
  • 方块面板 — 附近方块实体浏览器(告示牌、箱子等)
  • 屏幕检查器 — 当前 GUI/库存槽位查看器
  • Groovy 检查器 — Java 对象的下钻式对象浏览器
  • 控制台 — 连接到运行中客户端的交互式 Groovy REPL
  • 聊天历史 — 最近的客户端消息

自 v2.0.0 起捆绑 — 模组自身在 http://localhost:<bridge port + 100> 提供构建后的 UI(默认 http://localhost:9976; 加入时的聊天消息会以可点击链接打印确切 URL)。 仅限回环,仅静态 资源,并且提供的页面连接到为其提供服务的桥接实例,因此并行游戏实例各自获得自己的 UI。通过在 config/debugbridge.json 中设置 "web_ui_enabled": false 来禁用。

对于 UI 开发,开发服务器仍然可用(带 HMR):

cd web-ui
npm run dev          # → http://localhost:5173

Web UI 直接连接到 WebSocket 服务器——无需 MCP 层。

架构

+-----------------------------------+
|  MCP Client (Claude Code, etc.)   |
+---------------+-------------------+
                | MCP Protocol (stdio)
+---------------v-------------------+
|  mcdev-mcp Server (TypeScript)    |
|  Runtime + static analysis tools  |
| github.com/use-ai-for-mc/mcdev-mcp|
+---------------+-------------------+
                | WebSocket (localhost:9876–9886)
+---------------v-------------------+
|  DebugBridge Mod [THIS REPO]      |
|  +-----------------------------+  |
|  | BridgeServer (WebSocket)    |  |
|  | Native endpoints + execute  |  |
|  | Groovy runtime + Java bridge |  |
|  | Mojang mapping resolver     |  |
|  +-----------------------------+  |
+-----------------------------------+
                ^
                | WebSocket (same port)
+---------------+-------------------+
|  Vue Web UI (bundled, :9976;      |
|  npm dev server :5173)            |
+-----------------------------------+

Mojang 映射支持

模组在启动时自动下载官方 Mojang 映射,并使用它们将人类可读的名称(net.minecraft.client.Minecraft)转换为运行时使用的混淆名称。在 1.21.11+ 中,Mojang 提供未混淆的名称,映射为空操作。

精确版本 26.1 和 26.2 稳定构建直接面向 Mojang 命名的类,并完全跳过映射下载/重映射。

安全模型

DebugBridge 仅绑定到本地主机(127.0.0.1)。 只有同一台机器上运行的进程才能连接。调试端口从不暴露到网络。

这是一个开发和调试工具,不是远程管理系统。任何具有本地主机访问权限的人已经拥有对 Minecraft 进程的完全控制权,因此桥接不会引入新的攻击面。

  • 仅客户端 — 完全在客户端运行,无法影响服务器或其他玩家
  • 无出站连接 — 仅从 Mojang 的官方 API 进行启动映射下载
  • 门控功能 — runCommand 和会话控制默认禁用(通过配置选择加入)
  • 开发者警告 — 首次启动屏幕告知用户模组已激活;在接受之前不提供任何服务
  • Web UI 服务器 — 相同的仅限回环姿态;仅提供 jar 中捆绑的静态资源(仅 GET,无目录列表,路径遍历被拒绝)

仓库布局

mod/
  core/          — 共享 Java:BridgeServer、Groovy 运行时、映射解析器、提供程序接口
  fabric-1.19/   — 适用于 Minecraft 1.19.x 的 Fabric 模组(提供程序实现 + mixin)
  fabric-1.21.11/— 适用于 Minecraft 1.21.11 的 Fabric 模组(提供程序实现 + mixin)
  fabric-26.1/   — 适用于精确 Minecraft 26.1 的 Fabric 模组(提供程序实现 + mixin)
  fabric-26.2-dev/— 适用于 Minecraft 26.2 稳定版的 Fabric 模组
web-ui/          — Vue 3 + Pinia + Tailwind 检查应用

安装

从 GitHub 发布版 获取适用于你的 Minecraft 版本的 jar (debugbridge-1.19-*.jar、debugbridge-1.21.11-*.jar、debugbridge-26.1-*.jar 或 debugbridge-26.2-*.jar),将其放入实例的 mods/ 文件夹,并使用 Fabric Loader 启动。仅客户端——服务器上无需安装任何内容。 首次运行时,模组会在游戏内显示开发者警告,并在你接受之前保持非活动状态;同一门控会将 developer_mode_accepted 写入 config/debugbridge.json。一旦接受,捆绑的 Web UI 位于 http://localhost:9976(游戏内启动消息会打印确切 URL)。

对于本地精确版本 26.1 的 Prism Launcher 实例,使用仓库脚本:

JAVA_HOME_26_1=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home \
  PRISM_INSTANCE_NAME=26.1 \
  ./build-and-deploy-26.1.sh

要在不构建或触碰实例的情况下检查选定的 Prism 实例、Java 路径、解析的 Gradle 版本、目标 mods 目录和冒烟测试端口:

JAVA_HOME_26_1=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home \
  PRISM_INSTANCE_NAME=26.1 \
  ./build-and-deploy-26.1.sh --preflight

该脚本构建 mod/fabric-26.1,暂存 jar,使用 unzip -tq 验证,并以原子方式将其交换到选定 Prism 实例的 mods/ 目录。在替换已安装的 jar 之前,它会验证构建和暂存的 jar 声明精确的 Minecraft 26.1 和 com.debugbridge.fabric261.DebugBridgeMod 入口点。如果桥接在最终冒烟运行中使用非默认 端口,在调用脚本时设置 SMOKE_PORT=<port>; 部署后命令提示将使用该端口。

构建

稳定版 1.x Fabric 模块需要 JDK 21+,fabric-26.1 和稳定版 26.2 需要 JDK 25(模块路径 fabric-26.2-dev,匹配 26.x 版本清单声明的运行时),Web UI 需要 Node >=20.19。

# Fabric mods
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ./gradlew build
# JARs -> mod/fabric-*/build/libs/

# Exact 26.1 bridge
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home ./gradlew :fabric-26.1:jar

# 26.2 stable bridge
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home ./gradlew :core:test :fabric-26.2-dev:jar

# Web UI
cd web-ui
npm install
npm run dev          # dev server at http://localhost:5173
npm run build        # production build → web-ui/dist/

测试

三层,在值得的地方自动化:

1. 核心单元测试 — 纯 JVM,无 Minecraft。通过 .github/workflows/build.yml 在每个 PR 上运行。

cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ./gradlew :core:test

覆盖 Groovy 桥接运行时、映射解析器内核(带存根 Fabric SPI),以及每个端点的线路协议测试(使用存根提供程序)。

2. 针对实时模组的冒烟测试 — tools/smoke-test.mjs。通过 WebSocket 连接,命中每个内核候选端点,验证响应。约 30 秒。需要 Node 22+ 以使用内置的 WebSocket 全局变量。

# Smoke test against running 1.21.11 mod
node tools/smoke-test.mjs --port 9876 --version 1.21.11

# 1.19 alongside (default ports: 1.21.11=9876, 1.19=9877)
node tools/smoke-test.mjs --port 9877 --version 1.19

# Exact 26.1 after deploying to a Prism instance
node tools/smoke-test.mjs --port 9876 --version 26.1 --game-dir-contains '/instances/26.1/' --include-textures
node tools/record-video-smoke.mjs --port 9876 --version 26.1 --game-dir-contains '/instances/26.1/'

3. 线路形状回归模式 — 使用 --regression DIR 的相同脚本。将每个实时响应的结构形状(每个层级的键集、值类型)与捕获的夹具进行比较;漂移时失败。

# Capture baselines once after a known-good build
node tools/smoke-test.mjs --port 9876 --version 1.21.11 \
    --fixtures tools/fixtures/1.21.11

# Later, after deploying a new build, check for drift
node tools/smoke-test.mjs --port 9876 --version 1.21.11 \
    --regression tools/fixtures/1.21.11

形状比较器容忍值差异(瞬态游戏状态),但标记任何结构变化——添加/删除的键、类型不匹配。条件字段可能产生误报: snapshot.target 仅在玩家瞄准某物时存在;nearbyEntities[].primaryEquipment 仅在最近的实体穿着某物时存在。从内容丰富填充的状态捕获夹具,或将条件字段差异视为预期。

用法

与 Claude Code / MCP 一起使用

安装 mcdev-mcp 并在你的 MCP 客户端中配置它。MCP 服务器自动连接到 DebugBridge(扫描端口 9876–9886)。工具包括:

  • 运行时(需要此模组):mc_execute、mc_snapshot、mc_nearby_entities、mc_entity_details、mc_looked_at_entity、mc_nearby_blocks、mc_block_details、mc_screen_inspect、mc_chat_history、mc_screenshot、mc_record_video、mc_get_item_texture、mc_set_entity_glow、mc_set_block_glow、mc_clear_block_glow
  • 会话控制 / 开发循环(需要 session_control_enabled):mc_join_server、mc_leave_server、mc_quit_client,以及用于驱动重建 → 重新启动 → 重新加入循环的 mc_wait_for_bridge / mc_wait_until_in_world
  • 静态(离线工作):mc_get_class、mc_get_method、mc_search、mc_find_refs、mc_find_hierarchy

直接 WebSocket

连接到 ws://127.0.0.1:9876 并发送 JSON:

{
  "id": "1",
  "type": "execute",
  "payload": {
    "code": "return player.blockPosition().toShortString()"
  }
}

每个请求获得匹配的 {id, type, payload} 响应。

record_video 存储

录制默认是临时的,因此 AI 驱动的冒烟测试不会填满 游戏目录:

{
  "id": "rec-1",
  "type": "record_video",
  "payload": {
    "frames": 120,
    "interval": "frame",
    "output": "grid",
    "storage": "temp",
    "ttlHours": 24
  }
}

storage 默认为 "temp",写入系统临时目录下 DebugBridge 拥有的子文件夹。响应包括 storage、directory 和 expiresAt。使用 "storage": "persistent" 将输出保留在 <gameDir>/debugbridge-recordings/<requestId>/ 下;requestId 是可选的 经过清理的子目录名称,不是任意文件系统路径。

JAR 中捆绑的依赖项

  • Apache Groovy 5.0.6 — JVM 脚本运行时(Apache-2.0)
  • Java-WebSocket 1.6.0 — WebSocket 服务器(MIT)
  • Gson 2.14.0 — JSON 解析(Apache 2.0)

许可证

MIT 许可证——详情请参阅 LICENSE 文件。