MCP CAD Studio

MCP CAD Studio

一款独立的参数化 CAD 工作区，以 MCP 服务和交互式 MCP App 的形式提供。Agent 可以通过工具创建和编辑模型；用户则可以在实时 3D 工作室中操作相同的模型，该工作室可在任何兼容的宿主中渲染。

功能

• 通过 studio_ui 工具渲染完整的 3D 编辑器。
• 创建方块、球体、圆柱体、圆锥体、多边形拉伸体、导入的网格、变换，以及嵌套的并集／差集／交集树。
• 生成可编辑的支架、管道、齿轮、外壳和螺栓。
• 通过乐观修订检查，加载、修补、重新生成和删除持久化模型文档。
• 在拉伸轮廓和原始网格到达 CAD 内核之前进行预检，并提供可操作的拓扑诊断。
• 导入 ASCII／二进制 STL 和 OBJ；导出 ASCII STL 和 OBJ。
• 让已打开的应用与由模型发起的 MCP 工具调用保持同步。
• 支持通过 stdio 或 Streamable HTTP 运行，并直接支持 HTTPS。
• 使用内置的 WebAssembly CAD 内核——无需安装 OpenSCAD、Python、编译器、Docker 或原生 CAD 软件。

服务端的数据工具独立于 UI。无法渲染 MCP Apps 的客户端仍可执行所有 CAD 操作，并接收结构化的模型／网格数据。

安装

唯一的运行时要求是 Node.js 20 或更高版本。CAD 引擎和所有 JavaScript 依赖项都会随软件包一并安装。

运行已发布的 npm 软件包：

npx -y mcp-cad-studio --stdio

或克隆并构建：

git clone https://github.com/flujo-app/mcp-cad-studio.git
cd mcp-cad-studio
npm install
npm run build
npm start -- --stdio

MCP 客户端配置（stdio）

{
  "mcpServers": {
    "cad-studio": {
      "command": "npx",
      "args": ["-y", "mcp-cad-studio", "--stdio"]
    }
  }
}

默认情况下，模型会持久化到 ~/.mcp-cad-studio/models.json。使用 --data-file <path> 可选择其他文件，或使用 --no-persist 创建内存会话。

HTTPS／Streamable HTTP

使用生成的自签名证书运行本地 HTTPS 端点：

mcp-cad-studio --transport https --host 127.0.0.1 --port 8787

对于可远程访问的生产环境服务，请使用受信任的证书：

mcp-cad-studio --transport https \
  --host 0.0.0.0 \
  --port 8787 \
  --tls-cert /run/secrets/fullchain.pem \
  --tls-key /run/secrets/privkey.pem

MCP 端点为 /mcp；只读健康检查端点为 /health。也支持在反向代理处终止 TLS——在代理后方使用 --transport http 运行。

MCP 工具

工具	用途
studio_ui	打开交互式 MCP App，并可选择一个模型
list_models	列出已保存的模型和修订版本
load_model	加载参数化文档及其渲染网格
create_model	根据声明式形状树创建模型
generate_model	创建模板模型，或通过 modelId 就地重新生成模型
update_model	就地修补或替换模型的定义、名称或颜色
validate_shape	在不保存的情况下预检形状
transform_model	应用增量平移、旋转或缩放
boolean_models	将已保存的模型合并、相减或相交，生成新模型
duplicate_model	创建可编辑的副本
delete_model	永久删除模型
import_model	导入 STL／OBJ 文本或 base64 数据
export_model	导出 ASCII STL／OBJ 数据

所有变更操作的结果都会在 structuredContent 中包含 models、activeModel 和 mesh，因此 UI 和模型看到的是相同的规范状态。只有确实需要创建独立模型时才应创建新模型。要创建修订版本，请先调用 load_model，然后将返回的 modelId 和 revision 作为 expectedRevision 传递给 update_model、generate_model 或 delete_model。

更新而不创建副本

update_model 会保留模型 ID，并支持完整替换 shape，也支持小型 RFC 6901 JSON-Pointer 风格补丁。以下示例无需重新发送盒子的完整定义，即可修改已保存盒子的 X 尺寸：

