mc-mod-mcp

一个 MCP 服务器，可在你编写 Minecraft 模组时为 Claude 提供基于事实的解答。

它针对模组开发领域中目前依然活跃的两个时代——1.8.9（Forge/MCP，Java 8，Hypixel 风格客户端模组）和 1.21.10+（NeoForge 或 Fabric，Java 21，Mojang 映射，数据组件）。对于 1.21.x，它还可以针对 linkie 进行实时映射查询，并在 linkie 尚未获取最新版本时直接从 piston-meta 拉取映射。

如果没有这个工具，Claude 往往会混淆这两个时代，幻觉出 new ResourceLocation(...)（自 1.20.5 起已移除），忘记物品现在使用数据组件（Data Components）而非 NBT，以及在编写 ServerboundUseItemPacket 时遗漏新的 sequence/yaw/pitch 字段。有了它，模型就有事实可查，而不是靠猜名字。

安装

git clone https://github.com/ratph6/mc-mod-mcp
cd mc-mod-mcp
npm install
npm run build

然后将 Claude Code 指向构建好的二进制文件：

claude mcp add mc-mod node "$PWD/dist/index.js"

（或者如果你愿意，可以手动编辑 ~/.claude/config.json）。

使用方法

直接用简单的英语提问即可。Claude 会自动选择工具。以下是一些实际使用示例：

How do I send a useItem packet in 1.21.10 Fabric?
Translate this 1.8.9 snippet to 1.21+: Minecraft.getMinecraft().thePlayer.addChatMessage(new ChatComponentText("hi"))
Scaffold a NeoForge 1.21.10 mod main class for examplemod
Show me a @ModifyVariable mixin example
What's the Yarn name for LocalPlayer in 1.21.10?

工具

名称	功能
`mc_version_info`	加载器、Java、映射、构建系统、特定时代的文档链接
`mc_lookup_class`	针对某个概念（`Block`, `Level`, `BlockEntity` 等）查询 1.8.9 与 1.21+ 的全限定类名
`mc_lookup_api`	任务的标准代码片段（发送聊天、打开 GUI、注册方块等）
`mc_translate`	给定一个时代的符号，建议另一个时代的等效项
`mc_event`	“X 事件在何时触发？”——提供 1.8.9 + NeoForge + Fabric 的答案
`mc_mixin`	Mixin 模式目录（`@Inject`, `@ModifyArg`, `@WrapOperation`, `@Accessor` 等）及 mixin 配置 JSON
`mc_gotchas`	特定时代的陷阱——数据组件、ResourceLocation 工厂、mod bus 与 game bus 等。可过滤。
`mc_gradle`	针对特定时代 + 加载器的 `build.gradle` / `settings.gradle` / `gradle.properties`
`mc_mappings_translate`	Yarn ↔ Mojang 类名翻译（精选）
`mc_list_scaffolds`	枚举脚手架模板
`mc_scaffold`	生成样板代码（模组主类、物品/方块、指令、按键绑定、mixin、网络数据包等）
`mc_docs`	特定时代的文档链接
`mc_list_versions`	实时：linkie 所知的每个版本，按命名空间分类
`mc_mappings_search`	实时：针对 linkie 映射 API 的全文搜索
`mc_lookup_field`	实时：针对 linkie 的字段名查询（精选表格不跟踪字段）
`mc_mojang_mappings`	通过 piston-meta 直接拉取 Mojang 的 `client_mappings.txt`。用于 26.1.x 及任何 linkie 无法处理的版本。

前十二个是精选的——速度快、确定性高、无需联网。后四个按需联网。

扩展

知识以扁平数据的形式存储在 src/knowledge.ts 中。向 CLASSES / METHODS / EVENTS / MIXIN_PATTERNS / GOTCHAS / YARN_TO_MOJANG / GRADLE_TEMPLATES 添加条目，运行 npm test 即可。脚手架是同一文件中的模板函数，通过 SCAFFOLD_KINDS 列出。

src/
  index.ts          MCP server, tool definitions, stdio transport
  knowledge.ts      Curated data + scaffold templates
  linkie.ts         Live calls to linkie's mappings API
  mojang.ts         Live piston-meta + proguard parser
  smoke.test.ts     node:test smoke tests