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

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": ["/absolute/path/to/mc-modpack-mcp/dist/index.js"]
    }
  }
}

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

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

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