Mc Mod Config

io.github.dcd887Published by GitHub account dcd887v1.0.0Updated Oct 24, 2026

读写 Minecraft 模组配置文件（TOML/JSON），带 schema 校验

VerifiedSTDIODesktop onlyFiles & StorageDeveloper Tools

Overview

AI-generated overview

Local MCP server that lets an assistant read, validate, compare and clean up Minecraft mod config files (.cfg, .toml, .json) from modpacks.

What you can do
  • Read and parse a single mod config file into structured data with reported issues
  • Scan a config directory recursively and list configs with mod ID, format and size
  • Validate all configs for empty values, invalid numbers, parse errors and oversized strings
  • Diff two config directories to show added, removed and changed files across a modpack update
  • Find orphaned configs whose mod JAR is no longer in the mods directory
  • Return bundled default configs for popular performance mods such as Sodium, OptiFine, Phosphor, Lithium and Fabric API
When to use it
Useful when maintaining or troubleshooting a Minecraft modpack: checking why a mod misbehaves, auditing configs after an update, or pruning leftover config files. It is a niche, fully offline helper for modpack authors and players rather than a general-purpose tool.
Requirements
Runs locally over stdio as an npm package (mc-mod-config-mcp) and needs Node.js 18+ and npm; the README describes building it and pointing the client at the compiled entry file with an absolute path. No accounts, API keys or network access are needed; optional environment variables such as MOD_CONFIG_EXTENSIONS, MOD_CONFIG_MAX_FILE_MB and MOD_CONFIG_MAX_STRING_LEN override built-in defaults.
Before you install
Tools read config files from paths you give them, so point them only at modpack directories you intend to expose. The README describes the server as read-only analysis with no network calls, but it does not document any write or delete capability, so do not assume it can repair configs. Config contents are passed to the assistant as tool output.

Installation

In SourceWeft

  1. Open Mc Mod Config in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mc-mod-config-mcp

[M8ven Verified]

MCP server for Minecraft mod configuration file management. Reads, validates, compares, and cleans up .cfg, .toml, and .json config files from modpacks.

Tools

ToolDescription
read_mod_configParse a single config file (.cfg, .toml, .json) and return structured data with any issues
list_mod_configsRecursively scan a config directory and list all configs with mod ID, format, and size
validate_mod_configsValidate all configs for common issues: empty values, invalid numbers, parse errors, oversized strings
compare_mod_configsDiff two config directories (before/after modpack update) and report added/removed/changed files
find_orphaned_configsFind config files whose mod JAR is no longer present in the mods/ directory
get_mod_default_configReturn known default/baseline config for popular mods (Sodium, OptiFine, Phosphor, Lithium, Fabric API)

Supported Config Formats

FormatExtensionLoader
Forge INI-style.cfgForge
Fabric TOML.tomlFabric
JSON.jsonAny

Features

  • Multi-format parsing — handles Forge .cfg, Fabric .toml, and .json configs natively
  • Validation engine — detects empty values, invalid numbers, parse errors, and oversized strings
  • Config comparison — key-level diff for tracking changes across modpack updates
  • Orphan detection — matches config files against installed mod JARs plus a built-in known-mods database
  • Default configs — bundled known-good defaults for popular performance mods
  • Fully offline — no network calls; all data is local or built-in

Installation

Prerequisites

  • Node.js 18+
  • npm

Build

bash
cd mc-mod-config-mcpnpm installnpm 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:

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

Path note: Replace ${MC_MOD_CONFIG_ROOT} with the absolute path to this project's root directory. On Windows, use forward slashes: ["C:/path/to/mc-mod-config-mcp/dist/index.js"]（把 C:/path/to/ 替换成你的实际路径）。 Alternatively, set an environment variable MC_MOD_CONFIG_ROOT pointing to the project root and use the variable in the config.

Configuration

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

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

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

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

Usage Examples

Read a config file

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

List all configs in a modpack

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

Validate configs for issues

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

Compare configs before and after an update

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

Find orphaned configs

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

Get default config for a mod

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

Architecture

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

The MCP uses the official @modelcontextprotocol/sdk v1.x with McpServer and StdioServerTransport.

Testing

bash
npm run buildnpm test

All unit tests are fully offline and do not require a Minecraft installation.

Platform Compatibility

ToolWindowsmacOSLinux
read_mod_config✅✅✅
list_mod_configs✅✅✅
validate_mod_configs✅✅✅
compare_mod_configs✅✅✅
find_orphaned_configs✅✅✅
get_mod_default_config✅✅✅

All tools use cross-platform Node.js fs and path APIs. All paths are resolved as absolute paths before processing. The Forge .cfg parser handles sections, type detection, and quoted values; the Fabric .toml parser handles nested tables and arrays.

License

MIT

Source: README.md at commit 365d450

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the server did not start.

Version history

1
  1. v1.0.0LatestOct 23, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts