mc-modpack

mc-modpack-mcp

用于 Minecraft 模组包诊断的 MCP（Model Context Protocol）服务。支持 Fabric/Forge 模组冲突检测、日志分析、崩溃报告分析和 AI 智能诊断。核心诊断引擎完全离线运行；可选的 AI 分析使用基于中国的 DashScope（通义千问）API。get_java_versions 需要在 Windows 上安装 PCL 启动器；其他工具可跨平台使用。

功能

• Java 版本检测 — 读取 PCL 配置，列出所有可用的 Java 运行时并提供版本建议
• 版本信息 — 解析实例 JSON，提取 Minecraft 版本、加载器、Java 要求和 JVM 参数
• 冲突检测 — 根据外部 rules.json 查找已知的问题模组组合（易于扩展）
• 整洁度扫描 — 检测 mods/ 目录中的非 JAR 文件、源码 JAR 和脚本
• 日志分析 — 读取 latest.log，支持按级别（INFO/WARN/ERROR）筛选和关键词搜索
• 崩溃报告分析 — 查找崩溃报告、对错误分类并自动建议修复方法
• 依赖项查询 — 查询 Modrinth API，获取模组版本和依赖信息
• 易读的输出 — 所有工具均返回带有表情符号和 💡 提示的友好文本，并在 --- JSON --- 下方提供 JSON
• CLI 模式 — 运行 npm run diagnose，通过交互式终端进行诊断（无需 MCP）
• 外部规则引擎 — 编辑 src/rules.json，即可添加新的冲突、崩溃模式或 Java 版本范围，无需修改代码

工具

工具	描述
get_java_versions	列出 PCL 配置中的所有 Java 运行时
get_version_info	读取实例元数据（版本、加载器、Java、JVM 参数、模组数量）
list_mods	扫描 mods/ 目录，可按正则表达式筛选
detect_conflicts	检测已知的模组冲突，并自动推荐替换方案
scan_cleanliness	查找 mods/ 目录中的非 JAR 文件、源码 JAR 和脚本
read_log	读取 latest.log，支持按级别、关键词和尾部行数筛选
find_crash_reports	列出 crash-reports/ 中的所有崩溃报告
analyze_crash	解析崩溃报告，提取异常类型和摘要
check_mod_dependencies	查询 Modrinth API，获取模组依赖项和兼容性信息
get_replacement_recommendations	获取针对已知冲突的模组替换建议
ai_diagnose	🤖 使用通义千问生成 AI 智能完整诊断报告（需要 DASHSCOPE_API_KEY）

安装

前置条件

• Node.js 18+
• npm
• 一个 Minecraft 实例（任意启动器均可；macOS/Linux 用户必须为所有工具显式传入 mc_dir）

注意： get_java_versions 会读取 PCL 启动器配置，仅适用于 Windows。其他工具均可跨平台使用。

构建

cd mc-modpack-mcp
npm install
npm run build

作为独立 MCP 服务运行

node dist/index.js

服务通过 stdio（JSON-RPC 2.0）通信，可供任何兼容 MCP 的客户端使用。

MCP 客户端配置

将以下内容添加到 MCP 客户端配置中（例如 .mcp.json 或同等配置文件）：

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

使用示例

从 PCL 获取 Java 版本

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

检测实例中的冲突

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

读取 WARN 日志（最后 50 行）

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

通过 Modrinth 检查模组依赖项

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

架构

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)

MCP 使用官方的 @modelcontextprotocol/sdk v1.x，并采用 McpServer 和 StdioServerTransport。所有工具均使用与 MCP SDK 规范兼容的 server.tool() 注册模式。

AI 模块（src/ai.ts）

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

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

技能

此仓库还包含用于整合包诊断的 Trae Work 技能。克隆后，请将该技能复制到 Trae Work 技能目录：

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

请参阅 SKILL.md，了解包含 8 个阶段的诊断工作流的完整技能文档。

测试

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

或在 Windows（PowerShell）上运行：

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

测试运行前会创建备份，并将结果记录到 test_logs/。详细输出请参阅各个测试日志文件。

平台兼容性

工具	Windows	macOS	Linux
get_java_versions	✅ 完整支持	⚠️ 仅支持 PCL	⚠️ 仅支持 PCL
get_version_info	✅	✅	✅
list_mods	✅	✅	✅
detect_conflicts	✅	✅	✅
scan_cleanliness	✅	✅	✅
read_log	✅	✅	✅
find_crash_reports	✅	✅	✅
analyze_crash	✅	✅	✅
check_mod_dependencies	✅	✅	✅

所有工具均接受 mc_dir 作为显式路径。get_java_versions 会在 Windows 上自动检测 PCL；在其他平台上，如果没有 PCL 配置，则会返回明确的提示信息。

使用规则引擎

所有冲突规则、Java 版本映射和崩溃分析模式都位于 src/rules.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." }
  ]
}

部分	用途
conflicts	模组冲突检测规则
javaVersionMap	Minecraft 与 Java 版本兼容性
crashAnalysisPatterns	崩溃报告分类和修复建议

CLI 用法

无需设置 MCP，即可运行快速交互式诊断：

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

CLI 将会：

1. 自动检测你的 Minecraft 实例
2. 检查 Java 运行时（Windows 上的 PCL）
3. 扫描模组冲突
4. 检查目录整洁度
5. 检查崩溃报告

许可证

MIT