{
  "modelId": "5e44fd24-b7df-450a-a7bb-31c95496832f",
  "expectedRevision": 3,
  "patches": [
    { "op": "replace", "path": "/shape/size/0", "value": 80 }
  ]
}

补丁可以针对 /shape、/name 或 /color，并按顺序应用。支持 add、replace 和 remove。完成后的定义会经过架构和几何检查，然后才会修改已保存的模型。

对于模板级编辑，例如更改齿轮的齿数，请使用现有的 modelId 和 expectedRevision 调用 generate_model。模板会在同一文档中重新生成，而不会创建另一个模型。

参数化模型格式

create_model 和 update_model 接受递归形状树。例如，带有圆柱形孔洞的板：

{
  "name": "Mounting plate",
  "color": "#60a5fa",
  "shape": {
    "kind": "difference",
    "children": [
      { "kind": "box", "size": [80, 50, 6], "center": true },
      {
        "kind": "cylinder",
        "height": 8,
        "radius": 5,
        "segments": 48,
        "center": true
      }
    ]
  }
}

每个节点都可以包含变换：

{
  "transform": {
    "translation": [10, 0, 4],
    "rotation": [0, 0, 45],
    "scale": [1, 1, 1]
  }
}

旋转使用角度制。内核中的尺寸不限定单位；工作室会将其标记为毫米。

形状对象采用严格校验：拼写错误或不受支持的字段会报错，而不会被静默忽略。validate_shape 无需保存即可检查草稿，并报告 JSON 路径、错误代码和建议的修复方法。检查包括：

• 重复、零长度、零面积和自相交的拉伸轮廓；
• 不完整或超出范围的网格数组，以及退化三角形；
• 开放边界、被过多面共享的边、绕序不一致，以及顶点处不连通的曲面扇；
• 形状树和扭曲拉伸的复杂度限制；
• 由 Manifold CAD 内核进行最终验证。

如果内核仍然拒绝某个形状，其状态会被转换为针对非有限顶点、非流形几何、无效构造、结果超大以及其他内核状态类别的指导信息。

架构

flowchart LR
  A[Agent or person] --> H[MCP host]
  H <-->|stdio or Streamable HTTP/S| S[MCP CAD Studio server]
  H <-->|MCP Apps JSON-RPC bridge| U[Interactive CAD app]
  U -->|tools/call| H
  S --> P[Persistent parametric documents]
  S --> K[Bundled Manifold WebAssembly kernel]
  K --> M[Render mesh and STL/OBJ]
  M --> S

studio_ui 工具通过 _meta.ui.resourceUri 链接到 ui://cad-studio/studio.html。该组件使用稳定的 MCP Apps 桥接机制（ui/initialize、ui/notifications/* 和 tools/call），而不要求使用特定宿主的全局变量。模型轮询会感知版本，因此外部工具所做的编辑也会显示在已打开的编辑器中。

开发

npm install
npm run check

npm run check 会执行严格的 TypeScript 检查、16 项内核／存储／协议／传输测试，以及生产构建。测试套件使用真实的 WebAssembly 几何引擎，以及内存和 Streamable HTTP MCP 客户端。

常用命令：

npm run dev       # HTTP development server on port 8787
npm test          # Vitest suite
npm run typecheck # TypeScript only
npm run build     # bundle the MCP App and server
npm pack          # verify the single-package artifact

将当前版本发布到 npm：

npm run release

发布命令会在需要时通过 npm 登录，运行完整的检查套件，公开发布包，并确认 npm 已提供该版本。可以安全地重复运行：如果该确切版本已经发布，命令会验证项目并跳过重复发布。

运行 npm run release:check 可在不发布的情况下验证发布辅助程序。

安全说明

• 工具架构会限制形状深度、节点数、网格大小和导入文件大小。
• 修改工具会准确声明只读／破坏性／开放世界提示。
• expectedRevision 可防止并发编辑期间意外覆盖和删除过期内容。
• 补丁路径仅限可编辑的模型字段，并会拒绝原型遍历。
• 应用资源声明了空的外部资源／连接 CSP。
• 生成的自签名证书仅供本地开发使用。
• 身份验证因部署方式而异。请将远程多用户实例置于经过身份验证的网关之后，并在那里实施按用户授权。

许可证

MIT