内容
# @adhisang/minecraft-modding-mcp
[](https://www.npmjs.com/package/@adhisang/minecraft-modding-mcp)
[](LICENSE)
[](https://nodejs.org/)
[](https://github.com/adhi-jp/minecraft-modding-mcp/actions/workflows/ci.yml)
**English** | [日本語](docs/README-ja.md)
> **Note**: This project is entirely vibe-coded — built with AI-assisted development without formal specs.
---
`@adhisang/minecraft-modding-mcp` 是一个用于 AI 辅助 Minecraft 模组工作流的 MCP 服务器，基于 [Model Context Protocol](https://modelcontextprotocol.io/) 构建。当智能体需要检查 Minecraft 源代码、解析映射、比较版本、分析模组 JAR、验证 Mixin、Access Widener 或 Access Transformer 文件，或使用 MCP 客户端处理 NBT 和注册表数据时，可以使用它。
它运行在 stdio 上，并与 Claude Desktop、Claude Code、VS Code、Codex CLI、Gemini CLI 和其他支持 MCP 的客户端配合使用。
**41 个工具**（6 个入口 + 35 个专家）| **9 个资源** | **4 个命名空间映射** | **SQLite 支持的缓存**
## 功能
- **源代码探索**：浏览、列出和搜索反编译的 Minecraft 源代码，带有行级上下文
- **映射感知符号工作**：在 `obfuscated`、`mojang`、`intermediary` 和 `yarn` 之间转换类、字段和方法名称
- **版本比较**：比较 Minecraft 版本之间的类签名、注册表条目和迁移导向的摘要
- **模组 JAR 分析**：读取 Fabric、Forge 和 NeoForge 元数据、入口点、Mixin 配置、依赖项、源代码和重映射预览
- **项目验证**：验证 Mixin 源代码、`.accesswidener` 文件和 Forge/NeoForge Access Transformer 文件针对目标版本
- **NBT、注册表、缓存和诊断**：修补 NBT 有效载荷、检查生成的注册表数据和管理缓存/运行时状态
- **MCP 资源**：通过 URI 资源的版本、类源代码、工件元数据和映射
## 快速入门
### 包用户
需求：
- Node.js 22+
- Java 仅在 `remap-mod-jar` 和反编译或重映射流程需要 Vineflower 或 tiny-remapper 时需要
在本地启动服务器：
```bash
npx -y @adhisang/minecraft-modding-mcp
```
在 MCP 客户端配置中使用相同的命令。如果自动 JAR 下载在您的环境中被阻止，请设置 `MCP_VINEFLOWER_JAR_PATH` 和 `MCP_TINY_REMAPPER_JAR_PATH`。
### 客户端设置
CLI 客户端可以直接注册包命令。
Claude Code：
```bash
claude mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp
```
OpenAI Codex CLI：
```bash
codex mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp
```
运行 `claude mcp list` 或 `codex mcp list` 以验证服务器可用。
stdio 传输自动检测换行符分隔和 `Content-Length` 帧，因此相同的服务器命令适用于 Codex 和标准 MCP 客户端。
#### Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"minecraft-modding": {
"command": "npx",
"args": ["-y", "@adhisang/minecraft-modding-mcp"]
}
}
}
```
#### VS Code
将以下内容添加到 `.vscode/mcp.json` 到您的工作区：
```json
{
"servers": {
"minecraft-modding": {
"command": "npx",
"args": ["-y", "@adhisang/minecraft-modding-mcp"]
}
}
}
```
#### Gemini CLI
将以下内容添加到 `~/.gemini/settings.json`：
```json
{
"mcpServers": {
"minecraft-modding": {
"command": "npx",
"args": ["-y", "@adhisang/minecraft-modding-mcp"]
}
}
}
```
然后运行：
```text
/mcp list
```
#### 自定义环境
传递环境变量以覆盖默认值：
```json
{
"mcpServers": {
"minecraft-modding": {
"command": "npx",
"args": ["-y", "@adhisang/minecraft-modding-mcp"],
"env": {
"MCP_CACHE_DIR": "/path/to/custom/cache",
"MCP_MAPPING_SOURCE_PRIORITY": "maven-first"
}
}
}
}
```
当构建使用非默认的 Gradle 用户主目录时，请传递 `gradleUserHome` 在缓存支持的源代码、映射、验证和工作流调用上。该服务器将其视为每个调用的 Gradle 用户主目录，并在 `<gradleUserHome>/loom-cache` 和 `<gradleUserHome>/caches/fabric-loom` 之前搜索，而不是 MCP 进程默认的。
## 从这里开始
这六个顶级工作流工具涵盖了常见路径并返回摘要优先的结果。它们是智能体和 MCP 客户端的最佳默认起点。
所有六个返回 `result.summary` 首先，并且可以在有明确后续步骤时包含 `summary.nextActions`。从表格中选择工具，然后使用示例和参考文档获取确切的有效载荷。
| 工具 | 从这里开始 |
| --- | --- |
| `inspect-minecraft` | 版本、工件、类、文件和源代码搜索 |
| `analyze-symbol` | 符号存在检查、映射转换、生命周期跟踪和工作区符号解析 |
| `compare-minecraft` | 版本对差异、类差异、注册表差异和迁移导向概述 |
| `analyze-mod` | 模组元数据、反编译/搜索流程、类源代码和安全重映射预览/应用 |
| `validate-project` | 工作区摘要加上直接 Mixin、Access Widener 和 Access Transformer 验证 |
| `manage-cache` | 缓存库存、验证和预览/应用清理工作流 |
### 工作流笔记
这些笔记涵盖了入职培训期间的高频决策。有关完整的陷阱列表、确切的合同、迁移说明和环境变量，请参阅 [docs/tool-reference.md](docs/tool-reference.md)。
- `search-class-source` 默认 `queryMode="auto"` 并保留分隔符查询，如 `foo.bar`、`foo_bar` 和 `foo$bar` 在索引路径上。使用 `queryMode="literal"` 进行显式全子字符串扫描。
- 如果您已经没有工件，请为 `inspect-minecraft` 优先选择 `subject.kind="workspace"` 而不是猜测工件详细信息。当工件上下文是唯一缺少的输入时，可重试的 `suggestedCall` 保留请求任务。
- `trace-symbol-lifecycle` 期望 `Class.method` 在 `symbol` 中。 在单独的 `descriptor` 字段中保留确切的重载匹配。
- 对于 `26.1+` 等非混淆版本，`check-symbol-exists` 和 `analyze-symbol task="exists"` 验证 `mojang` 查找是否针对运行时字节码（当没有映射图存在时），并在运行时 JAR 本身无法访问时返回 `mapping_unavailable`。
- `analyze-mod` 和 `validate-project` 需要结构化的 `subject` 对象和规范的 `include` 组；过时的字符串主题或域包含有效载荷返回 `ERR_INVALID_INPUT` 并带有可重试的 `suggestedCall`。
- `validate-project task="project-summary"` 在发现的 Mixin、Access Widener 和 Access Transformer 检查中传播 `preferProjectVersion=true`。如果无法从请求或 `gradle.properties` 解析版本，则摘要返回恢复指导而不是猜测。
- `validate-mixin` 和 `validate-project` 保持 `mapping-health` 轻量级用于 `obfuscated` 和 `mojang` 验证，避免除 `intermediary` 或 `yarn` 命名空间请求外完整的 Tiny 映射图加载。
- `validate-project task="project-summary"` 使用轻量级工件探针进行 `tasks["minecraft.artifact.resolved"]`；它不反编译 Minecraft 或重建源索引仅报告探针状态。设置 `VALIDATE_PROJECT_TASKS_OFF=1` 以省略附加 `tasks` 字段。
- 如果工作区使用 `GRADLE_USER_HOME=/tmp/...` 或另一个隔离的 Gradle 主目录构建，请传递该路径作为 `gradleUserHome`，以便源代码、映射、运行时和项目验证查找使用相同的 Loom 缓存，而不是 MCP 进程主目录下的过时缓存。
- `manage-cache` 在 `cacheKinds: ["binary-remap"]` 下报告损坏的 Mojang 二进制重映射缓存目录，状态为 `corrupt`，并且可以通过 `selector.artifactId` 在预览/应用工作流中删除。
### 检查 Minecraft 源代码的版本
```json
{
"tool": "inspect-minecraft",
"arguments": {
"task": "class-source",
"subject": {
"kind": "class",
"className": "net.minecraft.server.Main",
"artifact": {
"type": "resolve-target",
"target": {
"kind": "version",
"value": "1.21.10"
}
}
}
}
}
```
### 映射或检查符号
```json
{
"tool": "analyze-symbol",
"arguments": {
"task": "map",
"subject": {
"kind": "method",
"owner": "net.minecraft.server.Main",
"name": "tickServer"
},
"version": "1.21.10",
"sourceMapping": "mojang",
"targetMapping": "intermediary",
"signatureMode": "name-only",
"detail": "standard"
}
}
```
### 总结模组 JAR
```json
{
"tool": "analyze-mod",
"arguments": {
"task": "summary",
"subject": {
"kind": "jar",
"jarPath": "/path/to/mymod-1.0.0.jar"
}
}
}
```
### 验证工作区
```json
{
"tool": "validate-project",
"arguments": {
"task": "project-summary",
"subject": {
"kind": "workspace",
"projectPath": "/workspace/modid",
"discover": ["mixins", "access-wideners", "access-transformers"]
},
"preferProjectVersion": true,
"preferProjectMapping": true
}
}
```
工作区摘要仍默认为发现混淆和访问扩展器。在摘要运行中添加 `"access-transformers"` 到 `subject.discover`。
## 文档
- [详细示例请求](docs/examples.md) 用于复制有效载荷和常见工作流
- [工具和配置参考](docs/tool-reference.md) 用于确切的输入、输出、资源行为、环境变量和迁移说明。从 [Which Tool for Which Question](docs/tool-reference.md#which-tool-for-which-question) 决策表开始，当您不确定要调用哪个工具时。
## 工具表面
从这些顶级工作流工具开始，除非您已经知道您想要的确切专业操作。较低级别的工具仍然可用于狭隘的后续工作和自动化。
### 顶级工作流工具
<!-- BEGIN GENERATED TOOL TABLE: top-level-workflow-tools -->
| 工具 | 目的 |
| --- | --- |
| `inspect-minecraft` | 检查版本、工件、类、文件、源代码文本和工作区感知查找流程 |
| `analyze-symbol` | 处理符号存在检查、命名空间映射、生命周期跟踪、工作区符号解析和 API 概览 |
| `compare-minecraft` | 比较版本对、类差异、注册表差异和迁移导向的摘要 |
| `analyze-mod` | 总结模组元数据、反编译和搜索模组代码、检查类源代码和预览或应用重映射 |
| `validate-project` | 总结工作区并运行直接 Mixin、Access Widener 或 Access Transformer 验证 |
| `manage-cache` | 列出、验证和预览或应用缓存清理和重建操作 |
<!-- END GENERATED TOOL TABLE: top-level-workflow-tools -->
### 源代码探索
用于浏览 Minecraft 版本、解析源代码工件和读取或搜索反编译源代码的工具。
<!-- BEGIN GENERATED TOOL TABLE: source-exploration -->
| 工具 | 目的 |
| --- | --- |
| `list-versions` | 从 Mojang 元数据和本地缓存列出可用的 Minecraft 版本 |
| `resolve-artifact` | 从版本、JAR 路径或 Maven 坐标解析源代码工件 |
| `find-class` | 在工件内查找简单或完全限定的类名 |
| `get-class-source` | 从工件中读取类源代码或按需解析支持的工件 |
| `get-class-members` | 从字节码中列出构造函数、字段和方法 |
| `search-class-source` | 按符号、文本或路径搜索索引的类源代码 |
| `get-artifact-file` | 读取具有字节限制的完整源文件 |
| `list-artifact-files` | 列出索引的源文件路径并使用光标分页 |
| `index-artifact` | 为现有工件重建索引元数据 |
<!-- END GENERATED TOOL TABLE: source-exploration -->
对于 `26.1+` 等非混淆版本，`mapping="mojang"` 直接使用运行时/反编译路径并跳过 Loom 源代码 jar 发现，而 `intermediary` 和 `yarn` 回退到 `obfuscated` 并带有警告。
### 版本比较和符号跟踪
用于跨 Minecraft 版本比较类和注册表更改并跟踪符号随时间存在的工具。
<!-- BEGIN GENERATED TOOL TABLE: version-comparison-symbol-tracking -->
| 工具 | 目的 |
| --- | --- |
| `trace-symbol-lifecycle` | 跟踪 `Class.method` 在 Minecraft 版本间是否存在 |
| `diff-class-signatures` | 比较一个类在两个版本间并返回成员增量 |
| `compare-versions` | 比较两个版本之间的类和注册表更改 |
<!-- END GENERATED TOOL TABLE: version-comparison-symbol-tracking -->
### 映射和符号
用于转换符号名称和检查符号存在的工具。
<!-- BEGIN GENERATED TOOL TABLE: mapping-symbols -->
| 工具 | 目的 |
| --- | --- |
| `find-mapping` | 查找类、字段或方法符号的映射候选 |
| `resolve-method-mapping-exact` | `find-mapping` 的严格快捷方式（种类=方法，签名模式=确切）；需要完整的 owner+name+descriptor 三元组 |
| `get-class-api-matrix` | 显示一个类 API 跨 `obfuscated`、`mojang`、`intermediary` 和 `yarn` |
| `resolve-workspace-symbol` | 从 Gradle 工作区解析编译可见的符号名称 |
| `check-symbol-exists` | 检查类、字段或方法在命名空间中是否存在 |
<!-- END GENERATED TOOL TABLE: mapping-symbols -->
专家和批处理工具共享 `detail` (`summary` | `standard` | `full`) + `include[]` 响应契约以获取更短的响应（取代旧的每个工具的 `compact` 标志）。请参阅 [docs/tool-reference.md](docs/tool-reference.md) 获取每个工具的默认值和完整字段列表。
### NBT 实用程序
用于使用类型化的 JSON 表示法解码、修补和编码 Java 版 NBT 二进制数据的工具。
<!-- BEGIN GENERATED TOOL TABLE: nbt-utilities -->
| 工具 | 目的 |
| --- | --- |
| `nbt-to-json` | 将 Java 版 NBT 二进制有效载荷解码为类型化的 JSON |
| `nbt-apply-json-patch` | 将 RFC 6902 修补程序应用于类型化的 NBT JSON |
| `json-to-nbt` | 将类型化的 JSON 编码回 Java 版 NBT 二进制 |
<!-- END GENERATED TOOL TABLE: nbt-utilities -->
### 模组分析
用于从模组 JAR 中提取元数据、反编译模组源代码、搜索模组代码和重映射模组命名空间的工具。
<!-- BEGIN GENERATED TOOL TABLE: mod-analysis -->
| 工具 | 目的 |
| --- | --- |
| `analyze-mod-jar` | 从 JAR 中提取模组元数据、依赖项、入口点、Mixin 配置信息和打包的访问转换器路径 |
| `decompile-mod-jar` | 反编译模组 JAR并反选返回一个类源代码 |
| `get-mod-class-source` | 从反编译的 mod 缓存中读取一个类源代码 |
| `search-mod-source` | 按类、方法、字段或内容搜索反编译的 mod 源代码 |
| `remap-mod-jar` | 将 Fabric 或 Quilt 模组 JAR 映射到 `yarn` 或 `mojang` 名称 |
<!-- END GENERATED TOOL TABLE: mod-analysis -->
### 验证
用于验证 Mixin 源代码、Access Widener 文件和 Forge/NeoForge Access Transformer 文件针对目标 Minecraft 版本的工具。工作区选项允许验证使用加载器/运行时上下文。
<!-- BEGIN GENERATED TOOL TABLE: validation -->
| 工具 | 目的 |
| --- | --- |
| `validate-mixin` | 验证 Mixin 源代码针对目标 Minecraft 版本（如果某个阶段预算延迟工作，则返回 `validationStatus: "partial"` 和 `targetOutcomes`） |
| `validate-access-widener` | 验证 Access Widener 内容针对目标 Minecraft 版本，可选使用运行时感知的 Loom 工件 |
| `validate-access-transformer` | 验证 Access Transformer 内容针对目标 Minecraft 版本，可选使用 Forge/NeoForge 运行时工件 |
| `verify-mixin-target` | 单次调用探测器，用于检查拥有 `@Shadow` / `@Accessor` / `@Invoker` 建议的成员/所有者存在性 |
<!-- END GENERATED TOOL TABLE: validation -->
### 注册表和诊断
用于查询生成的注册表数据和检查服务器运行时状态的工具。
<!-- BEGIN GENERATED TOOL TABLE: registry-diagnostics -->
| 工具 | 目的 |
| --- | --- |
| `get-registry-data` | 读取生成的注册表快照并可选地包含条目数据 |
| `get-runtime-metrics` | 检查运行时指标和延迟快照 |
<!-- END GENERATED TOOL TABLE: registry-diagnostics -->
### 批量查找
工具共享一个解析的工件或 Minecraft 版本，并跨固定短列表。结果包括每个项目的一个状态以及聚合 `summary`。请参阅 [批量查找合同](docs/tool-reference.md#batch-lookup-contract) 获取失败处理和重试映射。
在单个 MCP 服务器进程中，需要相同二进制回退的批量类查找共享一个飞行中的源代码索引/反编译重建。
<!-- BEGIN GENERATED TOOL TABLE: batch-lookup -->
| 工具 | 目的 |
| --- | --- |
| `batch-class-source` | 针对一个共享解析的工件查找多个类的源代码（每个调用 1..50 个条目） |
| `batch-class-members` | 针对一个共享解析的工件查找多个类的成员（每个调用 1..50 个条目） |
| `batch-symbol-exists` | 在一个共享的 Minecraft 版本工件上探测多个条目的符号存在（仅限工作区/版本目标） |
| `batch-mappings` | 使用一个共享的 Minecraft 版本将多个符号映射到映射命名空间（无共享工件） |
<!-- END GENERATED TOOL TABLE: batch-lookup -->
详细的参量约束、迁移说明、资源行为和完整的环境变量矩阵位于 [docs/tool-reference.md](docs/tool-reference.md)。
## 开发
仓库需求：
- Node.js 22+
- `pnpm`
- 当本地运行重映射或反编译流程时需要 Java
设置和运行仓库：
```bash
pnpm install
pnpm dev
```
构建打包形状：
```bash
pnpm build
pnpm start
```
总是运行：
```bash
pnpm check
pnpm test
```
在相关情况下运行：
- `pnpm test:manual:stdio-smoke` 用于 MCP 传输、注册或手动工作流更改
- `pnpm test:manual:package-smoke` 在检查打包安装和分发行为时
- `pnpm test:perf` 用于搜索、索引或性能敏感的更改
- `pnpm test:coverage` 或 `pnpm test:coverage:lcov` 用于覆盖率检查（`lines=80`、`branches=70`、`functions=80`）
- `pnpm validate` 用于完整的本地验证套件
## 许可
[MIT](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器