rpgmaker-xp-mcp

git clone https://github.com/SerifeusStudio/rpgmaker-xp-mcp.git
cd rpgmaker-xp-mcp
npm install
npm run build

その後、以下の設定では、コマンドとして dist/index.js のパスを指定して node を使用してください。

get_actors · get_actor · update_actor · create_actor · search_actors

XP のアクターは、MZ 形式の特徴ではなく parameters Table（6×100。各レベルの MaxHP、MaxSP、STR、DEX、AGI、INT）を使用します。create_actor はデフォルトで線形の成長曲線を生成します。装備スロットは weapon_id と armor1_id～armor4_id（盾／兜／胴／アクセサリー）です。

get_items · get_weapons · get_armors · get_skills · update_item · search_items · create_weapon · create_armor

create_weapon／create_armor は、エディターのデフォルトフィールドを使って Weapons.rxdata／Armors.rxdata に追加します（任意のフィールドを上書きできます）。防具の kind は、0＝盾、1＝兜、2＝胴、3＝アクセサリーです。

get_skill · create_skill · create_damage_skill · create_healing_skill · create_state_skill · update_skill · search_skills

XP にダメージ計算式はありません。ダメージは、ステータス影響率（物理は atk_f／str_f、魔法は int_f）で補正した power を、対象の pdef_f／mdef_f で軽減した値です。負の power は回復を意味します。 create_buff_skill はありません。XP にバフシステムはないため、ステートを使用してください。

対象範囲：0＝なし、1＝敵1体、2＝敵全体、3＝味方1体、4＝味方全体、 5＝味方1体（HP 0）、6＝味方全体（HP 0）、7＝使用者。

get_map · get_map_infos · get_map_events · get_map_event · update_map_event · create_map_event · create_transfer_event · search_map_events · add_event_command · add_show_text

マップは Data/MapXXX.rxdata に保存されています。get_map は includeTiles: true が指定されていない場合、タイルの Table を要約します。イベントはイベント ID をキーとするハッシュです。

add_show_text は、XP のメッセージ構造（1行目＝コード 101、続きの行＝401、1つのボックスにつき4行）を処理します。XP 固有の仕様として、コード 101 はテキストを直接保持します（VX 以降とは異なります）。選択肢のテキストは 102 配列と 402 分岐の両方に重複して保存されるため、両者の内容を一致させる必要があります。移動ルートは 209／509 です。

get_map_design_guide · get_map_size_advisory · create_map · get_map_tiles · set_map_tiles · fill_region · apply_autotile · scatter_tiles

apply_autotile はオートタイルをペイントし、8 近傍の接続性に基づいてセルごとに継ぎ目のないエッジバリエーションを計算します。有機的な形状の blob（池、湖、森）、cells リスト（川、曲がりくねった道）、または region 矩形（四角形の床のみ）を指定してください。scatter_tiles は、オプションの焦点グラデーションを使い、指定した密度で小物を配置します。これらを組み合わせることで、マップがプログラムで生成されたように見せてしまう、四角ばった池や角に固まったディテールを避けられます。MAP-DESIGN.md §5b を参照してください。

レイヤー（Map.data の z、z0→z1→z2 の順に描画＝エディターの Layer 1/2/3）は、役割に応じて割り当てます。z0 は地形（オートタイル）、z1 は地面の小物（優先度 0）、z2 は頭上の要素（優先度 > 0 — プレイヤーが後ろを歩く樹冠や屋根）です。

タイル ID：0 = 空、48–383 = オートタイル（slot=id/48-1、variant=id%48）、≥384 = 通常のタイル（col=(id-384)%8、row=(id-384)/8）。

マップを作成する前に get_map_design_guide を読み込んでください。create_map も、基本ルールをインラインで返します。get_map_size_advisory は、画面数、焦点となるポイントの目標数、推奨される小物の配置密度、既存のマップのサイズ超過に関する警告を報告します。

