loenn-mcp

loenn-mcp

AI エージェント向け Celeste マップエディター — Claude、GitHub Copilot、その他の MCP クライアントで Celeste の .bin マップを完全に編集できるようにする Model Context Protocol（MCP）サーバーです。スクリプト作成や CI に使えるスタンドアロンの pcgscene CLI も備えています。Lönn を開かずに、マップの読み込み、編集、分析、生成、プレビューができます。

「AI エージェント向け」とは、このサーバーを利用する対象（あらゆる MCP クライアント）を指しており、内部で動作するものを指しているわけではありません。ここにあるすべてのツールは決定論的かつ手続き的です。AI は内部にありませんをご覧ください。

Everest の MOD、および Lönn や Ahorn で作成したマップに対応しています。

目次

• 機能
• 安全性：バックアップ、コピー、コミット
• Lönn でマップを開く
• Sprite Fusion のグレーボックスルーム
• Summer Engine のグレーボックスルーム
• 共有 PCG コア（CelPcg）
• seleCte レベル
• ツールリファレンス
• インストールとセットアップ
• JSON のラウンドトリップと作成
• pcgscene CLI
• プロシージャル生成
• 画像からマップへの変換
• シード指定による地形生成
• 分析と洞察
• AI は内部にありません（v7.0.0）
• 設定
• アーキテクチャ
• 要件
• ライセンス

機能

マップを完全に操作する MCP ツール（全リストはツールリファレンスを参照）に加え、スクリプト作成や CI に使える pcgscene コマンドラインツールを備えています。書き込みのたびにタイムスタンプ付きのバックアップが作成され、Lönn で開いているマップへの MCP による書き込みは保護されます。また、Sprite Fusion で描画したグレーボックスルームをそのままインポートできます。

コアツール

読み取りとクエリ

• list_maps — すべての .bin ファイルを一覧表示します
• read_map_overview — 部屋、エンティティ、トリガー、スタイルグラウンドの概要を表示します
• read_room — 部屋の詳細情報（タイル、エンティティ、トリガー、デカール）を表示します
• get_room_tiles — タイルグリッドを生データで取得します（FG または BG）
• read_map_metadata — マップ全体を読み込まずにメタデータをすばやく確認します
• search_entities — 種類、位置、部屋を指定してエンティティを検索します
• search_triggers — 種類を指定してトリガーを検索します
• compare_rooms — 2つの部屋を並べて比較します

編集

• add_entity / remove_entity — エンティティを配置または削除します
• update_entity / move_entity — エンティティのプロパティや位置を変更します
• add_trigger / remove_trigger — トリガーを配置または削除します
• set_room_tiles — タイルグリッドを置き換えます
• add_room / remove_room — 部屋を作成または削除します
• create_map — 新しい .bin ファイルを作成します
• update_room — 部屋のプロパティ（音楽、暗さ、風など）を変更します
• clone_room — 部屋を複製します
• batch_add_entities — 複数のエンティティを一度に追加します
• resize_room — 部屋のサイズを変更します

JSON とコンテンツ作成（JSON の往復変換とコンテンツ作成を参照）

• map_to_json / json_to_map — 任意の .bin を型付き JSON に変換し、元に戻します。バイト単位で一致し、情報が失われる書き込みは拒否します
• check_authoring_json — 手書きのコンテンツを解決します。Lönn プラグインのデフォルト値を補完し、不明な名前にはフラグを立てます
• merge_json_into_map — エンティティ、トリガー、部屋をマップに追加します。ドライランの差分と強調表示付きプレビュー、マップ全体で一意の ID、配置チェックに対応し、追加のみを行います
• run_author_script — JavaScript のコンテンツ作成スクリプト（js/、lucid-dream スタイル）を実行し、その出力をマージします

デカールとエフェクト

• list_decals / add_decal / remove_decal — 前景／背景のデカールを管理します
• list_stylegrounds / add_styleground / update_styleground / remove_styleground — マップのエフェクトを管理します

定義とカタログ

• list_entity_definitions / get_entity_definition — エンティティの種類を閲覧します。マップに配置されている名前（例：MyMod/CloudBoss）で定義を検索します
• find_missing_definitions — マップ内にある、インストール済みの Lönn プラグインで定義されていない名前空間付きのエンティティ／トリガーを検索します
• audit_plugin_coverage — 対応する Lönn プラグインがない C# の [CustomEntity] 名と、C# コードがないプラグインを確認します（.csproj のコンパイル対象リストを読み取ります）
• list_trigger_definitions / get_trigger_definition — トリガーの種類を閲覧します
• list_effect_definitions / get_effect_definition — エフェクトの種類を閲覧します

分析とインサイト

基本分析

• analyze_map — エンティティ数、種類別の内訳、ワールドの境界を分析します
• visualize_map_layout — ASCII のミニマップを表示します
• preview_map_section — 詳細な ASCII プレビューを表示します

高度な分析

• analyze_entity_usage — マップ全体のエンティティ統計を分析します
• analyze_difficulty — 部屋／マップの難易度を推定します
• find_entity_references — 指定した種類のエンティティがある場所をすべて検索します
• detect_map_patterns — 設計の類型（直線型、ハブ型など）を特定します
• analyze_room_connectivity — 隣接グラフを分析します

提案と改善

• suggest_improvements — 部屋に対する実行可能な改善案を提案します
• compare_maps — マップ間の構造的な差分を表示します

Wiki とキャッシュ

• wiki_save / wiki_search / wiki_list / wiki_get — 分析結果を保存し、取得します

プロジェクト管理

• get_mod_info — プロジェクトのメタデータと構造を取得します
• validate_map / batch_validate_and_fix — 自動修正機能付きでプレイ可能かどうかを検証します
• game_status / game_reload_map / game_teleport / game_log — Everest のデバッグサーバーを通じて実行中のゲームを操作します。現在地の確認、編集したマップの再読み込み、部屋への移動、読み込みエラーの確認ができます
• game_play_tas — 部屋のスポーン地点から CelesteTAS の入力を再生し、終了時の部屋、位置、死亡回数、ダッシュ回数を報告します。部屋をクリアできること、または近道が機能しないことを証明します
• validate_audio — マップが参照するすべてのオーディオイベントを GUIDs.txt およびゲームの FMOD バンクと照合し、最も近い一致候補を提案します
• export_room_json / import_room_json — JSON 形式で部屋をやり取りします

差分

• summarize_map_diff — スナップショットを使ってマップの変遷を追跡します

レンダリング

• render_map_html — タイル、色分けされたエンティティマーカー、ズーム／パン、検索、ミニマップを備えたインタラクティブな HTML マッププレビューです。.bin または型付き JSON ダンプを読み込み、計画中のマージ（overlay）をハイライト表示できます。

プロシージャル生成

パターンベースの生成

• build_pattern_library — 既存のマップからパターンを抽出します
• generate_room_from_pattern — 戦略とシードを指定して部屋を生成します
• ingest_external_map — GameBanana からダウンロードしてパターンを抽出します

画像と地形の生成

• generate_map_from_image — 色分けされた画像をプレイ可能なマップに変換します
• generate_terrain_map — パーリンノイズとボロノイ分割のバイオームを使ってマップをプロシージャル生成します
• preview_terrain_biomes — 生成前にバイオームのレイアウトをプレビューします

---

安全性：バックアップ、コピー、コミット

マップが通知なく上書きされることはありません。

