Mcdev MCP

mcdev-mcp

 

一 MCP（模型上下文协议）服务器 它使AI编码代理能够有效地与Minecraft mod开发协同工作。提供两者 静态分析 反编译的源代码和 运行时交互 一个正在运行的Minecraft实例。

特性

静态分析（离线工作）

• 已分解的源代码访问 --使用自动下载和反编译Minecraft客户端 葡萄花
• 开发人员快照支持 --使用开发快照（例如。， 26.1-snapshot-10)缺少ProGuard映射
• 符号搜索 --按名称搜索类、方法和字段(mc_search)
• 源检索 --获取完整的类源代码或带有上下文的单个方法
• 套餐探索 --列出包路径下的所有类或查找可用包
• 类层次结构 --查找子类和接口实现者
• 调用图分析 --在整个代码库中查找方法调用者和被调用者

运行时交互（需要 DebugBridge 摩登派青年

• 现场Lua执行 --在正在运行的Minecraft JVM中执行Lua脚本(mc_execute)
• 游戏状态快照 --球员位置、健康状况、身高、时间、天气(mc_snapshot)
• 截图、录音和屏幕检查 --游戏窗口JPEG、用于临时调试的多帧联系人表和当前GUI结构(mc_screenshot, mc_record_video, mc_screen_inspect)
• 世界反思 --附近的实体和块实体，以及每个id的详细信息(mc_nearby_entities, mc_entity_details, mc_nearby_blocks, mc_block_details, mc_looked_at_entity)
• 视觉标记 --概述实体或块，供用户发现(mc_set_entity_glow, mc_set_block_glow, mc_clear_block_glow)
• 项目纹理渲染 --将库存槽、项目id或另一个实体上的槽渲染为PNG(mc_get_item_texture, mc_get_item_texture_by_id, mc_get_entity_item_texture)
• 聊天记录 --最近的客户端聊天消息(mc_chat_history)
• 斜杠命令 --执行游戏内命令(mc_run_command，选择加入开发工具）
• 脚本执行日志 --回顾过去 mc_execute 运行和错误模式(mc_script_logs，通过Claude Desktop用户设置选择加入）

MCP资源

• mcdev://guides/python-scripting --希望直接从Python驱动DebugBridge的AI代理的有线协议参考（绕过MCP工具）：WebSocket帧、最小异步客户端和您通过它发送的Lua表面。通过标准MCP访问 resources/list + resources/read，服务器中有一个指针 instructions 所以特工们知道要看。

快速开始

安全说明-- init 只是故意终止。 MCP服务器只公开读取/查询工具。下载和反编译Minecraft源代码必须由您在终端中触发；连接到服务器的AI代理没有可触发的工具界面 init, rebuild, clean，或 callgraph.

1.在终端中初始化

# Download, decompile, and index Minecraft sources (~2-5 minutes)
npx mcdev-mcp init -v 1.21.11

此命令：

1. 下载Minecraft客户端JAR
2. 使用Vineflower进行分解（纯Java，8线程）
3. 构建符号索引（类、方法、字段、继承）
4. 为生成调用图 mc_find_refs

数据存储在操作系统缓存目录中（请参阅 存储位置 下面），因此它持续存在 npx 调用。预计大致 每个Minecraft版本约2 GB --大部分已反编译 .java 源代码和SQLite调用图数据库。所有这些都是可再生的，因此您的操作系统可以在存储压力下自由地将其驱逐 init 将重建它所需要的东西。

2.添加到您的MCP客户端

Codex桌面/Codex CLI

Codex可以直接启动本地stdio MCP服务器。使用以下命令安装已发布的软件包：

codex mcp add mcdev-mcp -- npx -y mcdev-mcp serve

如果您是从本地签出进行开发的，请先构建Codex并将其指向本地服务器：

git clone https://github.com/use-ai-for-mc/mcdev-mcp.git
cd mcdev-mcp
npm install
npm run build
codex mcp add mcdev-mcp -- node "$(pwd)/dist/index.js"

验证Codex是否可以看到它：

codex mcp list
codex mcp get mcdev-mcp

添加服务器后，重新启动Codex Desktop，或启动新的Codex会话。Codex将在会话需要时自动启动MCP服务器；你不跑 serve 用手。

其他MCP客户端

{
  "mcpServers": {
    "mcdev": {
      "command": "npx",
      "args": ["-y", "mcdev-mcp", "serve"]
    }
  }
}

这 serve 子命令通过stdio启动MCP服务器。您的MCP客户端（Claude Desktop、Cursor等）会自动启动它——您永远不会运行 serve 直接。

3.（可选）安装实时游戏工具的DebugBridge

静态分析工具(mc_search, mc_get_class, mc_find_refs，…）尽快工作 init 完成。运行时工具(mc_execute, mc_snapshot、屏幕截图、世界内省、物品纹理、发光标记等）还需要 DebugBridge模块 安装在您要驱动的Minecraft实例中。如果没有DebugBridge，这些工具只会报告连接错误——静态部分不受影响地工作。

支持的版本

从源代码安装（开发）

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

从旧版本升级？ 如果您之前使用了DecompilerMC进行安装，请运行 npx mcdev-mcp clean --all 首先删除旧的缓存数据。

MCP工具

版本管理（静态工具）

在使用静态工具之前，请设置活动的Minecraft版本：

mc_version

管理活动的Minecraft版本。来电 action: "set" 在其他静态工具之前，或 action: "list" 查看已初始化的内容。

{
  "action": "set",
  "version": "1.21.11"
}

{
  "action": "list"
}

静态工具要求

mc_search

按名称模式搜索反编译的源代码中的类、方法或字段。

{
  "query": "Minecraft",
  "type": "class"
}

mc_get_class

获取类的完整反编译源代码。

{
  "className": "net.minecraft.client.Minecraft"
}

mc_get_method

获取具有上下文的特定方法的源代码。

{
  "className": "net.minecraft.client.Minecraft",
  "methodName": "tick"
}

mc_find_refs

查找谁调用方法（调用者）或它调用什么（被调用者）。

{
  "className": "net.minecraft.client.MouseHandler",
  "methodName": "setup",
  "direction": "callers"
}

注： 需要生成调用图（包含在 init 默认情况下）。

mc_list_classes

列出特定包路径下的所有类（包括子包）。

{
  "packagePath": "net.minecraft.client.gui.screens"
}

mc_list_packages

列出所有可用的软件包。可选择按命名空间进行筛选。

{
  "namespace": "minecraft"
}

mc_find_hierarchy

查找扩展或实现给定类或接口的类。

{
  "className": "net.minecraft.world.entity.Entity",
  "direction": "subclasses"
}

______________________________________________________________________

运行时工具

这些工具需要Minecraft与 DebugBridge 已安装mod。

mc_connect

连接到正在运行的Minecraft实例。如果需要，其他运行时工具会自动连接。通过 reset: true 在重新连接之前断开连接并清除状态（在切换实例时很有用）。如果 port 扫描端口9876-9885。

{
  "port": 9876,
  "reset": false
}

mc_execute

在运行游戏中执行Lua代码。Lua环境在调用之间持续存在。

local mc = java.import("net.minecraft.client.Minecraft"):getInstance()
local player = mc.player
return player:blockPosition():toShortString()

mc_snapshot

获取当前游戏状态（玩家、世界、时间、天气）的结构化快照。

{}

mc_screenshot

将游戏窗口捕获为JPEG文件并返回其路径。

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

mc_record_video

捕获一小段帧以调试时间渲染问题（动画故障、着色器错误、粒子、单个屏幕截图无法解决的子刻度伪影）。返回一个合成网格JPEG（默认）或N个单独的帧JPEG。

{
  "frames": 60,
  "interval": 50,
  "output": "grid",
  "downscale": 2,
  "quality": 0.75
}

interval 要么 "frame" （每个渲染节拍，~60 Hz）或毫秒（数字，>=1）。建议使用数字间隔（50-100ms），除非您特别需要子刻度细节；在 "frame" 节奏编码器可能会落后，响应 dropped 计数告诉跳过了多少帧。每次通话上限为300帧。文件登陆 /debugbridge-recordings//.

mc_screen_inspect

快照玩家当前打开的屏幕（胸部UI、库存、前进屏幕等），并返回其结构。

{
  "includeIcons": false
}

集 includeIcons: true 将屏幕中的每个唯一项目呈现为小PNG，并附加由注册表id键入的图标映射。

mc_chat_history

获取最新的客户端聊天消息——用户在聊天中看到的内容。

{
  "limit": 50,
  "includeJson": false
}

集 includeJson: true 包含每条消息的完整Minecraft Component JSON（在聊天消息样式很重要时很有用）。

mc_nearby_entities

列出玩家半径内的实体（怪物、物品、投射物、玩家）。

{
  "range": 64,
  "limit": 100,
  "includeIcons": false
}

返回每个实体的id、类型、位置和主要设备摘要。通过 id 到 mc_entity_details, mc_set_entity_glow，或 mc_get_entity_item_texture 钻进去。

mc_entity_details

按id获取一个实体的完整详细信息（ id 字段返回 mc_nearby_entities 或 mc_looked_at_entity).

{
  "entityId": 12345
}

mc_looked_at_entity

返回玩家当前瞄准的实体id（光线投射），或 null 如果视线中没有任何东西。

{
  "range": 64
}

mc_nearby_blocks

列出附近的区块实体（标志、箱子、横幅、信标、料斗等）。不包括普通世界块——使用 mc_block_details 对于任何特定的职位。

{
  "range": 16,
  "limit": 100
}

mc_block_details

获取区块实体的详细信息，请访问 (x, y, z)：标志线、胸前物品、横幅图案等。

{
  "x": 100,
  "y": 64,
  "z": 200
}

mc_set_entity_glow

用团队颜色光晕勾勒出一个实体，以便用户可以发现它。通过 glow: false 移除。

{
  "entityId": 12345,
  "glow": true
}

mc_set_block_glow

突出显示世界上的一个块（1.19上的黄色轮廓，新版本上的香草光泽）。通过 glow: false 仅删除此位置。

{
  "x": 100,
  "y": 64,
  "z": 200,
  "glow": true
}

mc_clear_block_glow

清除通过设置的所有块高光 mc_set_block_glow 在一次通话中。

{}

mc_get_item_texture

将玩家库存插槽N中的项目渲染为附加为MCP图像内容的PNG。

{
  "slot": 0
}

mc_get_item_texture_by_id

渲染注册表id的默认纹理（例如。 minecraft:diamond)而不需要该物品在任何库存中。

{
  "itemId": "minecraft:diamond"
}

mc_get_entity_item_texture

渲染由另一个实体携带的物品。 slot 是 "mainhand", "offhand"，或其中一个护甲插槽名称。

{
  "entityId": 12345,
  "slot": "mainhand"
}

mc_run_command *（选择加入开发工具）*

执行Minecraft斜线命令。

{
  "command": "/give @s minecraft:diamond 64"
}

默认情况下禁用。 这两台服务器(MCDEV_RUN_COMMAND=1)以及DebugBridge模块(runCommandEnabled 在 BridgeConfig)必须选择加入。请参阅 选择加入/开发工具 在......下面

mc_script_logs *（选择加入开发工具）*

查看过去的文件备份日志 mc_execute 运行（时间戳、代码、结果、错误、持续时间），总结常见错误模式，或打印日志路径。

{
  "mode": "errors",
  "limit": 20
}

默认情况下禁用。 由...启用 MCDEV_SCRIPT_LOGS=1Claude Desktop MCPB将其公开为面向用户的切换（“日志脚本执行”）——请参阅 选择加入/开发工具.

选择加入/开发工具

两个运行时工具被封闭在环境变量后面，因此默认服务器只公开只读和“安全”的包装器。桥接mod有自己的匹配标志，因此如果mod没有选择加入，只打开服务器端的env什么也不做。

当env变量未设置（或设置为 0/false)，该工具根本没有注册，也不会出现在MCP客户端的工具列表中。

基于AST的Java索引器（预览版）

集 MCDEV_AST_PARSER=1 之前 init 或 rebuild 使用新 java解析器-备份索引器。与默认正则表达式解析器相比：

• 正确处理多行注释、嵌套泛型、记录、密封类型、模式匹配和lambda初始化字段（正则表达式解析器会默默地对每个字段进行错误计数）。
• 获取接口常数和 default/static 正则表达式解析器遗漏的接口方法。
• 不会将嵌套的类成员折叠到外部类型的列表中。

在Minecraft 1.21.11源代码（500个文件示例）的正面交锋中，AST解析器发现 约2×更多字段 和 减少约33%（正确归因）的方法 与正则表达式解析器相比。每个文件的速度大约慢4.5倍，因此完整的重新索引大约需要 75秒 而不是17——在一个 init 下载+反编译已经需要2-5分钟了。

MCDEV_AST_PARSER=1 npx mcdev-mcp init -v 1.21.11
# or, to re-index an already-decompiled version:
MCDEV_AST_PARSER=1 npx mcdev-mcp rebuild -v 1.21.11 --with-callgraph

MCP服务器盖章 manifest.indexerVersion 因此，它可以分辨出哪个解析器生成了现有的索引。当您翻转标记但尚未重建时，服务器会在下一次工具调用时为每个版本打印一个一次性提示：

[source-store/manifest:1.21.11] Index was built with the 'regex' parser, but the server is now running the 'ast' parser.
  This is fine — existing indices still work — but the new parser would produce a better index.
  Run `mcdev-mcp rebuild -v 1.21.11` (or `init -v 1.21.11` for a full re-fetch) to refresh.
  Set MCDEV_SUPPRESS_INDEXER_HINT=1 to silence this message.

需求

注： 建议使用Java 17+ callgraph 由于Gradle兼容性，命令。

CLI命令

通过调用 npx mcdev-mcp （或 node dist/cli.js 来自源校验）。

重新索引

要重新索引版本，请执行以下操作：

# Clean existing data for a version
npx mcdev-mcp clean -v 1.21.11 --all

# Re-initialize
npx mcdev-mcp init -v 1.21.11

建筑

mcdev-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── cli.ts                # CLI commands
│   ├── tools/
│   │   ├── static/           # Decompiled source tools
│   │   └── runtime/          # DebugBridge runtime tools
│   ├── decompiler/           # Vineflower integration
│   ├── indexer/              # Symbol index builder
│   ├── callgraph/            # Call graph generation & queries
│   └── storage/              # Source & index storage
└── dist/                     # Compiled output

运作原理

┌─────────────────────────────────────────────────────────────┐
│                     MCP Client (AI Agent)                    │
└─────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┴────────────────────┐
         ▼                                          ▼
┌─────────────────────────────┐    ┌──────────────────────────────────┐
│   Static Tools (8)          │    │   Runtime Tools (18 + 2 opt-in)  │
│  ┌────────────────────────┐ │    │  ┌────────────────────────────┐  │
│  │ mc_version             │ │    │  │ mc_connect / mc_execute    │  │
│  │ mc_search              │ │    │  │ mc_snapshot / mc_screenshot│  │
│  │ mc_get_class / method  │ │    │  │ mc_screen_inspect          │  │
│  │ mc_list_classes / pkgs │ │    │  │ mc_chat_history            │  │
│  │ mc_find_hierarchy      │ │    │  │ mc_nearby_entities + det.  │  │
│  │ mc_find_refs           │ │    │  │ mc_nearby_blocks   + det.  │  │
│  └───────────┬────────────┘ │    │  │ mc_looked_at_entity        │  │
│              │              │    │  │ mc_set_*_glow / mc_clear_* │  │
│       ┌──────┴──────┐       │    │  │ mc_get_item_texture (×3)   │  │
│       ▼             ▼       │    │  │ ─── opt-in (env-gated) ─── │  │
│  ┌─────────┐  ┌──────────┐  │    │  │ mc_run_command             │  │
│  │  Index  │  │Callgraph │  │    │  │ mc_script_logs             │  │
│  │ (JSON)  │  │ (SQLite) │  │    │  └─────────────┬──────────────┘  │
│  └────┬────┘  └────┬─────┘  │    │                │                 │
└───────┼────────────┼────────┘    │         ┌──────┴──────┐          │
        ▼            ▼              │         ▼             │          │
┌────────────────────────────┐      │   ┌──────────────┐    │          │
│ Decompiled Src (local)     │      │   │  WebSocket   │    │          │
│ (Vineflower)               │      │   │ to Minecraft │    │          │
└────────────────────────────┘      │   └──────┬───────┘    │          │
                                    └──────────┼────────────┘
                                               ▼
                                    ┌────────────────────────────┐
                                    │ DebugBridge Mod (in game)  │
                                    │ github.com/use-ai-for-mc/  │
                                    │ debugbridge                │
                                    └────────────────────────────┘

看 docs/ARCHITECTURE.md 详细的设计文档。

存储位置

mcdev-mcp 将所有缓存数据存储在操作系统标准缓存目录中，由 env-paths.此目录下的所有内容都是 可再生 --可以随时安全删除——以及 init 将在下次运行时重建所需的东西。

磁盘使用率：大约 每个Minecraft版本2 GB （JAR约60 MB，反编译源代码约1.8 GB，调用图数据库约200 MB，符号索引约50 MB）。跑 npx mcdev-mcp status 查看缓存了哪些版本，以及 npx mcdev-mcp clean --all （或 clean -v --all)以回收空间。

