BrickBuilderMCP

# LegoMCP MCP 服务器，允许大型语言模型（LLM）设计可搭建的乐高模型，通过生成验证的 LDraw 文件，而不是在 CAD 应用程序中点击。  * 一座1,024件的堡垒城市，完全通过这些工具设计 - 1,576个验证的螺柱连接，零浮动零件，零碰撞，在每个阶段都经过验证。模型为 [examples/fortress_city.ldr](examples/fortress_city.ldr)；在 Studio 中打开它。* 将它放入 Claude Desktop，询问 Claude *"给我建造一个小红房子放在棕色底板上,"* 然后 LLM 获得 55 个语义工具，6 个提示和 5 个参考资源，涵盖：真正的 LDraw 目录（24,009 个零件），搭建性检查（无浮动 / 无碰撞 / 无重叠），连接感知绑定，逐件装配的建造模式，持久项目，自动保存，聊天中的内联渲染预览和调试工具包（`render_validation`，`inspect_part`，`collision_detail`，`describe_errors`）。输出是一个真正的 `.ldr` / `.mpd` 文件，可以在 [BrickLink Studio](https://www.bricklink.com/v3/studio/download.page) 或 [LeoCAD](https://www.leocad.org/) 中打开。 > **状态：早期，但基础已经具备。** 整个流程从头到尾运行 - 安装，与 Claude 对话，获取可导出的 `.ldr` - 连接模型在整个 24k 零件目录中强制执行：每个零件都报告它实际抓取的内容，严格模式拒绝物理上不可能的位置，验证器的基本事实是真实的螺柱↔接收器配对（双向 - 悬挂零件在悬垂下是首要连接）。结构化架构（墙壁，塔，门，屋顶 - 上面的堡垒）通过帮助程序可靠地构建。 > > **使用 LLM 设计乐高模型仍然很困难。** 模型必须推理 3D 几何，砖块连接，交错 / 绑定模式，颜色和比例，并且在数十个工具调用中保持所有这些一致。有机形状，曲线和螺柱不在顶部技术尚未达到交付工具的范围（连接模型仅限螺柱 - 销，夹子和支架是第二阶段）。语义工具包使任何这些成为可能; 使它变得流利是实际的研究问题。 > > **渲染器**，**目录**，**验证/反馈循环**，**导入/导出**路径和 **CLI** 是今天运行良好的部分。 --- ## 目录 - [为什么存在](#为什么存在) - [不可妥协的规则](#不可妥协的规则) - [需求](#需求) - [安装和配置 Claude Desktop](#安装和配置-claude-desktop) - [内联预览模式](#内联预览模式-env-var) - [坐标约定](#坐标约定-ldraw) - [分组工具](#分组工具) - [模型状态](#模型状态) - [放置（原始）](#放置原始) - [高级助手（首选）](#高级助手首选) - [目录和搜索](#目录和搜索) - [连接](#连接) - [子组件](#子组件) - [验证和调试](#验证和调试) - [渲染](#渲染) - [持久性：检查点/项目/自动保存](#持久性检查点项目自动保存) - [建造模式](#建造模式) - [注意（多模态上下文）](#注意多模态上下文) - [导入/导出](#导入导出) - [撤销/重做](#撤销重做) - [提示（斜杠菜单）](#提示斜杠菜单) - [资源](#资源) - [作为独立代理运行](#作为独立代理运行-no-claude-desktop) - [独立 CLI：`render` / `bom` / `instructions`](#独立-cli) - [开发](#开发) - [已知限制](#已知限制) - [许可证](#许可证) --- ## 为什么存在 让 LLM 通过屏幕自动化驱动 CAD 应用程序失败 - 太多的微操作，没有空间真实性，错误累积。LegoMCP 为 LLM 提供了一个**语义 API**：每个操作都是一个键入的函数调用，每个更改都根据真实的乐高连接规则进行验证，每个状态都是可逆的。CAD 应用程序成为查看器；MCP 服务器是真实来源。 ## 不可妥协的规则 工具链强制执行这些规则，以便 LLM 导出的内容实际上是可以搭建的： 1. **连接规则** - 每个零件要么位于地面（y ≈ 0），要么与直接位于上方或下方的零件有至少一个螺柱-接收器配对。两个方向都是真正的连接：坐在下面的螺柱上 **或悬挂在上面的接收器上**（向下搭建是允许的）。仅凭砖块对齐而不与螺柱对齐 - 例如，半个螺柱偏移或 1 宽砖块居中于 2 宽砖块上 - 不是连接，被报告为 `浮动`。在 **目录中的每个零件** 上执行此操作，而不是硬编码的子集。 2. **锚定规则** - 连接的岛屿必须通过螺柱连接链（在任意方向）到达地面。“塔”如果砖块相互接触但整个结构悬浮，则被报告为 `未锚定`。 3. **无重叠** - 砖块不得占据相同的 AABB。`add_part(strict=True)` 在插入时拒绝重叠和未连接的放置，并且 **每个 `add_part`/`move_part`/`rotate_part` 结果都带有 `connectivity` 报告 + `warnings`**，以便立即发现问题，而不是在下一个 `validate_model` 处。 4. **真实几何** - AABBs，螺柱位置和尺寸来自实际解析的 LDraw `.dat` 文件（递归遍历子零件和 `stug-NxN` 螺柱组基元）。“2x4 砖块”确实是 80 LDU × 40 LDU × 24 LDU，带有 8 个螺柱，位置正确。 --- ## 需求 - **macOS**（已测试）或 Linux。Windows 应该可以通过 WSL 运行；未测试。 - **`uv`** - Python 工具链管理器。`brew install uv`（macOS）或 `curl -LsSf https://astral.sh/uv/install.sh | sh`。 - **~150 MB 磁盘** 用于 LDraw 零件库（一次性下载）。 - **Claude Desktop** 用于内联预览工作流。独立代理无需它，但需要 `ANTHROPIC_API_KEY`。 --- ## 安装和配置 Claude Desktop ```bash # 1. 克隆和安装 git clone <此仓库> LegoMCP && cd LegoMCP uv tool install --from . lego-mcp # 2. 下载完整的 LDraw 零件库（~135 MB，一次性，几分钟） lego-mcp install-library # 3. 连接到 Claude Desktop。编辑： # ~/Library/Application Support/Claude/claude_desktop_config.json { "mcpServers": { "lego": { "command": "/Users/<您>/\.local/bin/lego-mcp", "env": { "LEGO_MCP_INLINE_MODE": "file_url" } } } } ``` 用您的用户名替换 `<您>`。**完全退出 Claude Desktop（⌘Q）** 并重新打开，以便它启动新的服务器。 在任何聊天中验证：输入 `/` - 您应该看到一个包含 **start**，**build**，**from_plans**，**from_image**，**rescue** 和 **techniques** 提示的 `lego` 组。 ### 渲染实时显示在这里 `~/Library/Application Support/lego_mcp/renders/` 每次 `render_model` / `render_progress` / `render_validation` 调用都会写入 `<timestamp>_<model>.png`（保留历史记录）并覆盖 `latest.png`。通过 `LEGO_MCP_RENDERS_DIR` 环境变量覆盖。 在任何时候打开最新的： ```bash open "$HOME/Library/Application Support/lego_mcp/renders/latest.png" ``` Preview.app 在文件更改时自动刷新，因此请保持打开状态以获取实时更新。 --- ## 内联预览模式（env var） 通过 Claude Desktop 配置中的 `env` 块中的 `LEGO_MCP_INLINE_MODE` 设置。 | 模式 | 聊天文本内容 | 每次渲染的字节数 | 使用场景 | |---|---|---|---| | **`data_uri`**（默认） | `` | ~16 KB | 您希望内联预览在 *任何* MCP 客户端（网页，桌面，未来客户端）中都能工作。 | | **`file_url`**（推荐用于 Claude Desktop） | `` | ~150 字节 | 您正在使用 Claude Desktop，它渲染本地文件 URL。约 200 倍更便宜。 | | **`none`** | 无 | 0 | 您只希望 LLM 视觉 `MCPImage` 块；聊天中没有人类预览。 | `MCPImage` 块（Claude 的视觉输入）**始终**存在，与模式无关 - 只有面向人类的预览文本会发生变化。 --- ## 坐标约定（LDraw） - 右手坐标系，**-Y 向上**。 - 1 螺柱 = **20 LDU** 宽。1 板 = **8 LDU** 高。1 砖 = **24 LDU** 高（= 3 板）。 - 零件原点位于 **底部中心**。 - 基板（3811）在 y=0 处，其顶面在 y=-4 处。坐在它上面的砖块，其底面在 y=-4 处。 - 通过从 y 中减去 24 来将一个砖块堆叠在另一个上面。 - “A x B 砖块”其较长轴沿 +X。因此，2x4 砖块为 80 LDU（X）× 40 LDU（Z）× 24 LDU 高。 旋转是 **命名** 的，而不是矩阵：`identity`，`rot90y`，`rot180y`，`rot270y`，`rot90x`，`rot90z`。 --- ## 分组工具 共 55 种工具。**LLM 构建时的推荐优先级**：高级助手 → 连接保证放置（`find_valid_placements` + `add_part_at_placement`，`place_on_top`）→ 仅在调试回退时使用原始 `add_part`。每个调用都显示 **最有用的参数**；完整的签名在工具文档字符串中。 ### 模型状态 | 工具 | 功能 | |---|---| | `create_model(name, include_manual=True)` | 重置为全新空模型。结果包含 `getting_started` - 构建手册（坐标，连接规则，工作流程，工具顺序）- 以便 LLM 在构建开始时获取规则。同一手册作为 MCP 服务器 `instructions` 在连接时提供。 | | `list_parts(limit, subassembly)` | 列出当前零件（可选过滤到一个子组件）。 | | `bill_of_materials(subassembly, bricklink=False)` | 可订购的零件列表：每个（part_id，color）的数量，带有零件 + 颜色名称，按需求量排序。`bricklink=True` 还返回一个 BrickLink Wanted List XML（`bricklink_xml`），您可以上传它来订购；颜色如果没有经过验证的 BrickLink 映射，将在 `bricklink_warnings` 中标记，而不是猜测。 | ### 放置（原始） | 工具 | 功能 | |---|---| | `add_part(part_id, color, x, y, z, rotation, strict=False)` | 显式放置。`strict=True` 在插入时拒绝重叠和未连接的放置。结果包含 `connectivity`（已连接的零件，螺柱接合， grounded）+ `warnings`。 | | `remove_part(instance_id)` | 按 ID 删除。 | | `move_part(instance_id, x, y, z)` | 重新定位。报告新位置的连接性。 | | `rotate_part(instance_id, rotation)` | 更改方向。报告新方向的连接性。 | ### 高级助手（首选） 这些编码了真正的乐高砌筑/建筑技术，以便 LLM 不必手动计算交错/角落/缝合。默认严格网格；拒绝离网坐标。  *`build_wall_segment(..., bond="running")` - 每一行的缝隙与下面一行偏移半个砖块。* | 工具 | 功能 | |---|---| | `build_wall_segment(x0, z0, x1, z1, height_rows, color, bond, base_y, palette)` | 带有 `running` / `stretcher` / `stack` 键合的直线墙。端部填充较短的砖块；跟踪缝隙以避免相邻行共享缝隙。 | | `build_room(x_min, z_min, x_max, z_max, height_rows, color, bond, base_y)` | 矩形空心房间。4 个交错墙 + 2x2 角柱。 | | `build_perimeter(points, height_rows, color, bond, base_y)` | 封闭正交轮廓（任意平面矩形）。每行交替角落所有权。 | | `build_wall_with_openings(x0, z0, x1, z1, height_rows, color, openings=[...])` | 带有矩形 / 圆拱 / 尖拱开口的直线墙。 | | `build_stepped_gable_roof(...)` / `build_stepped_pyramid_roof(...)` | 连接感知屋顶。 | | `build_floor(x_min, z_min, x_max, z_max, y, color, part_id)` | 用板铺设矩形区域。 | | `build_corner(x, z, height_rows, color, brick_part)` | 单角柱（用于手工搭建的房间）。 | | `place_on_top(base_id, new_part_id, color, stud_offset_x, stud_offset_z, rotation)` | 从已知锚点进行螺柱网格堆叠。 | | `place_next_to(reference_id, new_part_id, color, side, stud_offset, rotation)` | 冲放置（在现有零件的北部/南部/东部/西部）。 | | `repeat_pattern(part_id, count, dx, dy, dz, ...)` | 沿直线排列相同零件的阵列。 | ### 目录和搜索 | 工具 | 功能 | |---|---| | `search_parts(query, limit=20)` | 24k 目录的关键词搜索。 AND-of-tokens；使用单个具体词语（“arch”，“wheel”，“window”）。 | | `get_part_info(part_id)` | 尺寸，螺柱数，`bbox_local`，并且对于斜坡，一个 `orientation` 块（`high_edge`，`low_edge`，纯文本摘要），这样您不必在旋转后猜测。 | | `list_colors()` | 22 种命名颜色 + LDraw ID。 | | `parts_that_mount_on(part_id, limit=20)` | **反向** 安装搜索。基于足迹的索引，涵盖整个目录；第一次调用会构建索引（~1s），然后查询时间约为 ~ms。 | ### 连接 | 工具 | 功能 | |---|---| | `find_connections(a, b, full_nesting_only=False, min_studs_matched=1)` | B 在 A 上和 A 在 B 上的所有有效放置。 | | `find_valid_placements(part_id, near_part_id, limit=20)` | 与现有实例真正连接的世界坐标放置 - 在顶部 **和悬挂在下方**，预先过滤以防止与模型其余部分的碰撞，按螺柱匹配排序。每个条目都带有 `token`。 | | `add_part_at_placement(token, color)` | 在 `find_valid_placements` 结果处放置零件 - 严格检查，零坐标数学。这是附加单个零件的首选方法。 | | `suggest_next_brick_for_wall(subassembly)` | 启发式下一砖建议（第 1 阶段存根）。 | ### 子组件 | 工具 | 功能 | |---|---| | `set_current_subassembly(name)` | 用组名标记后续添加的内容。 | | `list_subassemblies()` | 名称 + 计数。 | | `remove_subassembly(name)` | 删除具有该标签的所有零件。 | | `clone_subassembly(src, dst, x_offset, y_offset, z_offset)` | 复制已构建的组件。 | | `mirror_subassembly(src, dst, axis, plane_offset)` | 双侧对称 - 建造一半大教堂，镜像它。 | | `analyze_assembly_ports(subassembly)` | 已构建模块上的暴露螺柱/接收器。 | | `find_subassembly_connections(movable, target)` | 一个模块可以连接到另一个模块的位置。 | | `move_subassembly(name, dx, dy, dz)` | 平移整个组。 | ### 验证和调试 | 工具 | 功能 | |---|---| | `validate_model(max_errors=200, check_support=True)` | 9 项报告：零件，连接，冲突，未知零件，浮动，未锚定，网格对齐错误，垂直缝评分，墙体键质量。错误包括 `suggestion` 字符串。 | | `inspect_part(instance_id, neighbor_studs=2)` | 集中式诊断用于一个零件：位置，AABB，旋转，子组件，验证标志，它与哪些零件冲突（带有重叠区域和最小分离距离），它连接到了哪些零件，附近的零件在 XZ 方向上。 | | `collision_detail(part_a, part_b)` | 对于标记的配对：重叠 AABB，体积，每个轴的最小分离平移距离，一行“将零件 X 按 Y LDU 移到 Z 以清除”建议。 | | `describe_errors(max_errors=10)` | 将每个 `validate_model` 错误与一次往返 `inspect_part` / `collision_detail` 上下文丰富化。 | ### 渲染 所有四个返回 `[markdown_preview, summary_dict, MCPImage]` - 人类看到内联图像，LLM 通过其视觉通道看到图像。 | 工具 | 功能 | |---|---| | `render_model(width=800, height=600, color_mode="model", hidden_edges=True)` | 等距 PNG。`color_mode`：\"model\"（实际颜色），\"instance\"（每个件一个颜色，用于调试），\"row\"（按砖块课程着色），\"rotation\"（按方向着色）。 | | `render_progress(width, height, color_mode, hidden_edges)` | 建造模式渲染：已构建零件为实心，未构建零件为幽灵。 | | `render_validation(width=900, height=700)` | 按验证状态对每个零件进行颜色编码：**绿色** = 确定，**红色** = 碰撞，**橙色** = 浮动，**紫色** = 未锚定，**黄色** = 离网，**灰色** = 未知 part_id。一次性\"哪里有问题？\"视图。 | | `view_latest_render()` | 重新显示最近的渲染结果而无需重新渲染。 |  *`build_room` 上干净的 `render_validation`：每个零件都是绿色 - 没有冲突，没有浮动，没有离网。当出现问题时，相关零件会更改颜色（**红色** = 碰撞，**橙色** = 浮动，**紫色** = 未锚定，**黄色** = 离网，**灰色** = 未知 part_id），以便您一眼就能发现问题。* #### 压力测试：导入9,361个零件的星际驱逐舰 `import_ldr("10030-1.mpd")` 接着是 `render_model(...)` 对 **帝国星际驱逐舰（套装10030）** — 9,361个零件，跨135个子模块，其中约7,290个带有非规范旋转矩阵（倾斜的船体板）。导入：**0.09秒**。  *✨ **当前渲染器。** 读取每个`.dat`文件中的真实三角形/四边形几何体并直接投影。桥式上层建筑、后部的三个引擎排气环、天线碟——所有形状都真实呈现。与`import_ldr`使用的相同解析/转换管道，只是连接到目录的实际网格数据。* <details> <summary>早期渲染器草稿，因其趣味性而保留</summary>  *🪨 渲染器的第一版将每个零件绘制为其世界空间边界长方体。轮廓和比例正确——每个零件都正确定位和旋转，你可以清楚地看到加载器正确地遍历了135个子模块的层次结构——但斜坡、曲线和引擎细节都变成了块状的灰色方块。在调试加载器/转换管道时很有用。它看起来像一个Minecraft星际驱逐舰。* </details> > 构建模式尚未训练到可以设计如此复杂的东西——用于greebling、翼板面板边界和曲面技术等的语义工具是未来工作。但 **导入 + 渲染路径在这种规模下仍然成立**：你可以加载任何OMR模型，检查它，运行验证，并开始逐步构建。 > > LDraw模型 © Roland Dahl ([rolandd 在LDraw OMR](https://library.ldraw.org/omr/sets/308))，可根据 [CCAL 2.0](https://www.ldraw.org/article/398.html) 重新分发。从 [library.ldraw.org/library/omr/10030-1.mpd](https://library.ldraw.org/library/omr/10030-1.mpd) 下载。帝国星际驱逐舰是卢卡斯电影公司 / 华特迪士尼公司的商标。 ### 持久性：检查点 / 项目 / 自动保存 三个层次 — 选择合适的： | 层次 | 工具 | 使用场景 | |---|---|---| | **检查点** （内存中，瞬间） | `save_checkpoint(name)` / `restore_checkpoint(name)` / `list_checkpoints()` | 在进行风险较高的更改之前。重启后丢失。 | | **项目** （磁盘上，命名） | `save_project(name)` / `load_project(name)` / `list_projects()` | 您想要保留的有意义的中间结果。多块MPD + JSON注释。重启后存活。 | | **自动保存** （自动） | `autosave_status()` / `restore_autosave()` | 每25次突变，模型被转储到 `_autosave.mpd`。崩溃后，调用 `restore_autosave()` 以继续之前的工作。 | ### 构建模式 逐一遍历已完成的模型（供人类或机器人物理组装）。  *`render_progress()` 构建中：目标室的底部一行已放置（实红色），其余目标显示为淡化的幽灵状态，以便您了解还有哪些部分需要构建。* | 工具 | 功能 | |---|---| | `start_builder_session()` | 快照成为目标；构建集被清除。此后，新的 `add_part` 调用会添加到目标中，而不是构建。 | | `end_builder_session(mark_all_built=True)` | 退出构建模式。 | | `builder_status()` | 快速快照：总件数 / 已构建件数 / 剩余件数 / 下一件 / 阻塞计数 / 完成？ | | `next_unbuilt_step(limit=1)` | 下一个可放置的未构建零件（仅将已构建零件视为支撑）。 | | `mark_built(id)` / `mark_built_batch(ids)` / `unmark_built(id)` / `reset_build_progress()` | 向前 / 向后 / 重新开始。 | | `plan_build_sequence(subassembly, max_steps=50, start_after=0)` | 编译整个目标到分页步骤列表。 | | `next_build_step(subassembly, built_count=0)` | 与上述相同，但每次调用（与 `plan_build_sequence` 兼容）。 | | `render_progress()` | 在一个图像中查看已构建 + 未构建。 | ### 注释（多模态上下文） 适用于克劳德正在阅读计划/照片并需要记住跨多个回合的尺寸的工作流。 | 工具 | 功能 | |---|---| | `add_note(key, text)` / `get_note(key)` / `list_notes()` / `remove_note(key)` | 键控的粘性观察。注释随项目一起保存（由 `save_project` 保存）。 | ### 导入/导出 | 工具 | 功能 | |---|---| | `export_ldr(path)` / `export_mpd(path)` | 写入磁盘。相对路径位于渲染目录（因此它在克劳德桌面版的只读 cwd 下有效）。 | | `import_ldr(path)` | 加载 `.ldr` 或 `.mpd` 文件。多块 MPD 被展平，子组件标签保留。 | ### 撤销/重做 | 工具 | 功能 | |---|---| | `undo()` / `redo()` | O(1) 基于操作的。最近 500 次突变。 | --- ## 提示（斜线菜单） 从克劳德桌面的 `/` 菜单中调用。每个提示都用正确的上下文初始化对话。 | 提示 | 功能 | |---|---| | **`start`** | 在新会话中首先打开此页面。完整的一页参考：每个工具、构建/验证/渲染循环、三个保存层、构建模式。 | | **`build`** *(目标，比例)* | 带有工作流 + 技术的通用“构建 X”提示。 | | **`from_plans`** *(主题)* | 多模态大教堂式构建：上传计划、分解为子组件、构建一半 + 镜像。 | | **`from_image`** | 从上传的参考照片构建。 | | **`rescue`** *(路径)* | 加载现有模型，清理，修复冲突。 | | **`techniques`** | 打印乐高技术备忘录（运行/英语绑定、SNOT、MILS等）。 | ## 资源 只读参考LLM可以通过`resources/read`获取。 | URI | 内容 | |---|---| | `lego://techniques` | 乐高搭建技术备忘录 | | `lego://coords` | LDraw坐标约定参考 | | `lego://workflow` | 构建/验证/渲染循环 | | `lego://connections` | 乐高积木连接规则——`floating`/`unanchored`背后的规则 | | `lego://model/current` | 当前模型的实时状态（JSON） | --- ## 作为独立代理运行（无克劳德桌面） ```bash uv sync --extra agent export ANTHROPIC_API_KEY=sk-ant-... uv run python -m lego_mcp.agent "给我搭建一个16x12的乐高房间，5块高" ``` 代理启动 `lego-mcp` 作为子进程，通过MCP JSON-RPC获取工具列表，将工具交给克劳德，通过Anthropic SDK，并循环直到克劳德停止调用工具。最终模型导出到 `./agent_build.mpd` 并渲染。 --- ## 独立CLI 三个一键命令，适用于 `.ldr` / `.mpd` 文件在shell中——无需MCP服务器，无需克劳德桌面： - `lego-mcp render <file>` — 渲染为PNG（如下）。 - `lego-mcp bom <file>` — 可订购的零件清单（如下）。 - `lego-mcp instructions <file>` — 分步搭建顺序（如下）。 ### `lego-mcp render` 在shell中渲染 `.ldr` / `.mpd` 文件时使用——预览OMR下载、批量渲染网站、生成旋转动画或简单检查发送的模型——无需启动MCP服务器或打开克劳德桌面。 ```bash lego-mcp render path/to/model.mpd # 在输入旁边写入 model.png lego-mcp render model.mpd -o /tmp/out.png -w 1600 -H 1100 # 显式输出 + 尺寸 lego-mcp render model.mpd --color-mode instance # 每个零件一种颜色（调试） lego-mcp render model.mpd --hidden-edges # 显示内部接触面为虚线 lego-mcp render model.mpd --view-angle 90 # 摄像头绕Y轴90° lego-mcp render model.mpd --turntable 24 # 24帧扫描360° → model_000.png … model_023.png lego-mcp render model.mpd --background "#0a0a0a" # 黑色背景 lego-mcp render model.mpd \ --watermark "ACME © 2026" \ --watermark-position bottom-right \ --watermark-color "#ffffff" \ --watermark-opacity 200 lego-mcp render --help # 完整帮助 ``` 所有标志： | 标志 | 默认值 | 功能 | |---|---|---| | `<input>` *(位置参数)* | — | `.ldr` 或 `.mpd` 文件的路径。 | | `-o, --output PATH` | `<input-stem>.png` 在输入旁边 | 输出PNG路径。 | | `-w, --width N` | `1200` | 像素宽度。 | | `-H, --height N` | `900` | 像素高度。（`--h` 保留用于帮助。） | | `--color-mode {model,instance,row,rotation}` | `model` | `model` = 实际颜色；`instance` = 每个零件一种颜色；`row` = 按砖块课程颜色；`rotation` = 按方向颜色。 | | `--hidden-edges` | 关闭 | 将完全覆盖的接触面绘制为虚线引导线。 | | `--view-angle DEG` | `0` | 摄像头方位角（绕Y轴旋转），俯仰角恒定。 **使用90的倍数进行展示渲染** — 它们显示其他角落的相同经典等距视图。接近 `45/135/225/315` 的角度使模型几乎正面面对， 而正交面正面视图没有水平深度偏移，因此看起来像平面/剪切（正确，但对眼睛刺激）。 | | `--turntable N` | — | 而不是一张图片，写入 **N帧** 扫描360°。每个帧到 `<stem>_NNN.png`。覆盖 `--view-angle`。 | | `--background #RRGGBB` | `#f5f5f8` | 图片背景颜色。接受 `#fff` 简写。 | | `--watermark TEXT` | — | 在渲染的图片上叠加文本。 | | `--watermark-position {top-left,top-right,bottom-left,bottom-right}` | `bottom-right` | 在哪里绘制水印。 | | `--watermark-color #RRGGBB` | `#282828` | 水印文本颜色。 | | `--watermark-opacity N` | `140` | 水印alpha（0透明..255不透明）。 | | `--watermark-size N` | `18` | 水印字体大小（像素）。 | | `--watermark-margin N` | `14` | 水印与图片边缘的距离（像素）。 | | `-q, --quiet` | 关闭 | 在stdout上抑制进度行。 | 当可用的TTF字体时，水印使用TTF字体（按顺序探测Helvetica / Arial / DejaVu），在最小系统上回落到PIL的位图默认值，因此它永远不会硬失败。 ### `lego-mcp bom` — 您需要的零件 汇总模型为可订购的零件清单：每行一个 `(part_id, color)`，按需求量从多到少排序，并附有零件总数。 与 `bill_of_materials` MCP工具在聊天中返回的数据相同。 ```bash lego-mcp bom model.ldr # 人类可读表格（默认） lego-mcp bom model.ldr -f csv -o parts.csv # 电子表格 lego-mcp bom model.ldr -f json # 结构化（脚本） lego-mcp bom model.ldr -f bricklink -o wanted.xml # BrickLink Wanted List 上传并订购 ``` | 标志 | 默认值 | 功能 | |---|---|---| | `<input>` *(位置参数)* | — | `.ldr` / `.mpd` 文件的路径。 | | `-f, --format {table,csv,json,bricklink}` | `table` | 输出格式。 `bricklink` 编写一个Wanted List XML，您可以上传到 bricklink.com。 | | `-o, --output FILE` | stdout | 写入文件而不是打印。 | > BrickLink导出映射其可以验证的颜色并 **将其他颜色标记为警告** （打印到stderr，并在XML中作为注释留下）——而不是猜测错误的颜色ID——因此请仔细检查任何标记的批次后再订购。 ### `lego-mcp instructions` — 分步搭建顺序 编译完成的模型为支持尊重的装配顺序：基板和地面零件优先，然后每个零件都有一个放置位置。 ```bash lego-mcp instructions model.ldr # 完整的编号搭建顺序 lego-mcp instructions model.ldr --max 20 # 前20步 lego-mcp instructions model.ldr --start 20 --max 20 # 下一页 lego-mcp instructions model.ldr --json # 完整的步骤有效载荷（位置，支持） ``` ### 一行命令 ```bash # 为带有标签线的模型生成英雄图像 lego-mcp render hero.mpd -o hero.png -w 1920 -H 1080 \ --watermark "Built with LegoMCP" --watermark-opacity 90 # 比较两种颜色模式并排（重新运行并使用不同的 --color-mode） lego-mcp render m.mpd -o m_model.png --color-mode model lego-mcp render m.mpd -o m_instance.png --color-mode instance # 为动画生成36帧旋转动画 lego-mcp render m.mpd --turntable 36 -o /tmp/spin.png # → /tmp/spin_000.png … /tmp/spin_035.png — 喂给ffmpeg / GIF工具 ``` --- ## 开发 ```bash uv sync --extra dev --extra agent uv run pytest # 128个测试，包括真正的MCP stdio握手 ``` 架构和决策位于 [NOTES.md](NOTES.md)。 ### 项目布局 ``` src/lego_mcp/ ├── server.py # FastMCP 工具 + 状态 + 工具调度 ├── parts.py # LDraw .dat 解析器 + 目录 + 索引缓存 ├── render.py # 内置等距渲染器 + 桩 + 子面 ├── helpers.py # build_wall / build_room / build_floor / place_on_top / ... ├── connections.py # 桩-受体配合组合数学 ├── connection_graph.py # 通过BFS检测浮动 + 未锚定 ├── mount_index.py # 反向安装搜索（基于足迹桶） ├── connectors.py # 类型连接器模型（第1阶段：仅桩） ├── assembly_ports.py # 模块级暴露端口分析 ├── build_steps.py # 构建序列（完整 + 目标部分） ├── prompts.py # 6个提示 + 4个资源 ├── agent.py # 独立克劳德驱动代理 └── __main__.py # `lego-mcp` CLI：服务器 / 安装库 / --help tests/ # 128个测试，pytest ``` --- ## 已知限制 - **坡面渲染器是AABB.** 斜坡绘制为长方体。 使用 `get_part_info(slope_id)` 的 `orientation` 块来推理斜坡方向——这是更大的推理胜利。 真正的楔形几何体是一个计划中的后续工作。 - **非规范旋转零件绘制为定向长方体** — 矩阵保留，盒子正确旋转，但这些零件不参与桩-交配连接分析（网格仅在轴对齐时才有意义）。 对于导入显示足够好，针对新构造故意限制。 - **搜索是关键词-AND.** “vehicle base car chassis” 返回 0；“chassis” 单独返回很多。 解决方法：使用单个具体单词。 语义搜索正在路线图上。 - **连接模型仅限于桩.** 销钉 / 铰链 / 轴 / 夹子需要 `!LDCAD CONN` 解析（LDCad扩展LDraw元数据）。 第二阶段。 - **`mount_index` 排名基于足迹天真.** 通常为小目标表面miniFig-leg变体，因为它们恰好共享足迹。 “kind=”过滤器（brick/plate/tile vs accessory）会有帮助。 - **无物理.** 结构上不健全的模型在几何上连接仍然通过验证。 查看 [NOTES.md](NOTES.md) 完整的决策日志 + 延迟项。 --- ## 许可证 MIT. 查看 [LICENSE](LICENSE).