utmt-mcp

<div align="center">

<kbd>中文</kbd> · <kbd>English</kbd>

</div>

通过 UndertaleModCli 读取和导出 GameMaker 数据文件（.win、.ios、.droid、.unx）的 MCP 服务器。

专为 LLM 工具调用而设计 —— 所有输出均为干净的 JSON，实体按名称查找。

跨平台 —— 支持 Windows、macOS、Linux。UndertaleModCli 为这三个平台都提供了官方构建。

快速开始

npx utmt-mcp

或全局安装：

npm install -g utmt-mcp
utmt-mcp

环境要求

• Node.js 18+
• .NET 运行时（UndertaleModCli 需要）
• UndertaleModCli —— 加入 PATH，或通过环境变量 / 工具参数指定

安装 UndertaleModCli

从 GitHub Releases 下载对应平台的构建包，解压后任选一种方式：

• 把可执行文件加入系统 PATH，或
• 将 UTMT_CLI_PATH 环境变量设置为可执行文件的完整路径

在 Windows 上 CLI 二进制文件带 Windows 可执行文件后缀；macOS 和 Linux 上没有后缀。其余用法完全一致。

配置

环境变量

变量	说明
UTMT_CLI_PATH	UndertaleModCli 可执行文件的完整路径

MCP 客户端配置

在 MCP 客户端中（如 Claude Desktop、Cursor、Claude Code 等）：

{
  "mcpServers": {
    "utmt": {
      "command": "npx",
      "args": ["-y", "utmt-mcp"],
      "env": {
        "UTMT_CLI_PATH": "/path/to/UndertaleModCli"
      }
    }
  }
}

或者在每次工具调用时显式传入 CLI 路径（无需环境变量）：

{
  "mcpServers": {
    "utmt": {
      "command": "npx",
      "args": ["-y", "utmt-mcp"]
    }
  }
}

工具

utmt-info

获取 GameMaker 数据文件的概览信息。返回 JSON，包含项目名称、GM 版本、isYYC 标志和各类资源数量。

参数：

• dataFilePath（必填）— 数据文件路径
• cliPath（可选）— UndertaleModCli 路径

utmt-list-entities

列出指定类型的实体。返回 JSON 数组，包含索引、名称和简要属性。

参数：

• dataFilePath（必填）
• entityType（必填）— 可选值：sprites、sounds、scripts、code、rooms、gameobjects、fonts、backgrounds、paths、shaders、strings、timelines、embeddedtextures、embeddedaudio、extensions、sequences、particlesystems
• filter（可选）— 不区分大小写的名称过滤
• offset（可选）— 分页偏移（默认：0）
• limit（可选）— 最大返回数，1-500（默认：50）
• cliPath（可选）

utmt-get-entity

获取单个实体的详细信息。返回 JSON，包含所有属性。

参数：

• dataFilePath（必填）
• entityType（必填）— 可选值：sprite、sound、script、code、room、gameobject、font、string、generalinfo
• name（必填）— 实体名称（string 类型用数字索引；generalinfo 忽略此参数）
• cliPath（可选）

utmt-decompile-code

将代码条目反编译回 GML 源码。YYC 编译的游戏不可用。

参数：

• dataFilePath（必填）
• codeName（必填）— 代码条目名称（如 gml_Script_myFunction）
• cliPath（可选）

utmt-export-entity

将单个实体导出到磁盘。

参数：

• dataFilePath（必填）
• entityType（必填）— 可选值：sprite、sound、code、embeddedtexture
• name（必填）— 实体名称（embeddedtexture 用数字索引）
• outputPath（必填）— 输出文件或目录路径
• cliPath（可选）

导出格式：

• sprite → 输出目录中的 PNG 帧
• sound → .ogg 或 .wav 文件
• code → 反编译后的 .gml 文件
• embeddedtexture → PNG 文件

utmt-search

跨所有类型按名称模式搜索实体。不区分大小写的子串匹配。

参数：

• dataFilePath（必填）
• query（必填）— 搜索关键字
• entityTypes（可选）— 限定搜索类型（空 = 全部）
• cliPath（可选）

utmt-get-room-assets

获取一个房间内使用的所有资源：精灵（含尺寸及使用它们的对象）、对象（含位置和精灵）、代码条目（来自事件）以及图层汇总。

参数：

• dataFilePath（必填）
• roomName（必填）— 房间名称（如 scene_gameplay）
• cliPath（可选）

