Loenn MCP

宠物mcp

  

Celeste AI代理地图编辑器 一 模型上下文协议 （MCP）服务器，允许GitHub Copilot、Claude和其他MCP客户端读取、编辑、分析、， 按程序生成，并预览Celeste .bin 无需打开Lönn即可打开地图文件。

______________________________________________________________________

特性

18个类别的60个MCP工具

地图阅读

地图阅读扩展（v5中的新功能）

地图编辑

地图编辑扩展（v5中的新功能）

贴花（v5中新增）

风格背景

实体/触发器目录

目录扩展（v5中的新功能）

分析

高级分析——受gdep启发（v5中的新功能）

建议——受gdep启发（v5中的新功能）

Wiki/Cache——受gdep启发（v5中的新功能）

Mod项目（v5中的新功能）

导入/导出（v5中的新功能）

Diff&Fix——受gdep启发（v5中的新功能）

渲染

过程生成

图像到地图和地形生成（v4）

______________________________________________________________________

快速开始

1--从PyPI安装

pip install loenn-mcp

或者从源代码克隆并安装：

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

2--连接到GitHub副本（VS代码）

添加到您的项目 .vscode/mcp.json:

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

然后问Copilot这样的问题：

• *“01_City_A.bin有哪些房间？”*
• *在a-03房间（120、80）的位置加一个草莓*
• *“渲染07_Hell_A.bin的HTML预览并打开它”*
• *“从我所有的地图中构建一个模式库，然后生成5个挑战室”*

3--连接到克劳德桌面

添加 claude_desktop_config.json:

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

4--一键地图预览（独立）

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

HTML预览在浏览器中打开，并支持：

• 滚动 为了变焦， 拖拽 锅， 捏 触摸
• 单击房间→ 详细信息面板（实体、触发器、大小）
• 生活 搜索 过滤器(F 聚焦）
• 小地图 带视口指示器
• 键盘快捷键： + / - 变焦， 0 适合， Esc 取消选择

______________________________________________________________________

程序生成（PCG）

发电策略

模型配置文件

端到端管道

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

代理提示示例：

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

可繁殖世代（种子）

通过 seed= 和 model_profile="deterministic" 每次都能得到完全相同的房间：

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

ingest_external_map 可以直接从以下位置获取地图 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"
)

下载的文件将保存到 PCG/Datasets/ 带着一个 attribution.json 文件。 在构建其模式之前，始终验证mod的许可证是否允许衍生品使用。

______________________________________________________________________

图像到地图转换（v4中的新功能）

将任何颜色映射图像直接转换为可播放的Celeste地图。每个像素变成一个8×8的图块，颜色映射到图块类型和实体。

默认颜色映射

用法

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

运作原理

1. 加载图像，并可选择按以下方式缩小 scale 因素
2. 每个像素都与颜色图中最接近的颜色相匹配（在容差范围内）
3. 网格被分割成房间大小的块（默认40×23块=320×184 px）
4. 每个区块都变成了一个有适当瓷砖、实体和玩家后代的房间
5. 完整的地图写为 .bin 文件

需要 Pillow --安装方式： pip install loenn-mcp[image]

______________________________________________________________________

种子地形生成（v4中的新功能）

受以下启发，使用Perlin噪声和Voronoi图按程序生成完整的地图 AliShazly/地图生成器.

生物群落

用法

生成地形图（种子=42，难度=3）

预览地形生物群落

preview_terrain_biomes（种子=42，宽度_房间=4，高度_房间=3）

输出：

