Vibe CAD

AI-native conversational CAD — an open-source MCP connector for FreeCAD (chat-native, zero-install).

AI 对话式 CAD —— FreeCAD MCP 连接器（Chat-native 零安装）

给一年只设计几次东西的人：免费的 FreeCAD + 一个让你永远不用学 FreeCAD 的 AI。 在任意 MCP 客户端（Claude Desktop / Cowork / OpenClaw / Cursor…）中，用自然语言完成 中等复杂度的参数化设计与多零件装配，交付可制造文件（3D 打印 3MF/STL、CNC STEP、激光 DXF）。

状态：R1 运行时 → R2 语义建模 → R3 视觉反馈 → R4 位置控制 → R5 可指代性 → R6a 工程图+每步回图 → R6b 参数修改 → R7 阵列/拉伸/重定位 → R8 装配 DSL（多零件/贴面对齐/干涉守卫）——已全部本机实跑验证。设计文档见 docs/superpowers/specs/2026-06-08-vibecad-design.md。

快速开始（用户）

Claude Desktop / Cowork（推荐）：去 Releases 最新版 下载 VibeCAD.mcpb，双击安装——Claude Desktop 弹出安装窗口后点安装即可，零终端、零配置文件、无需预装 uv/Python（宿主自动准备隔离 Python 环境）。装好后对 AI 说"帮我准备好 CAD 环境"即可。逐步图文教程见 用户手册。

其他客户端（Claude Code / Cursor 等）走 stdio 方式：装好 uv 后 claude mcp add --transport stdio vibecad -- uvx vibecad（已发布 PyPI），详见用户手册附录 A。

首发形态：Chat-native 零安装

用户无需安装 FreeCAD —— MCP server 首次运行自动拉取无头 FreeCAD 运行时（micromamba）， 每步回传文本诊断 + 软渲染图 + 可旋转 glTF 交互预览。装 FreeCAD 解锁 Live 模式是升级而非门槛。

架构（方案 B：进程内自建）

• MCP 框架：Python 官方 MCP SDK（FastMCP），stdio 起步
• 几何引擎：conda-forge FreeCAD 1.1+ 进程内 import
• 运行时分发：micromamba 自动安装（全平台矩阵）
• 工具面：纯语义工具（add_hole/fillet_edges/assemble/fasten），每工具事务 + 几何断言 + 规则检查
• 反馈三级：glTF artifact（主）/ 软渲染图 / 纯文本诊断

开发

uv sync            # 安装 server 依赖（不含 FreeCAD）
uv run vibecad     # 启动 MCP server（stdio，先跑纯 stdlib launcher）
uv run pytest      # 跑单元测试（slow 集成测试默认跳过）
uv run ruff check  # 静态检查

FreeCAD 运行时（首次使用）

server 启动即可握手；FreeCAD 运行时（约 2-3GB）按需后台获取，不阻塞握手：

1. 调用 ensure_runtime —— 未就绪则后台开始安装（micromamba → conda env python=3.12 freecad=1.1.0 → pip 装 server → 冒烟），立即返回 started。
2. 轮询 get_runtime_status 至 phase=ready；若返回 needs_reconnect=true，表示运行时已就绪但当前会话仍在引导解释器，请重连本 MCP server。
3. 重连后调用 smoke_cad —— 进程内造 10×10×10 Box、导出 STEP，返回体积/包围盒（证 A1/A3）。

环境变量：

• VIBECAD_HOME —— 运行时落盘根目录（默认平台数据目录）
• VIBECAD_AUTO_INSTALL=1 —— server 启动即自动后台安装（默认需显式 ensure_runtime）
• VIBECAD_FREECAD_ENV=<conda env 路径> —— 复用现成的 FreeCAD env（只校验不自建）
• VIBECAD_PIP_SPEC=<本地源/包名> —— 预发布期指向本地仓库源
• 集成测试：VIBECAD_RUN_INTEGRATION=1 uv run pytest -m slow（真实下载 2-3GB）

陈旧安装锁：若安装异常中断，手动删除 <VIBECAD_HOME>/.install.lock。 FreeCAD 运行时由 vibecad.runtime（D4）按需获取，与本 venv 隔离。

语义建模工具（Round 2）

