Loenn MCP Server

loenn-mcp

A Celeste map editor for AI agents — a Model Context Protocol (MCP) server that brings full Celeste .bin map editing to Claude, GitHub Copilot, and other MCP clients, plus a standalone pcgscene CLI for scripting and CI. Read, edit, analyze, generate, and preview maps without opening Lönn.

"For AI agents" describes who talks to this server (any MCP client), not what runs inside it — every tool here is deterministic and procedural. See No AI Inside.

Works with Everest mods and maps from Lönn or Ahorn.

Contents

• Features
• Safety: backups, copies and commits
• Opening maps in Lönn
• Sprite Fusion gray-box rooms
• Summer Engine gray-box rooms
• Shared PCG core (CelPcg)
• seleCte levels
• Tool reference
• Installation & setup
• JSON round-trip & authoring
• pcgscene CLI
• Procedural generation
• Image-to-map conversion
• Seeded terrain generation
• Analysis & insights
• No AI inside (v7.0.0)
• Configuration
• Architecture
• Requirements
• License

Features

MCP tools for complete map manipulation (full list in the tool reference), plus the pcgscene command-line tool for scripting and CI. Every write keeps a timestamped backup, maps open in Lönn are protected from MCP writes, and gray-box rooms painted in Sprite Fusion import directly.

Core Tools

Reading & Querying

• list_maps — List all .bin files
• read_map_overview — Summary of rooms, entities, triggers, stylegrounds
• read_room — Full room details (tiles, entities, triggers, decals)
• get_room_tiles — Raw tile grid (FG or BG)
• read_map_metadata — Quick metadata without full read
• search_entities — Find entities by type, position, room
• search_triggers — Find triggers by type
• compare_rooms — Side-by-side room comparison

Editing

• add_entity / remove_entity — Place or delete entities
• update_entity / move_entity — Modify entity properties or position
• add_trigger / remove_trigger — Place or delete triggers
• set_room_tiles — Replace tile grid
• add_room / remove_room — Create or delete rooms
• create_map — Create new .bin file
• update_room — Modify room properties (music, dark, wind, etc.)
• clone_room — Duplicate a room
• batch_add_entities — Add multiple entities at once
• resize_room — Change room dimensions

JSON & Authoring (see JSON round-trip & authoring)

• map_to_json / json_to_map — Any .bin to typed JSON and back, byte-identical; refuses lossy writes
• check_authoring_json — Resolve hand-written content: defaults filled from Lönn plugins, unknown names flagged
• merge_json_into_map — Add entities/triggers/rooms to a map; dry-run diff + highlighted preview, map-wide unique IDs, placement checks, additions only
• run_author_script — Run a JavaScript authoring script (js/, lucid-dream style) and merge its output

Decals & Effects

• list_decals / add_decal / remove_decal — Manage foreground/background decals
• list_stylegrounds / add_styleground / update_styleground / remove_styleground — Manage map effects

Definitions & Catalog

• list_entity_definitions / get_entity_definition — Browse entity types; look a definition up by the name placed in maps (e.g. MyMod/CloudBoss)
• find_missing_definitions — Namespaced entities/triggers in a map that no installed Lönn plugin defines
• audit_plugin_coverage — C# [CustomEntity] names with no Lönn plugin, and plugins with no C# code (reads the .csproj compile list)
• list_trigger_definitions / get_trigger_definition — Browse trigger types
• list_effect_definitions / get_effect_definition — Browse effect types

Analysis & Insights

Basic Analysis

• analyze_map — Entity counts, type breakdown, world bounds
• visualize_map_layout — ASCII mini-map
• preview_map_section — Detailed ASCII preview

Advanced Analysis

• analyze_entity_usage — Entity stats across entire map
• analyze_difficulty — Room/map difficulty estimation
• find_entity_references — Locate all instances of an entity type
• detect_map_patterns — Identify design archetypes (linear, hub, etc.)
• analyze_room_connectivity — Adjacency graph analysis