utmt-search-strings

按内容搜索字符串表。字符串没有名字，常规 utmt-search（按名字）搜不到它们。返回匹配的字符串索引和内容（每条截断到 500 字符）。

参数：

• dataFilePath（必填）
• query（必填）— 不区分大小写的内容搜索关键字
• limit（可选）— 最大返回数（默认：50）
• cliPath（可选）

utmt-export-all

批量导出某类型的全部资源到目录。支持：sprites、sounds、embeddedtextures。精灵导出为每个精灵一个 PNG 帧子目录，声音为 ogg/wav 文件，内嵌纹理为编号 PNG。返回导出/失败数量。

参数：

• dataFilePath（必填）
• entityType（必填）— 可选值：sprites、sounds、embeddedtextures
• outputDir（必填）— 导出目标目录
• cliPath（可选）

utmt-get-object-code

反编译对象上某个事件的 GML 代码。返回 JSON，包含对象名、事件类型、子类型和反编译代码。子类型是零基索引：alarm 是闹钟编号；step 0=begin/1=normal/2=end；collision 是另一对象索引；其余映射到事件专属按键。单条目事件用 0（如 create）。YYC 编译的游戏不可用。

参数：

• dataFilePath（必填）
• objectName（必填）— 对象名（如 o_player）
• eventType（必填）— 可选值：create、destroy、alarm、step、collision、keyboard、mouse、other、draw、keypress、keyrelease、trigger、cleanup、gesture、precreate
• subtype（可选）— 零基事件子类型索引（默认：0）
• cliPath（可选）

utmt-find-references

查找某个资产的引用。sprite：哪些对象使用它作为精灵、哪些房间包含这些对象的实例；object：哪些房间实例化它、哪些对象继承它；variable/function：哪些代码条目引用了它（扫描字节码指令）；string：传入字符串索引，查找推入该字符串的代码条目。返回 JSON。

参数：

• dataFilePath（必填）
• type（必填）— sprite、object、variable、function、string
• name（必填）— 资产名（string 类型传索引）
• cliPath（可选）

utmt-find-unknown-functions

列出未被任何脚本、代码条目、内置函数或扩展函数解析的函数条目（缺失脚本、外部 DLL 函数、YYC 隐藏函数）。反混淆和完整性审计用。

参数：

• dataFilePath（必填）
• cliPath（可选）

utmt-extract-embedded-data

从 YYC 编译的可执行文件或内存 dump 中提取内嵌的 GameMaker 数据文件。扫描输入二进制中的 FORM+GEN8 头，把恢复的数据文件（data.win）写入输出路径。纯字节扫描，无需 UndertaleModCli。

参数：

• dataFilePath（必填）— YYC 可执行文件或 dump
• outputPath（必填）— 输出数据文件路径

utmt-dead-resource-analysis

分析哪些字符串、变量、函数未被使用（没有被任何资产名或代码指令引用）。返回 JSON，含各分类总数和样本。内置变量/函数已排除。字符串检查还能发现未本地化的残留文本。

参数：

• dataFilePath（必填）
• limit（可选）— 每类样本上限（默认：50）
• cliPath（可选）

utmt-find-replace

在全部代码条目中查找并替换文本（或正则），然后重新编译。写操作：结果保存到新的输出文件，原始文件绝不被修改。仅适用于 VM 编译的游戏（非 YYC）。

参数：

• dataFilePath（必填）— 输入数据文件
• outputFilePath（必填）— 输出文件（必须与输入不同）
• find（必填）— 查找文本（或正则）
• replace（必填）— 替换文本
• caseSensitive（可选）— 区分大小写（默认：false）
• isRegex（可选）— 按正则处理（默认：false）
• cliPath（可选）

utmt-export-strings-json

将字符串表全部导出为 JSON 文件。用于本地化、词频分析、文本资产审计。

参数：

• dataFilePath（必填）
• outputPath（必填）— 输出 JSON 路径
• cliPath（可选）

支持的数据文件格式

• data.win — Windows
• game.ios — iOS
• game.droid — Android
• game.unx — Linux/macOS

开发

git clone <repo>
cd utmt-mcp
pnpm install
pnpm run build

测试

npm test

