Minecraft Modding MCP

@adhisang/minecraft改装mcp

](https://www.npmjs.com/package/@adhisang/minecraft-modding-mcp)  ](https://nodejs.org/) 

英语 | 日本语

备注：这个项目完全是氛围编码的——使用人工智能辅助开发构建，没有正式的规范。

______________________________________________________________________

@adhisang/minecraft-modding-mcp 是一个用于人工智能辅助Minecraft建模工作流的MCP服务器，基于 模型上下文协议。当代理需要检查Minecraft源代码、解析映射、比较版本、分析mod JAR、验证Mixin、Access Widener或Access Transformer文件，或使用MCP客户端的NBT和注册表数据时，请使用它。

它在stdio上运行，可与Claude Desktop、Claude Code、VS Code、Codex CLI、Gemini CLI和其他支持MCP的客户端配合使用。

37工具 （6名参赛者+31名专家）| 7资源 | 4个命名空间映射 | SQLite支持的缓存

特性

• 资源勘探：使用行级上下文浏览、列出和搜索反编译的Minecraft源代码
• 映射感知符号工作：转换类、字段和方法名称 obfuscated, mojang, intermediary，以及 yarn
• 版本比较：比较Minecraft版本之间的类签名、注册表项和面向迁移的摘要
• Mod JAR分析：读取Fabric、Forge和NeoForge元数据、入口点、Mixin配置、依赖关系、源代码和重新映射预览
• 项目验证：验证Mixin源， .accesswidener 将Forge/NeoForge访问转换器文件与目标版本进行比较
• NBT、注册表、缓存和诊断：修补NBT有效负载，检查生成的注册表数据，并管理缓存/运行时状态
• MCP资源：通过基于URI的资源公开版本、类源、工件元数据和映射

快速开始

套餐用户

要求：

• Node.js 22+
• Java只需要 remap-mod-jar 以及反编译或重新映射需要Vineflower或微型重映射器的流

在本地启动服务器：

npx -y @adhisang/minecraft-modding-mcp

在MCP客户端配置中使用此命令。如果您的环境中阻止了自动JAR下载，请设置 MCP_VINEFLOWER_JAR_PATH 和 MCP_TINY_REMAPPER_JAR_PATH 在那里。

客户端设置

CLI客户端可以直接注册package命令。

克劳德代码：

claude mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp

OpenAI Codex CLI：

codex mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp

跑 claude mcp list 或 codex mcp list 注册后验证服务器是否可用。

stdio传输自动检测换行符和 Content-Length 框架，因此相同的服务器命令可以在Codex和标准MCP客户端之间工作。

克劳德桌面版

将以下内容添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "minecraft-modding": {
      "command": "npx",
      "args": ["-y", "@adhisang/minecraft-modding-mcp"]
    }
  }
}

VS Code

添加以下内容 .vscode/mcp.json 在您的工作空间中：

{
  "servers": {
    "minecraft-modding": {
      "command": "npx",
      "args": ["-y", "@adhisang/minecraft-modding-mcp"]
    }
  }
}

Gemini CLI

添加以下内容 ~/.gemini/settings.json:

{
  "mcpServers": {
    "minecraft-modding": {
      "command": "npx",
      "args": ["-y", "@adhisang/minecraft-modding-mcp"]
    }
  }
}

然后运行：

/mcp list

自定义环境

传递环境变量以覆盖默认值：

{
  "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"
      }
    }
  }
}

从这里开始

这六个顶级工作流工具涵盖了常见路径，并返回摘要优先结果。它们是代理和MCP客户端的最佳默认起点。

六个人都回来了 result.summary 首先，可以包括 summary.nextActions 当有明确的后续步骤时。从表格中选择工具，然后使用示例和参考文档获取确切的有效载荷。

工作流注释

这些说明涵盖了入职期间的高频决策。有关完整的陷阱列表、确切的合约、迁移说明和环境变量，请参阅 docs/tool-reference.md.