布局

/
├── tools/
│   └── vineflower.jar         # Decompiler, downloaded once
├── java-callgraph2/           # Call graph tool, cloned once
├── cache/
│   └── {version}/
│       ├── jars/               # Downloaded Minecraft client JARs
│       └── client/             # Decompiled Minecraft sources
├── index/
│   └── {version}/
│       ├── manifest.json       # Index metadata
│       └── minecraft/          # Per-package symbol indices
└── tmp/                        # Temporary files (cleaned by --all)

从1.0之前的安装升级？ 早期版本将所有内容存储在 ~/.mcdev-mcp/。如果您在那里有数据并想保留它，请手动将其移动到新位置（例如在macOS上： mv ~/.mcdev-mcp ~/Library/Caches/mcdev-mcp).否则，就跑吧 init 再次，下载步骤是幂等的。

发展

npm run build    # Compile TypeScript
npm test         # Run tests
npm run lint     # Lint code
npm run mcpb     # Build a Claude Desktop MCPB bundle for the current platform

释放

发布是由标签驱动的。推a v* 标签触发GitHub操作：

1. 运行完整的测试矩阵和TypeScript检查
2. 在上构建单个通用MCPB捆绑包 ubuntu-latest
3. 将包发布到npm
4. 使用创建GitHub版本 .mcpb 附上的

