内容
# loenn-mcp
[](https://pypi.org/project/loenn-mcp/)
[](LICENSE)
[](https://www.python.org/)
**AI 驱动的 Celeste 地图编辑器** — 一个 [模型上下文协议](https://modelcontextprotocol.io/) (MCP) 服务器，为 Claude、GitHub Copilot 和其他 MCP 客户端提供完整的 Celeste `.bin` 地图编辑功能。无需打开 Lönn 即可读取、编辑、分析、生成和预览地图。
与 [Everest](https://github.com/EverestAPI/Everest) 模组和来自 [Lönn](https://github.com/CelestialCartographers/Loenn) 或 [Ahorn](https://github.com/CelestialCartographers/Ahorn) 的地图兼容。
## 功能
**87 个 MCP 工具**，涵盖 19 个类别，提供完整的地图操作和 AI 辅助设计。
### 核心工具
**读取和查询**
- `list_maps` — 列出所有 `.bin` 文件
- `read_map_overview` — 房间、实体、触发器、样式地块的摘要
- `read_room` — 完整的房间详细信息（瓷砖、实体、触发器、贴花）
- `get_room_tiles` — 原始瓷砖网格（前景或背景）
- `read_map_metadata` — 快速的元数据读取，无需完整读取
- `search_entities` — 按类型、位置、房间查找实体
- `search_triggers` — 按类型查找触发器
- `compare_rooms` — 并排比较房间
**编辑**
- `add_entity` / `remove_entity` — 放置或删除实体
- `update_entity` / `move_entity` — 修改实体属性或位置
- `add_trigger` / `remove_trigger` — 放置或删除触发器
- `set_room_tiles` — 替换瓷砖网格
- `add_room` / `remove_room` — 创建或删除房间
- `create_map` — 创建新的 `.bin` 文件
- `update_room` — 修改房间属性（音乐、黑暗、风等）
- `clone_room` — 复制房间
- `batch_add_entities` — 一次添加多个实体
- `resize_room` — 更改房间尺寸
**贴花和效果**
- `list_decals` / `add_decal` / `remove_decal` — 管理前景/背景贴花
- `list_stylegrounds` / `add_styleground` / `update_styleground` / `remove_styleground` — 管理地图效果
**定义和目录**
- `list_entity_definitions` / `get_entity_definition` — 浏览实体类型
- `list_trigger_definitions` / `get_trigger_definition` — 浏览触发器类型
- `list_effect_definitions` / `get_effect_definition` — 浏览效果类型
### 分析和洞察
**基本分析**
- `analyze_map` — 实体数量、类型分布、世界边界
- `visualize_map_layout` — ASCII 微缩地图
- `preview_map_section` — 详细的 ASCII 预览
**高级分析**
- `analyze_entity_usage` — 整个地图的实体统计
- `analyze_difficulty` — 房间/地图难度估计
- `find_entity_references` — 查找某个实体类型的全部实例
- `detect_map_patterns` — 确定设计原型（线性、中心等）
- `analyze_room_connectivity` — 邻接图分析
**建议和改进**
- `suggest_improvements` — 可行的房间建议
- `compare_maps` — 地图之间的结构差异
**Wiki 和缓存**
- `wiki_save` / `wiki_search` / `wiki_list` / `wiki_get` — 持久化和检索分析结果
**项目管理**
- `get_mod_info` — 项目元数据和结构
- `validate_map` / `batch_validate_and_fix` — 可玩性验证和自动修复
- `export_room_json` / `import_room_json` — JSON 房间交换
**差异**
- `summarize_map_diff` — 通过快照跟踪地图演变
### 渲染
- `render_map_html` — 交互式 HTML 预览（缩放、平移、搜索、微缩地图）
### 程序生成
**基于模式的生成**
- `build_pattern_library` — 从现有地图中提取模式
- `generate_room_from_pattern` — 使用策略 + 种子生成房间
- `ingest_external_map` — 从 GameBanana 下载和提取模式
**图像和地形生成**
- `generate_map_from_image` — 将颜色映射的图像转换为可玩的地图
- `generate_terrain_map` — 使用 Perlin 噪声 + Voronoi 生物群落的程序地图
- `preview_terrain_biomes` — 在生成前预览生物群落布局
### 程序生成（高级）
**PCGHelper 工具** — MdMC/WFC 瓦片生成
- `pcg_mdmc_presets` — 列出配置预设
- `pcg_skeleton_generate` — 布局非重叠房间骨架
- `pcg_markov_fill` — 用 MdMC/WFC/混合填充房间
- `pcg_score_room` — 评估趣味性和难度
- `pcg_pipeline` — 一次性端到端生成
---
## 安装和设置
### 从 PyPI 安装
```bash
pip install loenn-mcp
```
或从源代码：
```bash
git clone https://github.com/Maggy-Studio/loenn-mcp
cd loenn-mcp
pip install -e .
```
### 连接到 Claude Desktop
添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"loenn-mcp": {
"command": "python",
"args": ["-m", "loenn_mcp.server"],
"env": {
"LOENN_MCP_WORKSPACE": "/absolute/path/to/your/mod"
}
}
}
}
```
### 连接到 GitHub Copilot（VS Code）
添加到 `.vscode/mcp.json`：
```json
{
"servers": {
"loenn-mcp": {
"type": "stdio",
"command": "python",
"args": ["-m", "loenn_mcp.server"],
"env": {
"LOENN_MCP_WORKSPACE": "${workspaceFolder}"
}
}
}
}
```
### 在本地预览地图
```bash
python -m loenn_mcp.preview_map Maps/01_City_A.bin
python -m loenn_mcp.preview_map Maps/01_City_A.bin g- # 按前缀过滤
```
交互式 HTML 预览支持缩放、平移、房间详细信息、搜索和微缩地图，带有键盘快捷键。
---
## 程序生成
### 生成策略
| 策略 | 描述 |
|---|---|
| `balanced` | 探索和挑战的混合（默认） |
| `exploration` | 开放空间，温和的平台游戏，很少有障碍 |
| `challenge` | 密集的瓷砖，许多障碍，紧密的跳跃 |
| `speedrun` | 线性路径，最少的平台，快速流程 |
### 模型配置文件
| 配置文件 | 行为 | 用例 |
|---|---|---|
| `creative` | 每次调用随机种子 | 最大化多样性 |
| `deterministic` | 从策略稳定种子 | 可复制的布局 |
| `architect` | 随机种子 | 强调形状/连接性 |
### 快速入门示例
```python
# 1. 从现有地图构建模式库
build_pattern_library()
# 2. 创建新地图
create_map("Maps/PCG/Generated.bin", "PCG/Generated")
# 3. 生成房间
generate_room_from_pattern(
map_path="Maps/PCG/Generated.bin",
room_name="a-01",
strategy="exploration",
seed=42,
model_profile="deterministic"
)
# 4. 验证和预览
validate_room("Maps/PCG/Generated.bin", "a-01")
render_map_html("Maps/PCG/Generated.bin")
```
### 种子生成
使用 `seed=<int>` + `model_profile="deterministic"` 进行可复制输出：
```python
# 两次调用生成相同的房间
generate_room_from_pattern(..., strategy="challenge", seed=1234, model_profile="deterministic")
generate_room_from_pattern(..., strategy="challenge", seed=1234, model_profile="deterministic")
```
### GameBanana 集成
从社区模组中下载和提取模式：
```python
# 干运行（仅预览）
ingest_external_map(
source_url="https://gamebanana.com/mods/53774",
attribution="Spring Collab 2020",
confirm_download=False
)
# 下载和提取
ingest_external_map(
source_url="https://gamebanana.com/mods/53774",
attribution="Spring Collab 2020 (various authors)",
confirm_download=True,
tags="community,expert"
)
```
模式保存到 `PCG/Datasets/`，并附上出处。始终验证模组许可证是否允许衍生使用。
---
## 图像到地图转换
将颜色映射的图像直接转换为可玩的 Celeste 地图。每个像素成为一个 8×8 瓦片。
### 默认颜色映射
| 颜色 | 十六进制 | 映射到 |
|---|---|---|
| 黑色 | `#000000` | 实心瓦片 |
| 白色 | `#FFFFFF` | 空气（空） |
| 红色 | `#FF0000` | 尖刺障碍 |
| 绿色 | `#00FF00` | 玩家出生点 |
| 蓝色 | `#0000FF` | 跳跃平台 |
| 黄色 | `#FFFF00` | 草莓 |
| 洋红色 | `#FF00FF` | 弹簧 |
| 青色 | `#00FFFF` | 补充水晶 |
| 橙色 | `#FF8000` | 易碎块 |
| 灰色 | `#808080` | 背景实心 |
### 用法
```python
# 基本转换
generate_map_from_image(image_path="Assets/my_level.png")
# 自定义颜色和缩放
generate_map_from_image(
image_path="Assets/large_map.png",
output_path="Maps/Custom/level.bin",
scale=4, # 4×4 像素块 → 1 瓦片
color_map_json='{"#FF0000":"solid","#00FF00":"spawn"}'
)
```
需要 `Pillow`：`pip install loenn-mcp[image]`
---
## 种子地形生成
使用 Perlin 噪声和 Voronoi 生物群落生成完整的地图。灵感来自 [AliShazly/map-generator](https://github.com/AliShazly/map-generator)。
### 生物群落
| 生物群落 | 地形 |
|---|---|
| `mountain` | 密集的瓦片，紧密的平台，尖刺 |
| `forest` | 中等密度，许多平台，弹簧 |
| `plains` | 开放空间，温和的平台，可收集物 |
| `lake` | 稀疏的瓦片，跳跃平台，补充水晶 |
| `cave` | 封闭的，易碎块，黑暗房间 |
| `summit` | 稀疏的平台，风效果 |
### 快速示例
```python
# 生成 4×3 地图，种子为 42
generate_terrain_map(seed=42, difficulty=3, width_rooms=4, height_rooms=3)
# 在生成前预览生物群落布局
preview_terrain_biomes(seed=42, width_rooms=4, height_rooms=3)
# 输出：
# [P] [^] [^] [F]
# [~] [P] [^] [M]
# [C] [~] [P] [F]
```
### 参数
| 参数 | 默认值 | 描述 |
|---|---|---|
| `seed` | -1（随机） | 整数种子，用于可复制输出 |
| `width_rooms` | 4 | 水平房间数量 |
| `height_rooms` | 3 | 垂直房间数量 |
| `frequency` | 8.0 | Perlin 噪声频率（越低越平滑） |
| `voronoi_points` | 12 | 生物群落区域中心数量 |
| `biome_set` | all | 逗号分隔的生物群落名称 |
| `difficulty` | 3 | 1-5 难度等级 |
---
## 分析和洞察
用于地图设计、难度和模式的高级分析工具。
### 快速示例
```python
# 分析难度
analyze_difficulty(map_path="Maps/MyMod/1-City.bin")
# 检测游戏模式
detect_map_patterns(map_path="Maps/MyMod/1-City.bin")
# → "standard-level (7-15 rooms)", "linear-horizontal", "checkpointed"
# 获取房间建议
suggest_improvements(map_path="Maps/MyMod/1-City.bin", room_name="lvl_a-01")
# 跟踪地图演变
summarize_map_diff(map_path="Maps/MyMod/1-City.bin") # 保存快照
# ... 编辑地图 ...
summarize_map_diff(map_path="Maps/MyMod/1-City.bin") # 显示差异
# 缓存结果以便立即重用
wiki_save(key="city_difficulty", content="Avg 4.2/10, 3 hard rooms", tags="analysis")
wiki_search(query="difficulty")
# 批量验证
batch_validate_and_fix(map_path="Maps/MyMod/1-City.bin", auto_fix=True)
# 搜索和克隆
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_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 缓存
分析结果以 `.loenn_mcp_wiki/` 中的 JSON 文件形式存在，以便在会话之间立即重用。
---
## AI 驱动的分析
利用 Claude AI 进行智能地图反馈、房间描述和实体建议。
### 设置
```bash
pip install loenn-mcp
export ANTHROPIC_API_KEY="sk-ant-..." # 从 https://console.anthropic.com/ 获取
```
### 可用工具
| 工具 | 描述 |
|---|---|
| `ai_analyze_map` | 设计反馈（常规/难度/视觉/流程） |
| `ai_describe_room` | 以各种风格生成房间描述 |
| `ai_suggest_entities` | 带有坐标的实体放置建议 |
### 示例
```python
# 获取设计反馈
ai_analyze_map(map_path="Maps/MyMod/1-City.bin", analysis_type="general")
# → "优势：良好的检查点。 在 3-5 房间添加更多草莓..."
# 生成描述
ai_describe_room(map_path="Maps/MyMod/1-City.bin", room_name="lvl_a-03", style="atmospheric")
# → "一个风化的悬崖，古老的石头遇到了咆哮的狂风..."
# 获取实体建议
ai_suggest_entities(map_path="Maps/MyMod/1-City.bin", room_name="lvl_a-03", goal="add_challenge")
# → "1. 在 (120, 80) 添加尖刺以进行计时挑战..."
```
### 分析类型
- `general` — 整体设计与建议
- `difficulty` — 难度曲线分析
- `visual` — 视觉多样性和主题反馈
- `flow` — 玩家移动和导航
### 描述风格
- `atmospheric` — 富有感染力的，注重情绪的
- `technical` — 关注游戏性的技术性描述
- `story` — 叙事片段
- `brief` — 1-2 句总结
### 建议目标
- `improve_flow` — 更好的玩家引导
- `add_challenge` — 测试技能的元素
- `reduce_difficulty` — 无障碍性
- `add_secrets` — 探索奖励
如果未设置 `ANTHROPIC_API_KEY`，则会优雅地降级。
---
## 高级 PCG（MdMC/WFC）
Lönn 模组 [PCGHelper](https://github.com/Maggy-Studio/PCGHelper) 的完整 Python 端口 — MdMC/WFC 瓦片生成、骨架布局和端到端流水线。
### 工具
| 工具 | 描述 |
|---|---|
| `pcg_mdmc_presets` | 列出 7 个 MdMC 配置文件预设 |
| `pcg_skeleton_generate` | 布局非重叠房间骨架 |
| `pcg_markov_fill` | 用 MdMC/WFC/混合填充房间 |
| `pcg_score_room` | 评估趣味性和难度 |
| `pcg_pipeline` | 一次性端到端生成 |
### 生成模式
- `mdmc` — 多维马尔可夫链
- `wfc` — 波函数崩溃
- `hybrid` — 两者的组合
### 评分指标
**趣味性 I** = w1·全局 NLE + w2·局部 NLE + w3·香农熵
**难度 D** = z1·孔隙率 + z2·局部 LE + z3·NLE 稀缺性
### MdMC 预设
| 键 | 描述 |
|---|---|
| `000011012` | L 型（默认） |
| `000011112` | 3 邻居因果关系 |
| `001001112` | 4 邻居 |
| `011011012` | 5 邻居 |
| `010111010` | 十字（推荐 WFC） |
| `101000101` | 仅对角线 |
| `111101111` | 所有 8 个邻居 |
### 示例
```python
# 一次性端到端生成
pcg_pipeline(
map_path="Maps/MyMod/1-City.bin",
room_count=8,
generation_mode="mdmc",
seed=42,
ensure_playable=True,
place_entities=True,
)
# → "PCG 流水线完成：已添加 8 个房间"
# 评估房间
pcg_score_room(map_path="Maps/MyMod/1-City.bin", room_name="lvl_a-03")
# → "趣味性 I = 0.4231 | 难度 D = 0.5812"
# 填充现有空房间
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", # 获取玩家出生点
end_room="skel_2", # 获取金色莓果
seed=99,
)
```
---
## 配置
| 变量 | 默认值 | 描述 |
|---|---|---|
| `LOENN_MCP_WORKSPACE` | 当前目录 | 您的 Celeste 模组项目的根目录。所有地图路径相对于此路径。路径遍历受到阻止。 |
---
## 架构
### 核心模块
**`celeste_bin.py`** — 独立的 `.bin` 解析器
- 纯 Python（无需 Everest/Lönn）
- 完整读取/写入往返，无数据丢失
- 处理所有 7 种值类型：bool、uint8、int16、int32、float32、查找字符串、原始字符串、RLE 编码字符串
- 递归元素树匹配 Lönn/Maple 格式
**`pcg.py`** — 程序生成
- 从房间中提取模式（大小、实体密度、瓷砖图案、游戏标签）
- 带有重复数据消除的 JSON 模式库
- 基于策略的生成（平衡、探索、挑战、速度通关）
- 可复制输出的种子随机性
- 模型配置文件（确定性、创造性、建筑师）
**`image_map.py`** — 图像到地图转换
- 颜色到角色映射（可配置的调色板）
- 自动房间分割
- 从像素颜色中放置实体
- 支持缩放（降采样）
- 模糊颜色匹配
**`terrain_gen.py`** — 种子地形生成
- 带有分形八进制的 Perlin 噪声
- Voronoi 生物群落分区
- 完全种子化（相同种子 = 相同输出）
- 难度缩放（1-5）
- 生物群落感知实体
**`gdep_tools.py`** — 游戏分析
- Wiki 缓存（`.loenn_mcp_wiki/`）
- 模式检测（线性、中心、富含收集品等）
- 难度分析（1-10 难度等级）
- 房间连接图
- 地图差异跟踪与快照
- 批量验证和自动修复
- 可行建议
**`ai_analyzer.py`** — AI 驱动的分析
- Claude API 集成
- 设计反馈（常规、难度、视觉、流程）
- 房间描述（氛围、技巧、故事、简短）
- 实体放置建议
- 优雅降级
**`server.py`** — MCP 服务器
- 使用 [FastMCP](https://github.com/jlowin/fastmcp) 构建
- 路径穿越保护
- 原子地图写入
- 显式下载确认
---
## 要求
- Python 3.9+
- `fastmcp >= 3.0.0`
- `anthropic >= 0.40.0` （可选，用于 AI 驱动的工具）
- `Pillow >= 9.0` （可选，用于图像到地图转换）
安装所有可选功能：
```bash
pip install loenn-mcp[image]
```
不需要 Celeste 安装。
---
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器