Minecraft 开发工具

Runtime Interaction (requires [DebugBridge](https://github.com/use-ai-for-mc/debugbridge) mod)

• Live Lua Execution — Execute Lua scripts inside the running Minecraft JVM (mc_execute)
• Game State Snapshots — Player position, health, dimension, time, weather (mc_snapshot)
• Screenshots, Recordings & Screen Inspection — Game-window JPEG, multi-frame contact sheet for temporal debug, and current-GUI structure (mc_screenshot, mc_record_video, mc_screen_inspect)
• World Introspection — Nearby entities and block-entities, plus per-id details (mc_nearby_entities, mc_entity_details, mc_nearby_blocks, mc_block_details, mc_looked_at_entity)
• Visual Markers — Outline entities or blocks for the user to spot (mc_set_entity_glow, mc_set_block_glow, mc_clear_block_glow)
• Item Texture Rendering — Render an inventory slot, an item id, or a slot on another entity as PNG (mc_get_item_texture, mc_get_item_texture_by_id, mc_get_entity_item_texture)
• Chat History — Recent client-side chat messages (mc_chat_history)
• Slash Commands — Execute in-game commands (mc_run_command, opt-in dev tool)
• Script Execution Logs — Review past mc_execute runs and error patterns (mc_script_logs, opt-in via Claude Desktop user setting)

Static Tool Requirements

Requirements

Note: Java 17+ is recommended for the callgraph command due to Gradle compatibility.

Download, decompile, and index Minecraft sources (~2-5 minutes)

npx mcdev-mcp init -v 1.21.11 ```

This command: 1. Downloads the Minecraft client JAR 2. Decompiles using Vineflower (pure Java, 8 threads) 3. Builds the symbol index (classes, methods, fields, inheritance) 4. Generates call graph for mc_find_refs

Data is stored in your OS cache directory (see Storage location below), so it persists across npx invocations. Expect roughly ~2 GB per Minecraft version — mostly decompiled .java sources and a SQLite callgraph database. All of it is regeneratable, so your OS is free to evict it under storage pressure and init will rebuild what it needs.

3. (Optional) Install DebugBridge for live-game tools

The static analysis tools (mc_search, mc_get_class, mc_find_refs, …) work as soon as init finishes. The runtime tools (mc_execute, mc_snapshot, screenshots, world introspection, item textures, glow markers, etc.) additionally require the DebugBridge mod installed in the Minecraft instance you want to drive. Without DebugBridge, those tools will just report a connection error — the static half keeps working unaffected.

Verify Installation

npx mcdev-mcp status

Note: mc_version (with action: "set") must be called before using any other static MCP tools. If the version isn't initialized, the AI will be instructed to ask you to run init.

Install from source (development)

```bash git clone https://github.com/use-ai-for-mc/mcdev-mcp.git cd mcdev-mcp npm install npm run build

Use the local build instead of npx

node dist/cli.js init -v 1.21.11 node dist/cli.js serve # stdio MCP server; MCP clients launch this ```

Upgrading from an older version? If you have a previous installation using DecompilerMC, run npx mcdev-mcp clean --all first to remove old cached data.

or, to re-index an already-decompiled version:

MCDEV_AST_PARSER=1 npx mcdev-mcp rebuild -v 1.21.11 --with-callgraph

The MCP server stamps `manifest.indexerVersion` so it can tell which parser produced the existing index. When you flip the flag but haven't rebuilt yet, the server prints a one-time hint per version on the next tool call:

Installing the MCPB in Claude Desktop

Download the bundle from the Releases page and double-click the .mcpb file. Claude Desktop will validate the manifest and offer to install it. After install, run mcdev-mcp init -v <version> in a terminal once to populate the cache (the extension cannot trigger init itself — it's deliberately terminal-only, see Quick Start).

Quick Start

Security note — init is intentionally terminal-only. The MCP server only exposes read/query tools. Downloading and decompiling Minecraft sources must be triggered by you in the terminal; an AI agent connected to the server has no tool surface to trigger init, rebuild, clean, or callgraph.

`mc_screenshot`

Capture the game window as a JPEG file and return its path.

{
  "downscale": 2,
  "quality": 0.75
}

(Optional) Skip Call Graph

```bash

CLI Commands

Invoke via npx mcdev-mcp <command> (or node dist/cli.js <command> from a source checkout).

`mc_list_packages`

List all available packages. Optionally filter by namespace.

{
  "namespace": "minecraft"
}

1. Bump the version. npm version only touches package.json; mirror the same

2. Commit the manifest bump (npm version already committed package.json)

git commit -am "Sync manifest.json version" git tag -f "v$(node -p 'require(\"./package.json\").version')"

Third-Party Components

This project includes or uses third-party software under the following licenses:

• DecompilerMC (MIT) — Decompiler logic adapted and translated from Python to TypeScript in src/decompiler/
• Vineflower (Apache-2.0) — Java decompiler used for source generation
• java-callgraph2 — Cloned at runtime for static call graph generation

Additional runtime dependencies (downloaded/used): - Mojang — Official ProGuard mappings and Minecraft client JAR

See LICENSE for full license text and third-party attributions.