rpgmaker-mv-mcp

RPG Maker MV MCP サーバー

Model Context Protocol サーバーです。AI アシスタント （Claude Code、Claude Desktop、またはあらゆる MCP クライアント）を、RPG Maker MV プロジェクトの共同開発者にします。操作対象すべてを自動でバックアップします。

アシスタントに、次のようなことを頼めます。

「ファイアボールのスキルを作成してください。魔法ダメージ、a.mat * 4 - b.mdf * 2、MP 12、炎属性で。」 「ゲーム内で町長について言及しているイベントをすべて探してください。」 「城門に、『止まれ！何者だ？』と言う衛兵を配置してください。」 「すべての武器のバランスを調整してください。攻撃力を一律で10％上げてください。」 「プロジェクトを検証してください。何か壊れていますか？」

主な特長

• データベースへのフルアクセス — 12 種類すべてのデータベース（アクター、クラス、スキル、アイテム、武器、防具、敵、トループ、ステート、アニメーション、タイルセット、コモンイベント）と System.json に、コンパクトな汎用 CRUD インターフェースからアクセスできます。
• 高水準のスキルビルダー — 名前と計算式を指定するだけで、エディターで有効なダメージ／回復／強化／ステート系スキルを作成できます。
• マップとイベント — マップの作成、イベントの作成／編集／削除、イベントコマンドの一括挿入、メッセージボックスの自動分割を伴う会話の追加、組み込みのイベントコマンドコードリファレンスの参照ができます。
• タイルセットとマップの描画 — タイルセット（シート、自動タイルの種類、通行可否）を調べ、シート画像を確認し、マップのタイルセットを切り替え、長方形、塗りつぶし、単一セルで地面、水、壁、オブジェクトを描画できます。自動タイルの端と角はエディターとまったく同じ方法で計算されるため、ゲーム内でも正しく表示されます。render_map では結果をテキストで確認できます。
• マップを確認 — render_map_image は、実際のタイルセット画像、自動タイル、影、イベントスプライト、番号付きイベントマーカー、リージョン ID、オプションのグリッドを使って、マップを PNG にレンダリングします。これにより、アシスタントは手探りで作業する代わりに、作成した内容を確認できます。
• マップ接続 — connect_maps は、1 回の呼び出しで 2 つのマップに双方向の「プレイヤー移動」ドアを設置します（出現タイル、フェード、効果音を指定可能）。list_map_connections では、マップグラフ、一方向のドア、接続先が無効なドア、到達できないマップを確認できます。
• 一括編集とバランス調整 — bulk_update_records（「すべての武器の攻撃力を +10%」など）とドライラン差分、ステータス曲線を生成する generate_param_curve ／ generate_enemy_scaling、balance_report（クラス曲線、敵の HP に対するダメージ、敵の脅威度）、simulate_battle（実際のダメージ計算式を使った、トループ対パーティのモンテカルロシミュレーション）が利用できます。
• ローカライズ — export_texts ／ import_texts では、ゲーム内のすべてのテキスト（データベース、システム用語、マップ名、会話、選択肢、戦闘イベント）を CSV または JSON でやり取りできます。制御コードを維持し、長い会話は追加のメッセージボックスに分割します。
• スキルファイル、プロンプト、リソース — 同梱の SKILL.md ワークフローガイド、MCP リソースとしてのリファレンステーブル、すぐに使えるプロンプト（new_town、balance_check など）については、スキル、プロンプト、リソースを参照してください。
• すべてを検索 — すべてのデータベースと、すべてのマップ上のすべてのイベントを対象に部分一致検索できます。イベントコマンドリスト内も検索できるため、特定の会話を表示するイベントやスクリプトを実行するイベントを見つけられます。
• プラグイン管理 — エディター独自の js/plugins.js 形式で、プラグインの有効化／無効化／設定、新しいプラグインのひな形作成、プラグインソースの編集ができます。
• プレイテスト制御 — NW.js 経由でゲームを起動し（一般的なインストール先から自動検出）、標準出力／標準エラー出力を取得できます。または、組み込みの HTTP サーバー経由でブラウザーに配信できます。
• 制作支援ツール — build_dialogue_tree は、入れ子になった会話と選択肢、カットシーンの効果（フェード、音声、画像、移動ルートなど）、ゲーム進行のコマンド（戦闘、ショップ、アイテム、パーティ、シーンなど）を、適切なインデントのイベントコマンドに変換します。create_event_from_template は、宝箱、鍵のかかったドア、宿屋、ショップ、セーブポイント、NPC を 1 回の呼び出しで作成します。詳しくはカットシーンとゲーム進行のノードを参照してください。
• アセット — import_asset は画像や音声をプロジェクトにコピーし、list_assets はアセットの一覧と使用箇所を表示し、preview_asset はアシスタントが画像を確認できるようにします。詳しくはアセットを参照してください。
• マップ生成とスタンプ — generate_map は、入口／出口／宝箱のマーカーがあるシード付きのダンジョンや洞窟を作成します。capture_stamp ／ place_stamp を使えば、手作業で作成したマップの一部を再利用できます。詳しくはマップ生成とスタンプを参照してください。
• 分析 — audit_assets、lint_events、simulate_event を使って、ゲームを起動せずにイベントまたはプロジェクト全体を確認できます。詳しくは分析を参照してください。find_usages は ID の読み取り、書き込み、使用箇所をすべて表示し、check_references は存在しないレコードへの参照を検出します。また、analyze_progression では、到達可能なマップとイベントを確認できます。詳しくは使用箇所と進行の分析を参照してください。
• 安全対策 — 各セッションでファイルを初めて変更する前に、すべてのファイルが .mcp-backups/ にスナップショットとして保存されます。restore_backup で変更を元に戻し、validate_project でリリース前に壊れた参照を検出できます。また、変更セットを使えば、編集内容をまとめてステージングし、1 ステップでコミットして取り消せます。

