loenn-mcp

Celeste map editor for AI agents — a Model Context Protocol (MCP) server that lets GitHub Copilot, Claude, and other MCP clients read, edit, analyze, procedurally generate, and preview Celeste .bin map files without ever opening Lönn.

Built for use with Everest mods. Works with maps created by Lönn or Ahorn.

Features

60 MCP tools across 18 categories

Map Reading

Map Reading Extensions (NEW in v5)

Map Editing

Map Editing Extensions (NEW in v5)

Decals (NEW in v5)

Stylegrounds

Entity / Trigger Catalog

Catalog Extensions (NEW in v5)

Analysis

Advanced Analysis — gdep-inspired (NEW in v5)

Suggestions — gdep-inspired (NEW in v5)

Wiki / Cache — gdep-inspired (NEW in v5)

Mod Project (NEW in v5)

Import / Export (NEW in v5)

Diff & Fix — gdep-inspired (NEW in v5)

Rendering

Procedural Generation

Image-to-Map & Terrain Generation (v4)

Quick Start

1 — Install from PyPI

pip install loenn-mcp

Or clone and install from source:

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

2 — Connect to GitHub Copilot (VS Code)

Add to your project's .vscode/mcp.json:

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

Then ask Copilot things like:

• "What rooms are in 01_City_A.bin?"

• "Add a strawberry to room a-03 at position (120, 80)"

• "Render an HTML preview of 07_Hell_A.bin and open it"

• "Build a pattern library from all my maps, then generate 5 challenge rooms"

3 — 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"
      }
    }
  }
}

4 — One-click map preview (standalone)

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

The HTML preview opens in your browser and supports:

• Scroll to zoom, drag to pan, pinch on touch

• Click a room → detail panel (entities, triggers, size)

• Live search filter (F to focus)

• Minimap with viewport indicator

• Keyboard shortcuts: + / - zoom, 0 fit, Esc deselect

Procedural Generation (PCG)

Generation strategies

Model profiles

End-to-end pipeline

1. Build pattern library from existing maps
2. (Optional) ingest community maps from GameBanana
3. Create a blank map
4. Generate rooms with a chosen strategy and seed
5. Validate each room
6. Render HTML preview

Example agent prompts:

# Step 1 — build pattern library
build_pattern_library()

# Step 2 — ingest a GameBanana mod for richer pattern data
ingest_external_map(
  source_url="https://gamebanana.com/mods/53774",
  attribution="Spring Collab 2020 (various authors)",
  confirm_download=True,
  tags="community,collab"
)

# Step 3 — create map and generate rooms
create_map("Maps/PCG/MyAIMap.bin", "PCG/MyAIMap")
generate_room_from_pattern(
  map_path="Maps/PCG/MyAIMap.bin",
  room_name="a-01",
  strategy="exploration",
  seed=42,
  model_profile="deterministic"
)
generate_room_from_pattern(
  map_path="Maps/PCG/MyAIMap.bin",
  room_name="a-02",
  strategy="challenge",
  x=320
)

# Step 4 — validate
validate_room("Maps/PCG/MyAIMap.bin", "a-01")

# Step 5 — preview
render_map_html("Maps/PCG/MyAIMap.bin")

Reproducible generation (seeded)

Pass seed=<integer> and model_profile="deterministic" to get the exact same room every time:

# These two calls produce identical output:
generate_room_from_pattern(map_path="...", room_name="r1", strategy="challenge", seed=1234, model_profile="deterministic")
generate_room_from_pattern(map_path="...", room_name="r2", strategy="challenge", seed=1234, model_profile="deterministic")

GameBanana integration

ingest_external_map can fetch maps directly from GameBanana:

# Dry-run (no download) — shows what would happen
ingest_external_map(
  source_url="https://gamebanana.com/mods/53774",
  attribution="Spring Collab 2020",
  confirm_download=False
)

