DebugBridge

A Fabric client mod for Minecraft (1.19, 1.21.11, and 26.2 development snapshots) that exposes game state over a local WebSocket server, plus a Vue web UI for visual inspection. Built for AI-assisted Minecraft development and debugging.

What It Does

DebugBridge runs a localhost-only WebSocket server (default port 9876, scans 9876–9886) inside Minecraft. External tools — CLI scripts, the bundled Vue web UI, or MCP clients like Claude Code — can inspect and interact with the running game through two complementary APIs:

Native endpoints (fast, high-level)

Purpose-built Java endpoints that return structured JSON in a single round-trip — no scripting overhead:

Two endpoint families are gated off by default in config/debugbridge.json: runCommand (run_command_enabled) sends commands as the player, and the session-control trio disconnect / joinServer / quit (session_control_enabled) lets an automation loop leave a world, join a server, or shut the client down. joinServer pre-accepts the server resource pack and defers the connect until the client has settled (no loading overlay — joining during the startup resource reload would silently drop the server pack), acking only once the connect attempt has actually started; it's safe to fire the moment the bridge port answers after a launch.

Groovy execution (execute endpoint)

Run Groovy scripts inside the Minecraft JVM with full access to Minecraft APIs via a mapping-aware Java bridge — write Mojang names and they resolve to the runtime (intermediary) names automatically, even on obfuscated builds. Convenience globals mc, player, and level are pre-bound. The sandbox allows file I/O for reading/writing data. Each request has a configurable timeout (default 10s, max 5 min).

// 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

The web-ui/ directory contains a Vue 3 + Pinia + Tailwind app for visual inspection of game state:

• Dashboard — Player snapshot overview
• Entities panel — Nearby entity list with detail drill-down, equipment icons, glow toggling
• Blocks panel — Nearby block-entity browser (signs, chests, etc.)
• Screen inspector — Current GUI/inventory slot viewer
• Groovy inspector — Drill-down object browser for Java objects
• Console — Interactive Groovy REPL connected to the running client
• Chat history — Recent client-side messages

Bundled since v2.0.0 — the mod serves the built UI itself at http://localhost:<bridge port + 100> (default http://localhost:9976; the join-time chat message prints the exact URL as a clickable link). Loopback-only, static assets only, and the served page connects to the bridge instance that served it, so side-by-side game instances each get their own UI. Disable with "web_ui_enabled": false in config/debugbridge.json.

For UI development, the dev server still works (with HMR):

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

The web UI connects directly to the WebSocket server — no MCP layer required.

Architecture

+-----------------------------------+
|  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 Mapping Support

The mod automatically downloads official Mojang mappings at startup and uses them to translate human-readable names (net.minecraft.client.Minecraft) to the obfuscated names used at runtime. In 1.21.11+, Mojang ships unobfuscated names and mapping is a no-op.

The 26.2 development build targets Mojang-named snapshot classes directly and skips mapping download/remap entirely.

Security Model

DebugBridge binds exclusively to localhost (127.0.0.1). Only processes running on the same machine can connect. The debug port is never exposed to the network.

This is a development and debugging tool, not a remote administration system. Anyone with localhost access already has full control over the Minecraft process, so the bridge does not introduce new attack surface.

• Client-side only — runs entirely on the client, cannot affect servers or other players
• No outbound connections — only startup mapping downloads from Mojang's official APIs
• Gated features — runCommand and session control are disabled by default (opt-in via config)
• Developer warning — first-launch screen informs the user the mod is active; nothing serves until accepted
• Web UI server — same loopback-only posture; serves only the static assets bundled in the jar (GET-only, no directory listing, path-traversal rejected)

Repo Layout

mod/
  core/          — Shared Java: BridgeServer, Groovy runtime, mapping resolver, provider interfaces
  fabric-1.19/   — Fabric mod for Minecraft 1.19.x (provider impls + mixins)
  fabric-1.21.11/— Fabric mod for Minecraft 1.21.11 (provider impls + mixins)
  fabric-26.2-dev/— Fabric mod for Minecraft 26.2 development snapshots
web-ui/          — Vue 3 + Pinia + Tailwind inspection app

Installation

Grab the jar for your Minecraft version from the GitHub releases (debugbridge-1.19-*.jar or debugbridge-1.21.11-*.jar), drop it into your instance's mods/ folder, and launch with Fabric Loader. Client-side only — nothing to install on a server. On first run the mod shows a developer warning in-game and stays inactive until you accept it; the same gate writes developer_mode_accepted into config/debugbridge.json. Once accepted, the bundled web UI is at http://localhost:9976 (the in-game startup message prints the exact URL).

Building

Requires JDK 21+ for the stable Fabric modules, JDK 25 for fabric-26.2-dev (matches the runtime declared by the snapshot's own version manifest), and Node ≥20.19 for the web UI.

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

# 26.2 development snapshot 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/

Testing

Three layers, automated where it pays off:

1. Core unit tests — pure JVM, no Minecraft. Runs every PR via .github/workflows/build.yml.

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

Covers the Groovy bridge runtime, mapping resolver kernel (with stubbed Fabric SPI), and wire-contract tests for every endpoint (using stub providers).

2. Smoke test against a live mod — tools/smoke-test.mjs. Connects via WebSocket, hits each kernel-candidate endpoint, validates the response. ~30 seconds. Requires Node 22+ for the built-in WebSocket global.

# 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

3. Wire-shape regression mode — same script with --regression DIR. Compares each live response's structural shape (key sets at every level, value types) against a captured fixture; fails on drift.

# 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

The shape comparator tolerates value differences (transient game state) but flags any structural change — added/removed keys, type mismatches. Conditional fields can produce false positives: snapshot.target is only present when the player is aiming at something; nearbyEntities[].primaryEquipment only when the closest entity wears something. Capture fixtures from a richly-populated state, or treat conditional-field diffs as expected.

Usage

With Claude Code / MCP

Install mcdev-mcp and configure it in your MCP client. The MCP server auto-connects to DebugBridge (scans ports 9876–9886). Tools include:

• Runtime (requires this mod): 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 / dev loop (requires session_control_enabled): mc_join_server, mc_leave_server, mc_quit_client, plus mc_wait_for_bridge / mc_wait_until_in_world for driving rebuild → relaunch → rejoin loops
• Static (works offline): mc_get_class, mc_get_method, mc_search, mc_find_refs, mc_find_hierarchy

Direct WebSocket

Connect to ws://127.0.0.1:9876 and send JSON:

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

Each request gets a matching {id, type, payload} response.

Dependencies Bundled in JAR

• Apache Groovy 5.0.6 — JVM scripting runtime (Apache-2.0)
• Java-WebSocket 1.6.0 — WebSocket server (MIT)
• Gson 2.14.0 — JSON parsing (Apache 2.0)

License

MIT License — see LICENSE file for details.