Mc Modpack

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