单元测试零依赖（Node 内置 node --test），校验所有脚本生成器的 null 安全、转义和结构。集成测试会真实调用 UndertaleModCli：对一个生成的空白数据文件跑全部工具脚本（覆盖 GM 1.x 空集合路径），若检测到本机 vividstasis 的 data.win 还会对真实文件再跑一遍。集成测试需要设置 UTMT_CLI_PATH（或 PATH 中能找到 UndertaleModCli）；CLI 或数据文件缺失时对应用例自动跳过。

许可证

MIT

---

<div align="center">

<kbd>中文</kbd> · <kbd>English</kbd>

</div>

<a id="en"></a>

English

MCP server for reading and exporting GameMaker data files (.win, .ios, .droid, .unx) via UndertaleModCli.

Designed for LLM tool use — all output is clean JSON, entity lookup is by name.

Cross-platform — runs on Windows, macOS, and Linux. UndertaleModCli publishes builds for all three platforms.

Quick Start

npx utmt-mcp

Or install globally:

npm install -g utmt-mcp
utmt-mcp

Prerequisites

• Node.js 18+
• .NET runtime (required by UndertaleModCli)
• UndertaleModCli — either in PATH, or specify via env var / tool parameter

Installing UndertaleModCli

Download the build for your platform from GitHub Releases, extract, and either:

• Add the executable to your system PATH, or
• Set the UTMT_CLI_PATH environment variable to the full path of the executable

On Windows the CLI binary has a Windows executable suffix; on macOS and Linux it has no suffix. Everything else is identical.

Configuration

Environment Variables

Variable	Description
UTMT_CLI_PATH	Full path to the UndertaleModCli executable

MCP Client Configuration

In your MCP client (e.g. Claude Desktop, Cursor, Claude Code, etc.):

{
  "mcpServers": {
    "utmt": {
      "command": "npx",
      "args": ["-y", "utmt-mcp"],
      "env": {
        "UTMT_CLI_PATH": "/path/to/UndertaleModCli"
      }
    }
  }
}

Or with an explicit CLI path in each tool call (no env needed):

{
  "mcpServers": {
    "utmt": {
      "command": "npx",
      "args": ["-y", "utmt-mcp"]
    }
  }
}

Tools

utmt-info

Get overview of a GameMaker data file. Returns JSON with project name, GM version, isYYC flag, and resource counts.

Parameters:

• dataFilePath (required) — Path to the data file
• cliPath (optional) — Path to UndertaleModCli

utmt-list-entities

List entities of a given type. Returns JSON array with index, name, and brief properties.

Parameters:

• dataFilePath (required)
• entityType (required) — One of: sprites, sounds, scripts, code, rooms, gameobjects, fonts, backgrounds, paths, shaders, strings, timelines, embeddedtextures, embeddedaudio, extensions, sequences, particlesystems
• filter (optional) — Case-insensitive name filter
• offset (optional) — Pagination offset (default: 0)
• limit (optional) — Max results, 1-500 (default: 50)
• cliPath (optional)

utmt-get-entity

Get detailed info for a single entity. Returns JSON with all properties.

Parameters:

• dataFilePath (required)
• entityType (required) — One of: sprite, sound, script, code, room, gameobject, font, string, generalinfo
• name (required) — Entity name (or numeric index for string type; ignored for generalinfo)
• cliPath (optional)

utmt-decompile-code

Decompile a code entry back to GML source. Not available for YYC-compiled games.

Parameters:

• dataFilePath (required)
• codeName (required) — Code entry name (e.g. gml_Script_myFunction)
• cliPath (optional)

utmt-export-entity

Export a single entity to disk.

Parameters:

• dataFilePath (required)
• entityType (required) — One of: sprite, sound, code, embeddedtexture
• name (required) — Entity name (or numeric index for embeddedtexture)
• outputPath (required) — Output file or directory path
• cliPath (optional)

Export formats:

• sprite → PNG frames in output directory
• sound → .ogg or .wav file
• code → Decompiled .gml file
• embeddedtexture → PNG file

utmt-search

Search entities by name pattern across all types. Case-insensitive substring match.

Parameters:

• dataFilePath (required)
• query (required) — Search query
• entityTypes (optional) — Limit to specific types (empty = all)
• cliPath (optional)

utmt-get-room-assets

Get all assets used in a room: sprites (with dimensions and which objects use them), objects (with position and sprite), code entries (from events), and layer summary.

Parameters:

• dataFilePath (required)
• roomName (required) — Room name (e.g. scene_gameplay)
• cliPath (optional)

utmt-search-strings

