mc-pack-builder

mc-pack-builder-mcp

用于构建 Minecraft 整合包的 MCP 服务。可创建整合包结构、在 Modrinth 上搜索模组、解析依赖项、检查兼容性，并导出可供分发的标准化整合包。

工具

工具	说明
create_pack	创建新的整合包目录结构（pack.mcmeta、version.txt、loader.txt、mods/）
get_pack_info	读取现有整合包的元数据：MC 版本、加载器、模组数量和常见问题
search_mods	按关键词在 Modrinth 上搜索模组，返回 ID、名称、描述和下载量
get_mod_info	获取 Modrinth 模组的详细信息：版本历史、依赖项和支持的 MC 版本
resolve_dependencies	递归解析模组的完整依赖链（直接和间接依赖）
check_pack_compatibility	根据目标 MC 版本检查已安装模组是否存在已知的不兼容问题
generate_dependency_list	为现有整合包中的所有模组生成完整依赖项列表
export_standard_pack	导出可供分发的整洁整合包：清理额外文件、解开嵌套 ZIP、生成模组列表，并可选择拆分为多个分卷

功能

• 创建整合包结构 — 生成包含所有必需文件的标准整合包目录
• 集成 Modrinth — 直接通过 Modrinth API 搜索并查询模组元数据
• 解析依赖项 — 遍历完整依赖树，确保满足所有要求
• 兼容性检查 — 检测已知冲突（例如，OptiFine 与 Fabric 不兼容、Sodium 与 Embeddium 冲突）
• 导出标准整合包 — 自动清理 .minecraft 中的额外文件，解开嵌套 ZIP 包，生成带样式的 modlist.html 或纯文本 modlist.txt，并可选择将大型整合包拆分为不超过 256 MB 的分卷，方便分发
• 离线运行 — 所有本地整合包工具均可离线使用；只有搜索和信息工具需要连接 Modrinth

安装

先决条件

• Node.js 18+
• npm

构建

cd mc-pack-builder-mcp
npm install
npm run build

作为独立 MCP 服务运行

node dist/index.js

服务通过 stdio（JSON-RPC 2.0）进行通信。任何兼容 MCP 的客户端都可以使用它。

MCP 客户端配置

将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "mc-pack-builder": {
      "command": "node",
      "args": ["${MC_PACK_BUILDER_ROOT}/dist/index.js"]
    }
  }
}

路径说明： 将 ${MC_PACK_BUILDER_ROOT} 替换为此项目根目录的绝对路径。在 Windows 上，请使用正斜杠：["C:/Users/xxx/Desktop/mc-pack-builder-mcp/dist/index.js"]。或者，设置指向项目根目录的环境变量 MC_PACK_BUILDER_ROOT，并在配置中使用该变量。

配置

本工具零配置即可用（内置默认值，任何环境开箱即用）。以下项目可通过环境变量或项目根目录 .env 文件覆盖（复制 .env.example 为 .env）：

变量	默认值	说明
PACK_BUILDER_MODRINTH_API_BASE	https://api.modrinth.com/v2	Modrinth API 根地址，支持自建网关/代理
PACK_BUILDER_USER_AGENT	mc-pack-builder-mcp/1.1	请求 User-Agent（Modrinth 要求标明来源）
PACK_BUILDER_VOLUME_MAX_MB	256	分卷导出时每卷的最大体积（MB）
PACK_BUILDER_SKIP_DIRS	mods,config,resourcepacks,shaderpacks,saves,datapacks,worlds	解压嵌套压缩包时跳过的顶层目录（逗号分隔）

优先级：环境变量 > .env 文件 > 内置默认值。改动后重启 MCP 服务即可生效。

扩展兼容性规则：编辑 src/pack-rules.json（构建后为 dist/pack-rules.json），即可新增或覆盖规则，无需修改代码。

• rules.incompatible_pairs：互斥模组对，例如 { "mods": ["sodium", "embeddium"], "reason": "..." }；同一整合包中同时出现 ≥2 个名单内模组时会发出警告。
• rules.loader_incompatible：加载器专属的不兼容规则，例如 { "loader": "fabric", "mods": ["optifine"], "reason": "..." }。
• rules.pack_format：MC 版本到 pack.mcmeta 的 pack_format 数值映射（create_pack 的默认取值）。

使用示例

创建新的整合包

{
  "name": "create_pack",
  "arguments": {
    "pack_dir": "/path/to/MyModpack",
    "name": "My Modpack",
    "mc_version": "1.20.1",
    "loader": "fabric"
  }
}

读取整合包信息

{
  "name": "get_pack_info",
  "arguments": {
    "pack_dir": "/path/to/MyModpack"
  }
}

在 Modrinth 上搜索模组

{
  "name": "search_mods",
  "arguments": {
    "query": "sodium",
    "limit": 5
  }
}

解析依赖项

{
  "name": "resolve_dependencies",
  "arguments": {
    "project_id": "geckolib"
  }
}

检查整合包兼容性

{
  "name": "check_pack_compatibility",
  "arguments": {
    "pack_dir": "/path/to/MyModpack",
    "mc_version": "1.20.1"
  }
}

生成依赖项列表

{
  "name": "generate_dependency_list",
  "arguments": {
    "pack_dir": "/path/to/MyModpack"
  }
}

导出标准整合包（可发布）

{
  "name": "export_standard_pack",
  "arguments": {
    "source_pack_dir": "C:/Users/xxx/Desktop/MyModpack",
    "output_dir": null,
    "clean_minecraft_extra": true,
    "minecraft_dir": "C:/Users/xxx/.minecraft",
    "unwrap_nested": true,
    "generate_modlist": true,
    "modlist_format": "html",
    "split_volumes": false,
    "volume_max_mb": 256
  }
}

**输出：**在同级目录中创建一个 _ready 目录（或使用自定义的 output_dir），其中包含清理后的软件包。返回一份 JSON 报告，列出执行的所有操作、警告、模组数量，以及（如果启用了分卷）每个分卷的路径和大小。

架构

mc-pack-builder-mcp/
├── src/
│   ├── index.ts        # MCP server + all tool implementations
│   └── pack-rules.json # 兼容性规则 & pack_format 映射（可外部扩展）
├── dist/               # Compiled JavaScript (output of tsc)
├── __tests__/
│   └── unit.test.ts    # Unit tests (offline)
├── package.json        # Node.js dependencies (@modelcontextprotocol/sdk, zod, adm-zip)
├── tsconfig.json       # TypeScript config (CommonJS output)
├── test.js             # Integration test runner
├── test_logs/          # Test output logs (gitignored)
├── .env.example        # 环境变量配置示例
└── .gitignore

MCP 使用官方的 @modelcontextprotocol/sdk v1.x，以及 McpServer 和 StdioServerTransport。

测试

npm run build
node test.js

测试会在 os.tmpdir() 下创建临时目录，并在结束后自行清理。无需安装 Minecraft。

平台兼容性

工具	Windows	macOS	Linux
create_pack	✅	✅	✅
get_pack_info	✅	✅	✅
search_mods	✅	✅	✅
get_mod_info	✅	✅	✅
resolve_dependencies	✅	✅	✅
check_pack_compatibility	✅	✅	✅
generate_dependency_list	✅	✅	✅
export_standard_pack	✅	✅	✅

所有工具均使用跨平台的 Node.js fs 和 path API。依赖网络的工具（search_mods、get_mod_info、resolve_dependencies）无论在哪个平台上都需要互联网连接。

许可证

MIT