mc-mod-config

mc-mod-config-mcp

用于管理 Minecraft 模组配置文件的 MCP 服务。可读取、验证、比较和清理整合包中的 .cfg、.toml 和 .json 配置文件。

工具

工具	说明
read_mod_config	解析单个配置文件（.cfg、.toml、.json），并返回结构化数据及发现的问题
list_mod_configs	递归扫描配置目录，并列出所有配置文件及其模组 ID、格式和大小
validate_mod_configs	检查所有配置文件中的常见问题：空值、无效数字、解析错误和过长字符串
compare_mod_configs	比较两个配置目录（整合包更新前后），并报告新增、移除或更改的文件
find_orphaned_configs	查找其模组 JAR 已不再存在于 mods/ 目录中的配置文件
get_mod_default_config	返回热门模组（Sodium、OptiFine、Phosphor、Lithium、Fabric API）的已知默认配置或基线配置

支持的配置格式

格式	扩展名	加载器
Forge INI 风格	.cfg	Forge
Fabric TOML	.toml	Fabric
JSON	.json	任意

功能

• 多格式解析 — 原生支持 Forge .cfg、Fabric .toml 和 .json 配置文件
• 验证引擎 — 检测空值、无效数字、解析错误和过长字符串
• 配置比较 — 按键进行差异比较，以追踪整合包更新带来的变化
• 孤立文件检测 — 将配置文件与已安装的模组 JAR 及内置的已知模组数据库进行匹配
• 默认配置 — 为热门性能模组提供内置的可靠默认配置
• 完全离线 — 不进行网络调用；所有数据均来自本地或内置内容

安装

先决条件

• Node.js 18+
• npm

构建

cd mc-mod-config-mcp
npm install
npm run build

作为独立 MCP 服务运行

node dist/index.js

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

MCP 客户端配置

将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "mc-mod-config": {
      "command": "node",
      "args": ["${MC_MOD_CONFIG_ROOT}/dist/index.js"]
    }
  }
}

路径说明： 将 ${MC_MOD_CONFIG_ROOT} 替换为本项目根目录的绝对路径。在 Windows 上，请使用正斜杠：["C:/path/to/mc-mod-config-mcp/dist/index.js"]（把 C:/path/to/ 替换成你的实际路径）。也可以设置指向项目根目录的环境变量 MC_MOD_CONFIG_ROOT，并在配置中使用该变量。

配置

本工具零配置即可用（内置默认值，任何环境开箱即用）。以下项目可通过环境变量或项目根目录 .env 文件覆盖（复制 .env.example 为 .env）：

变量	默认值	说明
MOD_CONFIG_EXTENSIONS	cfg,toml,json	支持扫描/解析的配置文件扩展名（逗号分隔，可扩展自定义扩展名）
MOD_CONFIG_MAX_FILE_MB	50	单个配置文件大小上限（MB），超过则跳过
MOD_CONFIG_MAX_STRING_LEN	500	校验时字符串值长度告警阈值

扩展已知模组默认配置库：编辑 src/mod-defaults.json（构建后为 dist/mod-defaults.json），在 defaults 下新增或覆盖模组即可，无需改代码。例如新增 "iris": { "name": "Iris", "fallbackConfig": { "enableShaders": true } }。

优先级：环境变量 > .env 文件 > 内置默认值。改动后重启 MCP 服务生效。

使用示例

读取配置文件

{
  "name": "read_mod_config",
  "arguments": {
    "configPath": "/path/to/mods/sodium/sodium.toml"
  }
}

列出整合包中的所有配置文件

{
  "name": "list_mod_configs",
  "arguments": {
    "configDir": "/path/to/modpack/config"
  }
}

检查配置问题

{
  "name": "validate_mod_configs",
  "arguments": {
    "configDir": "/path/to/modpack/config"
  }
}

比较更新前后的配置文件

{
  "name": "compare_mod_configs",
  "arguments": {
    "oldConfigDir": "/path/to/old-modpack/config",
    "newConfigDir": "/path/to/new-modpack/config"
  }
}

查找孤立配置文件

{
  "name": "find_orphaned_configs",
  "arguments": {
    "modsDir": "/path/to/modpack/mods",
    "configDir": "/path/to/modpack/config"
  }
}

获取模组的默认配置

{
  "name": "get_mod_default_config",
  "arguments": {
    "modId": "sodium"
  }
}

架构

mc-mod-config-mcp/
├── src/
│   └── index.ts        # MCP server + all tool implementations
├── dist/               # Compiled JavaScript (output of tsc)
├── skills/
│   └── mc-mod-config-helper.md  # Trae Work skill for config management
├── __tests__/
│   └── unit.test.ts    # Unit tests (fully offline)
├── package.json        # Node.js dependencies (@modelcontextprotocol/sdk, zod)
├── tsconfig.json       # TypeScript config (CommonJS output)
└── .gitignore

MCP 使用官方 @modelcontextprotocol/sdk v1.x，并采用 McpServer 和 StdioServerTransport。

测试

npm run build
npm test

所有单元测试均可完全离线运行，无需安装 Minecraft。

平台兼容性

工具	Windows	macOS	Linux
read_mod_config	✅	✅	✅
list_mod_configs	✅	✅	✅
validate_mod_configs	✅	✅	✅
compare_mod_configs	✅	✅	✅
find_orphaned_configs	✅	✅	✅
get_mod_default_config	✅	✅	✅

所有工具都使用跨平台的 Node.js fs 和 path API。处理前，所有路径都会解析为绝对路径。Forge .cfg 解析器会处理分区、类型检测和带引号的值；Fabric .toml 解析器会处理嵌套表和数组。

许可证

MIT