内容
<div align="center">
# Cleanroom Modding MCP
### 🤖 一个用于构建Cleanroom（Minecraft 1.12.2）模组并配备AI代理的MCP服务器
_Cleanroom / Forge 1.12.2 生态系统的文档、SRG映射和跨加载器移植知识_
[](https://opensource.org/license/gpl-3.0)
[](https://nodejs.org/)
</div>
## 这是什么？
**cleanroom-modding-mcp** 是一个 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，其目标是使AI代理在1.12.2模组开发方面的能力与资深模组开发者相当。它主要服务于以下三个工作流程：
1. **从零开始的 [Cleanroom](https://github.com/CleanroomMC/Cleanroom) 模组开发** — Cleanroom是Minecraft 1.12.2的Forge模组加载器的延续，运行于Java 25+，并内置混入（mixin）支持。
2. **移植到Cleanroom** — Fabric和NeoForge的代码库被保留为 *移植参考*：可搜索的源加载器文档，用于将模组移植到1.12.2。
3. **移植回Cleanroom** — 现代Minecraft知识（文档、Parchment/Mojang映射）作为反移植的源侧。
> **状态：** 该项目是从 [`OGMatrix/mcmodding-mcp`](https://github.com/OGMatrix/mcmodding-mcp) 分叉并重新定向的，按照 [DESIGN.md](DESIGN.md) 进行改造。分发层和身份已完成；Cleanroom特定的代码库和工具将逐步落地。
## 快速开始
将以下内容添加到您的MCP客户端配置文件（例如 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"cleanroom": {
"command": "npx",
"args": ["cleanroom-modding-mcp"]
}
}
}
```
文档数据库在安装时自动下载（并在启动时自动更新）。可选数据库可以通过以下命令安装：
```bash
npx cleanroom-modding-mcp manage
```
## 数据库
所有数据库资产都附在该仓库的 `v{version}` GitHub Releases上，并通过SHA256清单验证。
| 数据库 | 文件 | 已安装 | 自动更新 |
| --- | --- | --- | --- |
| 📚 文档 | `docs.db` | 自动（安装后/首次使用） | 每次启动 |
| 🗺️ 映射 | `mappings.db` | 通过 `manage`（预构建下载或本地1.12.2构建） | 安装后¹ |
| 🧩 模组示例 | `examples.db` | 通过 `manage` | 安装后 |
| 🧬 Cleanroom API | `cleanroom-api.db` | 通过 `manage` | 安装后 |
¹ 映射数据库也可以 **在设备上构建** — `npx cleanroom-modding-mcp manage --build-mappings` 获取MCP源代码（~730 KB from `maven.outlands.top` / `maven.minecraftforge.net`）并在1分钟内本地构建1.12.2 MCP/SRG数据（无需现代参考版本）。本地构建的数据库永远不会被自动更新覆盖；可以通过 `manage` 显式切换回预构建的数据库。
数据库存放在共享的平台标准数据目录中：
- Linux: `$XDG_DATA_HOME/cleanroom-modding-mcp` （默认为 `~/.local/share/cleanroom-modding-mcp`）
- macOS: `~/Library/Application Support/cleanroom-modding-mcp`
- Windows: `%APPDATA%/cleanroom-modding-mcp`
## 工具
四个基本工具始终可用；映射和模组示例工具组在安装其可选数据库时自动注册。
| 工具 | 用途 |
| --- | --- |
| `search_docs` | 混合全文 + 语义搜索。作用域 `target`（Cleanroom/Forge 1.12.2，默认），`reference`（Fabric/NeoForge移植材料），或 `all` |
| `get_example` | 模组开发主题的代码示例，按作用域/加载器/版本过滤 |
| `explain_concept` | 从加载器角度（默认为Cleanroom）解释概念 — 功能，SRG名称，混入，`mcmod.info`，… |
| `list_targets` | 定位：加载器/版本矩阵，索引版本，已安装数据库 |
| `resolve_symbol` | 崩溃日志主力：解析任意符号（SRG `func_/field_/p_`，混入notch令牌，可读名称）到所有映射层（需要 `mappings.db`） |
| `search_mappings`, `get_class_details`, `get_method_signature`, `list_mapping_versions`, `browse_package` | Minecraft类/方法/字段映射 — 1.12.2 MCP/SRG（默认）+ 现代Parchment/Mojang反移植参考（需要 `mappings.db`） |
| `search_cleanroom_api`, `get_api_class` | Cleanroom/Forge框架API表面（`com.cleanroommc.*`，`zone.rong.mixinbooter.*`，`net.minecraftforge.*`）：类，事件目录，注释目录，签名 + 来自固定Cleanroom源的Javadoc（需要 `cleanroom-api.db`） |
| `search_mod_examples`, `get_mod_example`, `list_canonical_mods`, `list_mod_categories`, `get_mod_patterns` | 精选模组示例（需要 `examples.db`） |
## 环境变量
| 变量 | 影响 |
| --- | --- |
| `CLEANROOM_MCP_DATA_DIR` | 覆盖共享数据目录 |
| `CLEANROOM_MCP_SKIP_AUTO_UPDATE` | 跳过启动数据库更新检查 |
| `DB_PATH` | 文档数据库文件的显式路径（**不**禁用自动更新，自动更新会指向默认路径） |
| `GITHUB_REPO_URL` | 覆盖用于发布查找的GitHub API仓库基准 |
| `GITHUB_TOKEN` | 用于发布后安装的身份验证GitHub API请求（速率限制） |
## 开发
```bash
pnpm install # 安装依赖
pnpm run build # 编译到 dist/
pnpm test # vitest
pnpm run validate # 类型检查 + 校验 + 测试
pnpm run index-docs # 爬取 + 将文档语料库索引到 data/docs.db
pnpm run index-mappings # 构建 data/mappings.db
pnpm run manifest -- --db docs --release-tag v0.5.0 # 生成发布清单
```
### 分发约定
每个数据库及其 `<id>-manifest.json` 都上传到主要的 `v{version}` 发布版本 — 没有每个数据库的单独发布标签。清单生成器（`scripts/generate-manifest.ts`），安装程序（`manage`），发布后安装和启动自动更新程序都读取 [`src/dbs.ts`](src/dbs.ts) 中的单个注册表；其他文件不得硬编码数据库文件名或仓库slug。
## 致谢与许可证
GPL-V3。从 [OGMatrix/mcmodding-mcp](https://github.com/OGMatrix/mcmodding-mcp) 分叉；为 [CleanroomMC](https://github.com/CleanroomMC) 生态系统重新定向（与CleanroomMC无关）。
