Mc Modpack

mc-modpack-mcp

[M8ven Verified]

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-mcpnpm installnpm 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-helpercp 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 buildMC_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# orMC_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