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

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

| Tool | Description |
|---|---|
| `ai_analyze_map` | Claude-powered design feedback (general/difficulty/visual/flow analysis) |
| `ai_describe_room` | Generate narrative descriptions of rooms in various styles |
| `ai_suggest_entities` | Get specific entity placement recommendations with coordinates |

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

| Variable | Default | Description |
|---|---|---|
| `LOENN_MCP_WORKSPACE` | Current working directory | Root of your Celeste mod project. The server resolves all map paths relative to this. Path traversal outside the workspace is blocked. |

---

## 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](https://github.com/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](https://github.com/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](https://github.com/jlowin/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](LICENSE).