mc-pack-builder

mc-pack-builder-mcp

Minecraft の Modpack 構築用 MCP サーバーです。パック構造の作成、Modrinth での Mod 検索、依存関係の解決、互換性の確認を行い、配布可能な標準形式の Modpack をエクスポートします。

ツール

ツール	説明
create_pack	新しい Modpack ディレクトリ構造（pack.mcmeta、version.txt、loader.txt、mods/）を作成します
get_pack_info	既存の Modpack メタデータ（MC バージョン、ローダー、Mod 数、よくある問題）を読み込みます
search_mods	Modrinth でキーワードから Mod を検索し、ID、名前、説明、ダウンロード数を返します
get_mod_info	Modrinth の Mod に関する詳細情報（バージョン履歴、依存関係、対応 MC バージョン）を取得します
resolve_dependencies	Mod の依存関係全体（直接および間接）を再帰的に解決します
check_pack_compatibility	インストール済み Mod と対象 MC バージョンを照合し、既知の非互換性を確認します
generate_dependency_list	既存のパックに含まれるすべての Mod の依存関係一覧を生成します
export_standard_pack	配布可能なクリーンな Modpack をエクスポートします。不要ファイルの削除、ネストされた ZIP の展開、Mod リストの生成、任意のボリューム分割を行います

特徴

• パック構造の作成 — 必要なファイルをすべて含む標準的な Modpack ディレクトリを生成します
• Modrinth 連携 — Modrinth API から Mod のメタデータを直接検索、取得します
• 依存関係の解決 — すべての要件を満たせるよう、依存関係ツリー全体をたどります
• 互換性の確認 — 既知の競合（例：Fabric と OptiFine、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 のルート URL。独自のゲートウェイ／プロキシに対応しています
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：相互に非互換な Mod の組み合わせ。例：{ "mods": ["sodium", "embeddium"], "reason": "..." }。同じ Modpack にリスト内の Mod が 2 つ以上含まれている場合に警告します。
• rules.loader_incompatible：ローダー固有の非互換性。例：{ "loader": "fabric", "mods": ["optifine"], "reason": "..." }。
• rules.pack_format：MC バージョンから pack.mcmeta の pack_format 数値への対応表（create_pack のデフォルト値）。

使用例

新しい Modpack を作成する

{
  "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 で Mod を検索する

{
  "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）を作成します。実行したすべての操作、警告、MOD の数、およびボリューム分割が有効な場合はボリュームごとのパスとサイズを記載した 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 は、McpServer と StdioServerTransport を使用する公式の @modelcontextprotocol/sdk v1.x を使用しています。

テスト

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