loenn-mcp

AI-powered Celeste map editor — A Model Context Protocol (MCP) server that brings full Celeste .bin map editing to Claude, GitHub Copilot, and other MCP clients. Read, edit, analyze, generate, and preview maps without opening Lönn.

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

Features

87 MCP tools across 19 categories for complete map manipulation and AI-assisted design.

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

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
• 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
• export_room_json / import_room_json — JSON room exchange

Diffing

• summarize_map_diff — Track map evolution with snapshots

Rendering

• render_map_html — Interactive HTML preview (zoom, pan, search, minimap)

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

Procedural Generation (Advanced)

PCGHelper Tools — MdMC/WFC tile generation

• pcg_mdmc_presets — List configuration presets
• pcg_skeleton_generate — Layout non-overlapping room skeleton
• pcg_markov_fill — Fill rooms with MdMC/WFC/hybrid
• pcg_score_room — Evaluate interestingness & difficulty
• pcg_pipeline — One-shot end-to-end generation

---

Installation & Setup

Install from PyPI

pip install loenn-mcp

Or from source:

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

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.

---

Procedural Generation

Generation Strategies

Strategy	Description
balanced	Mix of exploration and challenge (default)
exploration	Open spaces, gentle platforming, few hazards
challenge	Dense tiles, many hazards, tight jumps
speedrun	Linear path, minimal platforms, fast flow

Model Profiles

Profile	Behavior	Use Case
creative	Random seed each call	Maximum variety
deterministic	Stable seed from strategy	Reproducible layouts
architect	Random seed	Emphasis on shape/connectivity

Quick Start Example

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

Seeded Generation

Use seed=<int> + model_profile="deterministic" for reproducible output:

# 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 Integration

Download and extract patterns from community mods:

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

Patterns are saved to PCG/Datasets/ with attribution. Always verify mod licenses permit derivative use.

---

Image-to-Map Conversion

Convert color-mapped images directly into playable Celeste maps. Each pixel becomes one 8×8 tile.

Default Color Mapping

Color	Hex	Maps to
Black	#000000	Solid tile
White	#FFFFFF	Air (empty)
Red	#FF0000	Spike hazard
Green	#00FF00	Player spawn
Blue	#0000FF	Jump-through platform
Yellow	#FFFF00	Strawberry
Magenta	#FF00FF	Spring
Cyan	#00FFFF	Refill crystal
Orange	#FF8000	Crumble block
Grey	#808080	Background solid

Usage

# 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"}'
)

Requires Pillow: pip install loenn-mcp[image]

---

Seeded Terrain Generation

Generate complete maps with Perlin noise and Voronoi biomes. Inspired by AliShazly/map-generator.

Biomes

Biome	Terrain
mountain	Dense tiles, tight platforms, spikes
forest	Moderate density, many platforms, springs
plains	Open spaces, gentle platforms, collectibles
lake	Sparse tiles, jump-throughs, refills
cave	Enclosed, crumble blocks, dark rooms
summit	Sparse platforms, wind effects

Quick Example

# 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]

Parameters

Parameter	Default	Description
seed	-1 (random)	Integer seed for reproducible output
width_rooms	4	Rooms horizontally
height_rooms	3	Rooms vertically
frequency	8.0	Perlin noise frequency (lower = smoother)
voronoi_points	12	Number of biome region centres
biome_set	all	Comma-separated biome names
difficulty	3	1-5 scale for hazard density

---

Analysis & Insights

Advanced analysis tools for map design, difficulty, and patterns.

Quick Examples

# 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 Cache

Analysis results persist in .loenn_mcp_wiki/ as JSON files for instant re-use across sessions.

---

AI-Powered Analysis

Leverage Claude AI for intelligent map feedback, room descriptions, and entity suggestions.

Setup

pip install loenn-mcp
export ANTHROPIC_API_KEY="sk-ant-..."  # Get from https://console.anthropic.com/

Available Tools

Tool	Description
ai_analyze_map	Design feedback (general/difficulty/visual/flow)
ai_describe_room	Generate room descriptions in various styles
ai_suggest_entities	Entity placement recommendations with coordinates

Examples

# Get design feedback
ai_analyze_map(map_path="Maps/MyMod/1-City.bin", analysis_type="general")
# → "Strengths: Good checkpoints. Add more strawberries in rooms 3-5..."

# Generate descriptions
ai_describe_room(map_path="Maps/MyMod/1-City.bin", room_name="lvl_a-03", style="atmospheric")
# → "A windswept precipice where ancient stone meets howling gales..."

# Get entity suggestions
ai_suggest_entities(map_path="Maps/MyMod/1-City.bin", room_name="lvl_a-03", goal="add_challenge")
# → "1. Add spikes at (120, 80) for timing challenge..."

Analysis Types

