HexManiacAdvance (hma-mcp)

一个用于修改 GBA Pokémon ROM 的 MCP 服务。
Claude（或任何 MCP 客户端）通过 HexManiacAdvance 背后的引擎读取和编辑你的 ROM：
使用相同的锚点、表格、脚本编译器和重指向功能，每项编辑都可撤销，保存的文件也能直接在 HMA 中打开。

快速开始 · 示例 · 工具 · 工作原理 · 参与贡献

为什么要用

HMA 已经能理解 ROM：它知道 Pokémon 属性表的位置、哪些字节代表属性类型，以及如何重新编译脚本并在脚本变长时移动它。hma-mcp 让 AI 助手也拥有同样的理解能力，因此你可以用日常语言描述修改，并让它正确完成：

• 无需点击 GUI。 助手直接调用 HMA 引擎，无需操作 HMA 窗口。
• 使用名称，而非字节。 类型、招式、物种和道具均以名称读取和写入（FIRE、THUNDERBOLT）。输入错误时会提供建议并拒绝写入，而不是写入无效数据。
• 自动处理重指向。 脚本或文本变长时，HMA 引擎会找到空闲空间、移动内容并更新所有指针。
• 默认安全。 你发出 save 指令前，不会有任何内容写入磁盘；首次保存时会备份原文件，每项编辑也都能一步撤销。

效果示例

以下是 FireRed (U) 1.0 测试运行中的真实结果：

你： 打开 C:/hacks/firered.gba，并显示妙蛙种子的基础属性。

Claude： （open_rom、read_table） BULBASAUR：45 HP / 49 Atk / 49 Def / 45 Spe / 65 SpA / 65 SpD，GRASS/POISON。

你： 把小火龙改成火/龙属性。

Claude： （write_table_field） CHARMANDER 的 type2：FIRE → DRAGON。尚未保存；说“撤销”即可还原。

你： 在狩猎地带时间结束脚本中再加一声提示音。

Claude： （decompile_script、compile_script） 脚本从 17 字节增长到 20 字节，无法放入原位置，因此 HMA 将它从 1BFBC5 移到了 71A280 的空闲空间，并更新了 1 个指针。锚点 scripts.fromthumb.safari.end 也会随之移动。

你： 保存。

Claude： （save） 已保存 firered.gba 和 firered.toml。原文件已备份到 .hma-mcp-backups/。

快速开始

你需要一个自己转储的 ROM。

1. 获取服务

下载最新的发行版。这些构建版本是独立的，因此无需安装 .NET。

将 hma-mcp 可执行文件放在 resources/ 文件夹旁边。在 macOS 上，下载的构建版本会被隔离，直到你运行 xattr -dr com.apple.quarantine <folder>。

git clone --recurse-submodules https://github.com/dewayneku/hma-mcp.git
cd hma-mcp
dotnet publish src/HmaMcp -c Release -o ~/.local/share/hma-mcp

2. 连接客户端

Claude Code：

claude mcp add --scope user hma -- "C:/Users/you/AppData/Local/hma-mcp/hma-mcp.exe"

--scope user 会让它在每个项目中都可用。服务会在会话启动时加载，因此之后请打开一个新会话。

Claude Desktop（如果你没有使用 .mcpb）和其他 MCP 客户端：

{
  "mcpServers": {
    "hma": { "command": "C:/Users/you/AppData/Local/hma-mcp/hma-mcp.exe" }
  }
}

然后直接提出请求，例如：

• “打开我的 ROM，并列出名称中包含 ‘items’ 的所有表。”
• “将 Pikachu 的基础 Sp. Atk 设为 90，并将属性改为 Electric/Steel。”
• “反编译 scripts.newgame.setflags 并解释它的作用。”
• “查找 512 字节的空闲空间。”

工具

游戏

HMA 支持 FireRed、LeafGreen、Emerald、Ruby 和 Sapphire，以及基于这些游戏制作的改版。FireRed (U) 1.0 已通过 hma-mcp 的端到端测试，Emerald (U) 通过了较短的检查（表格、地图、脚本、文本、保存）。Ruby、Sapphire 和 LeafGreen 使用相同的引擎，但尚未通过 hma-mcp 的测试。欢迎反馈。

工作原理

flowchart LR
    A["Claude / any MCP client"] <-- "MCP over stdio" --> B["hma-mcp<br/>(17 tools)"]
    B --> C["HexManiac.Core<br/>(HMA's engine, built from source)"]
    C <--> D[("your ROM .gba<br/>+ HMA .toml metadata")]

• HMA 是一个 git 子模块（external/HexManiacAdvance），其核心库由 src/HexManiac.Core.Build 从源代码编译，因此服务运行的正是编辑器使用的代码。
• ROM 以无界面方式打开，与 HMA 自己的测试套件打开 ROM 的方式相同。
• compile_script 严格遵循 HMA 代码编辑器的步骤：编译、在内容变大时移动、更新指针，并保留编辑后遗留的孤立子脚本。
• 若要升级到较新的 HMA，请运行 git submodule update --remote external/HexManiacAdvance。

构建过程中发现的 HMA 本身的问题及其修复记录在 docs/hma-upstream-notes.md 中。

测试

python tests/smoke.py <path-to-hma-mcp> [path/to/firered.gba]

• 使用 ROM： 将 ROM 复制到临时文件夹，只编辑副本。检查读取、写入、枚举验证、撤销/重做、必须移动到空闲空间的脚本、hma_edit，以及保存 → 重新打开的往返流程（针对 FireRed (U) 1.0 编写）。tests/smoke_emerald.py 会在 Emerald (U) 上运行较短版本的测试。
• 不使用 ROM： 检查 MCP 握手和工具列表，并打开一个空白 ROM，以便 HMA 加载其所有参考数据。CI 会在 Windows、Linux 和 macOS 上运行这些测试。

法律声明

hma-mcp 不包含、下载或分发 ROM，将来也不会。请将其用于从自己拥有的游戏中转储的 ROM。Pokémon 是 Nintendo、Creatures Inc. 和 GAME FREAK inc. 的商标；本项目与它们无关，也未获其认可。

致谢

• HexManiacAdvance，由 haven1433 和贡献者开发（MIT）。这里的所有 ROM 知识都来自 HMA。
• MCP C# SDK。

采用 MIT 许可；请参阅 LICENSE。