SaltfishSheep/AI-MCP-NativeMinecraftAccess
GitHub: SaltfishSheep/AI-MCP-NativeMinecraftAccess
为 AI 编程智能体提供 Minecraft 混淆名称映射查找的 MCP 服务器，支持跨版本快速检索类、方法和字段。
Stars: 1 | Forks: 0
[English](README.md) | [中文](README_zh-CN.md)
# 原生 MC Mapping MCP Server
一个提供 Minecraft 混淆名称映射查找的 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器。帮助 AI 编程智能体处理 Minecraft 混淆的 Java 内部结构——用于 mod 开发、插件开发、Mixin、Access Transformers、基于反射的脚本编写等。
## 它的功能
Minecraft 的 Java 代码在运行时会被混淆——类、方法和字段名称会被替换为简短且无意义的标识符（`aed`、`func_70091_d`、`m_91087_`）。此 MCP 服务器让你的 AI 智能体能够：
- **搜索混淆 ↔ 反混淆映射**，支持 38 个 Minecraft 版本（1.7.10 – 1.20.1）
- **首次使用时自动构建映射缓存**——从 NeoForge Maven 和 Mojang 服务器下载
- **布尔表达式搜索**——`Entity&Player`、`{Block|Item}&client`、`func_149645`
### 使用场景
| 场景 | 如何提供帮助 |
|----------|---------------|
| **Forge / NeoForge 模组开发** | 编写 mixin 或 AT 配置时查找混淆的方法/字段名称 |
| **Fabric 模组开发** | 查找用于 access widener 的 intermediary ↔ named 映射 |
| **Spigot / Paper 插件** | 解析跨版本的 NMS (net.minecraft.server) 类名 |
| **Mixin / Access Transformers** | 发现需要定位的精确混淆名称 |
| **基于反射的代码** | 查找用于 `getDeclaredField`、`getMethod` 等的字段/方法名称 |
| **脚本引擎** | 解析原生 Minecraft API 名称（CustomNPCs、CraftTweaker 等） |
| **移植模组** | 比较 MC 版本间的映射以查找重命名的 API |
### MCP 工具
| 工具 | 描述 |
|------|-------------|
| `search` | 搜索 Minecraft 混淆的类/方法/字段名称映射 |
## 快速安装（MCP 客户端）
### 前置条件
- **Node.js ≥ 18**
### 第 1 步：克隆与构建
```
git clone https://github.com/SaltfishSheep/AI-MCP-NativeMinecraftAccess.git
cd AI-MCP-NativeMinecraftAccess
npm install
npm run build
```
### 第 2 步：添加到你的 MCP 客户端
将以下内容添加到你的 MCP 客户端配置中：
**Claude Desktop** (`claude_desktop_config.json`)：
```
{
"mcpServers": {
"native-mc-access": {
"command": "node",
"args": ["/absolute/path/to/AI-MCP-NativeMinecraftAccess/dist/index.js"]
}
}
}
```
**OpenCode** (`opencode.json`)：
```
{
"mcp": {
"native-mc-access": {
"type": "local",
"command": ["node", "/absolute/path/to/AI-MCP-NativeMinecraftAccess/dist/index.js"],
"enabled": true
}
}
}
```
**Cursor** (`.cursor/mcp.json`)：
```
{
"mcpServers": {
"native-mc-access": {
"command": "node",
"args": ["/absolute/path/to/AI-MCP-NativeMinecraftAccess/dist/index.js"]
}
}
}
```
**Windsurf** (`~/.codeium/windsurf/mcp_config.json`)：
```
{
"mcpServers": {
"native-mc-access": {
"command": "node",
"args": ["/absolute/path/to/AI-MCP-NativeMinecraftAccess/dist/index.js"]
}
}
}
```
## 用法
配置完成后，你的 AI 智能体就可以调用 `search` 工具了：
```
search(mc_version="1.12.2", expression="Entity&Player")
```
**查询示例：**
| 查询 | 描述 |
|-------|-------------|
| `Entity&Player` | 同时包含 "Entity" 和 "Player" 的条目 |
| `Entity::classname` | 类名恰好为 "Entity" |
| `walk:method` | 名称中包含 "walk" 的方法 |
| `static::modifier` | is_static 或访问权限精确匹配 "static" |
| `Potion:classname&Duration:name` | 类名为 "Potion"，名称为 "Duration" |
| `{Block\|Item}&client` | 客户端的 Block 或 Item 条目 |
| `func_70091_d` | 根据 ID 查找特定的 SRG 方法名 |
| `KeyBinding` | 所有提及 KeyBinding 的条目 |
| `output="%deobf_class%"` | 去重后的类列表 |
**表达式语法：**
| 语法 | 含义 | 示例 |
|--------|---------|---------|
| `term` | 不区分大小写的子字符串匹配（大小写完全匹配得分更高） | `KeyBinding` |
| `term:modifier` | 将搜索限制在特定列 | `Potion:classname`, `walk:method` |
| `term::modifier` | 强修饰符——要求完全匹配 | `Entity::classname` |
| `net.minecraft.Entity` | 点号表示法——匹配 `net/minecraft/Entity` 和 `net/minecraft$Entity` | `net.minecraft.entity.Entity` |
| `&` | AND（两者都必须匹配，优先级更高） | `Entity&Living` |
| `\|` | OR（匹配任意一个即可） | `Entity\|Player` |
| `{}` | 分组 | `{a\|b}&c` |
**修饰符：**
| 修饰符 | 搜索范围 | 描述 |
|----------|----------|-------------|
| `all` | 所有列 | 默认——搜索所有内容 |
| `class` | obf_class, deobf_class | 完整类路径（例如：`net/minecraft/entity/Entity`） |
| `classname` | deobf_class（最后一个 `/` 之后的部分） | 仅类名（例如：`net/minecraft/entity/Entity` 中的 `Entity`） |
| `package` | deobf_class（最后一个 `/` 之前的部分） | 仅包名（例如：`net/minecraft/entity`） |
| `name` | obf_name, deobf_name, srg_name | 字段/方法名称（仅限方法+字段） |
| `method` | obf_name, deobf_name, srg_name | 仅方法名（过滤 type=method） |
| `field` | obf_name, deobf_name, srg_name | 仅字段名（过滤 type=field） |
| `desc` | obf_desc, deobf_desc | 方法描述符 |
| `modifier` | access, is_static | 访问级别和静态状态 |
| `side` | sideonly | 端过滤器（common/server/client） |
提示：使用 `Player&Entity` 而不是 `PlayerEntity` 可以实现跨版本兼容，因为不同 MC 版本的命名规范有所不同。
## 支持的版本
涵盖 4 种工作流类型的 38 个 Minecraft 版本：
| 工作流 | 版本 | 数据源 |
|----------|----------|--------------|
| Legacy SRG | 1.7.10, 1.8–1.11.2 | SRG ZIP + MCP Stable CSV |
| Legacy TSRGv1 | 1.12.2–1.15.2 | TSRGv1 + MCP Stable CSV + static_methods + constructors |
| Legacy ProGuard | 1.16.1–1.16.5 | TSRGv1 + Mojang ProGuard |
| Modern | 1.17–1.20.1 | TSRGv2 + Mojang ProGuard |
## 工作原理
1. 在首次搜索某个 MC 版本时，服务器会从 [NeoForge Maven](https://maven.neoforged.net/) 和 [Mojang](https://piston-data.mojang.com/) 下载映射数据
2. 它会解析 SRG/TSRG/ProGuard 格式，并将其与 MCP CSV 数据合并
3. 合并后的缓存会存储为 `.mapping-caches/.csv`
4. 后续搜索将使用缓存的数据（会根据 `package.json` 版本进行验证）
5. 布尔表达式将被解析为 AST，并针对所有 CSV 行进行求值
## 输出格式
```
Found 382 results for "Entity&Player" in MC 1.12.2 (page 1/39)
1. [method] aed.cD -> net/minecraft/entity/player/EntityPlayer.getAbsorptionAmount srg=func_110139_bj desc=()F sideonly=common match=2.0 mismatch=42
2. [method] aed.bM -> net/minecraft/entity/player/EntityPlayer.applyEntityAttributes srg=func_110147_ax desc=()V sideonly=common match=2.0 mismatch=42
...
```
## 项目结构
```
AI-MCP-NativeMinecraftAccess/
├── package.json
├── tsconfig.json
├── src/
│ ├── index.ts # MCP server entry point
│ ├── types.ts # TypeScript type definitions
│ ├── util.ts # Shared utilities (CSV parsing, package version)
│ ├── version-table.ts # URL mapping table for 38 MC versions
│ ├── builder/
│ │ ├── index.ts # buildMappingCache entry point
│ │ ├── download.ts # HTTP fetch + minimal ZIP reader
│ │ ├── parsers.ts # SRG, TSRGv1, TSRGv2, ProGuard, CSV parsers
│ │ ├── workflows.ts # 4 merge workflow builders
│ │ └── cache.ts # CSV cache writer + validator
│ └── search/
│ ├── index.ts # Re-exports
│ ├── expression.ts # Boolean expression parser (AND/OR/braces)
│ └── csv-reader.ts # CSV reader + paginated search
├── dist/ # Built JavaScript (entry: dist/index.js)
└── .mapping-caches/ # Generated cache files (gitignored)
```
## 许可证
MIT 许可证——详见 [LICENSE](LICENSE)。
### 第三方数据
- **Mojang 映射** —— 在 [Mojang 的自定义许可证](https://account.mojang.com/documents/minecraft_eula)下提供。本服务器在运行时获取它们；不会对其进行重新分发。
- **MCP 映射** —— 由 Mod Coder Pack 社区维护，通过 NeoForge Maven 分发。
标签：AI, GNU通用公共许可证, MCP, Minecraft, MITM代理, Mod开发, Node.js, 工具, 自动化代码审查, 自动化攻击