• general — Overall design with suggestions
• difficulty — Difficulty curve analysis
• visual — Visual variety and theme feedback
• flow — Player movement and navigation

Description Styles

• atmospheric — Evocative, mood-focused
• technical — Gameplay-focused
• story — Narrative snippets
• brief — 1-2 sentence summaries

Suggestion Goals

• improve_flow — Better player guidance
• add_challenge — Skill-testing elements
• reduce_difficulty — Accessibility
• add_secrets — Exploration rewards

Gracefully degrades if ANTHROPIC_API_KEY is not set.

---

Advanced PCG (MdMC/WFC)

Full Python port of PCGHelper Lönn mod — MdMC/WFC tile generation, skeleton layout, and end-to-end pipeline.

Tools

Tool	Description
pcg_mdmc_presets	List 7 MdMC configuration presets
pcg_skeleton_generate	Layout non-overlapping room skeleton
pcg_markov_fill	Fill rooms with MdMC/WFC/hybrid
pcg_score_room	Evaluate interestingness & difficulty
pcg_pipeline	One-shot end-to-end generation

Generation Modes

• mdmc — Multi-dimensional Markov Chain
• wfc — Wave Function Collapse
• hybrid — Combination of both

Scoring Metrics

Interestingness I = w1·global_NLE + w2·local_NLE + w3·Shannon_entropy

Difficulty D = z1·hole_frequency + z2·local_LE + z3·NLE_scarcity

MdMC Presets

Key	Description
000011012	L-shape (default)
000011112	3-neighbour causal
001001112	4-neighbour
011011012	5-neighbour
010111010	Cross (WFC recommended)
101000101	Diagonals only
111101111	All 8 neighbours

Example

# One-shot end-to-end generation
pcg_pipeline(
    map_path="Maps/MyMod/1-City.bin",
    room_count=8,
    generation_mode="mdmc",
    seed=42,
    ensure_playable=True,
    place_entities=True,
)
# → "PCG pipeline complete: 8 rooms added"

# Score a room
pcg_score_room(map_path="Maps/MyMod/1-City.bin", room_name="lvl_a-03")
# → "Interestingness I = 0.4231 | Difficulty D = 0.5812"

# Fill existing empty rooms
pcg_markov_fill(
    map_path="Maps/MyMod/1-City.bin",
    room_names="skel_0,skel_1,skel_2",
    generation_mode="wfc",
    configuration="010111010",
    start_room="skel_0",  # gets the player spawn
    end_room="skel_2",    # gets the golden berry
    seed=99,
)

---

Configuration

Variable	Default	Description
LOENN_MCP_WORKSPACE	Current directory	Root of your Celeste mod project. All map paths are relative to this. Path traversal is blocked.

---

Architecture

Core Modules

celeste_bin.py — Standalone .bin parser

• Pure Python (no Everest/Lönn required)
• Full read/write round-trip with no data loss
• Handles all 7 value types: bool, uint8, int16, int32, float32, lookup string, raw string, RLE-encoded string
• Recursive element tree matching Lönn/Maple format

pcg.py — Procedural generation

• Pattern extraction from rooms (size, entity density, tile motifs, gameplay tags)
• JSON pattern library with deduplication
• Strategy-based generation (balanced, exploration, challenge, speedrun)
• Seeded randomness for reproducible output
• Model profiles (deterministic, creative, architect)

image_map.py — Image-to-map conversion

• Color-to-role mapping (configurable palette)
• Automatic room splitting
• Entity placement from pixel colors
• Scale support (downscaling)
• Fuzzy color matching

terrain_gen.py — Seeded terrain generation

• Perlin noise with fractal octaves
• Voronoi biome partitioning
• Fully seeded (same seed = identical output)
• Difficulty scaling (1-5)
• Biome-aware entities

gdep_tools.py — Game analysis

• Wiki caching (.loenn_mcp_wiki/)
• Pattern detection (linear, hub, collectible-rich, etc.)
• Difficulty analysis (1-10 scale)
• Room connectivity graphs
• Map diffing with snapshots
• Batch validation and auto-fix
• Actionable suggestions

ai_analyzer.py — AI-powered analysis

• Claude API integration
• Design feedback (general, difficulty, visual, flow)
• Room descriptions (atmospheric, technical, story, brief)
• Entity placement suggestions
• Graceful degradation

server.py — MCP server

• Built with FastMCP
• Path-traversal protection
• Atomic map writes
• Explicit download confirmation

---

Requirements

• Python 3.9+
• fastmcp >= 3.0.0
• anthropic >= 0.40.0 (optional, for AI-powered tools)
• Pillow >= 9.0 (optional, for image-to-map conversion)

Install with all optional features:

pip install loenn-mcp[image]

No Celeste installation required.

---

License

MIT — see LICENSE.