loenn-mcp

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\ \ \ . .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 s