loenn-mcp

# loenn-mcp [](https://pypi.org/project/loenn-mcp/) [](LICENSE) [](https://www.python.org/) **Celeste 地图编辑器，用于 AI 代理** — 一个 [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) 服务器，允许 GitHub Copilot、Claude 等 MCP 客户端读取、编辑、分析、**程序化生成** 和预览 Celeste `.bin` 地图文件，无需打开 Lönn。 专为与 [Everest](https://github.com/EverestAPI/Everest) 模组配合使用。适用于由 [Lönn](https://github.com/CelestialCartographers/Loenn) 或 [Ahorn](https://github.com/CelestialCartographers/Ahorn) 创建的地图。 --- ## 功能 ### 19 类别下的 87 种 MCP 工具 **地图读取** | 工具 | 描述 | |---|---| | `list_maps` | 列出项目中的所有 `.bin` 文件 | | `read_map_overview` | 房间、实体、触发器和样式基线的摘要 | | `read_room` | 单个房间的完整详细信息：瓷砖、实体、触发器、贴花 | | `get_room_tiles` | 房间的原始瓷砖网格（前景或背景） | **地图读取扩展（v5 新增）** | 工具 | 描述 | |---|---| | `read_map_metadata` | 快速元数据（包、房间数量、世界边界）无需完整读取 | | `search_entities` | 按类型、位置和房间搜索实体 | | `search_triggers` | 按类型搜索触发器 | | `compare_rooms` | 两个房间的并排比较（大小、难度、实体） | **地图编辑** | 工具 | 描述 | |---|---| | `add_entity` | 在房间中放置实体（自动分配 ID） | | `remove_entity` | 按 ID 删除实体 | | `add_trigger` | 在房间中放置触发器（矩形区域），可选路径节点 | | `remove_trigger` | 按 ID 删除触发器 | | `set_room_tiles` | 替换房间的瓷砖网格 | | `add_room` | 创建具有自定义位置/大小的新房间 | | `remove_room` | 从地图中删除房间 | | `create_map` | 创建新的空 `.bin` 地图文件 | **地图编辑扩展（v5 新增）** | 工具 | 描述 | |---|---| | `update_entity` | 更新现有实体的属性，ID | | `move_entity` | 将实体移动到新位置 | | `update_room` | 更新房间级属性（音乐、黑暗、风等） | | `clone_room` | 将房间克隆到新名称和位置 | | `batch_add_entities` | 一次添加多个实体（JSON 数组） | | `resize_room` | 更改房间尺寸 | **贴花（v5 新增）** | 工具 | 描述 | |---|---| | `list_decals` | 列出房间中的所有贴花（FG 或 BG） | | `add_decal` | 添加具有纹理、位置和缩放的贴花 | | `remove_decal` | 按索引删除贴花 | **样式基线** | 工具 | 描述 | |---|---| | `list_stylegrounds` | 列出前景 + 背景效果（带有索引） | | `add_styleground` | 将效果（视差、自定义 Lua 效果、`apply` 组等）添加到 FG 或 BG | | `remove_styleground` | 按索引删除效果 | | `update_styleground` | 合并属性更改到现有效果中 | **实体/触发器目录** | 工具 | 描述 | |---|---| | `list_entity_definitions` | 浏览项目中的 Lönn 实体 `.lua` 文件 | | `get_entity_definition` | 读取单个实体定义的完整源代码 | | `list_trigger_definitions` | 浏览 Lönn 触发器 `.lua` 文件 | | `list_effect_definitions` | 浏览 Lönn 效果 `.lua` 文件 | **目录扩展（v5 新增）** | 工具 | 描述 | |---|---| | `get_trigger_definition` | 读取触发器 `.lua` 文件的源代码，文件名 | | `get_effect_definition` | 读取效果 `.lua` 文件的源代码，文件名 | **分析** | 工具 | 描述 | |---|---| | `analyze_map` | 统计数据：实体数量、类型分布、世界边界 | | `visualize_map_layout` | 房间位置的 ASCII 微型地图 | | `preview_map_section` | 地图区域的详细 ASCII 预览 | **高级分析 — gdep 启发（v5 新增）** | 工具 | 描述 | |---|---| | `analyze_entity_usage` | 整个地图的实体使用统计数据 | | `analyze_difficulty` | 从危险、导航辅助、瓷砖覆盖率估计房间/地图难度 | | `find_entity_references` | 查找房间中所有出现的实体类型 | | `detect_map_patterns` | 检测设计原型（线性、中心、富含可收集物品等） | | `analyze_room_connectivity` | 邻接图：孤立房间、死胡同、中心 | **建议 — gdep 启发（v5 新增）** | 工具 | 描述 | |---|---| | `suggest_improvements` | 房间的可行建议（生成、地板、平衡） | | `compare_maps` | 两个地图文件之间的结构差异 | **Wiki / 缓存 — gdep 启发（v5 新增）** | 工具 | 描述 | |---|---| | `wiki_save` | 本地保存分析结果以供即时重复查询 | | `wiki_search` | 按关键字、内容或标签搜索缓存的 Wiki 条目 | | `wiki_list` | 列出所有 Wiki 条目 | | `wiki_get` | 检索特定的 Wiki 条目 | **模组项目（v5 新增）** | 工具 | 描述 | |---|---| | `get_mod_info` | 项目信息：everest.yaml、地图数量、PCG 库、Wiki | | `validate_map` | 具有可选自动修复的整图可玩性验证 | **导入/导出（v5 新增）** | 工具 | 描述 | |---|---| | `export_room_json` | 将房间导出为 JSON 以供外部编辑或共享 | | `import_room_json` | 从 JSON 将房间导入到地图中 | **差异和修复 — gdep 启发（v5 新增）** | 工具 | 描述 | |---|---| | `summarize_map_diff` | 基于快照的地图演化结构差异 | | `batch_validate_and_fix` | 批量可玩性检查，可选自动修复 | **渲染** | 工具 | 描述 | |---|---| | `render_map_html` | 交互式 HTML 预览（缩放、平移、房间详细信息、缩略图、搜索） | **程序化生成** | 工具 | 描述 | |---|---| | `build_pattern_library` | 从现有地图扫描并提取房间模式到可重用 JSON 库 | | `generate_room_from_pattern` | 使用模式 + 策略 + 种子生成新房间 | | `validate_room` | 检查房间的可玩性问题（生成、地板、边界） | | `ingest_external_map` | 从外部 URL 下载地图（GameBanana 等）并提取模式 | **图像到地图和地形生成（v4）** | 工具 | 描述 | |---|---| | `generate_map_from_image` | 将颜色映射图像（PNG/JPG/BMP）转换为完整的 playable Celeste 地图 | | `generate_terrain_map` | 使用种子 Perlin 噪声 + Voronoi 生物群落的程序化地图 | | `preview_terrain_biomes` | 生物群落布局的 ASCII 预览 | --- ## 快速入门 ### 1 — 从 PyPI 安装 ```bash pip install loenn-mcp ``` 或克隆并从源代码安装： ```bash git clone https://github.com/Maggy-Studio/loenn-mcp cd loenn-mcp pip install -e . ``` ### 2 — 连接到 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}" } } } } ``` 然后询问 Copilot： - *"01_City_A.bin 中有哪些房间？"* - *"在 a-03 房间的 (120, 80) 位置添加一个草莓"* - *"渲染 07_Hell_A.bin 的 HTML 预览并打开它"* - *"从所有地图中构建一个模式库，然后生成 5 个挑战房间"* ### 3 — 连接到 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" } } } } ``` ### 4 — 一键地图预览（独立） ```bash 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- # 按前缀过滤房间 ``` HTML 预览在您的浏览器中打开并支持： - **滚动** 缩放，**拖动** 平移，**捏合** 触摸 - 点击房间 → 详细信息面板（实体、触发器、大小） - 实时 **搜索** 过滤器（`F` 聚焦） - **缩略图** 带有视口指示器 - 键盘快捷键：`+` / `-` 缩放，`0` 适应，`Esc` 取消选择 --- ## 程序化生成（PCG） ### 生成策略 | 策略 | 描述 | |---|---| | `balanced` | 探索和挑战的混合 — 良好的默认选择 | | `exploration` | 开放空间，温和的平台游戏，很少的危险 | | `challenge` | 密集的瓷砖，许多危险，紧密的跳跃 | | `speedrun` | 线性路径，最少的平台，快速流程 | ### 模型配置文件 | 配置文件 | 种子行为 | 最适合 | |---|---|---| | `creative` | 每次调用随机种子 | 最大房间多样性 | | `deterministic` | 从策略名称稳定的种子 | CI 管道，可复制的布局 | | `architect` | 随机种子 | 强调房间形状和连接性 | ### 端到端管道 ``` 1. 从现有地图构建模式库 2. （可选）从 GameBanana 导入社区地图 3. 创建空白地图 4. 使用选择的策略和种子生成房间 5. 验证每个房间 6. 渲染 HTML 预览 ``` **示例代理提示：** ```python # 步骤 1 — 构建模式库 build_pattern_library() # 步骤 2 — 导入 GameBanana 模组以获取更丰富的模式数据 ingest_external_map( source_url="https://gamebanana.com/mods/53774", attribution="Spring Collab 2020（多个作者）", confirm_download=True, tags="community,collab" ) # 步骤 3 — 创建地图并生成房间 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 ) # 步骤 4 — 验证 validate_room("Maps/PCG/MyAIMap.bin", "a-01") # 步骤 5 — 预览 render_map_html("Maps/PCG/MyAIMap.bin") ``` ### 可复制的生成（种子） 传递 `seed=<integer>` 和 `model_profile="deterministic"` 以获得完全相同的房间： ```python # 这两个调用产生相同的输出： 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](https://gamebanana.com/games/6460) 获取地图： ```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（多个作者，请参见模组页面）", confirm_download=True, tags="expert,collab" ) ``` 下载的文件保存在 `PCG/Datasets/` 中，带有 `attribution.json` 文件。 **始终验证模组的许可证是否允许派生使用，然后再基于其模式构建。** --- ## 图像到地图转换（v4 新增） 将任何颜色映射图像直接转换为 playable 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","#0000FF":"air"}' ) ``` ### 工作原理 1. 加载图像并可选地按 `scale` 因子缩小 2. 每个像素与颜色映射中最近的颜色匹配（在容差范围内） 3. 网格分成房间大小的块（默认 40×23 瓷砖 = 320×184 像素） 4. 每个块成为具有适当瓷砖、实体和玩家生成的房间 5. 完整的地图作为 `.bin` 文件写入 需要 `Pillow` — 使用以下命令安装：`pip install loenn-mcp[image]` --- ## 种子地形生成（v4 新增） 使用 Perlin 噪声和 Voronoi 图生成完整的程序化地图，灵感来自 [AliShazly/map-generator](https://github.com/AliShazly/map-generator)。 ### 生物群落 | 生物群落 | 特征 | 地形 | |---|---|---| | `mountain` | 密集瓷砖 | 紧密平台，尖刺 | | `forest` | 中等密度 | 许多平台，弹簧 | | `plains` | 开放空间 | 温和的平台，可收集物品 | | `lake` | 稀疏瓷砖 | 跳跃平台，补充水晶 | | `cave` | 封闭 | 易碎块，黑暗房间 | | `summit` | 稀疏平台 | 风效 | ### 用法 ```python generate_terrain_map(seed=42, difficulty=3) ``` ### 预览地形生物群落 ```python preview_terrain_biomes(seed=42, width_rooms=4, height_rooms=3) ``` 输出： ``` # [P] [^] [^] [F] # [~] [P] [^] [M] # [C] [~] [P] [F] ``` ### 生成算法 1. **Perlin 噪声** 创建有机高度图地形 — 控制实心瓷砖、平台和间隙的出现 2. **Voronoi 图** 将地图划分为生物群落区域 — 每个房间继承其 Voronoi 区域的生物群落 3. **种子随机数生成器** 确保相同的 `seed` + 参数始终产生相同的输出 4. **难度缩放** （1-5）调整危险密度、瓷砖覆盖率和平台频率 5. 生物群落属性控制瓷砖字符、实体类型、房间标志（黑暗、水下、风） ### 参数 | 参数 | 默认值 | 描述 | |---|---|---| | `seed` | -1（随机） | 整数种子，用于复制输出 | | `width_rooms` | 4 | 水平房间数 | | `height_rooms` | 3 | 垂直房间数 | | `frequency` | 8.0 | Perlin 噪声频率（越低越平滑） | | `voronoi_points` | 12 | 生物群落区域中心数量 | | `biome_set` | all | 逗号分隔的生物群落名称 | | `difficulty` | 3 | 1-5 难度等级，控制危险密度 | --- ## 游戏分析与 Wiki（v5 新增 — gdep 启发） 来自游戏设计分析模式的高级分析工具。 ### 用法示例 ```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 (3 checkpoints)" # 获取房间建议 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 difficulty 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") # 以 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 进行智能地图设计反馈、叙事生成和实体放置建议。 **设置：** ```bash # 安装包含 AI 支持（anthropic 包） pip install loenn-mcp # 设置您的 API 密钥（从 https://console.anthropic.com/ 获取） $env:ANTHROPIC_API_KEY="sk-ant-api03-..." ``` **可用工具： | 工具 | 描述 | |---|---| | `ai_analyze_map` | Claude 驱动的设计反馈（常规/难度/视觉/流程分析） | | `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`，AI 工具将优雅地降级，返回有用的错误消息。 --- ## PCGHelper 工具（v5.2 新增） [PCGHelper Lönn 模组](https://github.com/Maggy-Studio/PCGHelper) 的完整 Python 端口 — MdMC/WFC 瓦片生成、骨架布局和端到端 PCG 管道，均可作为 MCP 工具访问。 | 工具 | 描述 | |---|---| | `pcg_mdmc_presets` | 列出所有 7 个 MdMC 配置矩阵预设及其描述 | | `pcg_skeleton_generate` | 布局一个非重叠的房间骨架，边缘到边缘连接 | | `pcg_markov_fill` | 使用 MdMC、WFC 或混合模式用瓦片填充房间 | | `pcg_score_room` | 评估房间的有趣度 I 和难度 D（论文 §4.2/§4.3） | | `pcg_pipeline` | 一次性端到端生成：骨架 → 瓎片填充 → 修复 → 实体 | **生成模式：** `mdmc`（多维马尔可夫链），`wfc`（波函数坍缩），`hybrid` **评分指标**（论文 §4.2/§4.3）： - **有趣度 I** = w1·全局 NLE 密度 + w2·局部 NLE 密度 + w3·香农熵 - **难度 D** = z1·洞穴频率 + z2·局部 LE 密度 + z3·NLE 稀缺性 **MdMC 配置矩阵预设：** | 键 | 描述 | |---|---| | `000011012` | E+S — L 形（论文默认） | | `000011112` | E+SW+S — 3 邻域因果 | | `001001112` | NE+E+SW+S — 4 邻域（论文） | | `011011012` | N+NE+W+E+S — 5 邻域 | | `010111010` | N+W+E+S — 十字（推荐用于 WFC） | | `101000101` | NW+NE+SW+SE — 仅对角线 | | `111101111` | 所有 8 个邻域 — 全上下文 | **示例 — 一次性管道：** ```python # 生成 8 个连接的房间，训练于现有地图房间 pcg_pipeline( map_path="Maps/MyMod/1-City.bin", room_count=8, room_width_tiles=40, room_height_tiles=23, generation_mode="mdmc", seed=42, carve_exits=True, ensure_playable=True, place_entities=True, name_prefix="gen_", ) # → "PCG 管道完成：添加 8 个房间 — gen_0 … gen_7" # 评估现有房间 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", seed=99, ) ``` --- ## 环境变量 | 变量 | 默认值 | 描述 | |---|---|---| | `LOENN_MCP_WORKSPACE` | 当前工作目录 | 您的 Celeste 模组项目的根目录。服务器解析所有地图路径相对于此路径。路径遍历在工作区外部被阻止。 | --- ## 工作原理 ### `celeste_bin.py` — 独立二进制解析器 纯 Python 实现的 Celeste `.bin` 地图格式（无需 Everest 或 Lönn）： - 完整的读写循环，无数据丢失 - 处理所有 7 种值类型：`bool`，`uint8`，`int16`，`int32`，`float32`，查找字符串，原始字符串，RLE 编码字符串 - 递归元素树匹配内部 Lönn/Maple 格式 ### `pcg.py` — 程序生成模块 提供： - **模式提取** — 将 `.bin` 房间转换为可重用的模式记录（尺寸类别、实体密度、瓦片图案、触发器使用、游戏标签） - **模式库** — 基于 JSON 的存储，具有通过内容哈希的重复数据删除 - **基于策略的生成** — `balanced`，`exploration`，`challenge`，`speedrun` 模式 - **种子随机性** — `random.Random(seed)` 用于可复制的输出；种子通过 MCP 工具参数公开 - **模型配置文件** — `deterministic` / `creative` / `architect` 配置文件控制种子如何解析 ### `image_map.py` — 图像到地图转换（v4 新增） 将颜色映射的图像转换为可玩的 Celeste 地图： - **颜色到角色映射** — 可配置的调色板，将颜色映射到瓦片和实体 - **自动房间分割** — 大型图像被分成房间大小的块 - **实体放置** — 从像素颜色中提取出生点、危险物、收藏品 - **比例支持** — 大型图像可以缩小（N×N 像素块 → 1 瓦片） - **容差匹配** — 模糊颜色匹配，用于手绘或抗锯齿图像 ### `terrain_gen.py` — 种子地形生成器（v4 新增） 受 [AliShazly/map-generator](https://github.com/AliShazly/map-generator) 启发的程序地图生成： - **Perlin 噪声** — 具有分形八度的纯 Python 实现，用于有机地形 - **Voronoi 生物群落** — 地图划分为不同的生物群落区域（山脉、森林、平原、湖泊、洞穴、山顶） - **完全种子化** — 相同的种子 + 参数 = 每次都相同的输出 - **难度缩放** — 1-5 规模控制危险物密度、瓦片覆盖率和平台频率 - **生物群落感知实体** — 每个生物群落都有适当的危险物、收藏品和房间标志 ### `gdep_tools.py` — 游戏分析工具（v5 新增） 集成 [pirua-game/ai_game_base_analysis_cli_mcp_tool](https://github.com/pirua-game/ai_game_base_analysis_cli_mcp_tool)（gdep）中的游戏分析概念： - **维基缓存** — 持久化分析结果，以便重复查询即时（`.loenn_mcp_wiki/`） - **模式检测** — 检测游戏设计原型（线性进展、中心布局、富含收藏品、风道） - **难度分析** — 根据危险物密度、导航辅助、瓦片覆盖率估计房间/地图难度（1-10 规模） - **房间连通性** — 邻接图分析，显示孤立房间、死胡同和中心 - **地图差异** — 基于快照的结构差异，用于跟踪地图随时间演变 - **批量验证** — 整个地图的可玩性检查（出生点、地板、边界）带有可选的自动修复 - **建议** — 基于房间分析的可行改进建议 ### `ai_analyzer.py` — AI 驱动的分析（新增） 集成 Anthropic 的 Claude API 以提供智能地图设计协助： - **地图分析** — 对设计、难度、视觉和流程的 AI 驱动反馈 - **房间描述** — 以氛围、科技、故事或简洁风格生成叙事描述 - **实体建议** — 获取具有坐标的特定实体放置建议 - **优雅降级** — 当未配置 `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 安装即可解析、生成或预览地图。 --- ## 许可证 MIT — 请参阅 [LICENSE](LICENSE)。