インストール

Node.js 18 以降が必要です。

クイックスタート（npm）

Claude Code または Claude Desktop のユーザーに最も簡単な方法です。

npm install -g @xerolo44/rpgmaker-mv-mcp

続いて設定します（下記を参照）。パッケージは npmjs.com および MCP Registry で入手できます。

Claude Code の設定

claude mcp add rpgmaker-mv -- npx @xerolo44/rpgmaker-mv-mcp --project "/path/to/YourGame"

Claude Desktop の設定

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "rpgmaker-mv": {
      "command": "npx",
      "args": [
        "@xerolo44/rpgmaker-mv-mcp",
        "--project", "/path/to/YourGame"
      ]
    }
  }
}

--project は省略可能です。指定しない場合は、まずアシスタントに set_project を呼び出すよう依頼してください。 プロジェクトはセッションの途中でも切り替えられます。

カスタムコネクター／URL ベースのクライアント（HTTPS）— 実験的

一部のクライアント（「カスタムコネクターを追加」などの UI）は、ローカルプロセスを起動せず、代わりに URL に接続します。その場合は、HTTPS モードでサーバーを実行してください。

node dist/index.js --http [port]   # default port 3939

これにより、https://127.0.0.1:<port>/mcp で Streamable HTTP MCP エンドポイントが起動し、localhost のみにバインドされます（ネットワークからは決してアクセスできません。すべてのリクエストはバインドアドレスだけでなく、接続ソケットのアドレスと照合されます）。localhost／127.0.0.1 用の自己署名 TLS 証明書が初回起動時に生成され、プロジェクト内の .certs/（gitignore 対象）にキャッシュされます。

ステータス： このエンドポイントはプロトコルレベルで完全に検証済みです（ハンドシェイク、セッション管理、および初回リリースの 41 個のツールを HTTPS 経由で curl を使って直接テスト済みです）。保証できないのは、GUI でコネクターを追加する際の一連の操作が自己署名の localhost 証明書を受け入れるかどうかです。通常のページとして URL を開くため、手動で「続行」を選択した後に受け入れるものもあります。一方、バックグラウンドの接続チェックがローカル生成の証明書を信頼せず、ユーザー向けのエラーも表示しないため、黙って拒否するものもあります。コネクターの追加処理が止まったまま何も表示されずに失敗する場合、ほぼ間違いなくこれが原因です。これはこのサーバーの問題ではなく、そのクライアントの証明書の信頼処理に関する制限です。現在、このサーバーを確実かつ手間なく利用するには、上記の stdio モード（Claude Code CLI／Claude Desktop のローカルサーバー設定）を使ってください。--http は、クライアントが URL を明示的に必要とする場合にのみ使用してください。

コネクターを使用するには、サーバープロセスを実行し続ける必要があります。コネクターを追加する前に、専用のターミナルウィンドウでサーバーを起動し、そのウィンドウを開いたままにしてください。

ツールリファレンス（78 個のツール）

