# DebugBridge<\/p>\n
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.<\/p>\n
## What It Does<\/p>\n
DebugBridge runs a localhost-only WebSocket server (default port 9876, scans 9876\u20139885) inside Minecraft. External tools \u2014 CLI scripts, the bundled Vue web UI, or MCP clients like Claude Code \u2014 can inspect and interact with the running game through two complementary APIs:<\/p>\n
### Native endpoints (fast, high-level)<\/p>\n
Purpose-built Java endpoints that return structured JSON in a single round-trip \u2014 no Lua overhead:<\/p>\n
| Endpoint | What it returns |
\n|—|—|
\n| `snapshot` | Player position, health, food, dimension, gamemode, time, weather |
\n| `nearbyEntities` | Entities within range: type, position, equipment, distance (with optional `includeIcons` for item textures) |
\n| `entityDetails` | Full entity info: equipment slots with damage\/custom names, vehicle, passengers, attributes, frame contents |
\n| `lookedAtEntity` | The entity the player is aiming at (raycast) |
\n| `nearbyBlocks` | Block-entities within range: signs, chests, banners, beacons, furnaces, etc. |
\n| `blockDetails` | Block-entity contents: sign lines, chest inventory, skull profile, beacon level |
\n| `screenInspect` | Current open screen\/gui: type, title, container slots with item stacks (with optional `includeIcons`) |
\n| `chatHistory` | Recent client-side chat messages (with optional `includeJson` for styled components) |
\n| `screenshot` | Capture the framebuffer as JPEG |
\n| `getItemTexture` \/ `getItemTextureById` \/ `getEntityItemTexture` | Render item icons as PNG (honors damage, custom model data, dyed leather, player heads) |
\n| `setEntityGlow` \/ `setBlockGlow` \/ `clearBlockGlow` | Highlight entities or blocks with an in-world outline |
\n| `search` | Search loaded classes by name pattern |
\n| `status` | Server health and connection info |<\/p>\n
### Lua execution (`execute` endpoint)<\/p>\n
Run Lua 5.2 scripts inside the Minecraft JVM with full access to Minecraft APIs via a Java reflection bridge. 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).<\/p>\n
“`lua
\n— Convenience globals already available
\nprint(“Player at: ” .. player:blockPosition():toShortString())
\nprint(“Dimension: ” .. mc.level:dimension().location())<\/p>\n
— Import anything else you need
\nlocal Vec3 = java.import(“net.minecraft.world.phys.Vec3”)<\/p>\n
— Iterate Java collections
\nfor entity in java.iter(level:entitiesForRendering()) do
\n if entity:distanceTo(player) < 10 then\n print(\"Nearby: \" .. java.typeof(entity))\n end\nend\n```\n\n## Vue Web UI\n\nThe `web-ui\/` directory contains a Vue 3 + Pinia + Tailwind app for visual inspection of game state:\n\n- **Dashboard** \u2014 Player snapshot overview\n- **Entities panel** \u2014 Nearby entity list with detail drill-down, equipment icons, glow toggling\n- **Blocks panel** \u2014 Nearby block-entity browser (signs, chests, etc.)\n- **Screen inspector** \u2014 Current GUI\/inventory slot viewer\n- **Lua inspector** \u2014 Drill-down object browser for Lua values and Java objects\n- **Console** \u2014 Interactive Lua REPL connected to the running client\n- **Chat history** \u2014 Recent client-side messages\n\nStart it with:\n```bash\ncd web-ui\nnpm run dev # \u2192 http:\/\/localhost:5173\n```\n\nThe web UI connects directly to the WebSocket server \u2014 no MCP layer required.\n\n## Architecture\n\n```\n+-----------------------------------+\n| MCP Client (Claude Code, etc.) |\n+---------------+-------------------+\n | MCP Protocol (stdio)\n+---------------v-------------------+\n| mcdev-mcp Server (TypeScript) |\n| Runtime + static analysis tools |\n| github.com\/weikengchen\/mcdev-mcp |\n+---------------+-------------------+\n | WebSocket (localhost:9876\u20139885)\n+---------------v-------------------+\n| DebugBridge Mod [THIS REPO] |\n| +-----------------------------+ |\n| | BridgeServer (WebSocket) | |\n| | Native endpoints + execute | |\n| | Lua runtime + Java bridge | |\n| | Mojang mapping resolver | |\n| +-----------------------------+ |\n+-----------------------------------+\n ^\n | WebSocket (same port)\n+---------------+-------------------+\n| Vue Web UI (localhost:5173) |\n| Dashboard, Inspector, Console |\n+-----------------------------------+\n```\n\n## Mojang Mapping Support\n\nThe 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.\n\nThe 26.2 development build targets Mojang-named snapshot classes directly and skips mapping download\/remap entirely.\n\n## Security Model\n\n**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.\n\nThis 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.\n\n- **Client-side only** \u2014 runs entirely on the client, cannot affect servers or other players\n- **No outbound connections** \u2014 only startup mapping downloads from Mojang's official APIs\n- **Gated features** \u2014 `runCommand` is disabled by default (opt-in via config)\n- **Developer warning** \u2014 first-launch screen informs the user the mod is active\n\n## Repo Layout\n\n```\nmod\/\n core\/ \u2014 Shared Java: BridgeServer, Lua runtime, mapping resolver, provider interfaces\n fabric-1.19\/ \u2014 Fabric mod for Minecraft 1.19.x (provider impls + mixins)\n fabric-1.21.11\/\u2014 Fabric mod for Minecraft 1.21.11 (provider impls + mixins)\n fabric-26.2-dev\/\u2014 Fabric mod for Minecraft 26.2 development snapshots\nweb-ui\/ \u2014 Vue 3 + Pinia + Tailwind inspection app\n```\n\n## Building\n\nRequires **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 \u226520.19** for the web UI.\n\n```bash\n# Fabric mods\ncd mod\nJAVA_HOME=\/opt\/homebrew\/opt\/openjdk@21\/libexec\/openjdk.jdk\/Contents\/Home .\/gradlew build\n# JARs -> mod\/fabric-*\/build\/libs\/<\/p>\n
# 26.2 development snapshot bridge
\ncd mod
\nJAVA_HOME=\/opt\/homebrew\/opt\/openjdk@25\/libexec\/openjdk.jdk\/Contents\/Home .\/gradlew :core:test :fabric-26.2-dev:jar<\/p>\n
# Web UI
\ncd web-ui
\nnpm install
\nnpm run dev # dev server at http:\/\/localhost:5173
\nnpm run build # production build \u2192 web-ui\/dist\/
\n“`<\/p>\n
## Testing<\/p>\n
Three layers, automated where it pays off:<\/p>\n
**1. Core unit tests** \u2014 pure JVM, no Minecraft. Runs every PR via `.github\/workflows\/build.yml`.<\/p>\n
“`bash
\ncd mod
\nJAVA_HOME=\/opt\/homebrew\/opt\/openjdk@21\/libexec\/openjdk.jdk\/Contents\/Home .\/gradlew :core:test
\n“`<\/p>\n
Covers the Lua bridge runtime, mapping resolver kernel (with stubbed Fabric SPI), and wire-contract tests for every endpoint (using stub providers).<\/p>\n
**2. Smoke test against a live mod** \u2014 `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.<\/p>\n
“`bash
\n# Smoke test against running 1.21.11 mod
\nnode tools\/smoke-test.mjs –port 9876 –version 1.21.11<\/p>\n
# 1.19 alongside (default ports: 1.21.11=9876, 1.19=9877)
\nnode tools\/smoke-test.mjs –port 9877 –version 1.19
\n“`<\/p>\n
**3. Wire-shape regression mode** \u2014 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.<\/p>\n
“`bash
\n# Capture baselines once after a known-good build
\nnode tools\/smoke-test.mjs –port 9876 –version 1.21.11
\n –fixtures tools\/fixtures\/1.21.11<\/p>\n
# Later, after deploying a new build, check for drift
\nnode tools\/smoke-test.mjs –port 9876 –version 1.21.11
\n –regression tools\/fixtures\/1.21.11
\n“`<\/p>\n
The shape comparator tolerates value differences (transient game state) but flags any structural change \u2014 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.<\/p>\n
## Usage<\/p>\n
### With Claude Code \/ MCP<\/p>\n
Install mcdev-mcp and configure it in your MCP client. The MCP server auto-connects to DebugBridge (scans ports 9876\u20139885). Tools include:<\/p>\n
– **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_get_item_texture`, `mc_set_entity_glow`, `mc_set_block_glow`, `mc_clear_block_glow`
\n– **Static** (works offline): `mc_get_class`, `mc_get_method`, `mc_search`, `mc_find_refs`, `mc_find_hierarchy`<\/p>\n
### Direct WebSocket<\/p>\n
Connect to `ws:\/\/127.0.0.1:9876` and send JSON:<\/p>\n
“`json
\n{
\n “id”: “1”,
\n “type”: “execute”,
\n “payload”: {
\n “code”: “return player:blockPosition():toShortString()”
\n }
\n}
\n“`<\/p>\n
Each request gets a matching `{id, type, payload}` response.<\/p>\n
## Dependencies Bundled in JAR<\/p>\n
– **LuaJ 3.0.1** \u2014 Pure Java Lua 5.2 (MIT)
\n– **Java-WebSocket 1.6.0** \u2014 WebSocket server (MIT)
\n– **Gson 2.14.0** \u2014 JSON parsing (Apache 2.0)<\/p>\n
## License<\/p>\n
MIT License \u2014 see LICENSE file for details.<\/p>\n","protected":false},"excerpt":{"rendered":"
Enable a MCP server to connect to a running Minecraft client instance and run Lua script live to explore the world and setting. This mod is for MOD DEVELOPERS, not for regular users.<\/p>\n","protected":false},"featured_media":55173,"template":"","meta":{"_minecraft_slug":"debugbridge","_minecraft_project_id":"XluaQP7T","_minecraft_author":"weikeng","_minecraft_license":"MIT","_minecraft_downloads":29,"_minecraft_follows":0,"_minecraft_client_side":"required","_minecraft_server_side":"unsupported","_minecraft_storage_type":"zip","_minecraft_archive_name":"debugbridge.zip","_minecraft_size_bytes":3486247,"_minecraft_version_count":4,"_minecraft_updated_at":"2026-05-16T13:52:33.183229Z","_minecraft_date_created":"2026-05-03T03:53:11.345611Z","_minecraft_date_modified":"2026-05-13T03:15:32.833920Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/debugbridge","_minecraft_icon_attachment_id":55173,"_minecraft_imported_at":"2026-06-03T01:37:18+00:00","_minecraft_import_hash":"0c245d260bb0e93ae2240ed998b73f65","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[97,126],"mod_loader":[99],"minecraft_version":[54,55,56,57,58,41,842],"class_list":["post-55172","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-fabric","mod_category-management","mod_loader-fabric","minecraft_version-1-19","minecraft_version-1-19-1","minecraft_version-1-19-2","minecraft_version-1-19-3","minecraft_version-1-19-4","minecraft_version-1-21-11","minecraft_version-26-2-snapshot-7"],"yoast_head":"\n