mc-modpack

mc-modpack-mcp

Minecraft の Modpack 診断用 MCP（Model Context Protocol）サーバーです。Fabric／Forge の Mod 競合検出、ログ分析、クラッシュレポートの解析、AI によるインテリジェントな診断に対応しています。コアの診断エンジンは完全にオフラインで動作します。オプションの AI 分析には、中国の DashScope（通義千問）API を使用します。get_java_versions の実行には Windows 上の PCL ランチャーが必要です。それ以外のツールはすべてクロスプラットフォームで動作します。

機能

• Java バージョンの検出 — PCL の設定を読み取り、利用可能なすべての Java ランタイムをバージョンの推奨情報とともに一覧表示します
• バージョン情報 — インスタンスの JSON を解析し、Minecraft のバージョン、ローダー、Java の要件、JVM 引数を抽出します
• 競合の検出 — 外部の rules.json から既知の問題のある Mod の組み合わせを検出します（簡単に拡張できます）
• クリーン度のスキャン — mods/ ディレクトリ内の JAR 以外のファイル、ソース JAR、スクリプトを検出します
• ログ分析 — latest.log を読み取り、レベルによる絞り込み（INFO/WARN/ERROR）とキーワード検索を行います
• クラッシュレポートの分析 — クラッシュレポートを検出し、エラーを分類して、修正方法を自動で提案します
• 依存関係の検索 — Modrinth API に問い合わせて、Mod のバージョンと依存関係の情報を取得します
• 人が読みやすい出力 — すべてのツールが絵文字と💡ヒントを含むわかりやすいテキストを返し、--- JSON --- の下に JSON も出力します
• CLI モード — npm run diagnose を実行して、ターミナル上で対話形式の診断を行えます（MCP は不要です）
• 外部ルールエンジン — src/rules.json を編集することで、コードに手を加えずに新しい競合、クラッシュパターン、Java バージョン範囲を追加できます

ツール

ツール	説明
get_java_versions	PCL の設定からすべての Java ランタイムを一覧表示します
get_version_info	インスタンスのメタデータ（バージョン、ローダー、Java、JVM 引数、Mod 数）を読み取ります
list_mods	mods/ ディレクトリをスキャンします。正規表現による絞り込みも可能です
detect_conflicts	既知の Mod 競合を検出し、自動置換の推奨情報を提示します
scan_cleanliness	mods/ 内の JAR 以外のファイル、ソース JAR、スクリプトを検出します
read_log	レベル／キーワード／末尾行による絞り込みを指定して latest.log を読み取ります
find_crash_reports	crash-reports/ 内のすべてのクラッシュレポートを一覧表示します
analyze_crash	クラッシュレポートを解析し、例外の種類と概要を抽出します
check_mod_dependencies	Mod の依存関係と互換性について Modrinth API に問い合わせます
get_replacement_recommendations	既知の競合に対する置換 Mod の候補を取得します
ai_diagnose	🤖 通義千問を使用した AI による包括的な診断レポートを生成します（DASHSCOPE_API_KEY が必要です）

インストール

前提条件

• Node.js 18+
• npm
• Minecraft のインスタンス（ランチャーは問いません。macOS／Linux ユーザーは、すべてのツールで mc_dir を明示的に指定する必要があります）

注： get_java_versions は PCL ランチャーの設定を読み取るため、Windows でのみ動作します。それ以外のツールはすべてクロスプラットフォームで動作します。

ビルド

cd mc-modpack-mcp
npm install
npm run build

スタンドアロンの MCP サーバーとして実行

node dist/index.js

サーバーは stdio（JSON-RPC 2.0）経由で通信します。MCP 対応のあらゆるクライアントから利用できます。

MCP クライアントの設定

MCP クライアントの設定（例：.mcp.json など）に追加します。

{
  "mcpServers": {
    "mc-modpack": {
      "command": "node",
      "args": ["/absolute/path/to/mc-modpack-mcp/dist/index.js"]
    }
  }
}

使用例

PCL から Java バージョンを取得

{
  "name": "get_java_versions",
  "arguments": {
    "mc_dir": "{your_minecraft_directory}"
  }
}

インスタンス内の競合を検出

{
  "name": "detect_conflicts",
  "arguments": {
    "mc_dir": "{your_minecraft_directory}",
    "instance_id": "rpg"
  }
}

WARN ログを読み取る（末尾 50 行）

{
  "name": "read_log",
  "arguments": {
    "mc_dir": "{your_minecraft_directory}",
    "instance_id": "rpg",
    "level": "WARN",
    "tail": 50
  }
}