グループ	ツール
プロジェクト	set_project, get_project_info
データベース	list_records, get_record, update_record, create_record, get_system, update_system, set_switch_name, set_variable_name
スキルヘルパー	create_damage_skill, create_healing_skill, create_buff_skill, create_state_skill
検索	search_records, search_map_events
マップとイベント	list_maps, get_map, create_map, update_map, get_event, update_event, create_event, delete_event, add_event_command, add_dialogue, event_command_reference
オーサリング	build_dialogue_tree, create_event_from_template
タイルセットと描画	get_tileset_info, get_tileset_image, set_map_tileset, paint_tiles, render_map, render_map_image, render_diff
生成	generate_map, capture_stamp, place_stamp, list_stamps
マップ接続	connect_maps, list_map_connections
一括処理とバランス調整	bulk_update_records, generate_param_curve, generate_enemy_scaling, balance_report, simulate_battle
ローカライズ	export_texts, import_texts
スキルファイル	install_skills
プラグイン	list_plugins, configure_plugin, add_plugin, remove_plugin, create_plugin, read_plugin, write_plugin
プレイテスト	playtest_start, playtest_status, playtest_log, playtest_stop
分析	audit_assets, lint_events, simulate_event, find_usages, check_references, analyze_progression
アセット	import_asset, list_assets, preview_asset
安全性	list_backups, restore_backup, validate_project, editor_status, begin_changeset, commit_changeset, discard_changeset, undo_changeset

各ツールの説明は AI 向けに記述されています。パラメーターの意味、RPG Maker 固有の仕様（対象範囲、コマンドコード、1 始まりの配列）、関連ツールへの参照がすべてスキーマに含まれているため、アシスタントは外部ドキュメントなしでサーバーを利用できます。

ツールプロファイル

すべての78個のツールがデフォルトで登録されています。クライアントによってはツール一覧が短いほうが扱いやすいため、--tools（カンマ区切りのリスト）または環境変数 RPGMV_TOOLS を使って、一部のツールグループだけを登録できます。

claude mcp add rpgmaker-mv -- npx @xerolo44/rpgmaker-mv-mcp --project "/path/to/YourGame" --tools maps,tiles,render,authoring

グループ：project、database、maps、tiles、render、plugins、playtest、search、maintenance（バックアップ、検証、editor_status、変更セットのツール）、connect、balance、localization、authoring、generation、analysis、assets。project（set_project、get_project_info）は常に有効で、all（デフォルト）を指定するとすべてが有効になります。不明なグループ名を指定すると、メッセージを表示してサーバーが終了します。install_skills、リソース、プロンプトは、どのプロファイルでも常に利用できます。

グループごとのツール数（77個のツールと、常に有効な install_skills を合わせて78個）：

• project（2）：set_project、get_project_info
• database（12）：list_records、get_record、update_record、create_record、get_system、set_switch_name、set_variable_name、update_system、create_damage_skill、create_healing_skill、create_buff_skill、create_state_skill
• maps（11）：list_maps、get_map、update_map、get_event、update_event、create_event、delete_event、add_event_command、add_dialogue、create_map、event_command_reference
• tiles（5）：get_tileset_info、get_tileset_image、set_map_tileset、paint_tiles、render_map
• render（2）：render_map_image、render_diff
• plugins（7）：list_plugins、configure_plugin、add_plugin、remove_plugin、create_plugin、read_plugin、write_plugin
• playtest（4）：playtest_start、playtest_status、playtest_log、playtest_stop
• search（2）：search_records、search_map_events
• maintenance（8）：list_backups、restore_backup、editor_status、validate_project、begin_changeset、commit_changeset、discard_changeset、undo_changeset
• connect（2）：connect_maps、list_map_connections
• balance（5）：bulk_update_records、generate_param_curve、generate_enemy_scaling、balance_report、simulate_battle
• localization（2）：export_texts、import_texts
• authoring（2）：build_dialogue_tree、create_event_from_template
• generation（4）：generate_map、capture_stamp、place_stamp、list_stamps
• analysis（6）：audit_assets、lint_events、simulate_event、find_usages、check_references、analyze_progression
• assets（3）：import_asset、list_assets、preview_asset

変更セット（取り消し可能なトランザクション編集）

複数の手順にわたる変更では、各呼び出しでディスクに書き込むのではなく、変更セットでまとめてください。

1. begin_changeset {label} — 以降、すべての編集ツールは結果をメモリ上にステージングします。読み取り（get_map、get_record、list_plugins など）ではステージング済みの編集内容が反映されますが、コミットするまでディスクには何も書き込まれません。プレイテストで確認できるのは、コミット済みのファイルだけです。
2. 通常どおり編集します。
3. commit_changeset を実行すると、ステージング済みのすべてのファイルが一括で書き込まれます（ステージング済みの .json ファイルは事前に検証されます。無効なファイルが1つでもあれば何も書き込まれず、変更セットは開いたままになります）。ファイルごとの概要が返されます。または、discard_changeset を実行してすべての変更を破棄します。
4. undo_changeset を実行すると、.mcp-backups/changesets/ にあるジャーナルから直近のコミットを取り消します（さらに前に戻るには、繰り返し実行します）。ファイルをコミット前の状態に復元するため、その後に加えた編集も上書きされます。