• すべての書き込みで、ファイルを置き換える前にタイムスタンプ付きのバックアップが作成されます。バックアップは mod フォルダーの外にあるバックアップストアに保存されます （Everest が読み込まず、mod の git もクリーンな状態に保たれます）： %LOCALAPPDATA%\loenn-mcp\backups\<mod>\<path>\<name>.<YYYYMMDD-HHMMSS-micro>.bin。 各ツールの結果の末尾には、書き込まれたファイルとそのバックアップのファイル名が記載されます。
• 新しいバイト列は置き換え前に再解析され、その後、一時ファイルに書き込まれてアトミックに置き換えられます。
• チャプターマップは、まずコピーしてください：map_copy でコピーし、そのコピーを編集してから map_diff を実行し、続いて map_commit を実行します（まずはドライランを実施してください。一部の部屋のみを対象にできます。プレイヤーのスポーン地点がない部屋など、検証に失敗した部屋は拒否されます）。
• LOENN_MCP_PROTECT（; 区切りの glob リスト。mod からの相対パス）に一致するマップは、map_commit 経由を除き、読み取り専用になります。CEL では次の設定を推奨します： Maps/CEL/Area/*.bin;Maps/CEL/BSide/*.bin;Maps/CEL/CSide/*.bin;Maps/CEL/DSide/*.bin;Maps/CEL/ZSide/*.bin。
• editor_open で起動したエディター、または自分で開いた Lönn でマップが開かれている間は、書き込みが拒否されます。Lönn の次回の保存で書き込みが上書きされるためです。
• map_backups でバックアップを一覧表示し、map_restore でバックアップを復元できます（その前に現在のファイルをバックアップします）。
• map_diff はバイト列ではなく内容を比較します。部屋、ジオメトリ、fg／bg のタイルセル、ID によるエンティティとトリガー、デカール、スタイルグラウンド、メタデータが対象です。Lönn は保存時にファイル全体を再エンコードするため、バイト差分からは有用な情報が得られません。

ラウンドトリップはテスト済みです。フォルダー内のすべてのマップを確認するには（.bin からツリーを経て .bin に戻す場合と、.bin から型付き JSON を経て .bin に戻す場合の両方で、バイト単位で一致します）：

LOENN_MCP_TEST_MAPS="<Maps folder>" python -m unittest discover -s tests -k RealMaps

Lönn でマップを開く

editor_open(map, room) は、指定したマップと部屋で Lönn を起動します。editor_wait は、保存（保存内容のセマンティック差分を報告します）または Lönn の終了まで待機します。editor_close は、まず Lönn に確認してから終了します。force は強制終了します。

この仕組みは、Lönn 1.0.10 のソースコードを読み、Windows でテストした次の仕様に基づいています：

仕組み	動作
Lönn.exe <map.bin>	前回のマップではなく、指定されたマップを開きます。
--storage-directory <dir>	設定、永続化データ、バックアップ、プラグイン設定に <dir> を使用します。MCP は分離されたコピー（設定とプラグイン設定を元に作成した %LOCALAPPDATA%\loenn-mcp\loenn-storage）を使用するため、最近使用したファイルには影響しません。storage="user" は通常の Lönn フォルダーを使用します。
部屋の選択	コマンドラインオプションはありません。Lönn は読み込み時に persistence.lastSelectedRoomName を選択するため、MCP は起動前にそのキー（およびカメラ）を書き込みます。
編集完了の検出	Lönn は <map>.bin.saving に保存し、検証してからマップの上書きに使います。MCP はマップのサイズ、mtime、ハッシュを監視し、.saving が存在する間は無視して、解析可能なバイト列のみを対象にします。
実行中の Lönn での再読み込み	できません。Lönn には IPC も単一インスタンスロックもありません。終了して再起動してください（editor_close の後に editor_open を実行します）。

エディター側はアダプター（loenn_mcp/editors）で構成されています。現在は LoennAdapter を使用しており、RysyAdapter は同じ監視機能で Rysy を起動します（--map）。そのため、ツールのインターフェイスを変更せずに Rysy ベースの構成へ移行できます。

Sprite Fusion のグレーボックスルーム

Sprite Fusion でグレーボックスルームを描画し、Celeste のルームとしてインポートします。

1. sf_make_tileset() は、%LOCALAPPDATA%\loenn-mcp\sprite-fusion に celeste_graybox.png、凡例、README を書き込みます。
2. Sprite Fusion で、タイルサイズを 16 にして celeste_graybox.png をインポートします。1 画面分として、マップを 40x23 セルにします （1 セル = Celeste の 8x8 タイル 1 個）。Collider をオンにしたレイヤーに地面を描画し、bg という名前のレイヤーに背景の壁を描画します。プレイヤー、トゲ、スプリング、リフィル、イチゴ、ジャンプスルー、またはドリームブロックは任意の場所に配置できます。
3. JSON（map.zip）としてエクスポートし、sf_import(export_path, map_path, room, output_path=...) を呼び出します。まずドライランを実行してください。

詳細：

• エクスポート内のタイル ID は、エクスポートされたスプライトシート内のインデックスです。そのため、タイルはピクセル単位でタイルセットと照合されます （Pillow が必要）。照合できない場合は ID を使用します。
• トゲとジャンプスルーは連続する区間ごとに結合され、ドリームブロックは長方形にまとめられます。エンティティには Lönn のデフォルト値が適用されます。
• Lönn の定義があるエンティティのみが配置されます（スプライトが優先されます）。タイルには Sprite Fusion の属性 entity、anchor およびエンティティデータを設定して別のエンティティを配置できます。不明な名前は拒否されます。
• タイルセットに含まれない、コライダーのないレイヤー上のタイルは装飾として扱われ、無視されます。レポートにはその数が表示されます。グレーボックスがうまく遊べるようになってから、Lönn で装飾を追加してください。
• 新しいルームが追加されます（デフォルトでは既存のルームの右側）。既存のルームは replace=true の場合にのみ変更されます。この場合、fg/bg タイルとエンティティが置き換えられ、トリガー、デカール、設定は保持されます。
• カスタム凡例（legend_path）を使うと、独自のタイルセットのタイルを種類や前景タイル文字に対応付けられます。

Summer Engine のグレーボックスルーム

Summer Engine は Godot 4.7 のフォークです。ルームをシーンとして描画して Celeste のルームに戻したり、Celeste のルーム（または Sprite Fusion のエクスポートデータ）を Summer に取り込んで調整したりできます。

• summer_init() は Documents\CEL-Graybox にプロジェクトを作成します。グレーボックスのタイルセットは Godot の TileSet（カスタムデータ kind、ソリッドタイルではコリジョン有効）として作成され、rooms/_template.tscn（レイヤー bg、fg、gameplay とオレンジ色の 40x23 画面枠）およびブリッジスクリプトが celeste/ に作成されます。
• summer_open(scene) は、ルームシーンで Summer エディターを起動します。Summer は AI チャットパネルを開き、サインインを求めます。描画するには 2D タブに切り替えてください。エクスポートする前に Ctrl+S で保存してください。
• summer_export_room(scene, map_path, room, ...) は、sf_import と同じ検証、ドライラン、安全な書き込みの手順で、シーンを Celeste のルームに変換します。replace=true にすると既存のルームが更新され、各ソリッドセルのタイルセットは保持されます。
• summer_import_room(map_path, room) は既存の Celeste のルームをプロジェクトに取り込みます。summer_from_sprite_fusion は Sprite Fusion のエクスポートデータに対して同じ処理を行います。
• グレーボックスタイルではないエンティティは、entity とそのフィールドをメタデータに持つ Marker2D ノードとして引き継がれます。
• Godot のタイルサイズにかかわらず、1 タイルは Celeste の 8x8 タイル 1 個です。他のタイルセットも使用できます（fg／solid／terrain という名前のレイヤー、またはコリジョンのあるタイルはすべてソリッドとして扱われます）。

実行方法：Summer.exe --path <project> --summer-editor-script <script.gd> --summer-editor-script-out <dir> は、インポートのスキャン後、ヘッドレスエディターで GDScript を実行し、result.json を書き込みます。各呼び出しにかかる時間は約 4 秒です。この処理にサインインやネットワーク接続は必要ありません。

共有 PCG コア（CelPcg）

csharp/ には、MCP、CEL の mod、Summer Engine のすべてで利用できるプロシージャル生成コアがあります （設計：docs/PCG-CORE-DESIGN.md）。

• CelPcg.Core（netstandard2.0、依存関係なし）：PCG32 乱数とシード導出、部屋モデル、 リーチモデル（CEL の overworld_gen/reach.py を移植：上方向へのジャンプ 3／横方向へのジャンプ 6、ダッシュ 4、スプリング、リフィル、 ジャンプスルー。登攀なし）、バリデーター（構造と、入口からすべての出口に到達可能かを検証）、プラットフォームチェーン生成器。
• CelPcg.Cli（celpcg）：celpcg generate --exits left:16:4,right:10:4 --difficulty 4 --seed 42 は celpcg-room JSON ドキュメントを出力します。celpcg validate --room room.json は再検証します。
• CelPcg.Tests：dotnet test csharp/CelPcg.Tests（決定性、リーチ制限、バニラのみのエンティティで すべて検証に合格する必要がある生成済みの部屋 1,200 個）。

pcg_generate_room(map_path, room, exits, difficulty, seed, ...) は、初回の使用時に CLI をビルドし（.NET 8 SDK 以降が必要）、部屋を生成して、グレーボックスインポーターと同じ検証済みパス経由で書き込みます。すべての出口への到達が証明された場合にのみ部屋が返されます。失敗したレイアウトは導出したシードで再試行されるため、同じリクエストには常に同じ部屋が返されます。シードは部屋に保存されます（celpcg_seed、celpcg_generator、celpcg_difficulty）。

この最初のバージョンの制限：入口は左または右の出口である必要があります。部屋のスタイルはプラットフォームチェーンのみです。テンプレートや MdMC/WFC による埋め込みはまだありません（設計のフェーズ 4）。

seleCte レベル

seleCte（Louis Robinet、FDG '25）は、多次元マルコフ連鎖を使って Celeste の バニラ部屋のタイルパターンを学習しました。レベルレイアウトを描画し、モデルからサンプリングして各部屋を埋め、Maple ライブラリ上の Julia スクリプトで部屋を、スポーン地点から始まりクリスタルハートで終わる .bin としてエンコードします。

selecte_generate(name, nb_rooms, proba, width, height, seed, ...) は、Python ジェネレーター（uv run）、Julia エンコーダー、続いて結果に対する pcgscene の準備チェックリストを、1 回の呼び出しで一括実行します。レベルの data.json、room_<n>.csv、両方のログ、.bin は <state dir>\selecte\<name> に保存されます。output_path を指定すると、 チェックリストで問題が見つからなかった場合に限り、ガード付き書き込み（バックアップ、保護されたマップ、開いているエディターの確認）で .bin も mod にコピーします（allow_problems=true の場合は問題があってもコピーします）。

• セットアップ：seleCte をクローンし、その中で uv sync と julia --project=. -e "using Pkg; Pkg.instantiate()" を実行します（Julia 1.11 以降。学習済みモデルはクローンに含まれており、Celeste 自体は不要です）。MCP はまず SELECTE_DIR、次にこのリポジトリの隣にある seleCte フォルダー、最後に ~/seleCte の順にクローンを探します。
• width／height が 22x14 なら数秒で実行されます。40x23（1 画面）は部屋ごとに数分かかります。proba が 0 の場合は回廊になり、 1 に近い値では迷宮になります。tries_limit は seleCte のプレイ可能性チェックに失敗した部屋を再サンプリングします。 reset_skeleton はプレイ不可能な部屋を残す代わりに、レイアウトを描き直します。
• seed と model を使うにはパッチ適用済みのクローンが必要です（上流版の seleCte には --seed がなく、常に pe_d5_full を使います）。クローンにこれらがない場合、ツールはジェネレーター自身のエラーを報告します。
• seleCte のプレイ可能性チェックでは重力、ジャンプ、ダッシュを考慮しないため、部屋をクリア可能と証明するものではありません。その確認には game_play_tas または pcg_generate_room のリーチモデルを使ってください。Everest が新しい .bin を登録するのはゲームの再起動後です。

ツールリファレンス

107 個のツールがあり、89 個がデフォルトで一覧表示されます。extra と表示されたツールは、LOENN_MCP_TOOLS=all を設定しない限り非表示です。tools/gen_tool_reference.py によって生成されます。

マップ読み取りツール

ツール	説明
list_maps	プロジェクト内のすべての .bin マップファイルを一覧表示します。
read_map_overview	.bin マップファイルを解析し、部屋と構造の概要を返します。
read_room	特定の部屋の詳細データ（タイル、エンティティ、トリガー）を取得します。
get_room_tiles	部屋のタイルグリッド全体をテキストで取得します。

マップ編集ツール

ツール	説明
add_entity	部屋にエンティティを追加し、マップを保存します。
remove_entity	ID を指定して部屋からエンティティを削除します。
add_trigger	部屋にトリガーを追加し、マップを保存します。
remove_trigger	ID を指定して部屋からトリガーを削除します。
set_room_tiles	部屋のタイルデータを設定します。各行は文字列で、「0」は空気を表します。
add_room	マップに空の部屋を追加します。
remove_room	マップから部屋を削除します。
create_map	新しい空の Celeste .bin マップファイルを作成します。

スタイルグラウンドツール

ツール	説明
list_stylegrounds	マップ内のすべてのスタイルグラウンド（前景および背景エフェクト）を一覧表示します。
add_styleground	マップにスタイルグラウンドエフェクトを追加します。
remove_styleground	レイヤー内のインデックスを指定して、マップからスタイルグラウンドを削除します。
update_styleground	既存のスタイルグラウンドを置き換えずに、プロパティをマージします。

エンティティ／トリガーカタログツール

ツール	説明
list_entity_definitions	プロジェクトで利用可能な Lönn エンティティ定義を一覧表示します。
get_entity_definition	Lönn のエンティティ Lua 定義を読み取り、プロパティを抽出します。
list_trigger_definitions	利用可能な Lönn トリガー定義を一覧表示します。
list_effect_definitions	利用可能な Lönn エフェクト定義を一覧表示します。
find_missing_definitions	インストール済みの Lönn プラグインで定義されていない、マップ内の名前空間付きエンティティとトリガーを一覧表示します。
audit_plugin_coverage	mod の C# [CustomEntity] 名と Lönn プラグイン定義を比較します。
validate_audio	マップが参照するすべてのオーディオイベントをサウンドバンクと照合します。

分析ツール

ツール	説明
analyze_map	マップファイルの詳細な統計情報を取得します。
visualize_map_layout (extra)	マップ内のすべての部屋の位置を ASCII で可視化します。

マッププレビューツール

ツール	説明
preview_map_section	Lönn のミニマップのような、マップセクションの ASCII プレビューを生成します。
render_map_html	ズーム、パン、検索、詳細パネルを備えたインタラクティブな HTML マッププレビューを描画します。

プロシージャル生成ツール

ツール	説明
build_pattern_library (extra)	ローカルの .bin マップをスキャンし、再利用可能なライブラリに部屋のパターンを抽出します。
generate_room_from_pattern (extra)	ライブラリのパターンとランダム性の戦略を使って、新しい部屋を生成します。
validate_room	部屋にプレイ上のよくある問題がないか確認します。
ingest_external_map (extra)	外部 URL から Celeste マップをダウンロードし、部屋のパターンを抽出します。

画像からのマップ生成と地形生成ツール

ツール	説明
generate_map_from_image (extra)	色分けされた画像を、プレイ可能な Celeste マップ全体に変換します。
generate_terrain_map (extra)	Perlin ノイズと Voronoi バイオームを使って、Celeste のマップをプロシージャルに生成します。
preview_terrain_biomes (extra)	マップを作成せずに、地形生成におけるバイオームの配置をプレビューします。

マップ読み取り拡張ツール

ツール	説明
read_map_metadata	部屋の内容をすべて一覧表示せずに、マップの概要メタデータを読み取ります。
search_entities	種類や位置を指定して、すべての部屋（または特定の部屋）のエンティティを検索します。
search_triggers	種類を指定して、すべての部屋のトリガーを検索します。
compare_rooms	同じマップ内の2つの部屋を並べて比較します。

マップ編集拡張ツール

ツール	説明
update_entity	ID を指定して、既存のエンティティのプロパティを更新します。
move_entity	エンティティを新しい位置に移動します。
update_room	部屋レベルのプロパティ（音楽、暗さ、風など）を更新します。
clone_room	既存の部屋を複製し、新しい名前と位置を設定します。
batch_add_entities	1回の呼び出しで部屋に複数のエンティティを追加します。

デカール

ツール	説明
list_decals	部屋内（前景または背景）のすべてのデカールを一覧表示します。
add_decal	部屋にデカールを追加します。
remove_decal	インデックスを指定してデカールを削除します。

高度な分析

ツール	説明
analyze_entity_usage (extra)	マップ全体でエンティティの使用状況を分析します。
analyze_difficulty	ハザードの密度、ナビゲーション補助、タイルのカバー範囲から、部屋またはマップの難易度を推定します。
find_entity_references (extra)	マップ全体で特定の種類のエンティティが出現する箇所をすべて検索します。
detect_map_patterns (extra)	ゲームプレイ設計の類型（直線型、ハブ型、収集要素が豊富なものなど）を検出します。
analyze_room_connectivity	部屋の隣接グラフを分析し、孤立した部屋、行き止まり、ハブを表示します。

提案

ツール	説明
suggest_improvements (extra)	分析に基づいて部屋の改善案を提案します。
compare_maps (extra)	2つのマップを比較し、構造上の違いを表示します。

Wiki／キャッシュ

ツール	説明
wiki_save (extra)	分析結果やメモをローカルの Wiki キャッシュに保存します。
wiki_search (extra)	キー、コンテンツ、タグを指定して Wiki キャッシュを検索します。
wiki_list (extra)	Wiki キャッシュ内のすべてのエントリを一覧表示します。
wiki_get (extra)	キーを指定して Wiki エントリを取得します。

Mod プロジェクト

ツール	説明
get_mod_info	現在の Mod プロジェクトの情報を取得します。
validate_map	マップ全体をプレイ可能性の問題がないか検証します。

カタログ拡張

ツール	説明
get_trigger_definition	Lönn のトリガー定義 .lua ファイルのソースを読み取ります。
get_effect_definition	Lönn のエフェクト定義 .lua ファイルのソースを読み取ります。

インポート／エクスポート

ツール	説明
export_room_json	外部での編集や共有用に、部屋を JSON ファイルとしてエクスポートします。
import_room_json	JSON ファイルからマップに部屋をインポートします。

差分と修正

ツール	説明
summarize_map_diff (extra)	マップの構造スナップショットを作成または比較します。
batch_validate_and_fix	マップ内のすべての部屋を検証し、必要に応じて問題を自動修正します。

部屋の設定

ツール	説明
get_room_settings	部屋の編集可能な設定（音楽、物理演算、風、カメラ、フラグ）をすべて取得します。
update_room_settings	JSON オブジェクトをマージして、部屋の設定（音楽、物理演算、風、カメラ、フラグ）を更新します。
rename_room	マップ内の部屋の名前を変更します。
move_room	部屋をワールド座標上の新しい位置に移動します。
resize_room	部屋のサイズを変更します（8 ピクセルのグリッドに合わせ、タイルデータを保持します）。

マップのメタデータと依存関係の設定

ツール	説明
get_map_metadata	マップレベルのメタデータブロック（Everest/celeste.yaml の meta 設定）を読み取ります。
set_map_metadata	マップレベルのメタデータプロパティ（Everest の meta ブロック）を設定します。
replace_audio_event	マップ内の FMOD オーディオイベントのパスを検索して置換します。
get_map_dependencies	マップの everest.yaml または meta ノードから Mod の依存関係リストを読み取ります。
set_map_dependencies	マップの everest.yaml に Mod の依存関係リストを書き込むか、更新します。

ML アセット分析

ツール	説明
analyze_map_assets (extra)	Maddie480 のグラフィックスダンプを基準に、ML 方式でマップのアセットを分析します。

Json Round-Trip And Authoring

ツール	内容
map_to_json	.bin マップを、変換し戻すとバイト単位で一致する型付き JSON に変換します。
json_to_map	型付き JSON（map_to_json の出力。編集しても構いません）を .bin マップに戻します。
check_authoring_json	マップなしでオーサリング JSON を解決します。Lönn の定義に基づいてデフォルト値を補完した各オブジェクトを表示し、不明な名前にフラグを付けます。
merge_json_into_map	オーサリング JSON のエンティティ、トリガー、ルームを既存のマップに追加します。
run_author_script	JavaScript オーサリングスクリプト（js/ パッケージ、lucid-dream スタイル）を実行し、その出力を使用します。

ライブゲームリンク

ツール	内容
game_status	実行中のゲームの現在地を表示します。マップ SID、サイド、ルーム、プレイヤーの位置を確認できます。
game_reload_map	ディスク上で編集したマップを、実行中のゲームに再読み込みさせます。
game_teleport	実行中のゲームでマップのルームを読み込みます（新しいデバッグセッション）。
game_play_tas	ルームのスポーン地点から CelesteTAS の入力を再生し、プレイヤーの到達地点を報告します。
game_log	ゲームの log.txt の最近の行を表示します。エラー、警告、レベルの読み込みを確認できます。

安全性：コピー、コミット、バックアップ、差分

ツール	内容
map_copy	編集が元のマップに影響しないよう、マップを作業用コピーに複製します。デフォルトの保存先：Maps//wip/.copy.bin。
map_commit	作業用コピーを実際のマップに適用します。ファイル全体、または指定したルームのみを適用できます。ドライランでは、最初に差分を表示します。
map_backups	マップのタイムスタンプ付きバックアップを新しい順に一覧表示します。
map_restore	バックアップのいずれかからマップを復元します（最初に現在のファイルをバックアップします）。
map_diff	2 つのマップの意味的な差分を表示します。ルーム、ジオメトリ、前景／背景タイル、エンティティ、トリガー、デカール、スタイルグラウンド、メタデータが対象です。

アセット

ツール	内容
check_assets	マップで使用されているものがすべて存在するか確認します。Lönn の定義があるエンティティ／トリガー名、デカールとパララックステクスチャが対象です。
check_sprites_xml	Sprites.xml を確認します。解析できること、ID が一意であること、すべての Anim/Loop にアトラス内のフレームがあることを検証します。ゲーム内でスプライトが表示されない場合は、最初にここを確認してください。

エディター

ツール	内容
editor_open	オプションでルームを指定して、Lönn（または Rysy）でマップを開きます。エディターを閉じるまで、MCP によるそのマップへの書き込みは拒否されます。
editor_wait	ユーザーがエディターで保存する（またはエディターを閉じる）まで待機し、変更内容を報告します。待機を続けるには、再度呼び出してください。
editor_status	このサーバーからのエディターセッションと、実行中の他の Lönn を一覧表示します。
editor_close	エディターセッションを閉じます。force を指定しない場合、エディターが未保存の変更について確認し、開いたままになることがあります。

Sprite Fusion

ツール	内容
sf_make_tileset	Sprite Fusion 用の Celeste グレーボックスタイルセットを作成します（PNG、凡例 JSON、README）。
sf_import	Sprite Fusion の JSON エクスポート（map.zip）を Celeste のルームとしてインポートします。ソリッド／背景タイルとグレーボックスエンティティが対象です。

Summer Engine

ツール	内容
summer_init	Summer Engine のグレーボックスプロジェクトを作成または更新します（コリジョン付きタイルセット、ルームテンプレート、ブリッジスクリプト）。
summer_open	オプションでルームシーンを指定して、Summer Engine でグレーボックスプロジェクトを開きます。
summer_rooms	Summer のグレーボックスプロジェクトにあるルームシーンを一覧表示します。
summer_export_room	Summer のルームシーンを Celeste のルームに変換します（新規作成、または replace=true で置き換え）。sf_import と同じ検証と安全な書き込みを行います。
summer_import_room	Celeste のルームを Summer プロジェクトにシーンとしてコピーします（前景／背景タイル、タイルとしてのグレーボックスエンティティ、マーカーとしてのその他の要素）。
summer_from_sprite_fusion	Sprite Fusion のエクスポート（map.zip）を Summer のルームシーンに変換し、エクスポート前に Summer で調整できるようにします。

Shared Pcg Core

ツール	内容
pcg_generate_room	共通の C# PCG コアを使ってグレーボックスルームを生成し、マップに書き込みます（最初にドライランを実行します）。

選択レベル

ツール	機能
selecte_generate	seleCte を使ってレベル全体を生成します（バニラマップのマルコフモデルからサンプリングした部屋を使用）。Julia でエンコードし、.bin を検証します。

---

インストールとセットアップ

Python パッケージをインストールする

PyPI パッケージ loenn-mcp は 5.2.0 以降更新されていないため、pip install loenn-mcp では古いバージョンがインストールされます。 代わりに、最新のリリースに添付されている wheel をインストールしてください。

pip install https://github.com/Magedeline/loenn-mcp/releases/download/v7.2.0/loenn_mcp-7.2.0-py3-none-any.whl

または、ソースからインストールします。

git clone https://github.com/Magedeline/loenn-mcp
cd loenn-mcp
pip install -e .

MCPB バンドルをインストールする（PyPI 不要、Python のセットアップ不要）

各リリースには、Claude Desktop などのMCPBに対応したホスト向けのバンドル loenn-mcp-<version>.mcpb が添付されています。これは uv ランタイムを使用します。ホストがバンドル上で uv run を実行し、uv が Python と依存関係を自動でインストールするため、マシンに必要なのはuvだけです。リリースページからバンドルをダウンロードしてホストで開き、「Celeste mod folder」の設定を自分の mod に指定してください。python tools/build_mcpb.py を実行すると、チェックアウトから同じバンドルをビルドできます（ソースは mcpb/ にあります）。また、server.json では MCP Registry に io.github.Magedeline/loenn-mcp として登録されています。

Claude Desktop に接続する

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "loenn-mcp": {
      "command": "python",
      "args": ["-m", "loenn_mcp.server"],
      "env": {
        "LOENN_MCP_WORKSPACE": "/absolute/path/to/your/mod"
      }
    }
  }
}

GitHub Copilot（VS Code）に接続する

.vscode/mcp.json に追加します。

{
  "servers": {
    "loenn-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "loenn_mcp.server"],
      "env": {
        "LOENN_MCP_WORKSPACE": "${workspaceFolder}"
      }
    }
  }
}

マップをローカルでプレビューする

python -m loenn_mcp.preview_map Maps/01_City_A.bin
python -m loenn_mcp.preview_map Maps/01_City_A.bin g-   # filter by prefix

インタラクティブな HTML プレビューでは、キーボードショートカットを使ってズーム、パン、部屋の詳細表示、検索、ミニマップを利用できます。

---

JSON のラウンドトリップと作成

マップはバイナリ形式から取り出しても 1 バイトも失わずに元に戻せます。また、新しいコンテンツを手作業または JavaScript で作成し、既存のマップにマージできます。 実行時に Ruby や Node は必要ありません。Node が必要なのは、JS 作成スクリプトを実行するときだけです。

型付き JSON：map_to_json / json_to_map

map_to_json("Maps/MyMod/1-City.bin")                 → Export/1-City.json
json_to_map("Export/1-City.json", "Maps/MyMod/1-City-copy.bin")

すべての属性はバイナリ型を保持するため、ラウンドトリップ後もバイト単位で一致します。

{
  "format": "celeste-map-json", "version": 1,
  "header": "CELESTE MAP", "package": "1-City",
  "source": {"file": "1-City.bin", "sha256": "…", "tree_sha256": "…"},
  "lookup": ["Map", "levels", "level", "…"],
  "root": {"name": "Map", "children": [
    {"name": "levels", "children": [
      {"name": "level", "attrs": {
        "name": ["lookup", "lvl_a-00"],
        "x": ["i16", -40], "width": ["i32", 320], "dark": ["bool", false],
        "music": ["string", "event:/music/lvl1/main"], "alpha": ["f32", 0.3]},
       "children": [{"name": "solids", "attrs": {"innerText": ["rle", "0000…"]}}]}]}]}
}

• 型： bool、u8、i16、i32、f32、lookup（文字列テーブル内の文字列）、 string（通常の文字列）、rle（ランレングス形式のタイルデータ。デコード済みで表示）。
• 値はファイルに格納されているものです。 lvl_a-00 という部屋名は、lvl_a-00 のままです。
• lookup はファイル内の順序どおりの文字列テーブルです。編集時に追加できるのは末尾への追加だけです。 標準的なライターでは再現されないファイルの特性（テーブル内の重複エントリや 特殊な RLE 分割など）は、任意の追加情報（[type, value, {"key_index": 12}]）として保持されます。
• 書き込み拒否： 値が型に適合しない場合（["u8", 300]）、未編集のダンプで元のバイト列を完全に再現できない場合（source.sha256 で確認）、または出力を読み戻したときに同じマップにならない場合、json_to_map は何も書き込みません。書き込みはアトミックに行われ（一時ファイルを作成してから置換）、タイムスタンプ付きのバックアップも保持します（「安全性」を参照）。
• 手書きのドキュメントでは lookup／source を省略し、値をそのまま指定できます （"x": 8）。この場合は、Celeste 独自のパッカーが選択する型が割り当てられます。

JSON を使った作成

自分で作成するコンテンツ向けの、より柔軟な形式です。必要なのは名前と位置だけです。

{"rooms": [
  {"room": "a-05",
   "entities": [{"name": "strawberry", "x": 120, "y": 64},
                {"name": "CEL/GreenBerry", "x": 200, "y": 40}],
   "triggers": [{"name": "CEL/PinkPlatBerryCollectTrigger", "x": 0, "y": 0,
                 "width": 16, "height": 184}]},
  {"room": "a-99", "x": 0, "y": 2400, "width": 320, "height": 184,
   "solids": "1111…\n1000…", "attrs": {"dark": true},
   "entities": [{"name": "player", "x": 24, "y": 160}]}
]}

• デフォルト値は Lönn プラグイン定義から取得されます。優先順位は、mod の Loenn/、ほかのインストール済み mod（ワークスペースが Celeste/Mods 内にある場合）、バニラの Lönn の順です。 上記の strawberry には winged、moon、checkpointID、order が追加されます。 "placement": "normal_winged" を指定すると、別の配置のデフォルト値が選択されます。それ以外のキー （単独のキー、または "data" 内のキー）は属性を設定し、"nodes": [[x, y], …] はノードを追加します。
• 不明な名前にはフラグが付けられます（入力ミス、エンティティとして列挙されたトリガー、インストールされていないヘルパーなど）。check_authoring_json を使うと、マップを作成せずに解決結果を確認できます。
• 既存の部屋には追加のみ行われます。 部屋の属性とタイルは、部屋を新規作成する場合（x、y、width、height を指定）に限り受け付けられます。
• 部屋名の照合では、lvl_ の有無は問いません。

結合：merge_json_into_map

merge_json_into_map("Maps/MyMod/1-City.bin", "plan.json")                  # dry run + preview
merge_json_into_map("Maps/MyMod/1-City.bin", "plan.json", dry_run=false)   # write

• デフォルトではドライランです。 部屋ごとの差分を出力し、追加されたオブジェクトすべてを囲んだ HTML プレビューを表示します（マゼンタ色、チェックに失敗した場合は赤色）。
• ID はマップ全体で一意です。新しい ID はどの部屋の最大 ID よりも大きい値から始まり、すでに使用されている明示的な "id" は拒否されます。
• 追加するオブジェクトごとに配置チェックを行います。部屋の中にあること、ソリッドタイルの中にないこと、どの部屋の端やスポーン地点からも隔離された空洞にないことを確認します。既存の部屋バリデーター（validate_room、validate_map）を結合の前後に実行し、結合によって発生した問題を報告します。問題がある場合、allow_problems=true を指定しない限り書き込みを拒否します。不明な名前を使用するには allow_unknown=true が必要です。
• 追加のみです。 出力バイト列を再度読み込み、元のデータと比較します。既存のデータに違いがあれば、何も書き込みません。

JavaScript でのマップ作成

js/ は、API が lucid-dream に準拠した、依存関係のない小規模な Node パッケージです（THIRD_PARTY_NOTICES.md を参照）。作成用 JSON を生成し、.bin の書き込みはすべて Python サーバーが行います。

// add-berries.js
const { Plan, Room, Entity, Trigger, Tiles, line } = require('loenn-mcp-author'); // or require('./js')

const plan = new Plan();
plan.room('a-05').add(Entity.Strawberry({ x: 120, y: 64 }));          // existing room
for (const [x, y] of line(64, 96, 192, 96, 3)) plan.room('a-06').add(Entity.Strawberry({ x, y }));
plan.room('l-07').add(Trigger('CEL/PinkPlatBerryCollectTrigger', { x: 1700, y: 300, width: 56, height: 104 }));

// a new room, lucid-dream style: pixel position, size in tiles, tiles as text
plan.addRoom(new Room([0, 2400], { name: 'a-99', size: [40, 23], fgTiles: new Tiles(`...`),
  entities: [Entity.Player({ x: 24, y: 160 })] }));

module.exports = plan;          // or: module.exports = async (api) => plan;  or: plan.emit();

• Entity.Strawberry(...) はプロパティ名を配置時の名前（strawberry）にキャメルケース化します。名前空間付きの名前には、Entity('CEL/GreenBerry', {...}) の呼び出し形式を使用します。
• サーバー経由で実行します（ドライラン、プレビュー付き）。 run_author_script("add-berries.js", map_path="Maps/MyMod/1-City.bin")。
• またはシェルから実行します。node js/bin/loenn-author.js add-berries.js --out plan.json、または loenn-json author add-berries.js --map Maps/MyMod/1-City.bin [--write]。
• テスト：node js/test/test.js。例：js/examples/。

JSON によるプレビュー

render_map_html は、.bin だけでなく、型付き JSON ダンプも受け取ります。また、オーバーレイ（作成用 JSON）をメモリ上だけで結合し、強調表示します。これは既存のレンダラーを基盤として構築された、maddievision/celestial のビューアーのアイデアです。

loenn-json CLI

loenn-json map2json Maps/MyMod/1-City.bin -o city.json
loenn-json json2map city.json Maps/MyMod/1-City.bin --overwrite
loenn-json --mod . merge Maps/MyMod/1-City.bin plan.json            # dry run
loenn-json --mod . merge Maps/MyMod/1-City.bin plan.json --write
loenn-json --mod . author add-berries.js --map Maps/MyMod/1-City.bin

その他の例：examples/authoring/。

---

pcgscene CLI

MCP クライアントの外部でマップをスキャンして修復するための、バッチ処理を主眼としたコマンドラインツールです。一度インストールすれば、スクリプト、プレコミットフック、CI から使用できます。.bin ファイルに変更を加えるすべてのコマンドは、MCP サーバーと同じく、アトミックでバックアップ付き、ラウンドトリップ検証済みの手順で書き込むため、実行に失敗してもマップが壊れることはありません。

pip install loenn-mcp
pcgscene scan MyMap.bin              # score every room + map connectivity
pcgscene validate MyMap.bin          # in-game readiness checklist (exit 0/1)
pcgscene fix MyMap.bin --dry-run     # preview safe auto-repairs
pcgscene fix MyMap.bin               # apply them (backed up first)
pcgscene diff before.bin after.bin   # what changed between two maps

コマンド	内容
scan	すべての部屋を採点します（興味深さ、難易度、出口の接続性、スポーンの有無、公平性ゲート）。さらに開始部屋からのマップ全体の到達可能性も確認します。
score	単一の部屋（--room NAME）の詳細レポートを出力します。
validate	ゲーム内での準備状況チェックリストです。名前の不備、スポーンの欠落、封鎖された出口、到達不能な部屋を確認し、CI で使いやすい終了コードを返します。
fix	安全な自動修復を行います。欠落しているスポーンの追加、不正な部屋名のサニタイズ、strawberry{golden} から実際の goldenBerry エンティティへの変換に対応します。--dry-run と --only spawns,names,berries をサポートします。
diff	2 つのマップ間の部屋、エンティティ、タイルの変更を表示します。
generate	プリセットに基づいて生成します（quick／simple_fair／explore／challenge）。再現可能な --seed を指定できます。フル版／Pro ビルドの pcg_helper モジュール（loenn-mcp-delta）が必要です。このビルドの generate は、理由を通知して安全に処理を中断します。

すべてのコマンドは機械可読な出力として --json（および --out FILE）を受け付けるため、エディタープラグインや CI のステップからレポートを直接利用できます。

---

プロシージャル生成

生成戦略

戦略	説明
balanced	探索とチャレンジを組み合わせます（デフォルト）
exploration	開けた空間、穏やかなプラットフォームアクション、少ない危険要素
challenge	密集したタイル、多くの危険要素、難度の高いジャンプ
speedrun	直線的な経路、最小限の足場、テンポの速い流れ

Model プロファイル

プロファイル	動作	ユースケース
creative	呼び出しごとにランダムなシード	最大限の多様性
deterministic	ストラテジーに基づく安定したシード	再現可能なレイアウト
architect	ランダムなシード	形状と接続性を重視

クイックスタート例

# 1. Build pattern library from existing maps
build_pattern_library()

# 2. Create a new map
create_map("Maps/PCG/Generated.bin", "PCG/Generated")

# 3. Generate rooms
generate_room_from_pattern(
  map_path="Maps/PCG/Generated.bin",
  room_name="a-01",
  strategy="exploration",
  seed=42,
  model_profile="deterministic"
)

# 4. Validate and preview
validate_room("Maps/PCG/Generated.bin", "a-01")
render_map_html("Maps/PCG/Generated.bin")

シード指定による生成

再現可能な出力を得るには、seed=<int> と model_profile="deterministic" を使用します：

# Both calls produce identical rooms
generate_room_from_pattern(..., strategy="challenge", seed=1234, model_profile="deterministic")
generate_room_from_pattern(..., strategy="challenge", seed=1234, model_profile="deterministic")

GameBanana との連携

コミュニティ製の MOD からパターンをダウンロードして抽出します：

# Dry-run (preview only)
ingest_external_map(
  source_url="https://gamebanana.com/mods/53774",
  attribution="Spring Collab 2020",
  confirm_download=False
)

# Download and extract
ingest_external_map(
  source_url="https://gamebanana.com/mods/53774",
  attribution="Spring Collab 2020 (various authors)",
  confirm_download=True,
  tags="community,expert"
)

パターンは帰属表示とともに PCG/Datasets/ に保存されます。MOD のライセンスで派生利用が許可されていることを必ず確認してください。

---

画像からマップへの変換

色分けされた画像を、プレイ可能な Celeste マップに直接変換します。各ピクセルが 8×8 タイルになります。

デフォルトの色マッピング

色	Hex	マッピング先
黒	#000000	ソリッドタイル
白	#FFFFFF	空気（空）
赤	#FF0000	トゲのハザード
緑	#00FF00	プレイヤーのスポーン地点
青	#0000FF	すり抜け可能なプラットフォーム
黄	#FFFF00	イチゴ
マゼンタ	#FF00FF	スプリング
シアン	#00FFFF	補充クリスタル
オレンジ	#FF8000	崩れるブロック
グレー	#808080	背景のソリッド

使用方法

# Basic conversion
generate_map_from_image(image_path="Assets/my_level.png")

# Custom colors and scale
generate_map_from_image(
    image_path="Assets/large_map.png",
    output_path="Maps/Custom/level.bin",
    scale=4,  # 4×4 pixel blocks → 1 tile
    color_map_json='{"#FF0000":"solid","#00FF00":"spawn"}'
)

Pillow が必要です：pip install loenn-mcp[image]

---

シード指定による地形生成

パーリンノイズとボロノイバイオームを使って、マップ全体を生成します。AliShazly/map-generator に着想を得ています。

バイオーム

バイオーム	地形
mountain	密集したタイル、狭いプラットフォーム、トゲ
forest	中程度の密度、多数のプラットフォーム、スプリング
plains	開けた空間、緩やかなプラットフォーム、収集アイテム
lake	まばらなタイル、すり抜け可能な足場、補充アイテム
cave	囲まれた空間、崩れるブロック、暗い部屋
summit	まばらなプラットフォーム、風の効果

簡単な例

# Generate a 4×3 map with seed 42
generate_terrain_map(seed=42, difficulty=3, width_rooms=4, height_rooms=3)

# Preview biome layout before generating
preview_terrain_biomes(seed=42, width_rooms=4, height_rooms=3)
# Output:
# [P] [^] [^] [F]
# [~] [P] [^] [M]
# [C] [~] [P] [F]

パラメーター

パラメーター	デフォルト	説明
seed	-1（ランダム）	出力を再現するための整数シード
width_rooms	4	水平方向の部屋数
height_rooms	3	垂直方向の部屋数
frequency	8.0	パーリンノイズの周波数（小さいほど滑らか）
voronoi_points	12	バイオーム領域の中心点の数
biome_set	all	カンマ区切りのバイオーム名
difficulty	3	ハザード密度を表す 1～5 のスケール

---

分析とインサイト

マップ設計、難易度、パターンを分析するための高度なツールです。

簡単な例

# Analyze difficulty
analyze_difficulty(map_path="Maps/MyMod/1-City.bin")

# Detect gameplay patterns
detect_map_patterns(map_path="Maps/MyMod/1-City.bin")
# → "standard-level (7-15 rooms)", "linear-horizontal", "checkpointed"

# Get room suggestions
suggest_improvements(map_path="Maps/MyMod/1-City.bin", room_name="lvl_a-01")

# Track map evolution
summarize_map_diff(map_path="Maps/MyMod/1-City.bin")  # save snapshot
# ... edit map ...
summarize_map_diff(map_path="Maps/MyMod/1-City.bin")  # show diff

# Cache results for instant re-use
wiki_save(key="city_difficulty", content="Avg 4.2/10, 3 hard rooms", tags="analysis")
wiki_search(query="difficulty")

# Batch validation
batch_validate_and_fix(map_path="Maps/MyMod/1-City.bin", auto_fix=True)

# Search and clone
search_entities(map_path="Maps/MyMod/1-City.bin", entity_type="strawberry")
clone_room(map_path="Maps/MyMod/1-City.bin", source_room="lvl_a-01", new_name="lvl_a-01-copy")

# Export/import rooms
export_room_json(map_path="Maps/MyMod/1-City.bin", room_name="lvl_a-01")
import_room_json(map_path="Maps/MyMod/2-Resort.bin", json_path="Export/lvl_a-01.json")

Wiki キャッシュ

分析結果は .loenn_mcp_wiki/ に JSON ファイルとして保存され、セッションをまたいで即座に再利用できます。

---

AI は搭載していません（v7.0.0）

v7.0.0 以降、loenn-mcp のすべてのツールは決定論的かつプロシージャルです。 マルコフ連鎖、波動関数崩壊、ノイズ、BFS／グラフ分析を使用します。サーバーは AI／LLM API を一切呼び出さず、API キーも必要とせず、AI モデルも同梱していません。以前の ai_analyze_map／ai_describe_room／ai_suggest_entities ツールと anthropic 依存関係は削除されました。

免責事項： このプロジェクトは、コーディングツールとして Claude （Anthropic）の支援を受けて開発されました。アルゴリズムは Robinet et al.、「Towards a Celeste AI Framework」（FDG '25、 DOI 10.1145/3723498.3723796）で公開されたものに基づいています。すべての出力は Lönn と ゲーム内で人間によるテストを行っています。

---

設定

変数	デフォルト	説明
LOENN_MCP_WORKSPACE	現在のディレクトリ	Celeste mod プロジェクトのルートです。すべてのマップパスはこのディレクトリを基準とします。パストラバーサルはブロックされます。
LOENN_MCP_LOENN	（同梱のテーブル）	loenn_mcp/data/vanilla_defs.json の代わりに、バニラのエンティティ／トリガーのデフォルト値を読み込む Lönn のインストール先（Lönn.exe またはその src/ を含むフォルダー）です。
LOENN_MCP_NODE	PATH 上の node	run_author_script 用の Node.js 実行ファイルです。
LOENN_MCP_AUTHOR_CLI	バンドルされた js/bin/loenn-author.js	代替のオーサリング CLI です。
LOENN_MCP_STATE_DIR	%LOCALAPPDATA%\loenn-mcp	バックアップ、分離された Lönn ストレージ、Sprite Fusion タイルセットの保存先です。
LOENN_MCP_PROTECT	（なし）	; 区切りのマップのグロブです。指定されたマップは map_commit のみが変更できます。
LOENN_MCP_TOOLS	core	all にすると、追加の分析ツールと旧式のジェネレーターツールも一覧表示されます。
LOENN_MCP_LOENN_STORAGE	isolated	editor_open で使用する Lönn ストレージのデフォルト値です（isolated または user）。
LOENN_EXE	Olympus の Lönn.exe	Lönn の実行ファイルです。
RYSY_EXE	Documents\GitHub\Rysy 内で最新の Rysy.exe	Rysy の実行ファイルです。
SUMMER_EXE	%LOCALAPPDATA%\SummerEngine\current\Summer.exe	Summer Engine の実行ファイルです。
LOENN_MCP_SUMMER_PROJECT	Documents\CEL-Graybox	Summer のグレーボックスプロジェクトです。
CELPCG_CLI	ビルド済みの csharp/CelPcg.Cli	別の celpcg ビルド（exe または dll）を使用します。
SELECTE_DIR	このリポジトリの隣にある seleCte。ない場合は ~/seleCte	selecte_generate 用の seleCte クローンです。
UV_EXE	PATH 上の uv	seleCte のジェネレーターを実行する uv 実行ファイルです。
JULIA_EXE	PATH 上の julia	seleCte のエンコーダーを実行する Julia 1.11 以降の実行ファイルです。
LOENN_MCP_DEBUGRC	http://localhost:32270	game_* ツール用の Everest デバッグサーバーです。

---

アーキテクチャ

コアモジュール

celeste_bin.py — スタンドアロンの.binパーサー

• 純粋なPython（Everest／Lönnは不要です）
• ロスレスな読み書きに対応しています。編集していないマップはバイト単位で完全に同じ内容で書き戻されます（文字列テーブルの順序、値の型、RLEデータを保持）。編集内容は文字列テーブルに追記されるだけです。
• 7種類すべての値型に対応しています：bool、uint8、int16、int32、float32、ルックアップ文字列、生文字列、RLEエンコード文字列
• Lönn／Maple形式と一致する再帰的な要素ツリー

map_json.py — .binマップ用の型付きJSON

• すべての値で型が保持されます。編集していないデータはバイト単位で完全に同じ内容に戻せます（エクスポート時に検証済みです）。
• 往復変換で元に戻らない書き込みは拒否します。celeste_bin経由でアトミックに書き込みます。

lua_defs.py — Luaを実行せずにLönnプラグインの定義を読み込みます

• プラグインファイルをトークン化し、リテラルテーブル（配置、フィールド型、ノードの上限）を評価します。
• このMod、インストール済みの他のMod、バニラの定義を収録したカタログ（data/vanilla_defs.json。tools/gen_vanilla_defs.pyでLönnから生成）

authoring.py — オーサリングJSONとマージ

• デフォルト値の補完、不明な名前のフラグ付け、マップ全体のID割り当て、配置チェック
• 再読み込みした出力バイトに対する追加のみの検証

js/ — JavaScriptオーサリングパッケージloenn-mcp-author（Node、依存関係なし）

pcg.py — プロシージャル生成

• ルームからパターンを抽出（サイズ、エンティティ密度、タイルのモチーフ、ゲームプレイタグ）
• 重複排除に対応したJSONパターンライブラリ
• 戦略ベースの生成（バランス型、探索型、チャレンジ型、スピードラン型）
• 再現可能な出力を得るためのシード付き乱数
• モデルプロファイル（決定論型、クリエイティブ型、アーキテクト型）

image_map.py — 画像からマップへの変換

• 色から役割へのマッピング（パレットを設定可能）
• ルームの自動分割
• ピクセルカラーからエンティティを配置
• スケールに対応（縮小）
• あいまいな色の照合

terrain_gen.py — シード付き地形生成

• フラクタルオクターブを使用したPerlinノイズ
• Voronoi分割によるバイオームの区分
• 完全にシード指定可能（同じシードなら同一の出力）
• 難易度のスケーリング（1～5）
• バイオームに応じたエンティティ

gdep_tools.py — ゲーム分析

• Wikiのキャッシュ（.loenn_mcp_wiki/）
• パターン検出（直線型、ハブ型、収集要素が豊富な型など）
• 難易度分析（1～10段階）
• ルーム接続グラフ
• スナップショットを使用したマップ差分
• 一括検証と自動修正
• 実行可能な提案

server.py — MCP サーバー

• FastMCPで構築
• パストラバーサル対策
• マップのアトミックな書き込み
• 明示的なダウンロード確認

safety.py — 書き込みポリシー：ガード、タイムスタンプ付きバックアップ保存、呼び出しごとの書き込みレポート

mapdiff.py — 2つのマップのセマンティック差分（ルーム、タイル、IDによるエンティティ、デカール、スタイルグラウンド、メタデータ）

editors/ — 保存監視機能付きのEditorAdapter、LoennAdapter（起動、ルームの事前選択、分離ストレージ）、RysyAdapter

assets.py — テクスチャインデックス（Mod、インストール済みMod、バニラのアトラス.meta）、Sprites.xmlとマップアセットのチェック

summer.py — Summer Engineブリッジ：プロジェクト設定、ヘッドレスエディタースクリプト、シーンのルームへのダンプとその逆変換

pcg_core.py — celpcg CLIをビルドして呼び出し、そのルームをインポート可能な変換データにします

selecte.py — seleCteブリッジ：クローンを検索し、そのジェネレーター（uv）とJuliaエンコーダーを実行して、ログを要約し、.binを検証します

sprite_fusion.py — グレーボックスのタイルセット、Sprite Fusionエクスポートの読み込み、ピクセル照合、ルームへの変換

cli.py — pcgsceneコマンドラインツール

• scan／score／validate／fix／diffに対応し、すべて--jsonを使用できます。
• celeste_binのアトミック書き込み処理を共有しており、別個の書き込みロジックが乖離することはありません。

---

要件

• Python 3.9+
• fastmcp >= 3.0.0
• Pillow >= 9.0（オプション：画像からマップへの変換、およびSprite Fusionのインポート時のピクセル照合）
• Node.js 14+（オプション。JavaScriptオーサリングスクリプトでのみ使用）

オプション機能をすべて含めてインストールするには：

pip install loenn-mcp[image]

Celesteのインストールは不要です。

---

ライセンス

MIT — LICENSEを参照してください。lucid-dream、Lönn、maddievision/celestialへのクレジット：THIRD_PARTY_NOTICES.md。