Search the string table by content. GameMaker strings have no names, so the regular utmt-search (which matches names) cannot find them. Returns matching string indices and their content, truncated to 500 chars each.

Parameters:

• dataFilePath (required)
• query (required) — Case-insensitive content search query
• limit (optional) — Max results (default: 50)
• cliPath (optional)

utmt-export-all

Batch-export every asset of one type to a directory. Supported types: sprites, sounds, embeddedtextures. Sprites export as per-sprite PNG frame subdirectories, sounds as ogg/wav files, embedded textures as numbered PNGs. Returns exported and failed counts.

Parameters:

• dataFilePath (required)
• entityType (required) — One of: sprites, sounds, embeddedtextures
• outputDir (required) — Output directory for all exported assets
• cliPath (optional)

utmt-get-object-code

Decompile the GML code of a specific event on a game object. Returns JSON with the object name, event type, subtype, and the decompiled code. Subtype is a zero-based index: for alarm it is the alarm number; for step 0=begin, 1=normal, 2=end; for collision it is the other object index; for others it maps to the event-specific key. Use subtype 0 for events that only have one entry (e.g. create). Not available for YYC-compiled games.

Parameters:

• dataFilePath (required)
• objectName (required) — Name of the game object (e.g. o_player)
• eventType (required) — One of: create, destroy, alarm, step, collision, keyboard, mouse, other, draw, keypress, keyrelease, trigger, cleanup, gesture, precreate
• subtype (optional) — Zero-based event subtype index (default: 0)
• cliPath (optional)

utmt-find-references

Find what references a given asset. For sprite: which objects use it as their sprite and which rooms contain instances of those objects. For object: which rooms instance it and which objects inherit from it. For variable/function: which code entries reference it (from bytecode instructions). For string: pass the string index and find code entries that push that string. Returns JSON.

Parameters:

• dataFilePath (required)
• type (required) — sprite, object, variable, function, string
• name (required) — Asset name (or string index for string)
• cliPath (optional)

utmt-find-unknown-functions

List function entries not resolved to any script, code entry, builtin, or extension function (missing scripts, external DLL functions, YYC-hidden functions). Useful for deobfuscation and completeness audits.

Parameters:

• dataFilePath (required)
• cliPath (optional)

utmt-extract-embedded-data

Extract the embedded GameMaker data file from a YYC-compiled executable or a memory dump. Scans the input binary for the FORM+GEN8 header and writes the recovered data file. Pure byte scan, no UndertaleModCli required.

Parameters:

• dataFilePath (required) — YYC executable or dump
• outputPath (required) — Output data file path

utmt-dead-resource-analysis

Analyze which strings, variables, and functions are unused (not referenced by any asset name or code instruction). Returns JSON with totals and a sample per category. Builtin variables/functions are excluded. The string check also catches unlocalized leftover text.

Parameters:

• dataFilePath (required)
• limit (optional) — Max sample entries per category (default: 50)
• cliPath (optional)

utmt-find-replace

Find and replace text (or regex) across ALL code entries, then recompile. WRITE OPERATION: the result is saved to a NEW output file — the original data file is never modified. Only applies to VM-compiled games (not YYC).

Parameters:

• dataFilePath (required) — Input data file
• outputFilePath (required) — Output file (must differ from input)
• find (required) — Text (or regex) to search for
• replace (required) — Replacement text
• caseSensitive (optional) — Case-sensitive search (default: false)
• isRegex (optional) — Treat find as regex (default: false)
• cliPath (optional)

utmt-export-strings-json

Export every string in the string table as a JSON file. Useful for localization, word-frequency analysis, and text asset audits.

Parameters:

• dataFilePath (required)
• outputPath (required) — Output JSON path
• cliPath (optional)

Supported Data File Formats

• data.win — Windows
• game.ios — iOS
• game.droid — Android
• game.unx — Linux/macOS

Development

git clone <repo>
cd utmt-mcp
pnpm install
pnpm run build

Tests

npm test

Unit tests use Node's built-in node --test (zero dependencies) and validate null-safety, escaping, and structure of every script generator. Integration tests invoke UndertaleModCli for real: they run every tool script against a freshly generated blank data file (exercising the GM 1.x null-collection path), and additionally against the local vividstasis data.win when present. Integration tests need UTMT_CLI_PATH (or UndertaleModCli on PATH) and skip the relevant cases when the CLI or data file is unavailable.

License

MIT