• search-class-source 默认为 queryMode="auto" 并保留分隔符查询，例如 foo.bar, foo_bar，以及 foo$bar 在索引路径上。使用 queryMode="literal" 用于显式的完整子字符串扫描。
• 如果您还没有工件，请选择 subject.kind="workspace" 为了 inspect-minecraft 而不是猜测工件细节。当工件上下文是唯一缺失的输入时，可重试 suggestedCall 保留请求的任务。
• trace-symbol-lifecycle 预期 Class.method 在 symbol.在单独的文件中保持精确的过载匹配 descriptor 现场。
• 对于未混淆的版本，例如 26.1+, check-symbol-exists 和 analyze-symbol task="exists" 验证 mojang 当不存在映射图时，对运行时字节码进行查找，并返回 mapping_unavailable 当运行时JAR本身无法访问时。
• analyze-mod 和 validate-project 要求结构化 subject 对象和规范 include 组；过时的字符串主题或域包含有效载荷返回 ERR_INVALID_INPUT 可重试 suggestedCall.
• validate-project task="project-summary" 传播 preferProjectVersion=true 在发现的Mixin、Access Widener和Access Transformer检查中。如果无法从请求中解析任何版本，或 gradle.properties，摘要返回恢复指导，而不是猜测。
• validate-mixin 和 validate-project 保持 mapping-health 轻量级 obfuscated 和 mojang 验证，避免完整的Tiny映射图加载，除非 intermediary 或 yarn 请求命名空间。
• validate-project task="project-summary" 使用轻量级伪影探测器 tasks["minecraft.artifact.resolved"]；它不会仅仅为了报告每个探测的状态而反编译Minecraft或重建源索引。集 VALIDATE_PROJECT_TASKS_OFF=1 省略添加剂 tasks 现场。

从版本检查Minecraft源代码

{
  "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"
        }
      }
    }
  }
}

绘制或检查符号

{
  "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"
  }
}

总结一个mod JAR

{
  "tool": "analyze-mod",
  "arguments": {
    "task": "summary",
    "subject": {
      "kind": "jar",
      "jarPath": "/path/to/mymod-1.0.0.jar"
    }
  }
}

验证工作区

{
  "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 当您希望在摘要运行中包含Access Transformer文件时。

文档

• 详细示例请求 用于可复制的有效载荷和通用工作流程
• 工具和配置参考 用于精确的输入、输出、资源行为、环境变量和迁移说明。从 哪个问题用哪个工具 当您不确定要调用哪个工具时，请使用决策表。
• 日本语README 了解日语入职概述

刀具表面

从这些顶级工作流工具开始，除非你已经知道你想要的确切的专业操作。低级工具仍然可用于狭义的后续工作和自动化。

顶级工作流工具

资源勘探

用于浏览Minecraft版本、解析源代码工件以及阅读或搜索反编译源代码的工具。

对于未混淆的版本，例如 26.1+, mapping="mojang" 直接使用运行时/反编译路径，跳过Loom源代码jar发现，而 intermediary 和 yarn 退回到 obfuscated 发出警告。

版本比较和符号跟踪

用于比较Minecraft版本之间的类和注册表更改以及跟踪符号存在随时间变化的工具。

映射和符号

用于在命名空间之间转换符号名称和检查符号存在的工具。

支持多种查找工具 compact 结果整形以缩短响应时间。看 docs/tool-reference.md 默认值和完整的每个工具字段列表。

NBT公用事业

使用类型化JSON表示对Java Edition NBT二进制数据进行解码、修补和编码的工具。

Mod分析

用于从mod JAR中提取元数据、反编译mod源代码、搜索mod代码和重新映射mod名称空间的工具。

验证

用于根据目标Minecraft版本验证Mixin源代码、Access Widener文件和Forge/NeoForge Access Transformer文件的工具。当项目路径可用时，工作区选项允许验证使用加载器/运行时上下文。

注册表和诊断

用于查询生成的注册表数据和检查服务器运行时状态的工具。

批量查找

在固定的候选名单中共享一个已解决工件或Minecraft版本的工具。结果包括每个项目一个状态加上一个汇总 summary。参见 批量查找合同 用于故障处理和重试映射。

在一个MCP服务器进程中，需要相同二进制回退的批处理类查找共享该工件的一个正在进行的源索引/反编译重建。

详细的参数约束、迁移说明、资源行为和完整的环境变量矩阵 docs/tool-reference.md.

发展

存储库要求：

• Node.js 22+
• pnpm
• Java在本地运行重映射或反编译流时

设置并运行存储库：

pnpm install
pnpm dev

构建包装形状：

pnpm build
pnpm start

始终运行：

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 对于完整的本地验证套件

许可证

麻省理工学院