HexManiacAdvance (hma-mcp)

GBA Pokémon ROM 改造用のMCPサーバーです。
Claude（または任意の MCP クライアント）が、HexManiacAdvanceのエンジンを通じて ROM を読み取り、編集します。
同じアンカー、テーブル、スクリプトコンパイラー、リポイント機能を使い、すべての編集を元に戻せるうえ、保存したファイルはそのまま HMA で開けます。

クイックスタート · 使用例 · ツール · 仕組み · コントリビューション

なぜ使うのか

HMA はすでに ROM の内容を理解しています。ポケモンのステータステーブルの場所や、どのバイトがタイプを表すか、スクリプトを再コンパイルしてサイズが増えた場合に移動する方法を把握しています。hma-mcp は AI アシスタントに同じ理解力を与えるため、変更内容を普段の言葉で伝えれば、正確に編集できます。

• GUI をクリックする必要はありません。 アシスタントは HMA ウィンドウを操作せず、HMA のエンジンを直接呼び出します。
• バイトではなく名前を使います。 タイプ、わざ、種族、道具は名前（FIRE、THUNDERBOLT）で読み書きできます。入力ミスは不正なデータとして書き込まれず、候補とともに拒否されます。
• リポイントは自動処理されます。 スクリプトやテキストのサイズが増えると、HMA のエンジンが空き領域を探して移動し、すべてのポインターを更新します。
• デフォルトで安全です。 save と指示するまではディスクに一切変更を加えません。初回保存時には元のファイルがバックアップされ、編集はすべて 1 回の取り消し操作で元に戻せます。

使用例

FireRed (U) 1.0 でのテスト実行から得られた実際の結果です。

あなた： C:/hacks/firered.gba を開いて、フシギダネの基本ステータスを見せてください。

Claude： （open_rom、read_table） フシギダネ：HP 45／攻撃 49／防御 49／素早さ 45／特攻 65／特防 65、くさ／どく。

あなた： ヒトカゲをほのお／ドラゴンタイプにしてください。

Claude： （write_table_field） ヒトカゲの type2：FIRE → DRAGON。まだ保存していません。「元に戻す」と言えば取り消せます。

あなた： サファリゾーンの時間切れスクリプトに、チャイムをもう 1 つ追加してください。

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』を含むテーブルをすべて一覧表示して。」
• 「ピカチュウの基礎特攻を90にして、でんき／はがねタイプにして。」
• 「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 のテストスイートが開くのと同じ方法で、ヘッドレスで開きます。
• 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 のハンドシェイクとツール一覧を確認し、HMA が参照データをすべて読み込めるよう、空の ROM を開きます。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 をご覧ください。