Minecraft 1.21.1 Forge/NeoForge MCP Server

一个 MCP (Model Context Protocol) 服务器，提供 MC 1.21.1 Forge (52.0.x) 和 NeoForge (21.1.x) API 文档浏览、代码生成与审查能力。

特性

• 20 个 MCP 工具：搜索 / 浏览 / 详情 / 事件 / 代码生成 / 代码审查
• 双 Loader 支持：Forge 与 NeoForge 的 API / 事件 / 模板均独立处理
• 智能搜索引擎：7 层搜索策略（精确匹配 → 类名 → 事件 → 前缀 → 子串 → CamelCase → 模糊）
• 代码生成：Mod 项目 / 方块 / 物品 / 实体 / 事件处理器 / 网络包 / 数据生成器模板
• 代码审查：16+ 规则检查常见 Modding 反模式
• 知识库：10 个核心主题（延迟注册、事件系统、客户端/服务端分离等）

快速开始

1. 安装依赖

npm install

2. 生成文档（可选但推荐）

文档生成需要 Gradle 缓存中的反编译源码。只要你曾经构建过一个 NeoForge/Forge mod 项目（./gradlew build），源码就已经在缓存里了。

npm run generate-docs

生成器会自动搜索以下位置：

Loader	Gradle 缓存路径
NeoForge	~/.gradle/caches/neoformruntime/intermediate_results/sourcesWithNeoForge_*.zip
NeoForge sources JAR	~/.gradle/caches/modules-2/files-2.1/net.neoforged/neoforge/
Forge	~/.gradle/caches/forge_gradle/minecraft_user_repo/
Forge sources JAR	~/.gradle/caches/modules-2/files-2.1/net.minecraftforge/forge/

也可以手动指定源码路径：

MC_SOURCE_JAR=/path/to/sources.jar npm run generate-docs

3. 构建

npm run build

4. 在 VS Code 中配置

在 VS Code 的 settings.json 或 .vscode/mcp.json 中添加：

{
  "mcpServers": {
    "mc-1.21.1": {
      "command": "node",
      "args": ["c:/Users/你的用户名/Desktop/1-21-1-modmcp/dist/src/index.js"],
      "env": {
        "MC_DOCS_DIR": "c:/Users/你的用户名/Desktop/1-21-1-modmcp/docs"
      }
    }
  }
}

工具列表

搜索

工具	描述
search_docs	全文模糊搜索 API 文档
search_api	按类名 / 分类 / 加载器过滤的结构化搜索

API 详情

工具	描述
get_api_detail	获取 API 或类的完整文档
get_document	获取指定路径的文档
get_document_section	获取文档中的特定章节

事件

工具	描述
search_events	搜索 Forge/NeoForge 事件
get_event_detail	获取事件详细信息及用法示例

浏览

工具	描述
browse_api_category	浏览 API 分类列表
list_documents	列出所有可用文档
get_registry_info	获取注册表信息

代码生成

工具	描述
generate_mod_project	生成 Mod 项目骨架
generate_block	生成自定义方块
generate_item	生成自定义物品
generate_entity	生成自定义实体
generate_event_handler	生成事件处理器
generate_network_packet	生成网络数据包
generate_data_provider	生成数据生成器

其他

工具	描述
review_mod_code	审查 Mod 代码并提供改进建议
get_modding_knowledge	获取特定主题的 Modding 知识
list_knowledge_topics	列出所有知识库主题

知识库主题

1. deferred-register — 延迟注册系统
2. event-system — 事件总线与订阅
3. client-server-separation — 客户端/服务端分离
4. datagen — 数据生成器
5. networking — 网络通信
6. capabilities — 能力系统 (Forge) / 附件系统 (NeoForge)
7. creative-tabs — 创造模式标签页
8. block-entity — 方块实体
9. access-transformers — AT 访问转换器
10. mod-config — Mod 配置
11. mixins — Mixin 注入

关于 Mojang 映射

MC 1.21.1 仍然使用混淆发布，但通过 Mojang 官方映射表 (Official Mappings) 反混淆后，源码即为人类可读的名称。Parchment 在此基础上补充了方法参数名。

只要你曾构建过 NeoForge/Forge mod 项目，反编译源码就已经在 Gradle 缓存中了。

技术栈

• TypeScript + Node.js (ESM)
• @modelcontextprotocol/sdk — MCP 协议 SDK
• zod — 参数校验
• adm-zip — 读取源码 JAR/ZIP

License

MIT