一度に開ける変更セットは1つだけです。変更セットを開いている間は restore_backup を実行できず、set_project を実行すると変更セットは破棄されます。コミット中にプロセスが終了した場合、次回プロジェクトを開いたときに、未完了のコミットはロールバックされます（最初にディスク上のファイルがバックアップされます）。この処理については、set_project と editor_status から報告されます。常に、RPG Maker エディターは閉じておいてください。

スキル、プロンプト、リソース

ツールに加えて、サーバーは MCP クライアントが利用できる3種類の組み込みガイダンスを提供します。

スキルファイル（skills/<name>/SKILL.md）は、アシスタント向けの短いワークフローガイドです。リソース（rpgmaker://skills/<name>）として提供され、install_skills ツールを使ってゲームプロジェクトにコピーできます。これにより、Claude Code はそのプロジェクト内で自動的に読み込みます（.claude/skills/、または scope: "user" を指定すると ~/.claude/skills/）。

スキル	内容
rpgmaker-mv-workflow	安全ルール、データ規約、用途別のツール、リリース前のアセットと分析
rpgmaker-map-building	計画 → 描画 → 確認 → 修正のループ、レイヤー、タイルの選択、マップの接続
rpgmaker-event-writing	会話、選択肢、インデント規則、スイッチ、一度限りの宝箱、トリガー
rpgmaker-balancing	目標、レポート／シミュレーションのワークフロー、曲線、ドライランによる一括編集
rpgmaker-localization	エクスポート／インポートのワークフロー、制御文字、メッセージの長さ
rpgmaker-plugin-dev	プラグインヘッダー、エンジンメソッドのエイリアス化、プラグインコマンド、テスト

リソース — rpgmaker://reference/event-commands、trait-codes、damage-formulas、database-fields は、アシスタントが最も必要とする参照表で、ツールを呼び出さずに利用できます。

プロンプト — MCP プロンプトに対応したクライアントでは、コマンドとして表示される、すぐに使えるワークフローです。new_town、design_dungeon、add_quest、balance_check、review_dialogue、translate_game、project_health があります。

マップ生成とスタンプ

generate_map は、既存の空のマップ（mapId）または新しいマップ（create。MapInfos.json にも登録されます）に、ダンジョン（通路でつながった部屋）または洞窟（有機的な形状でつながった領域）を生成します。結果は決定論的です。同じ seed、サイズ、オプションを指定すると、同じレイアウトになり、使用したシードは必ず返されます。すでにタイルまたはイベントがあるマップは、overwrite: true を渡さない限り拒否されます。

• タイルプロファイル。 マップはプロファイル（floor、wall、任意の wallTop、任意の重み付き decor）を使って描画されます。指定しない場合は、タイルセット自体のデータから候補が提案され（床には通行可能な A2 の種類、壁には通行を妨げる A4 の種類）、profileUsed／profileNotes として返されます。床が通行可能でない場合、壁が移動を妨げない場合、または入口から結果全体に到達できない場合、何も書き込まれません。
• マーカー。 markers（既定では入口と出口。宝箱はなし）は、優先度 0 の空のイベントを配置します。名前は Entrance、Exit、Chest 1..n で、プレイヤーの通行を妨げることはありません。これらはプレースホルダーです。ドアを接続するには connect_maps を使用し（allowOverlap を渡すか、先に delete_event でマーカーを削除してください）、宝箱には create_event_from_template を使って内容を設定します。
• サイズ。 ダンジョンには少なくとも 14x7（または 7x14）が必要です。洞窟は約 13x13 以上で安定します（テストでは MV の既定サイズ 17x13 で失敗したことはありません）。9x9～12x12 および細長いマップは、多くのシードで失敗します。別のシードを試すか、より大きなマップを使用してください。
• 見た目の確認。 render_map_image（showPassability を試してください）と render_diff を使用します。壁面は1行に単純化され、装飾はまばらです。確認済みの内容と未確認の内容については、CHANGELOG.md を参照してください。

