universal-game-modder

通用游戏 Mod 工具

一个 MCP 服务，可在 AI Agent 的驱动下检查和 Mod 任意游戏。

Universal Game Modder（UGM）是一个本地 Model Context Protocol 服务，可让 AI Agent（例如 Claude Code 中的 Claude）获得游戏逆向工程和 Mod 制作能力：它会自动检测游戏引擎，然后提供一套用于分析和修补二进制文件的工具——全部在你自己的机器上本地运行，无需云服务，也不进行遥测。

这是免费开源核心版（v0.1.3）。

---

⚠️ 负责任使用声明

UGM 是一款通用二进制分析与互操作工具，旨在用于对你合法拥有或获准分析的软件进行Mod 制作、互操作、安全研究和教育。 你需对自己的使用方式负责。安装前，请阅读 ACCEPTABLE_USE.md 和 LICENSE-EULA.md。

---

免费版包含的内容

• 一个 stdio MCP 服务，由 Agent 连接并驱动。
• 游戏引擎自动检测——指定游戏目录后，它会根据文件特征识别 Unity（Mono / IL2CPP）、Unreal、Godot、Java 和原生二进制文件。
• 原生二进制分析与修补工具集——PE 头分析、十六进制读取 / 写入 / 搜索 / 替换、IDA 风格的模式扫描、字符串提取、校验和及二进制差异比较，均在进程内原生运行（无需外部工具）。

引导式 game-modder 工作流技能和委托式反编译后端将在后续版本中推出；此版本包含 MCP 服务、引擎检测和原生工具集。

免费版不包含的内容（Pro 层级）

Web 控制面板、委托式 Unity / Unreal / JAR 反编译后端以及原生反汇编属于 Pro 层级，不包含在此版本中。免费版本身已具备完整功能，可用于引擎检测和原生二进制处理。

---

要求

• Node.js 18+（使用 ES 模块和 better-sqlite3）
• Claude Code 或任何支持 MCP 的客户端
• Windows / macOS / Linux（原生工具跨平台；最精简的版本不包含任何特定操作系统的二进制文件）

---

安装

# from the repo root
./setup.ps1

或手动安装（dist/ 中提供预构建文件；此版本无需编译）：

npm install

然后在 MCP 客户端中注册该服务。对于 Claude Code，请将以下内容添加到 MCP 配置中：

{
  "mcpServers": {
    "universal-game-modder": {
      "command": "node",
      "args": ["dist/index.js"]
    }
  }
}

首次运行时，ugm.config.json 中提供的是空占位符——免费版不需要外部路径。（Pro 委托后端才需要填写这些路径。）

配置解析

服务会读取以下第一个存在的文件，并将其与内置默认值合并：

1. UGM_CONFIG 环境变量指定的文件
2. package.json 旁边的 ugm.config.local.json——用于存放特定于你机器的路径；请勿将其纳入版本控制（仓库的 .gitignore 已配置好）
3. ugm.config.json——纳入版本控制的文件，仅含占位符

因此，你可以填写后端路径，而无需编辑任何可能被纳入发行版或拉取请求的文件。

---

快速入门

连接后，让 Agent 按顺序完成以下步骤。下面的每个示例在每次发布前都会针对真实二进制文件执行验证——请参阅已验证示例。

参数命名： 文件级工具使用 file_path（比较时使用 file_path_a / file_path_b）。游戏目录工具使用 game_path。反汇编工具使用 binary_path。

1. 检测游戏使用的技术：

detect_engine  { "game_path": "C:\\Path\\To\\Game" }

2. 将其设为活动目标：

load_game  { "game_path": "C:\\Path\\To\\Game" }

3. 分析二进制文件：

analyze_file_format  { "file_path": "...\\SomeBinary.dll" }   # magic bytes, managed vs native
analyze_pe_full      { "file_path": "...\\SomeBinary.exe" }   # PE headers, sections, data directories

4. 搜索并检查：

extract_strings          { "file_path": "...", "min_length": 8 }
extract_dll_classes      { "file_path": "...", "search_terms": ["Health","Damage"] }
pattern_scan             { "file_path": "...", "pattern": "48 8B ?? ?? ?? ?? ??" }
search_binary_pattern    { "file_path": "...", "patterns": ["maxHealth"] }

5. 修补并验证：

hex_read       { "file_path": "...", "offset": 4096, "length": 64 }
hex_replace    { "file_path": "...", "search_hex": "90 90", "replace_hex": "EB 00" }
calculate_checksums       { "file_path": "..." }              # before/after integrity
compare_binaries_detailed { "file_path_a": "...", "file_path_b": "..." }

6. 反汇编（原生，已包含）：

disassemble_function  { "binary_path": "...\\SomeBinary.exe", "rva": 4096 }
disassemble_range     { "binary_path": "...\\SomeBinary.exe", "rva": 4096 }

完整免费版工具列表

这 29 个工具完全在进程内运行，无需外部后端。

原生二进制工具（19 个）——除非另有说明，均接受 file_path： 检测 / PE：analyze_pe_full、analyze_file_format、analyze_dll_structure、rva_to_offset（+rva）、offset_to_rva（+offset） 十六进制：hex_read（+offset）、hex_write（+offset,hex_data）、hex_search（+hex_pattern）、hex_replace（+replace_hex） 扫描：pattern_scan（+pattern）、pattern_scan_all（+pattern）、search_binary_pattern（+patterns） 字符串 / 类：extract_strings、extract_strings_advanced、extract_dll_classes 完整性 / 差异：calculate_checksums、compare_binaries_detailed（file_path_a,file_path_b） Godot：analyze_godot_pck 反汇编：disassemble_function（binary_path,rva）

工作流 / 会话工具（10 个）： detect_engine、load_game、game_status、find_steam_games、mod_this_game、find_gameplay_values、build_and_deploy、debug_mod、scaffold_mod、list_available_tools

服务还会列出哪些工具（Pro 后端）

透明起见：该服务共公布 100 个工具。其余 64 个是 Unity（27 个）、Unreal（11 个）和 Java/JAR（26 个）反编译套件，它们会转发到外部 Pro 级后端可执行文件。这些工具会出现在工具列表中，但在未配置后端时调用其中任意一个，都会返回明确的错误：

ERROR: Backend unity-decompiler not configured (missing executable path)

这是免费版中的预期行为，并非缺陷。在 ugm.config.json 中配置这些工具的路径（Pro），即可启用它们。

已验证示例

上面的 Quickstart 调用并非空谈。每个版本发布前都必须通过验证：针对真实 PE 二进制文件执行这些调用，并要求每个调用都返回真实数据。v0.1.3 的验证（2026-09-02，在恢复后的发布版本上进行）运行了验证门禁中的 20 个文档所述调用和 3 项正常失败检查；结果记录在 VERIFICATION.md 中。

---

许可证

UGM 代码根据 MIT License 发布。工具的使用还受 LICENSE-EULA.md 和 ACCEPTABLE_USE.md 约束。Pro 级后端使用的第三方组件已在 licenses/ 中注明。

更新日志

请参阅 CHANGELOG.md。当前版本：v0.1.3——配置不再包含机器路径；磁盘故障后，发布版本已恢复并重新验证。v0.1.2 修复了引擎检测；v0.1.1 修复了文档并添加了验证门禁。