要剪切释放，请执行以下操作：

# 1. Bump the version. npm version only touches package.json; mirror the same
#    value into manifest.json by hand — the verify-version CI job hard-fails
#    if the two disagree with the tag.
npm version patch          # or: minor, major, 1.2.3, etc.
$EDITOR manifest.json      # set "version" to match package.json

# 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')"

# 3. Push the commit and the tag
git push --follow-tags

就是这样——工作流程 .github/workflows/ci.yml 处理剩下的。不 NPM_TOKEN 需要秘密；工作流通过以下方式发布到npm 可信发布 （OIDC）。必须在包的发布访问设置下的npm端配置受信任的发布者：owner use-ai-for-mc，回购 mcdev-mcp，工作流程 ci.yml.Releases还通过以下方式提供npm来源证明 npm publish --provenance.

MCPB构建也可以在本地运行：

npm run mcpb
# → dist-mcpb/mcdev-mcp-.mcpb

该捆绑包是通用的——纯JavaScript+ sql.js （SQLite编译为WebAssembly），没有本机二进制文件。相同 .mcpb 适用于macOS（arm64和x86_64）、Linux（x64/arm64）和Windows。运行时需要节点≥20（从 package.json engines).

在Claude Desktop中安装MCPB

局限性

• 静态分析: mc_find_refs 无法通过反射、JNI回调或动态创建的lambda/方法引用来跟踪调用
• 仅限客户端：服务器端类不包括在静态分析中
• 运行时工具：要求Minecraft与 DebugBridge 已安装mod

法律声明

此工具反编译Minecraft源代码以供开发参考。请尊重Mojang的知识产权：

您可以：

• 分解和研究代码以理解和学习
• 利用这些知识开发不包含大量Mojang代码的模组
• mod开发的引用类/方法名称

您不得：

• 分发反编译的源代码
• 分发Minecraft的修改版本
• 未经许可在商业上使用反编译代码

根据 Minecraft最终用户许可协议: *“您不得分发我们游戏或软件的任何修改版本”* 和 *“Mods可以分发；游戏客户端或服务器软件的黑客版本或修改版本不可以分发。”*

此工具用于 仅供参考 --不要将反编译的代码直接复制到项目中。

第三方组件

本项目包括或使用以下许可证下的第三方软件：

• 分解器MC （麻省理工学院）-在 src/decompiler/
• 葡萄花 （Apache-2.0）——用于源代码生成的Java反编译器
• java-callgraph2 --在运行时克隆以生成静态调用图

其他运行时依赖项（下载/使用）：

• 莫疆 --官方ProGuard映射和Minecraft客户端JAR

看 许可证 获取完整的许可证文本和第三方归属。

许可证

麻省理工学院 --版权所有（c）2025 mcdev-mcp贡献者