Suggestions & Improvements

• suggest_improvements — Actionable room suggestions
• compare_maps — Structural diff between maps

Wiki & Caching

• wiki_save / wiki_search / wiki_list / wiki_get — Persist and retrieve analysis results

Project Management

• get_mod_info — Project metadata and structure
• validate_map / batch_validate_and_fix — Playability validation with auto-fix
• game_status / game_reload_map / game_teleport / game_log — Drive the running game through Everest's debug server: see where you are, reload an edited map, jump to a room, read load errors
• game_play_tas — Play CelesteTAS inputs from a room's spawn and report the room, position, deaths and dashes at the end: proof a room is beatable, or that a shortcut fails
• validate_audio — Every audio event a map references, checked against GUIDs.txt and the game's FMOD banks, with closest-match suggestions
• export_room_json / import_room_json — JSON room exchange

Diffing

• summarize_map_diff — Track map evolution with snapshots

Rendering

• render_map_html — Interactive HTML map preview with tiles, colour-coded entity markers, zoom/pan, search and a minimap; reads a .bin or a typed JSON dump, and can highlight a planned merge (overlay)

Procedural Generation

Pattern-Based Generation

• build_pattern_library — Extract patterns from existing maps
• generate_room_from_pattern — Generate rooms with strategy + seed
• ingest_external_map — Download and extract patterns from GameBanana

Image & Terrain Generation

• generate_map_from_image — Convert color-mapped images to playable maps
• generate_terrain_map — Procedural maps with Perlin noise + Voronoi biomes
• preview_terrain_biomes — Preview biome layout before generation

---

Safety: backups, copies and commits

No map is overwritten silently.