\[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缓存

wiki将分析结果存储在 `.loenn_mcp_wiki/` 作为JSON文件。
结果在会话中持续存在，因此重复的查询会立即返回。

______________________________________________________________________

## AI动力分析（新-Claude API）

利用Anthropic的Claude AI进行智能地图设计反馈、叙事生成和实体放置建议。

**设置：**

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-..."

**可用工具：**

|工具|说明|
|---|---|
| `ai_analyze_map` |Claude提供的设计反馈（一般/难度/视觉/流程分析）|
| `ai_describe_room` |生成各种风格的房间叙事描述|
| `ai_suggest_entities` |获取具有坐标的特定实体放置建议|

**示例提示：**

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..."

**分析类型：**

- `general` --总体设计评估及改进建议
- `difficulty` --难度曲线与平衡分析
- `visual` --视觉多样性和主题一致性反馈
- `flow` --玩家移动流程和导航清晰度

**描述样式：**

- `atmospheric` --富有启发性、以情绪为中心的描述
- `technical` --以游戏为中心的描述
- `story` --叙述/故事片段
- `brief` --简洁的1-2句总结

**建议目标：**

- `improve_flow` --更好的玩家指导和导航
- `add_challenge` --技能测试要素
- `reduce_difficulty` --可访问性改进
- `add_secrets` --探索奖励

如果出现以下情况，AI工具将优雅地降级 `ANTHROPIC_API_KEY` 未设置，返回有用的错误消息。

______________________________________________________________________

## 环境变量

|变量|默认值|描述|
|---|---|---|
| `LOENN_MCP_WORKSPACE` |当前工作目录| Celeste mod项目的根目录。服务器解析与此相关的所有映射路径。工作区外的路径遍历被阻止。 |

______________________________________________________________________

## 运作原理

### `celeste_bin.py` --独立二进制解析器

Celeste的纯Python实现 `.bin` 地图格式（不需要珠穆朗玛峰或伦）：

- 完整的读/写往返，无数据丢失
- 处理所有7种值类型： `bool`, `uint8`, `int16`, `int32`, `float32`，查找字符串，原始字符串，RLE编码字符串
- 符合内部Lönn/Mapple格式的递归元素树

### `pcg.py` --程序生成模块

提供：

- **模式提取** --转换 `.bin` 将房间转换为可重复使用的图案记录（尺寸等级、实体密度、瓷砖图案、触发器使用、游戏标签）
- **模式库** --基于JSON的存储，通过内容哈希进行重复数据删除
- **基于战略的生成** — `balanced`, `exploration`, `challenge`, `speedrun` 模式
- **种子随机性** — `random.Random(seed)` 用于可重复输出；通过MCP工具参数暴露种子
- **模型配置文件** — `deterministic` / `creative` / `architect` 配置文件控制种子的解析方式

### `image_map.py` --图像到地图转换（v4中的新功能）

将彩色贴图图像转换为可播放的Celeste贴图：

- **颜色到角色映射** --可配置的调色板将颜色映射到图块和实体
- **自动房间分割** --大图像被划分为房间大小的块
- **实体放置** --直接从像素颜色中提取的产卵、危险、收藏品
- **规模支持** --大图像可以缩小（N×N像素块→ 1 tile)
- **公差匹配** --手绘或抗混叠图像的模糊颜色匹配

### `terrain_gen.py` --种子地形生成器（v4中的新功能）

程序图生成的灵感来自 [AliShazly/地图生成器](https://github.com/AliShazly/map-generator):

- **柏林噪声** --用于有机地形的分形倍频程纯Python实现
- **沃罗诺伊生物群落** --地图划分为不同的生物群落区域（山脉、森林、平原、湖泊、洞穴、山顶）
- **完全播种** --相同的种子+参数=每次输出相同
- **扩展难度** --1-5级控制危险密度、瓷砖覆盖率和平台频率
- **生物识别实体** --每个生物群落都有适当的危险、收藏品和房间标志

### `gdep_tools.py` --游戏分析工具（v5中的新功能）

整合了以下游戏分析概念 [pirua游戏/ai_game_base_analysis_cli_mcp-tool](https://github.com/pirua-game/ai_game_base_analysis_cli_mcp_tool) （GDEP）：

- **Wiki缓存** --在本地持久化分析结果，因此重复查询是即时的(`.loenn_mcp_wiki/`)
- **模式检测** --检测游戏设计原型（线性进程、枢纽布局、收藏丰富、风廊）
- **难度分析** --根据危险密度、导航设备、瓷砖覆盖率（1-10比例）估算房间/地图难度
- **房间连通性** --显示孤立房间、死角和枢纽的邻接图分析
- **地图差异** --基于快照的结构差分用于跟踪地图随时间的演变
- **批量验证** --全地图可玩性检查（产卵、地板、边界），可选自动修复
- **建议** --基于房间分析的可操作改进建议

### `ai_analyzer.py` --人工智能分析（新）

集成Anthropic的Claude API，用于智能地图设计帮助：

- **地图分析** --基于人工智能的设计、难度、视觉效果和流程反馈
- **房间描述** --以大气、技术、故事或简短的风格生成叙事描述
- **实体建议** --获取具有坐标的特定实体放置建议
- **优雅降级** --当发生以下情况时，会显示有用的错误消息 `ANTHROPIC_API_KEY` 未配置

### `server.py` --MCP服务器

建于 [FastMCP](https://github.com/jlowin/fastmcp)。所有文件路径都是相对于以下路径解析的 `LOENN_MCP_WORKSPACE` 具有路径遍历保护。映射写入是原子性的（解析→ 突变→ 写）。外部下载需要明确 `confirm_download=True`.

______________________________________________________________________

## 需求

- Python 3.9+
- `fastmcp >= 3.0.0`
- `anthropic >= 0.40.0` （可选——仅适用于AI驱动的工具）
- `Pillow >= 9.0` （可选-仅需要 `generate_map_from_image`)

安装时使用所有可选功能： `pip install loenn-mcp[image]`

无需安装Celeste即可解析、生成或预览地图。

______________________________________________________________________

## 许可证

麻省理工学院——见 [许可证](LICENSE).