# 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

```bash
cd mc-modpack-mcp
npm install
npm run build
```

### Run as standalone MCP server

```bash
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):

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

## Usage Examples

### Get Java versions from PCL

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

### Detect conflicts in an instance

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

### Read WARN logs (last 50 lines)

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

### Check mod dependencies via Modrinth

```json
{
  "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):**
```powershell
copy skills\mc-modpack-helper\SKILL.md "$env:USERPROFILE\.trae\skills\mc-modpack-helper\SKILL.md"
```

**macOS / Linux:**
```bash
mkdir -p ~/.trae/skills/mc-modpack-helper
cp skills/mc-modpack-helper/SKILL.md ~/.trae/skills/mc-modpack-helper/SKILL.md
```

See [SKILL.md](./skills/mc-modpack-helper/SKILL.md) for the full skill documentation with 8-phase diagnostic workflow.

## Testing

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

Or on Windows (PowerShell):

```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](./src/rules.json). You can customize them without modifying source code:

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

| 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:

```bash
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