Modrinth 経由で Mod の依存関係を確認

{
  "name": "check_mod_dependencies",
  "arguments": {
    "project_id": "sodium",
    "mc_version": "1.20.1",
    "loader": "fabric"
  }
}

アーキテクチャ

mc-modpack-mcp/
├── src/
│   └── index.ts        # All tool implementations + MCP server setup
├── dist/               # Compiled JavaScript (output of tsc)
├── skills/
│   └── mc-modpack-helper/
│       └── SKILL.md    # Trae Work skill for modpack diagnostics
├── package.json        # Node.js dependencies (@modelcontextprotocol/sdk, zod)
├── tsconfig.json       # TypeScript config (CommonJS output)
├── .gitignore
├── test.js             # Integration test runner
├── test_logs/          # Test output logs (gitignored)
└── backups/            # Backup snapshots from tests (gitignored)

この MCP は、公式の @modelcontextprotocol/sdk v1.x を McpServer および StdioServerTransport とともに使用します。すべてのツールは、MCP SDK 仕様に準拠した server.tool() 登録パターンを使用します。

AI モジュール（src/ai.ts）

ai_diagnose ツールは、独立したモジュールで通義千問 API をラップし、以下を提供します。

• callQwen(prompt) — Qwen モデルを呼び出してレポートを生成します
• buildDiagnosePrompt(data) — すべての構造化データを統合した診断プロンプトを構築します

スキル

このリポジトリには、modpack の診断用 Trae Work スキルも含まれています。クローンした後、スキルを Trae Work のスキルディレクトリにコピーしてください。

Windows（PowerShell）：

copy skills\mc-modpack-helper\SKILL.md "$env:USERPROFILE\.trae\skills\mc-modpack-helper\SKILL.md"

macOS / Linux：

mkdir -p ~/.trae/skills/mc-modpack-helper
cp skills/mc-modpack-helper/SKILL.md ~/.trae/skills/mc-modpack-helper/SKILL.md

8 フェーズの診断ワークフローを含むスキルの詳細なドキュメントは、SKILL.md を参照してください。

テスト

npm run build
MC_DIR=/path/to/your/.minecraft node test.js

または Windows（PowerShell）では：

$env:MC_DIR="C:\path\to\your\.minecraft"; node test.js

テストの実行前にバックアップが作成され、結果は test_logs/ に記録されます。詳細な出力については、個々のテストログファイルを参照してください。

プラットフォームの互換性

ツール	Windows	macOS	Linux
get_java_versions	✅ フル対応	⚠️ PCL のみ	⚠️ PCL のみ
get_version_info	✅	✅	✅
list_mods	✅	✅	✅
detect_conflicts	✅	✅	✅
scan_cleanliness	✅	✅	✅
read_log	✅	✅	✅
find_crash_reports	✅	✅	✅
analyze_crash	✅	✅	✅
check_mod_dependencies	✅	✅	✅

すべてのツールで、明示的なパスとして mc_dir を指定できます。get_java_versions は Windows では PCL を自動検出します。他のプラットフォームでは、PCL の設定が見つからない場合に明確なメッセージを返します。

ルールエンジンの使用

競合ルール、Java バージョンの対応関係、クラッシュ分析パターンはすべて src/rules.json にあります。ソースコードを変更せずにカスタマイズできます。

{
  "conflicts": [
    {
      "id": "my-custom-conflict",
      "name": "My Custom Conflict",
      "patterns": ["mod-a", "mod-b"],
      "severity": "error",
      "solution": "Install only one of these mods.",
      "emoji": "🔴"
    }
  ],
  "javaVersionMap": [
    { "mcFrom": "1.20.5", "mcTo": "1.20.6", "minJava": 17, "recommendedJava": 21, "notes": "..." }
  ],
  "crashAnalysisPatterns": [
    { "keywords": ["my-error-pattern"], "category": "custom", "solution": "Do something about it." }
  ]
}

セクション	目的
conflicts	Mod の競合検出ルール
javaVersionMap	Minecraft と Java バージョンの互換性
crashAnalysisPatterns	クラッシュレポートの分類と修正案

CLI の使用方法

MCP をセットアップせずに、対話形式で簡易診断を実行できます。

npm run diagnose
# or
MC_DIR=/path/to/.minecraft npm run diagnose

CLI は次の処理を行います。

1. Minecraft インスタンスを自動検出します
2. Java ランタイムを確認します（Windows では PCL）
3. Mod の競合をスキャンします
4. ディレクトリのクリーン度を確認します
5. クラッシュレポートを確認します

ライセンス

MIT