# Actual download + pattern extraction
ingest_external_map(
  source_url="https://gamebanana.com/mods/53774",
  attribution="Spring Collab 2020 (various authors, see mod page)",
  confirm_download=True,
  tags="expert,collab"
)

Downloaded files are saved to PCG/Datasets/ with an attribution.json file. Always verify the mod's licence permits derivative use before building on its patterns.

Image-to-Map Conversion (NEW in v4)

Convert any color-mapped image directly into a playable Celeste map. Each pixel becomes one 8×8 tile, with colors mapped to tile types and entities.

Default color mapping

Usage

# Basic — converts image using default color mapping
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","#0000FF":"air"}'
)

How it works

1. The image is loaded and optionally downscaled by scale factor

2. Each pixel is matched to the closest color in the color map (within tolerance)

3. The grid is split into room-sized chunks (default 40×23 tiles = 320×184 px)

4. Each chunk becomes a room with proper tiles, entities, and a player spawn

5. The complete map is written as a .bin file

Requires Pillow — install with: pip install loenn-mcp[image]

Seeded Terrain Generation (NEW in v4)

Generate complete maps procedurally using Perlin noise and Voronoi diagrams, inspired by AliShazly/map-generator.

Biomes

Usage

generate_terrain_map(seed=42, difficulty=3)

Preview terrain biomes

preview_terrain_biomes(seed=42, width_rooms=4, height_rooms=3)

Output:

[P] [^] [^] [F]

[~] [P] [^] [M]

[C] [~] [P] [F]

### Generation algorithm

1. **Perlin noise** creates organic heightmap terrain — controls where solid tiles, platforms, and gaps appear
2. **Voronoi diagrams** partition the map into biome regions — each room inherits the biome of its Voronoi region
3. **Seeded RNG** ensures the same `seed` + parameters always produce the exact same output
4. **Difficulty scaling** (1-5) adjusts hazard density, tile coverage, and platform frequency
5. Biome properties control tile characters, entity types, room flags (dark, underwater, wind)

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

---

## Game Analysis & Wiki (NEW in v5 — gdep-inspired)

Advanced analysis tools adapted from game design analysis patterns.

### Usage examples

