mc-modpack-mcp

MCP (Model Context Protocol) server for Minecraft modpack diagnostics. Supports Fabric/Forge mod conflict detection, log analysis, crash reports, and AI-powered intelligent diagnosis. Core diagnostic engine is fully offline; optional AI analysis uses China-based DashScope (通义千问) API. get_java_versions requires PCL launcher on Windows; all other tools work cross-platform.

Features

• Java version detection — reads PCL config to list all available Java runtimes with version recommendations
• Version info — parses instance JSON to extract Minecraft version, loader, Java requirements, JVM args
• Conflict detection — finds known problematic mod combinations from an external rules.json (easily extensible)
• Cleanliness scan — detects non-JAR files, source jars, scripts in mods/ directory
• Log analysis — reads latest.log with level filtering (INFO/WARN/ERROR) and keyword search
• Crash report analysis — finds crash reports, classifies errors, and suggests fixes automatically
• Dependency lookup — queries Modrinth API for mod version and dependency info
• Human-readable output — all tools return friendly text with emojis and 💡 tips, plus JSON below --- JSON ---
• CLI mode — run npm run diagnose for an interactive terminal-based diagnosis (no MCP needed)
• External rules engine — edit src/rules.json to add new conflicts, crash patterns, or Java version ranges without touching code

Tools

| Tool | Description | |------|-------------| | get_java_versions | List all Java runtimes from PCL config | | get_version_info | Read instance metadata (version, loader, Java, JVM args, mod count) | | list_mods | Scan mods/ directory, optionally filter by regex | | detect_conflicts | Detect known mod conflicts with auto-replacement recommendations | | scan_cleanliness | Find non-JAR files, source jars, scripts in mods/ | | read_log | Read latest.log with level/keyword/tail filtering | | find_crash_reports | List all crash reports in crash-reports/ | | analyze_crash | Parse a crash report, extract exception type and summary | | check_mod_dependencies | Query Modrinth API for mod deps and compatibility | | get_replacement_recommendations | Get replacement mod suggestions for known conflicts | | ai_diagnose | 🤖 AI-powered full diagnostics report using 通义千问 (requires DASHSCOPE_API_KEY) |

Installation

Prerequisites

• Node.js 18+
• npm
• A Minecraft instance (any launcher — macOS/Linux users must pass mc_dir explicitly for all tools)

Note: get_java_versions reads PCL launcher config and works on Windows only. All other tools are cross-platform.

Build

cd mc-modpack-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 (e.g., .mcp.json or equivalent):

{
  "mcpServers": {
    "mc-modpack": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"]
    }
  }
}

Path note: ${workspaceFolder} resolves to the project root in Trae/VS Code. If using another editor, replace with the absolute path, e.g. ["C:/Users/xxx/Desktop/mc-modpack-mcp/dist/index.js"]. See .mcp.example.json for a ready-to-use config template.

Usage Examples

Get Java versions from PCL

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

Detect conflicts in an instance

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

Read WARN logs (last 50 lines)

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

Check mod dependencies via Modrinth

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

Architecture

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)

The MCP uses the official @modelcontextprotocol/sdk v1.x with McpServer and StdioServerTransport. All tools use server.tool() registration pattern compatible with the MCP SDK specification.

AI Module (src/ai.ts)

ai_diagnose 工具使用独立模块封装通义千问 API，提供：

• callQwen(prompt) — 调用 Qwen 模型生成报告
• buildDiagnosePrompt(data) — 构建诊断 prompt，整合所有结构化数据

Skills

This repository also includes a Trae Work skill for modpack diagnostics. After cloning, copy the skill to your Trae Work skills directory:

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

See SKILL.md for the full skill documentation with 8-phase diagnostic workflow.

Testing

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

Or on Windows (PowerShell):

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

Tests create backups before running and log results to test_logs/. See individual test log files for detailed output.

Platform Compatibility

| Tool | Windows | macOS | Linux | |------|---------|-------|-------| | get_java_versions | ✅ Full | ⚠️ PCL-only | ⚠️ PCL-only | | get_version_info | ✅ | ✅ | ✅ | | list_mods | ✅ | ✅ | ✅ | | detect_conflicts | ✅ | ✅ | ✅ | | scan_cleanliness | ✅ | ✅ | ✅ | | read_log | ✅ | ✅ | ✅ | | find_crash_reports | ✅ | ✅ | ✅ | | analyze_crash | ✅ | ✅ | ✅ | | check_mod_dependencies | ✅ | ✅ | ✅ |

All tools accept mc_dir as an explicit path. get_java_versions auto-detects PCL on Windows; on other platforms it returns a clear message when PCL config is absent.

Using the Rules Engine

All conflict rules, Java version mappings, and crash analysis patterns live in src/rules.json. You can customize them without modifying source code:

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

| Section | Purpose | |---------|---------| | conflicts | Mod conflict detection rules | | javaVersionMap | Minecraft → Java version compatibility | | crashAnalysisPatterns | Crash report classification and fix suggestions |

CLI Usage

Run a quick interactive diagnosis without setting up MCP:

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

The CLI will:

1. Auto-detect your Minecraft instance
2. Check Java runtimes (PCL on Windows)
3. Scan for mod conflicts
4. Check directory cleanliness
5. Review crash reports

License

MIT