validate_assets · validate_connectivity

validate_assets は、すべてのデータファイルをスキャンし、参照されているグラフィックとオーディオのファイル名を調べます。対象は、タイルセット、オートタイル、パノラマ、フォグ、バトルバック、キャラクター、バトラー、アイコンのグラフィック、アニメーション、ウィンドウスキン、タイトル、ゲームオーバー、トランジション、BGM/BGS/ME、マップイベントのスプライトです。ディスク上にファイルがないものを報告します。参照切れは、通常、実行時まで検出されません。まずプロジェクトの Graphics/ と Audio/ を調べ、次に RTP を調べます。拡張子にかかわらず、ベース名を照合します。

validate_connectivity はワールドの移動グラフを構築し、開始マップから到達できないマップ、存在しないマップまたは範囲外のタイルを指す移動先、行き止まりを報告します。

create_tileset_identification_harness · get_tileset_catalog · save_tileset_catalog · validate_tileset_catalog · render_tileset_atlas · render_map

create_tileset_identification_harness は、根拠を重視したレビュー用バンドルを作成します。元のシート、タイル ID を焼き込んだラベル付きコピー、背景が透明な個別のタイル画像、元の行、オートタイルのソース、エンジンのメタデータ、カタログのテンプレート、インタラクティブなブラウザページが含まれます。レビュー済みのラベル、想定用途、オブジェクトのグリッド、レイヤー、確信度は別個のカタログに保存されるため、通行可能性や見た目の類似性が、知らないうちに意味上の断定へ変わることはありません。TILESET-CATALOG.md を参照してください。

render_tileset_atlas は、タイルセットをラベル付き PNG としてレンダリングします。グリッド付きで拡大し、各タイルの ID を焼き込み、通行可能性を示すドット（赤 = 通行不可、オレンジ = 一部通行可能）と、7 つのオートタイルスロットを示す凡例を表示します。

render_map は、マップのタイルレイヤーをフラットなトップダウンの PNG プレビューとしてエディターの外部でレンダリングするため、作成したものを視覚的に確認できます。タイルセットのグラフィック（ID ≥ 384）とオートタイル（ID 48–383、相互検証済みの 48 バリエーションの象限テーブルを使用）を使って、3 つのレイヤーすべてを合成します。オプション：layers、scale、region、drawGrid、drawEvents、passability。Data/.mcp-preview/map<NNN>.png に書き込み、パスを返します。

レイアウトのプレビューのみ — 優先度／頭上要素の描画順、フォグ、パノラマ、天候は含まれません。また、オートタイルのアニメーションにはフレーム 0 を使用します。

classify_asset · verify_tileset · register_tileset キャンバスの寸法だけでシートを分類すると、別のエンジン向けに作成されたアセットが気付かないうちに誤ってインポートされます。そのため、これらのツールは真のコンテンツタイルサイズを検出します（キャンバスを均等に分割できる候補を使ったエッジ周期性に基づき、標準の32pxを優先します）。さらに、ファイル名の特徴も確認します。$／! の接頭辞がある場合は、タイルセットではなく Characters に配置する単一オブジェクトのスプライトです。A1～A5 は、コンテンツが32pxではない場合に限りMV/MZオートタイルシートを示し、それ以外の場合はバトラーのバリエーションです。

verify_tileset はグリッドを重ねたプレビューを作成し、インポート前にスケールの問題を確認できるようにします。register_tileset は、シートに合ったサイズの通行設定／優先度／地形のテーブルを含む、保護機能付きの Tilesets.rxdata エントリーを追加します。また、明示的に強制されない限り、標準形式ではないアセットの登録を拒否します。

データベース — get_database · get_database_entry · update_database_entry

専用ツールがないもの（Classes、States、Enemies、Troops、CommonEvents、Tilesets…）も含め、すべてのデータベースファイルに汎用的にアクセスできます。タイルセットの通行可否は passages テーブルに格納されています。0 = 通行可能、1/2/4/8 = 下／左／右／上を通行不可、15 = 通行不可、+64 = 茂み、+128 = カウンターです。