スタンプは再利用可能なマップの一部です。capture_stamp は、長方形範囲（最大 64x64、6層すべて、および既定では範囲内のイベントも含む）を <project>/.mcp-stamps/<name>.json に保存します。place_stamp は、同じタイルセットを使うマップ上の左上隅 (x, y) に貼り付け、list_stamps は利用可能なスタンプを表示します。配置時には、すべてのレイヤー上の範囲を置き換え、周囲に合わせてオートタイルの端を再形成し、範囲からはみ出すことはありません。回転や反転には対応していません。

アセット

プロジェクトの画像および音声ファイル（img/* と audio/*、18 個のフォルダー）を扱うツールが 3 つあります。

• import_asset {source, folder, name?, overwrite?} は、コンピューターから <project>/<folder>/<name>.<ext> にファイルをコピーします。source には、ローカルドライブ上の通常ファイルへの絶対パスを指定する必要があります（相対パス、ネットワーク共有、デバイス、シンボリックリンクは不可）。ファイル形式はヘッダーのみから読み取られ、フォルダーに適合している必要があります。img/* では PNG シグネチャとヘッダーを持つファイル、audio/* では OggS（Ogg）で始まるファイル、または ftyp ボックスを持つファイル（M4A）を受け付けます。拡張子はソース名ではなく、ヘッダーの内容から決定されます。変換やサイズ変更は行われず、ファイルの残りの部分はチェックされません。サイズ上限は画像が 32 MiB、音声が 128 MiB です。
• list_assets {folder?, includeUsage?, limit?} は、1 つまたはすべてのフォルダーのファイルを、サイズ、PNG の寸法、警告（ヘッダーと拡張子の不一致、フォルダーに合わないシートサイズ、インターレース PNG）とともに一覧表示します。また、参照スキャンの対象となるフォルダーについては、usedBy と unused も表示します。未使用とは、データベース、マップ、コモンイベント、または敵グループに、その名前と完全一致する参照（大文字と小文字を区別）がないことを意味します。名前でファイルを読み込むプラグインやスクリプトは検出されません。
• preview_asset {folder, name, maxSize?} は、img/* フォルダー内の PNG を画像として返します（長辺が最大 maxSize ピクセルになるよう、ニアレストネイバー法で拡大縮小）。img/characters と img/faces では、名前から推測されるシートレイアウトを使用します。インターレース PNG、32 MiB を超えるファイル、1,600 万ピクセルを超える画像は拒否されます。音声はプレビューできません。

名前のルール。 名前は 1～64 文字で、使用できるのは A-Z a-z 0-9 space _ ! $ ( ) - です。先頭には英字、数字、!、または $ を使用し、末尾にスペースを置くことはできません。ドットは使用できません（拡張子は自動的に追加されます）。パス区切り文字も使用できず、Windows の予約デバイス名（CON、NUL、COM1、LPT1 など）も指定できません。img/characters では、先頭に連続する ! と $ の中に $ が含まれる名前（$Boss、!$Chest）は 1 文字用シートになります。! はマップ上で垂直方向のオフセットを付けないことを意味します。

バックアップと変更セット。 大文字と小文字を区別せず同じ名前のファイルがすでに存在する場合、overwrite: true のときにのみ置き換えられます。他の編集と同様に、サーバーセッション中にファイルへ加える最初の変更では、そのファイルのスナップショットが .mcp-backups/ に保存されます（list_backups、restore_backup）。そのため、バックアップにはセッション開始前のファイルが保持されます（set_project を再度呼び出すとスナップショットが最初から作成されます）。同じサーバーセッション中に作成済み、またはすでに置き換え済みのファイルには、その中間バージョンのバックアップはありません。バイナリファイルはステージングできないため、変更セットが開いている間は import_asset が拒否されます。先に変更セットをコミットするか破棄してください。インポートが拒否された場合、何も書き込まれません。音声の場合、.ogg または .m4a の対応ファイルがないと警告が表示されます（MV の Web ビルドでは両方が必要です）。

カットシーンとゲームフローのノード

会話、選択肢、条件、スイッチ、変数、移動に加えて、build_dialogue_tree はこれらのノードを適切にインデントされたコマンドにコンパイルします。MV エディターと同様に、すべての選択肢、if/else、バトルの分岐は、本文のインデント位置に空の {code: 0} 行を置いて終了します（空の分岐はその行だけです）。エンジンはこれをスキップします。

• カットシーン： wait、fade（アウト／イン）、tint、flash、shake、weather、playAudio、 fadeAudio、showPicture、erasePicture、animation、balloon、moveRoute。ルートは ステップのリストです（up、turnLeft、{wait: 10}、{jump: {x, y}}、{switchOn: 5}、{speed: 4}、 など）。繰り返しルート（repeat: true）は終了しないため、完了を待つことはできず、明示的な wait: true は拒否されます。
• ゲームフロー： battle（onWin、onEscape、onLose の本文。エディターと同様に、分岐とその終了コマンドは canEscape または canLose がオンになっているか、onWin にノードがある場合にのみ記述されます。どちらもない場合、バトルは単一のコマンドとなり、その後に続く処理へ進みます。オフになっているチェックボックスに対応する分岐の本文は拒否されます）、shop、callCommon、label／jump、exit、comment、 gold、item（アイテム、武器、防具）、party、learnSkill、recoverAll、nameInput、 plugin（プラグインコマンド行）、scene（メニュー、セーブ、ゲームオーバー、タイトル）。

例：tree 引数として使用するか、コマンドのみを確認するには dryRun: true を指定します。

[
  { "fade": "out" },
  { "battle": { "troopId": 3, "canLose": true,
      "onWin": [{ "gold": 200 }],
      "onLose": [{ "say": "Defeated..." }, { "scene": "gameOver" }] } },
  { "fade": "in" },
  { "shop": { "goods": [{ "type": "item", "id": 1 }, { "type": "weapon", "id": 2, "price": 300 }] } }
]

simulate_event は実行結果をドライランできます。演出コマンドはスキップされ、cosmetic にカウントされます。また、battleResult（win、escape、lose）によって実行するバトル分岐が選択されます。コマンドのレイアウトは公式の MV コアスクリプトと照合し、ブロックと移動ルートの構造は公開 MV プロジェクトの実際のマップファイルと照合しましたが、実際のゲームでは実行していません。そのため、重要なイベントはプレイテストしてください。制限事項については CHANGELOG.md を参照してください。

分析

ゲームを起動せずに実行できるチェック：

• audit_assets — プロジェクトが参照するすべての画像ファイルと音声ファイル（アクター、敵、タイルセット、マップ、イベントページ、イベントコマンドの一部（顔グラフィック、ピクチャ、音声、戦闘背景、遠景、アクターと乗り物のグラフィック）、System）が存在するかを確認します。また、大文字と小文字の不一致（Windows では問題ありませんが、Linux/macOS/web では動作しません）を一覧表示し、未使用ファイルも任意で一覧表示します。結果にはスキャン対象外のもの（たとえばプラグインのパラメーター）が記載されるため、「未使用」ファイルにはプラグインだけが使うファイルが含まれる場合があります。
• lint_events — マップ、コモンイベント、敵グループのイベントコマンドリストを静的にチェックします。ブロック構造と終了コマンドの不整合、到達不能なコマンド、長すぎるメッセージ行、存在しないマップまたは範囲外のタイルへの移動、存在しないコモンイベントの呼び出し、名前のないスイッチや変数を検出します。検出結果には場所が含まれます。行の長さ制限は概算です。
• simulate_event {mapId, eventId, ...} — 指定した状態（スイッチ、変数、セルフスイッチ、所持金、アイテム、選択肢への回答）をもとに、1 つのイベントページをドライランし、表示されるメッセージ、行われる変更、終了時の移動先、シミュレーションできなかったコマンドを返します。メッセージ、選択肢、条件、ループ、コモンイベント、スイッチ／変数／セルフスイッチ／所持金／アイテムの変更、移動、プラグインコマンド、ラベル、ジャンプに対応しています。戦闘では battleResult（win、escape、lose。デフォルトは win）で選択した分岐を実行します。アニメーションと吹き出し（212、213）、画面のフェード、色調変更、フラッシュ、画面の揺れ（221-225）、ウェイト（230）、ピクチャの表示／移動／消去（231、232、235）、天候（236）、音声の再生／フェード（241、242、245、246、249、250、251）、移動ルート（205）は無視され、cosmetic にのみカウントされます（移動ルートのスイッチ ON／OFF の処理は適用されます）。スクリプト、ピクチャの回転と色調変更（233、234）、その他のコマンドは未対応として一覧表示され、スキップされます。プロジェクトには一切変更を加えません。
• editor_status — RPG Maker エディターのプロセスが実行中と思われるかどうか（Windows のみ。それ以外では null）と、このサーバーが書き込んだファイルが別のものによって変更されたかどうか（通常はエディターが上書き保存した場合）を報告します。報告のみを行います。

使用状況と進行状況の分析

これらのツールはプロジェクト全体（ステージング済み変更セットのデータを含む）を読み取り、ゲームを実行することはありません。

• find_usages {kind, id, limit?} は、スイッチ、変数、アイテム、武器、防具、スキル、ステート、アクター、職業、敵、敵グループ、コモンイベント、マップが読み取られている、書き込まれている、または使用されているすべての場所を、Map003 event 5 page 1 command index 12 や Enemies #4 dropItems のような位置情報とともに一覧表示します（マップ、イベント、コモンイベントの ID は実際の ID で、ページはエディターと同じ 1 から始まる番号、コマンドインデックスは lint_events が報告するものと同じ 0 から始まる位置です）。正確な件数と、読み取られているのに一度も設定されていない（または設定されているのに一度も読み取られていない）スイッチや変数、どこからも呼び出されていないコモンイベント、どこからも移動先に指定されていないマップ、名前のない ID に関する警告も表示します。ID の名前変更、削除、再利用の前に使用してください。
• check_references {limit?} は、存在しないレコードを参照している箇所を検出します。たとえば、敵グループ 1 が存在しないのに敵グループ 1 を指定したバトルの処理、ショップの商品 7、スキルの習得 12、アクター 5、削除済みマップへの移動、存在しないレコードを指定した敵のドロップアイテムや職業の習得スキルなどです。find_usages がインデックス化する参照（イベントコマンド、ページ条件、敵のドロップアイテムと行動、職業の習得スキル、アクターの職業と装備、敵グループのメンバー、アイテムとスキルの効果、エンカウントリスト、System の startMapId と partyMembers）のみを対象に、検出結果を種類と ID ごとにまとめ、件数と最大 3 か所の位置情報を表示します。確認しなかった項目は notes に記載します。ID 0（「なし」）は報告せず、スイッチと変数はチェックしません。データベースファイルが存在しない、または読み取れない場合は、すべてのレコードが存在しないと報告するのではなく、そのファイル名を notes に記載します。リリース前、およびレコードの削除や名前変更後に実行してください。
• analyze_progression {goal?, includeGraph?, limit?} は、スタートマップからゲーム内をたどり、到達可能なマップと到達不能なマップ、出口のないマップ、実行されることのないイベントページ（最初に満たされない条件を含む）、読み取られているのに設定されていない、または設定されているのに読み取られていないスイッチと変数を報告し、平易な言葉で概要を表示します。goal（{switch}、{mapId}、または {event: {mapId, eventId}}）を指定すると、達成できるかどうかと、達成を妨げている理由が追加されます。includeGraph を指定すると、マップ間の移動を示す Mermaid フローチャートが追加されます。

分析で証明できること。 これはプレイスルーを過大近似したものです。ページ条件が成立する可能性があればそのページは実行され、実行されるとすべてのコマンドが反映されるものとして扱います。スイッチはオンにしかならず、アイテムは失われないものとします。そのため、到達不能と一度も設定されないはこのモデルにおける証明ですが、到達可能は「可能性を否定できない」という意味にすぎません。

確認できないこと。 イベントコマンド内の条件（分岐、選択肢）、ダメージ計算式（スイッチや変数を設定できる JavaScript として評価されます）、スクリプトコマンドとプラグインコマンド、ターゲットに変数を使う移動や戦闘、有効化されたプラグインとそのパラメーターおよびメモ欄（コモンイベントを呼び出したり、スイッチを設定したり、プレイヤーを移動させたりする可能性があります）、乗り物の開始マップは確認できません。スイッチがオフになる動作はモデル化せず、ソフトロックも検出しません。find_usages もすべてのコマンドをインデックス化するわけではなく、check_references が確認できるのもインデックスに含まれるものだけです（スクリプトコマンドやプラグインコマンド、メモ欄、プラグインパラメーター、ダメージ計算式、変数を指定するコマンドによる参照は検出できません）。一覧は CHANGELOG.md に記載されています。check_references は、find_usages のように配列内の位置ではなく、レコードが存在するかどうかを id フィールドで判定します。そのため、行の ID が位置と異なるテーブルでは、誤った結果が出る場合があります。find_usages、check_references、analyze_progression はプロジェクトのインデックスをメモリ上に構築します。Control Switches / Variables コマンドで ID の範囲全体を指定する、悪意のあるプロジェクトや機械生成されたプロジェクトでは、大量のメモリと処理時間を消費することがあります（5000 件のイベントを約 1000 万件の参照に展開した場合、約 1.2 GB のメモリ使用量が測定されました）。 信頼度。 プロジェクトにスクリプトまたはプラグインのコマンド、変数で指定された転送または戦闘、有効なプラグイン（または読み取れなかったマップや js/plugins.js）が含まれている場合、uncertainty.confidence は low になり、概要にはその理由が記載されます。コマンド内の条件やダメージ計算式だけが、解析で確認できない処理を行う場合は high のままです。到達不能や未使用の結果を信頼できるのは high の場合だけです。カスタムプラグインを使用しているプロジェクトのほとんどは low を報告します。find_usages の「一度も…しない」という警告にも同じことが当てはまり、スクリプトまたはプラグインのコマンドがその ID を操作する可能性がある場合は注記が付きます。

バランス調整ツールの概要

一括編集、曲線ジェネレーター、import_texts は、デフォルトで ドライラン を実行します。差分を返し、dryRun: false を指定するまでは何も書き込みません。simulate_battle と balance_report は、プロジェクトの実際のクラス曲線、装備、特性、ダメージ計算式を使用します（計算式は安全に評価され、実行前に許可リストと照合されます）。ステート、バフ、アイテムはモデル化しないため、結果は参考として扱い、重要な戦闘はプレイテストしてください。

バックアップ

セッション中にファイルを初めて変更すると、元のファイルが相対パスを維持したまま <project>/.mcp-backups/<session-timestamp>/ にコピーされます。セッションは最大 10 件まで保持されます。list_backups で利用可能なバックアップを確認でき、restore_backup で単一ファイルまたはセッション全体を復元できます。復元前に現在の状態もバックアップされるため、復元を元に戻すこともできます。

ゲームプロジェクトをバージョン管理している場合は、.mcp-backups/ と .mcp-stamps/ をゲームプロジェクトの .gitignore に追加してください（スタンプを共有する場合は .mcp-stamps/ を除外してください）。変更セットのジャーナルは .mcp-backups/changesets/ に保存され、削除されません。

重要な注意事項

• サーバーがファイルを編集している間は、RPG Maker MV エディターを閉じてください（またはエディターから保存しないでください）。 エディターはデータベース全体をメモリに保持しており、保存時に JSON ファイルを上書きして外部での変更を破棄します。ここで行った編集を確認するには、エディターでプロジェクトを開き直してください。
• MV のデータベース配列は 1 始まりで、インデックス 0 には null が入っています。ツールがこれを自動的に処理し、ID は常に配列の位置と一致します。
• MZ プロジェクト（.rmmzproject）も受け付けます。データ形式はほぼ同じですが、テストは行われていません。
• このリリースで確認されている制限事項（エディタープロセス名が未検証、生成マップの視覚的な品質が未確認、スクリプトによるプレイテストランナーがない、など）は CHANGELOG.md に記載されています。
• タイルの描画には paint_tiles を使用してください（update_map は data の変更を拒否します）。get_tileset_info / get_tileset_image でタイルを選択してください。タイルセットでタイルのシートに画像が割り当てられていない場合、タイルが表示されず、呼び出しは拒否されます。
• render_map_image は img/ からタイルセットとキャラクターの画像を読み込みます（暗号化された .rpgmvp を使用する環境では表示できません）。使用可能な画像がないシートは単色で描画され、回答に一覧表示されます。水はアニメーションの最初のフレームで描画されます。
• export_texts はプロジェクト内（デフォルトは localization/）に書き込みます。ファイルは上書き前にバックアップされ、既存の翻訳はキーに基づいて引き継がれます。
• NW.js プレイテストでは、Steam と KADOKAWA のインストールパス、プロジェクト独自の Game.exe、環境変数 RPGMAKER_MV_NWJS の順に自動検出します。
• ブラウザーのプレイテストモードでは、コンソール出力はブラウザーの開発者ツールに表示されます。playtest_log が必要な場合は、NW.js モードを使用してください。

ソースからのビルド

コントリビューターの方、またはローカルでのビルドを希望する方は、次の手順を実行してください。

git clone https://github.com/Xerolo44/RPG-Maker-MV-MCP.git
cd RPG-Maker-MV-MCP
npm install
npm run build

次に、Claude Code でローカルビルドを使用します。

claude mcp add rpgmaker-mv -- node "$(pwd)/dist/index.js" --project "/path/to/YourGame"

開発

npm run build   # compile TypeScript to dist/
npm run test:unit  # node:test unit tests in test/ (PNG, formulas, renderer, battle maths, generators, ...)
npm run smoke      # end-to-end test: real stdio client against a generated MV project
npm test           # build + unit tests (test/) + smoke test (what CI runs)

プロジェクトの構成とガイドラインについては CONTRIBUTING.md、リリース履歴については CHANGELOG.md、ツールの信頼モデルについては SECURITY.md を参照してください（ツールはファイルシステム全体にアクセスできます。--http モードを自分のマシン以外に公開する前にお読みください）。

ライセンス

MIT