• Every write keeps a timestamped backup before the file is replaced, in a backup store outside the mod folder (so Everest never loads it and the mod's git stays clean): %LOCALAPPDATA%\loenn-mcp\backups\<mod>\<path>\<name>.<YYYYMMDD-HHMMSS-micro>.bin. Each tool result ends with a line naming the file written and its backup.
• New bytes are re-parsed before anything is replaced, then written to a temp file and swapped in atomically.
• Copy first for chapter maps: map_copy, edit the copy, map_diff, then map_commit (dry run first; can take only some rooms; refuses rooms that fail validation, such as rooms without a player spawn).
• LOENN_MCP_PROTECT (glob list, ;-separated, relative to the mod) makes matching maps read-only except through map_commit. Recommended for CEL: Maps/CEL/Area/*.bin;Maps/CEL/BSide/*.bin;Maps/CEL/CSide/*.bin;Maps/CEL/DSide/*.bin;Maps/CEL/ZSide/*.bin.
• Writes are refused while the map is open in an editor started with editor_open, or open in your own Lönn, because Lönn's next save would overwrite them.
• map_backups lists backups, map_restore puts one back (backing up the current file first).
• map_diff compares meaning, not bytes: rooms, geometry, fg/bg tile cells, entities and triggers by id, decals, stylegrounds and metadata. Lönn re-encodes the whole file on save, so a byte diff says nothing useful.

Round trips are tested. To check every map in a folder (.bin to tree to .bin, and .bin to typed JSON to .bin, both byte-identical):

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

Opening maps in Lönn

editor_open(map, room) starts Lönn on that map and room. editor_wait blocks until you save (and reports the semantic diff of that save) or close Lönn. editor_close closes it, asking Lönn first; force kills it.

What this relies on, read from Lönn 1.0.10's source and tested on Windows:

The editor side is an adapter (loenn_mcp/editors): LoennAdapter today, and RysyAdapter launches Rysy (--map) with the same watching, so the tool surface can move to a Rysy-based setup unchanged.

Sprite Fusion gray-box rooms

Paint gray-box rooms in Sprite Fusion and import them as Celeste rooms.

1. sf_make_tileset() writes celeste_graybox.png, a legend and a README to %LOCALAPPDATA%\loenn-mcp\sprite-fusion.
2. In Sprite Fusion, import celeste_graybox.png with tile size 16. Make the map 40x23 cells for one screen (one cell = one 8x8 Celeste tile). Paint ground on a layer with Collider on, background walls on a layer named bg, and player, spikes, spring, refill, strawberry, jump-through or dream block anywhere.
3. Export as JSON (map.zip), then call sf_import(export_path, map_path, room, output_path=...), dry run first.

Details:

• Tile ids in an export index the exported spritesheet, so tiles are matched to the tileset by pixels (needs Pillow), falling back to ids.
• Spikes and jump-throughs merge along runs, dream blocks into rectangles. Entities get their Lönn defaults.
• Only entities with a Lönn definition are placed (sprites first). A tile can carry Sprite Fusion attributes entity, anchor and entity data to place another entity; unknown names are refused.
• Tiles on non-collider layers that are not in the tileset are decoration and are ignored, with a count in the report: decorate in Lönn after the gray-box plays well.
• A new room is added (default: to the right of the existing rooms). An existing room changes only with replace=true, which swaps its fg/bg tiles and entities and keeps triggers, decals and settings.
• A custom legend (legend_path) can map your own tileset's tiles to kinds and foreground tile characters.

Summer Engine gray-box rooms

Summer Engine is a Godot 4.7 fork. Rooms can be painted there as scenes and come back as Celeste rooms, and Celeste rooms (or Sprite Fusion exports) can go into Summer to be refined.

• summer_init() creates the project at Documents\CEL-Graybox: the gray-box tileset as a Godot TileSet (custom data kind, collision on solid tiles), rooms/_template.tscn (layers bg, fg, gameplay and an orange 40x23 screen frame) and the bridge scripts in celeste/.
• summer_open(scene) starts the Summer editor on a room scene. Summer opens on its AI chat panel, which asks you to sign in; switch to the 2D tab to paint. Save with Ctrl+S before exporting.
• summer_export_room(scene, map_path, room, ...) turns a scene into a Celeste room, with the same checks, dry run and safe write as sf_import. replace=true updates an existing room and keeps each solid cell's tileset.
• summer_import_room(map_path, room) puts an existing Celeste room into the project; summer_from_sprite_fusion does the same for a Sprite Fusion export.
• Entities that are not gray-box tiles travel as Marker2D nodes with metadata entity plus their fields.
• One tile is one 8x8 Celeste tile whatever the Godot tile size; foreign tilesets work too (a layer named fg/solid/terrain, or any tile with collision, counts as solid).

How it runs: Summer.exe --path <project> --summer-editor-script <script.gd> --summer-editor-script-out <dir> runs a GDScript in a headless editor after the import scan and writes result.json. Each call takes about 4 s. No sign-in or network is needed for this.

Shared PCG core (CelPcg)

csharp/ holds the procedural generation core that the MCP, the CEL mod and Summer Engine can all use (design: docs/PCG-CORE-DESIGN.md).

• CelPcg.Core (netstandard2.0, no dependencies): PCG32 random numbers and seed derivation, the room model, the reach model (ported from CEL's overworld_gen/reach.py: jump 3 up / 6 across, dash 4, springs, refills, jump-throughs; no climbing), a validator (structure + every exit reachable from the entry) and the platform-chain generator.
• CelPcg.Cli (celpcg): celpcg generate --exits left:16:4,right:10:4 --difficulty 4 --seed 42 prints a celpcg-room JSON document; celpcg validate --room room.json re-checks one.
• CelPcg.Tests: dotnet test csharp/CelPcg.Tests (determinism, reach limits, and 1,200 generated rooms that must all validate with vanilla-only entities).

pcg_generate_room(map_path, room, exits, difficulty, seed, ...) builds the CLI on first use (needs the .NET 8 SDK or later), generates, and writes through the same checked path as the gray-box importers. A room is only returned when every exit is proven reachable; failed layouts retry with derived seeds, so the same request always gives the same room. The seed is stored on the room (celpcg_seed, celpcg_generator, celpcg_difficulty).

Limits of this first version: the entry must be a left or right exit; rooms are one platform-chain style; no templates or MdMC/WFC fill yet (phase 4 of the design).

seleCte levels

seleCte (Louis Robinet, FDG '25) learned the tile patterns of Celeste's vanilla rooms with a multi-dimensional Markov chain. It draws a level layout, fills each room by sampling from the model, and a Julia script on the Maple library encodes the rooms as a .bin that starts on a spawn and ends on a crystal heart.

selecte_generate(name, nb_rooms, proba, width, height, seed, ...) runs the whole chain in one call: the Python generator (uv run), the Julia encoder, then pcgscene's readiness checklist on the result. The level's data.json, room_<n>.csv, both logs and the .bin land in <state dir>\selecte\<name>. output_path also copies the .bin into the mod through the guarded write (backup, protected maps, open editors), unless the checklist found problems (allow_problems=true copies anyway).

• Setup: clone seleCte, then uv sync and julia --project=. -e "using Pkg; Pkg.instantiate()" in it (Julia 1.11 or later; the trained model ships with the clone, Celeste itself is not needed). The MCP looks for the clone at SELECTE_DIR, then a seleCte folder next to this repository, then ~/seleCte.
• width/height 22x14 runs in seconds; 40x23 (one screen) takes minutes per room. proba 0 is a corridor, values near 1 a labyrinth. tries_limit resamples a room that fails seleCte's playability check; reset_skeleton redraws the layout instead of keeping an unplayable room.
• seed and model need the patched clone (upstream seleCte has no --seed and always uses pe_d5_full); the tool reports the generator's own error when a clone lacks them.
• seleCte's playability check ignores gravity, jumping and dashing, so rooms are not proven beatable: use game_play_tas or pcg_generate_room's reach model for that. Everest registers a new .bin only after a game restart.

Tool reference

107 tools; 89 are listed by default. Tools marked extra are hidden unless LOENN_MCP_TOOLS=all. Generated by tools/gen_tool_reference.py.

Map Reading Tools

Map Editing Tools

Styleground Tools

Entity / Trigger Catalog Tools

Analysis Tools

Map Preview Tools

Procedural Generation Tools

Image-To-Map And Terrain Generation Tools

Map Reading Extensions

Map Editing Extensions

Decals

Advanced Analysis

Suggestions

Wiki / Cache

Mod Project

Catalog Extensions

Import / Export

Diff & Fix

Room Settings

Map Metadata & Dependency Settings

Ml Asset Analysis

Json Round-Trip And Authoring

Live Game Link

Safety: Copies, Commits, Backups, Diff

Assets

Editors

Sprite Fusion

Summer Engine

Shared Pcg Core

Selecte Levels

---

Installation & Setup

Install the Python package

The PyPI package loenn-mcp has not been updated since 5.2.0, so pip install loenn-mcp gets an old version. Install the wheel attached to the latest release instead:

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

Or from source:

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

Install the MCPB bundle (no PyPI, no Python setup)

Every release attaches loenn-mcp-<version>.mcpb, a bundle for hosts that support MCPB, such as Claude Desktop. It uses the uv runtime: the host runs uv run on the bundle, and uv installs Python and the dependencies by itself, so only uv has to be on the machine. Download the bundle from the releases page, open it in the host, and point its "Celeste mod folder" setting at your mod. python tools/build_mcpb.py builds the same bundle from a checkout (sources in mcpb/), and server.json lists it for the MCP Registry as io.github.Magedeline/loenn-mcp.

Connect to Claude Desktop

Add to claude_desktop_config.json:

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

Connect to GitHub Copilot (VS Code)

Add to .vscode/mcp.json:

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

Preview Maps Locally

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

The interactive HTML preview supports zoom, pan, room details, search, and minimap with keyboard shortcuts.

---

JSON round-trip & authoring

Maps can leave the binary format and come back without losing a byte, and new content can be written by hand or in JavaScript and merged into an existing map. Nothing here needs Ruby or Node at runtime; Node is only used if you run JS authoring scripts.

Typed 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")

Every attribute keeps its binary type, so the round trip is byte-identical:

{
  "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…"]}}]}]}]}
}

• Types: bool, u8, i16, i32, f32, lookup (string-table string), string (plain string), rle (run-length tile data, shown decoded).
• Values are what the file holds. A room named lvl_a-00 stays lvl_a-00.
• lookup is the file's string table in file order; edits only append to it. File quirks a canonical writer would not reproduce (a duplicate table entry, an unusual RLE split) are kept as optional extras ([type, value, {"key_index": 12}]).
• Refusals. json_to_map writes nothing if a value does not fit its type (["u8", 300]), if an unedited dump would not reproduce its source byte-for-byte (checked with source.sha256), or if the output would not read back as the same map. Writes are atomic (temp file + replace) and keep a timestamped backup (see Safety).
• Hand-written documents may skip lookup/source and give bare values ("x": 8); those get the type Celeste's own packer would pick.

Authoring JSON

A looser format for content you write yourself. Only names and positions are needed:

{"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}]}
]}

• Defaults come from the Lönn plugin definitions: your mod's Loenn/, other installed mods (when the workspace is in Celeste/Mods), then vanilla Lönn. strawberry above gets winged, moon, checkpointID and order. "placement": "normal_winged" picks another placement's defaults; any other key (flat or under "data") sets an attribute; "nodes": [[x, y], …] adds nodes.
• Unknown names are flagged (typos, a trigger listed as an entity, a helper that isn't installed). check_authoring_json shows the resolved result without a map.
• Existing rooms are only added to. Room attributes and tiles are accepted only when creating a room (give x, y, width, height).
• Room names match with or without lvl_.

Merging: 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

• Dry run by default. It prints a per-room diff and renders an HTML preview with every added object ringed (magenta, or red when a check failed).
• IDs are unique across the whole map: new ones start above the highest ID in any room, and an explicit "id" that is already used is refused.
• Placement checks for each added object: inside the room, not inside solid tiles, not in an air pocket sealed off from every room edge and spawn. The existing room validators (validate_room, validate_map) run before and after, and any issue the merge introduces is reported. A write with problems is refused unless allow_problems=true; unknown names need allow_unknown=true.
• Only additions. The output bytes are re-read and compared with the original; if anything that was already there differs, nothing is written.

Authoring maps from JavaScript

js/ is a small dependency-free Node package whose API follows lucid-dream (see THIRD_PARTY_NOTICES.md). It produces authoring JSON; the Python server does all .bin writing.

// 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(...) camel-cases the property to the placed name (strawberry); namespaced names use the call form, Entity('CEL/GreenBerry', {...}).
• Run it through the server (dry run, with preview): run_author_script("add-berries.js", map_path="Maps/MyMod/1-City.bin").
• Or from a shell: node js/bin/loenn-author.js add-berries.js --out plan.json, or loenn-json author add-berries.js --map Maps/MyMod/1-City.bin [--write].
• Tests: node js/test/test.js. Examples: js/examples/.

JSON-driven preview

render_map_html takes a typed JSON dump as well as a .bin, and an overlay (authoring JSON) that is merged in memory only and highlighted. This is the viewer idea from maddievision/celestial built on the existing renderer.

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

More examples: examples/authoring/.

---

pcgscene CLI

A batch-first command-line tool for scanning and repairing maps outside an MCP client — install once, use from scripts, pre-commit hooks, or CI. Every command that touches a .bin file writes through the same atomic, backed-up, round-trip-validated path as the MCP server, so a bad run can never destroy a map.

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

Every command accepts --json (and --out FILE) for machine-readable output, so an editor plugin or CI step can consume the report directly.

---

Procedural Generation

Generation Strategies

Model Profiles

Documentation truncated — see the full README on GitHub.