运行时就绪并重连后，用以下语义工具完成「自然语言 → 参数化单零件 → 可制造文件」：

每个工具 = 参数校验 → 文档事务 → 参数化对象 → recompute → 几何断言（recompute() 返回值不可信，几何断言是唯一可信成功判据）→ 结构化返回。所有工具守卫「运行时就绪 + 已重连进 conda 解释器」。

开发态集成测试复用持久 FreeCAD env：VIBECAD_RUN_INTEGRATION=1 uv run pytest -m slow（首次自动装到 .vibecad-test-runtime/，约 4 分钟，后续秒进）。

视觉反馈（Round 3）

• render_part 回传 PNG 软渲染图（matplotlib Agg，无 GPU），作为 MCP ImageContent 在 Claude Desktop 等客户端内联可见——用户据此迭代式画图。
• export_part(fmt="gltf"/"all") 导出 glTF（.glb）工件（逐面 primitive + 面级 extras），供未来会渲 glTF 的 App/客户端交互旋转拾取。
• 注：当前为 MVP 级渲染（看清形状/朝向/比例，非照片级）；FreeCADGui 高质量离屏渲染留后续。

可指代性：标注图 + 标签注册表（Round 5）

没有鼠标拾取的对话式 CAD，靠标注渲染图让用户精确指代几何：

• render_part(annotate="faces") → 图上可见面贴 A/B/C 标签 + 包围盒尺寸线；同时返回标签表（{"A": "顶面·平面 面积1200mm² …"}）给 AI 读——用户说"顶面打孔"，AI 翻译成 add_hole(face="A")；不可见面注明在哪个视角可见（或"请直接用描述指代"）。
• render_part(annotate="edges") → 边标 E1/E2…（背面边虚线+表注），供 fillet_edges/chamfer_edges 指边。
• 标签过期保护（指纹校验）：FreeCAD 的面/边索引在布尔后会重排——每次标注存几何指纹快照，特征工具执行前按指纹找回；几何已变对不上则响亮报"标签已过期，请重新标注"，绝不静默猜面。几何变更后的工具返回带 labels_stale: true 提示，引导刷新标注图。
• 事务回滚：任何特征失败（孔落空、OCCT 圆角失败、标签过期）都完整回滚，不残留垃圾对象。

工程图三视图与每步回图（Round 6a）

• 每次建模/特征指令成功后自动附一张工程图拼图（add_box/add_cylinder/boolean_cut/add_hole/fillet_edges/chamfer_edges 返回 [结果, 图]）——用户"说一句看一眼"，无需手动调渲染；标签表当场刷新（labels 字段），不再需要 stale 提示。
• 拼图 2×2：front/right/top 三格工程图（FreeCAD TechDraw HLR 隐藏线消除：可见轮廓实线、隐藏轮廓虚线、圆孔红色点划中心线 + ⌀ 标注 + 定位尺寸、各视图总尺寸从投影自动推导）+ iso 立体格（面片渲染 + 面标签 + L/W/H 尺寸线）。
• 附图失败不连坐：建模操作已成功提交时渲染异常只追加 render_error 字段，绝不把成功操作报成失败。
• 每步返回还带 parts 参数清单（{"Box": {"length": 40, …}, "HoleTool": {"radius": 4, …}}）——AI 随时知道当前可改参数，"孔改大到 ⌀10"一步翻译成 modify_part。

装配（Round 8）

• 多零件：new_part 开新零件，既有 22 个工具经"活动零件"模型零感知工作（含 set_active_part 切换）；单零件用户完全无变化。
• align_parts 面贴面：跨零件用面标签指代（"盖板底面贴到底板顶面"），gap 控制间隙；装配后自动干涉检查——零件重叠响亮报干涉量并回滚（allow_interference 显式豁免压配）。
• 守卫锚定被操作零件：孔完整性/密封探针/单实体断言按对象所属零件计算（操作非活动零件同样受全套保护）。
• 装配工程图：iso 格零件分色、被遮挡特征虚线；export_part(split=True) 按零件拆分 STEP。

文档

• 用户手册 —— 安装、Claude Cowork 配置、场景化用法、故障排查
• 验收测试方案 —— 12 个对话场景清单 + Windows 手动验证

License

MIT