mc-pack-builder

mc-pack-builder-mcp

MCP server for Minecraft modpack building. Creates pack structures, searches mods on Modrinth, resolves dependencies, checks compatibility, and exports standardized modpacks ready for distribution.

Tools

Tool	Description
create_pack	Create a new modpack directory structure (pack.mcmeta, version.txt, loader.txt, mods/)
get_pack_info	Read existing modpack metadata: MC version, loader, mod count, and common issues
search_mods	Search Modrinth for mods by keyword, returns ID, name, description, download count
get_mod_info	Get detailed info about a Modrinth mod: version history, dependencies, supported MC versions
resolve_dependencies	Recursively resolve a mod's full dependency chain (direct + indirect)
check_pack_compatibility	Check installed mods against a target MC version for known incompatibilities
generate_dependency_list	Generate a complete dependency list for all mods in an existing pack
export_standard_pack	Export a clean, distribution-ready modpack: cleanup extras, unwrap nested zips, generate modlist, optional volume splitting

Features

• Pack structure creation — generates standard modpack directory with all required files
• Modrinth integration — search and query mod metadata directly from the Modrinth API
• Dependency resolution — follows the full dependency tree to ensure all requirements are met
• Compatibility checking — detects known conflicts (e.g. OptiFine with Fabric, Sodium vs Embeddium)
• Export standard pack — automatically cleans .minecraft extras, unwraps nested zip bundles, generates a styled modlist.html or plain modlist.txt, and optionally splits large packs into ≤256 MB volumes for easy distribution
• Offline operation — all local pack tools work without network; only search/info tools need Modrinth

Installation

Prerequisites

• Node.js 18+
• npm

Build

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

Run as standalone MCP server

node dist/index.js

The server communicates via stdio (JSON-RPC 2.0). It can be consumed by any MCP-compatible client.

Configuration for MCP clients

Add to your MCP client config:

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

Path note: Replace ${MC_PACK_BUILDER_ROOT} with the absolute path to this project's root directory. On Windows, use forward slashes: ["C:/Users/xxx/Desktop/mc-pack-builder-mcp/dist/index.js"]. Alternatively, set an environment variable MC_PACK_BUILDER_ROOT pointing to the project root and use the variable in the config.

Configuration

本工具零配置即可用（内置默认值，任何环境开箱即用）。以下项目可通过环境变量或项目根目录 .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 server 生效。

扩展兼容性规则：编辑 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 默认取值）。

Usage Examples

Create a new modpack

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

Read pack info

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

Search for a mod on Modrinth

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

Resolve dependencies

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

Check pack compatibility

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

Generate dependency list

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

Export standard pack (release-ready)

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

Output: Creates a _ready sibling directory (or custom output_dir) with the cleaned package. Returns a JSON report listing all actions taken, warnings, mod count, and — if volume splitting is enabled — per-volume paths and sizes.

Architecture

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

The MCP uses the official @modelcontextprotocol/sdk v1.x with McpServer and StdioServerTransport.

Testing

npm run build
node test.js

Tests create temporary directories under os.tmpdir() and clean up after themselves. No Minecraft installation is required.

Platform Compatibility

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

All tools use cross-platform Node.js fs and path APIs. Network-dependent tools (search_mods, get_mod_info, resolve_dependencies) require internet access regardless of platform.

License

MIT