```python
# Analyze difficulty across all rooms
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 (3 checkpoints)"

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

# Track map evolution with snapshots
summarize_map_diff(map_path="Maps/MyMod/1-City.bin")  # saves snapshot
# ... make edits ...
summarize_map_diff(map_path="Maps/MyMod/1-City.bin")  # shows diff

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

# Batch validate and auto-fix
batch_validate_and_fix(map_path="Maps/MyMod/1-City.bin", auto_fix=True)

# Search for specific entities
search_entities(map_path="Maps/MyMod/1-City.bin", entity_type="strawberry")

# Clone and modify rooms
clone_room(map_path="Maps/MyMod/1-City.bin", source_room="lvl_a-01", new_name="lvl_a-01-copy")

# Export/import rooms as JSON
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

The wiki stores analysis results in .loenn_mcp_wiki/ as JSON files. Results persist across sessions so repeated queries return instantly.

AI-Powered Analysis (NEW — Claude API)

Leverage Anthropic's Claude AI for intelligent map design feedback, narrative generation, and entity placement suggestions.

Setup:

# Install with AI support (anthropic package included)
pip install loenn-mcp

# Set your API key (get from https://console.anthropic.com/)
$env:ANTHROPIC_API_KEY="sk-ant-api03-..."

Available Tools:

Example prompts:

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

# Generate atmospheric room 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 placement 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 a timing challenge..."

Analysis Types:

• general — Overall design assessment with improvement suggestions

• difficulty — Difficulty curve and balancing analysis

• visual — Visual variety and theme consistency feedback

• flow — Player movement flow and navigation clarity

Description Styles:

• atmospheric — Evocative, mood-focused descriptions

• technical — Gameplay-focused descriptions

• story — Narrative/story snippets

• brief — Concise 1-2 sentence summaries

Suggestion Goals:

• improve_flow — Better player guidance and navigation

• add_challenge — Skill-testing elements

• reduce_difficulty — Accessibility improvements

• add_secrets — Exploration rewards

The AI tools gracefully degrade if ANTHROPIC_API_KEY is not set, returning helpful error messages.

Environment Variables

How It Works

celeste_bin.py — standalone binary parser

A pure-Python implementation of the Celeste .bin map format (no Everest or 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 the internal Lönn/Maple format

pcg.py — procedural generation module

Provides:

• Pattern extraction — converts .bin rooms into reusable pattern records (size class, entity density, tile motifs, trigger usage, gameplay tags)

• Pattern library — JSON-based store with deduplication by content hash

• Strategy-based generation — balanced, exploration, challenge, speedrun modes

• Seeded randomness — random.Random(seed) for reproducible outputs; seed exposed via MCP tool parameters

• Model profiles — deterministic / creative / architect profiles control how seeds are resolved

image_map.py — image-to-map conversion (NEW in v4)

Converts color-mapped images into playable Celeste maps:

• Color-to-role mapping — configurable palette mapping colors to tiles and entities

• Automatic room splitting — large images are divided into room-sized chunks

• Entity placement — spawns, hazards, collectibles extracted directly from pixel colors

• Scale support — large images can be downscaled (N×N pixel blocks → 1 tile)

• Tolerance matching — fuzzy color matching for hand-drawn or anti-aliased images

terrain_gen.py — seeded terrain generator (NEW in v4)

Procedural map generation inspired by AliShazly/map-generator:

• Perlin noise — pure-Python implementation with fractal octaves for organic terrain

• Voronoi biomes — map partitioned into distinct biome regions (mountain, forest, plains, lake, cave, summit)

• Fully seeded — same seed + parameters = identical output every time

• Difficulty scaling — 1-5 scale controls hazard density, tile coverage, and platform frequency

• Biome-aware entities — each biome has appropriate hazards, collectibles, and room flags

gdep_tools.py — game analysis tools (NEW in v5)

Integrates game analysis concepts from pirua-game/ai_game_base_analysis_cli_mcp_tool (gdep):

• Wiki caching — persist analysis results locally so repeated queries are instant (.loenn_mcp_wiki/)

• Pattern detection — detect gameplay design archetypes (linear progression, hub layouts, collectible-rich, wind corridors)

• Difficulty analysis — estimate room/map difficulty from hazard density, navigation aids, tile coverage (1-10 scale)

• Room connectivity — adjacency graph analysis showing isolated rooms, dead ends, and hubs

• Map diffing — snapshot-based structural diffing for tracking map evolution over time

• Batch validation — whole-map playability checks (spawns, floors, bounds) with optional auto-fix

• Suggestions — actionable improvement suggestions based on room analysis

ai_analyzer.py — AI-powered analysis (NEW)

Integrates Anthropic's Claude API for intelligent map design assistance:

• Map analysis — AI-powered feedback on design, difficulty, visuals, and flow

• Room descriptions — Generate narrative descriptions in atmospheric, technical, story, or brief styles

• Entity suggestions — Get specific entity placement recommendations with coordinates

• Graceful degradation — Helpful error messages when ANTHROPIC_API_KEY is not configured

server.py — MCP server

Built with FastMCP. All file paths are resolved relative to LOENN_MCP_WORKSPACE with path-traversal protection. Map writes are atomic (parse → mutate → write). External downloads require explicit confirm_download=True.

Requirements

• Python 3.9+

• fastmcp >= 3.0.0

• anthropic >= 0.40.0 (optional — only needed for AI-powered tools)

• Pillow >= 9.0 (optional — only needed for generate_map_from_image)

Install with all optional features: pip install loenn-mcp[image]

No Celeste installation required to parse, generate, or preview maps.

License

MIT — see LICENSE.