Minecraft 1.21.1 Forge/NeoForge MCP Server

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