スクリプト — get_scripts · get_script · update_script · create_script · search_scripts

zlib の処理を含む、RGSS スクリプトへの完全なアクセスを提供します。ソースは [magic, name, zlib-deflated code] のトリプレットとして保存されます。スクリプトごとのマジックナンバーはエディターでは意味を持ちません。慣例として、create_script は Main の上にスクリプトを挿入します。バイナリーセーフのため、スクリプトデータがUTF-8変換を経由することはありません。

システム — get_system · get_variables · set_variable_name · get_switches · set_switch_name · get_game_title · update_game_title · update_starting_position

.rxdata ファイルは、ベンダー提供のバグ修正版 @hyrious/marshal（src/vendor/marshal/） で解析し、プレーンな JSON に変換します。Ruby オブジェクトは、インスタンス変数をフィールドとして（先頭の @ を除いて）、{ "_class": "RPG::Actor", ... } になります。

ベンダー提供の理由： 上流版の ≤0.3.3 では、負のマルチバイト Marshal 整数が誤ってデコードされます。−150 が +106 としてデコードされます。XP では回復量は負の威力で表されるため、このバグにより、保存時にすべての回復スキルが気付かないうちにダメージスキルに変換されていました。詳細は research/REPORT.md をご覧ください。

RGSS のバイナリークラス Table（タイルおよびパラメーターのグリッド）、Color、Tone には専用のコーデックがあります。保存時、文字列は Ruby 1.9 のエンコーディング ivar を付けずに生のバイト文字列として書き込まれます。そうしないと XP の Ruby 1.8 / RGSS104E で読み込めません。 ゲームのタイトルは MZ と異なり、System データではなく Game.ini に格納されています。

RMXP のインストールに含まれるテンプレート .rxdata ファイル 16 個のうち、15 個はラウンドトリップ後もバイト単位で同一です。例外は Scripts.rxdata です。ラウンドトリップテストでは失敗扱いにせず、対象から除外します。このファイルには zlib 圧縮されたソースがバイナリー文字列として格納されているため、データベースの他の部分で使われる UTF-8 のパスではなく、生のパス（readRxdataRaw）が必要です。スクリプトツールは正しく処理します。スキップするのはラウンドトリップテストのみです。

• 自動バックアップ — セッション中にファイルへ初めて書き込む前に、元のファイルを Data/.mcp-backup/<name>.bak にコピーします（Game.ini の場合はプロジェクトのルート）。冒頭の警告をご覧ください。バックアップはファイルごとにセッション中 1 回です。
• 保存リビジョンマーカー — マップおよびイベントの書き込み時に、エディターと同様に System.magic_number を再生成します。これにより、既存のセーブファイルは変更後のマップを再読み込みし、古いコピーを保持しません。
• イベントリストの不変条件 — 保存時にコマンドリストを正規化します。すべてのコマンドに code／indent／parameters が設定され、末尾の {code: 0, indent: 0, parameters: []} 終端コマンドが必ず含まれます。
• 検証済みのエンジン計算式 — スキルツールには、Game_Battler 3 から抽出した XP の実際のダメージ計算アルゴリズムを記載しています。また、ヘルパーはデフォルトデータベースの規則（回復は負の威力で、int_f は 50）に合わせて調整されています。

サーバーは独自のガイダンスを提供するため、リポジトリを読み取れるクライアントに限らず、あらゆる MCP クライアントが規則を利用できます。

• サーバーの指示は接続時に送信され（ガバナンスとマップ設計の規則）、ほとんどのクライアントでコンテキストに挿入されます。
• ガイドはMCP リソース（rpgmaker-xp://docs/…）として公開されています。 map-design、tileset-catalog、authoring、wisdom。
• get_map_design_guide はガイド全体を返し、create_map はその主要な規則をインラインで返します。