内容
# CadQuery MCP — AI CAD Suite (分层路由器，80+ 操作，13 层)
[](https://docker.com)
[](https://modelcontextprotocol.io)
[](https://python.org)
[](https://cadquery.readthedocs.io)
一个 **Model Context Protocol (MCP)** 服务器，暴露了 [CadQuery](https://cadquery.readthedocs.io)、[trimesh](https://trimsh.org)、[gmsh](https://gmsh.info) 等的全部功能 — 通过一个 **精简的 3 工具路由接口**。与 AI 命名空间中 80 多个扁平工具不同，模型通过 `cad_help()` 发现功能，通过 `cad_run()` 执行任何操作，通过 `cad_manage()` 管理输出。
> **设计理念：** 模型的工具命名空间非常宝贵。该服务器将整个 CAD 套件压缩为 **3 个路由器工具**，跨越 **13 个功能层** — 每个层都是逻辑分组的操作集。
---
## 功能
- **80+ 参数化 CAD 操作**，跨越 13 个层 — 基本体素、草图、布尔运算、网格处理、有限元分析、计算机辅助制造、装配、格式转换等
- **3 路由器工具架构** — 模型调用 `cad_help()` → 发现 → 调用 `cad_run()`，并带有层 + 操作 + 参数
- **可流式传输的 HTTP 传输**，通过 `supergateway` — 长连接，带有健康检查
- **Docker-first** 部署 — 单个 `docker compose up -d` 命令即可启动一个完全隔离的 CAD 服务器
- **第 13 层：`templates`** — 现实世界的复用生成器（风扇罩、管道、支架、垫圈、支架网格）
- **多格式支持** — STEP、STL、OBJ、GLB、PLY、3MF、COLLADA、DXF、SVG、G-code、有限元网格格式（INP、CDB、BDF、VTU、XDMF）
- **参数化硬件库** — 螺栓、螺母、垫圈、轴承、工字梁、C 型槽钢、角钢、弹簧
- **STL 网格管道** — 导入、修复、简化、平滑、细分、切片、布尔运算、凸壳、体素化、曲率分析
- **CAM G-code 生成** — 轮廓、口袋、钻孔循环
- **有限元网格导出** — 通过 gmsh 进行四面体/六面体网格划分，通过 meshio 进行求解器格式导出
- **装配支持** — 多零件装配，带有约束，导出为 STEP/GLTF/VRML
- **CAD 分析** — 质量属性、边界框、表面积、射线交叉、符号距离、水密检查
---
## 架构：分层路由器
模型仅看到 **3 个工具** 在其命名空间中。所有 80+ 操作都位于这些路由器后面：
```
┌─ 模型的工具命名空间 ───────────────────────────────────────┐
│ │
│ cad_help(tier?) → 发现层 + 操作 │
│ cad_run(tier, op, params) → 执行任何 CAD 操作 │
│ cad_manage(action, file?) → 列出 / 删除 / 检查输出 │
│ │
│ (3 个工具 — 而不是 80+ 个扁平工具) │
└──────────────────────────────┬───────────────────────────────────┘
│
▼ (内部调度)
┌──────────────────────────────────────────────────────────────────┐
│ 13 个功能层 — 80+ 操作 │
│ │
│ primitive sketch_2d boolean_3d stl │
│ sketch_draw analysis mesh conversion │
│ assembly cam parts fem │
│ templates ← NEW! │
└──────────────────────────────────────────────────────────────────┘
```
### 为什么这很重要
- **保持模型的工具槽位计数低** — 对于具有严格工具预算的 LLM 来说至关重要
- **自我文档** — `cad_help()` 返回层描述 + 可用操作 + 示例用法
- **可扩展** — 添加新层不需要模型端更改（只需添加新的 TIERS 条目 + 处理程序）
- **类型安全参数调度** — 每个操作都验证其自己的参数，并带有清晰的错误消息
---
## 快速入门（Docker）
```bash
# 克隆或复制项目文件，然后：
docker compose up -d --build
# 验证它是否正在运行
curl http://localhost:8012/health
# → {"status":"ok"}
```
服务器在 `http://localhost:8012/mcp` 上监听，使用 [Streamable HTTP](https://spec.modelcontextprotocol.io/) 传输。
---
## 安装选项
### 选项 1：Docker（推荐）
```bash
docker compose up -d --build
```
所有依赖项（CadQuery、OpenCASCADE、trimesh、gmsh、meshio、pymeshlab、manifold3d 等）都预安装在容器中。输出文件通过绑定挂载保存在 [`./cad_output/`](./cad_output) 中。
### 选项 2：手动 pip（Ubuntu/Debian）
```bash
# CadQuery/OpenCASCADE 的系统依赖项
sudo apt-get install -y \
python3-dev build-essential pkg-config cmake \
libgl1-mesa-dev libglu1-mesa-dev libxrender-dev libxext-dev \
libxt-dev libxi-dev libsm-dev libglib2.0-0 libgomp1 \
libspatialindex-dev
# Python 包
pip install 'cadquery>=2.5' 'mcp>=1.0' 'trimesh[easy]>=4.0' \
manifold3d pymeshlab numpy-stl numpy scipy networkx shapely \
rtree sympy meshio gmsh ezdxf svg.path svgpathtools lxml \
pillow pycollada pygltflib ifcopenshell scikit-image
# Streamable HTTP 传输的 Supergateway
npm install -g supergateway
# 运行
supergateway --stdio "python cadquery_mcp.py" \
--outputTransport streamableHttp \
--streamableHttpPath /mcp --port 8012 --host 0.0.0.0 \
--cors --healthEndpoint /health
```
### 选项 3：Conda（通过 environment.yml）
```bash
conda env create -f environment.yml
conda activate base
# 然后安装选项 2 中列出的依赖项
```
> **注意：** [`environment.yml`](environment.yml) 是一个参考存根。所有实际依赖项都通过 [`Dockerfile`](Dockerfile) 中的 `pip` 安装。对于 conda，请手动安装上面的 pip 包。
---
## MCP 客户端配置
### Claude Desktop
编辑 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"cadquery": {
"type": "streamableHttp",
"url": "http://localhost:8012/mcp"
}
}
}
```
### VS Code（MCP 扩展）
```json
{
"mcp": {
"servers": {
"cadquery-mcp": {
"type": "streamableHttp",
"url": "http://localhost:8012/mcp"
}
}
}
}
```
### Cline / Roo Code
```json
{
"mcpServers": {
"cadquery-mcp": {
"type": "streamableHttp",
"url": "http://localhost:8012/mcp"
}
}
}
```
### 自定义 MCP 客户端（Python）
```python
import requests
MCP_URL = "http://localhost:8012/mcp"
# 发现层
response = requests.post(MCP_URL, json={
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "cad_help",
"arguments": {}
}
})
print(response.json())
# 创建一个盒子
response = requests.post(MCP_URL, json={
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "cad_run",
"arguments": {
"tier": "primitive",
"operation": "box",
"params": {"width": 50, "depth": 30, "height": 20},
"export_format": "both"
}
}
})
print(response.json())
```
---
## 工具参考
### 1. `cad_help(tier?)` — 发现功能
发现工具。调用时不带参数，列出所有 13 个层。调用时带有一个层名称，查看可用的操作及其描述。
| 调用 | 返回 |
|------|---------|
| `cad_help()` | 所有 13 个层，带有标签、描述和操作计数 |
| `cad_help("mesh")` | 网格处理层的操作 + 描述 |
| `cad_help("fem")` | 有限元层的操作 + 描述 |
| `cad_help("templates")` | 6 个现实世界模板生成器 |
### 2. `cad_run(tier, operation, params, export_format?)` — 执行 CAD 操作
执行路由器。参数：
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| `tier` | `string` | 层名称（例如 `"primitive"`、`"mesh"`、`"templates"`、`"fem"`） |
| `operation` | `string` | 层内的操作名称（例如 `"box"`、`"mesh_smooth"`、`"fan_shroud"`） |
| `params` | `dict` | 操作特定的参数（参见下面的层表） |
| `export_format` | `string` | 可选。`"step"`（默认）、`"stl"` 或 `"both"` |
### 3. `cad_manage(action, filename?)` — 文件管理
| 操作 | 参数 | 描述 |
|--------|-----------|-------------|
| `list` | 无 | 列出所有导出的 STEP、STL、OBJ、GLB、PLY、OFF、3MF、SVG、DXF、G-code 文件 |
| `delete` | `filename` | 从输出目录中删除文件 |
| `stl_info` | `filename` | 获取 STL 元数据（三角形计数、边界框、文件大小、头部注释） |
---
## 完整层参考 — 所有 13 个层，带有完整参数文档
### 层 1：`primitive` — 几何基元
从头开始创建基本的 3D 立体。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `box` | `width`、`depth`、`height` | 中心矩形盒 |
| `cylinder` | `radius`、`height` | XY 平面上的垂直圆柱体 |
| `tube` | `outer_radius`、`inner_radius`、`height` | 空心圆柱体（内径 < 外径） |
| `sphere` | `radius` | 实体球体 |
| `wedge` | `dx`、`dy`、`dz`、`xmin`、`zmin`、`xmax`、`zmax` | 梯形楔形 |
| `torus` | `major_radius`、`minor_radius` | 甜甜圈形状（通过 OCC BRepPrimAPI） |
| `cone` | `bottom_radius`、`top_radius`、`height` | 锥形/截头锥形 |
**示例：**
```python
cad_run("primitive", "torus", {"major_radius": 30, "minor_radius": 8, "name": "donut"})
# → {"name": "donut", "step": "/app/cad_output/donut.step"}
```
### 层 2：`sketch_2d` — 2D 草图和配置文件
创建 2D 配置文件，可选地拉伸成 3D。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `rect` | `width`、`height`、`extrude_distance?` | 矩形，可选拉伸 |
| `circle` | `radius`、`extrude_distance?` | 圆形，可选拉伸 |
| `polygon` | `radius`、`sides`（3-128）、`extrude_distance?` | 正多边形 |
| `slot` | `length`、`diameter`、`extrude_distance?` | 体育场/椭圆形 |
| `ellipse` | `x_radius`、`y_radius`、`extrude_distance?` | 椭圆形轮廓 |
| `trapezoid` | `width`、`height`、`angle_a`、`angle_b`、`extrude_distance?` | 梯形，可调节角度 |
| `gear` | `num_teeth`、`pitch_diameter`、`pressure_angle?`（默认 20°）、`height?` | 轮廓近似 |
| `text` | `text`、`font_size`、`height` | 3D 浮雕文本（凸起） |
### 层 3：`boolean_3d` — 布尔和 3D 操作
修改现有的 STEP 文件。所有操作都通过文件名从输出目录读取。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `cut` | `target_step`、`tool_step` | 布尔减法（目标 - 工具） |
| `union` | `target_step`、`tool_step` | 布尔融合 |
| `intersect` | `target_step`、`tool_step` | 布尔交集 |
| `fillet` | `step_filename`、`radius` | 圆润所有边缘 |
| `chamfer` | `step_filename`、`length`、`length2?` | 斜切所有边缘 |
| `shell` | `step_filename`、`thickness` | 空心化固体（正数 = 向外） |
| `split` | `step_filename`、`keep_top?`（True）、`keep_bottom?`（True) | 在 Z=0 平面分割 |
| `mirror` | `step_filename`、`plane`（XY/XZ/YZ） | 镜像跨轴平面 |
| `extrude_face` | `step_filename`、`distance` | 挤出顶部面 |
| `revolve` | `step_filename`、`angle_degrees?`（默认 0.0.0.0) | 旋转顶部面 |
| `thicken_face` | `step_filename`、`thickness` | 加厚顶部面成固体 |
### 层 4：`stl` — STL 导入和转换
导入、检查和转换 STL 网格文件。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `import_stl` | `stl_filename` | 导入 STL → CAD 实体 → 以 STEP/STL 导出 |
| `transform_stl` | `stl_filename`、`scale?`、`rotate_x/y/z?`、`translate_x/y/z?` | 缩放、旋转、平移 → 重新导出 |
| `stl_info` | `stl_filename` | 二进制 STL 元数据（三角形、边界框、大小、头部） |
| `stl_fix_normals` | `stl_filename` | 重新计算一致的面法线 |
| `stl_merge` | `stl_filenames`（列表） | 合并多个 STL 文件为一个 |
### 层 5：`sketch_draw` — 程序化绘图
使用线条、弧线和样条线编程构建 2D 配置文件，然后拉伸、旋转、拟合或扫描成 3D。使用内存中草图状态，键名为名称。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `start_sketch` | `plane?`（XY/XZ/YZ，默认为 XY） | 初始化命名的工作区 |
| `line` | `sketch_name?`、`x`、`y` | 添加线段（相对） |
| `line_to` | `sketch_name?`、`x`、`y` | 线条到绝对点 |
| `h_line` | `sketch_name?`、`distance` | 水平线 |
| `v_line` | `sketch_name?`、`distance` | 垂直线 |
| `arc_three` | `sketch_name?`、`x1`、`y1`、`x2`、`y2` | 三点圆弧 |
| `arc_tangent` | `sketch_name?`、`end_x`、`end_y` | 切线圆弧 |
| `spline` | `sketch_name?`、`points`（列表 [x,y]） | 插值样条线 |
| `polyline` | `sketch_name?`、`points`（列表 [x,y]） | 连接线段 |
| `close` | `sketch_name?` | 关闭线条回到起点 |
| `mirror_sketch` | `sketch_name?` | 镜像跨轴 |
| `offset_2d` | `sketch_name?`、`distance` | 偏移 2D 线条 |
| `extrude` | `sketch_name?`、`distance` | 拉伸草图到 3D |
| `revolve_sketch` | `sketch_name?`、`angle_degrees?` | 旋转（默认 360°） |
| `loft` | `sketch_name?`、`sketch_names`（列表） | 拟合多个草图 |
| `sweep` | `profile_name`、`path_name` | 扫描配置文件沿路径 |
**工作流：**
```
1. start_sketch("my_sketch", "XY")
2. h_line("my_sketch", 40)
3. v_line("my_sketch", 30)
4. arc_tangent("my_sketch", 0, 15)
5. close("my_sketch")
6. extrude("my_sketch", 10)
```
### 层 6：`analysis` — 分析和查询
查询 STEP 和 STL 文件的几何和物理属性。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `mass_properties` | `step_filename` | 体积、表面积、质心 |
| `bounding_box` | `step_filename` | 轴向对齐的边界框 |
| `surface_area` | `step_filename` | 总表面积（OCC BRepGProp） |
| `section_props` | `step_filename`、`cut_plane?` | 2D 截面属性 |
| `is_watertight` | `stl_filename` | 水密检查 + 欧拉数 |
| `mesh_volume` | `stl_filename` | 通过 trimesh 从 STL 网格计算体积 + 面积 |
| `ray_intersect` | `stl_filename`、`origin` [x,y,z]、`direction` [x,y,z] | 射线网格交点测试 |
| `signed_distance` | `stl_filename`、`point` [x,y,z] | 从点到网格的带符号距离 |
### 层 7：`mesh` — 网格处理（STL 管道）
完整的网格处理管道，通过 trimesh + 可选的 pymeshlab。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `mesh_boolean_union` | `target_stl`、`tool_stl` | 两个 STL 网格的联合 |
| `mesh_boolean_diff` | `target_stl`、`tool_stl` | 两个 STL 网格的差集 |
| `mesh_boolean_intersect` | `target_stl`、`tool_stl` | 两个 STL 网格的交集 |
| `mesh_repair` | `stl_filename` | 修复法线，删除退化面，流形修复 |
| `mesh_simplify` | `stl_filename`、`target_faces` | 二次曲线塌陷消减（pymeshlab 或 trimesh 回退） |
| `mesh_smooth` | `stl_filename`、`iterations?`（5）、`lambda?`（0.5） | 拉普拉斯平滑 |
| `mesh_subdivide` | `stl_filename`、`iterations?`（1） | 环形细分 |
| `mesh_slice` | `stl_filename`、`plane_height`、`plane_axis?`（x/y/z） | 平面切片 |
| `mesh_section` | `stl_filename`、`plane_height` | 2D 轮廓 → SVG 导出 |
| `mesh_curvature` | `stl_filename` | 主曲率分析（pymeshlab） |
| `mesh_convex_hull` | `stl_filename` | 凸壳网格 |
| `mesh_voxelize` | `stl_filename`、`pitch` | 体素化表示 → STL 盒 |
### 层 8：`conversion` — 格式转换
双向转换 CAD 和网格格式。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `convert_step_stl` | `input_filename` | STEP → STL |
| `convert_stl_step` | `input_filename` | STL → STEP |
| `convert_step_obj` | `input_filename` | STEP → Wavefront OBJ |
| `convert_step_glb` | `input_filename` | STEP → GLTF 二进制（GLB） |
| `convert_stl_ply` | `input_filename` | STL → Stanford PLY |
| `convert_stl_off` | `input_filename` | STL → 对象文件格式 |
| `convert_stl_3mf` | `input_filename` | STL → 3D 制造格式 |
| `convert_stl_collada` | `input_filename` | STL → COLLADA DAE |
| `export_dxf` | `step_filename` | CAD 面 → 2D DXF |
| `export_svg` | `step_filename` | CAD 轮廓 → SVG |
支持的格式对：
```
STEP ⇄ STL, OBJ, GLB, DXF, SVG
STL → PLY, OFF, 3MF, COLLADA, STEP
```
### 层 9：`assembly` — 多零件装配
创建、填充、约束和导出装配体。装配体状态存储在内存中。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `new_assembly` | `name` | 创建一个新的空装配体 |
| `add_part` | `assembly_name`、`step_filename`、`loc_x/y/z?`、`rot_x/y/z?`、`part_name?` | 添加 STEP 文件作为零件 |
| `constrain_mate` | `assembly_name`、`part_a`、`part_b` | 添加平面配合约束 |
| `constrain_align` | `assembly_name`、`part_a`、`axis_a`、`part_b`、`axis_b` | 添加轴对齐约束 |
| `solve` | `assembly_name` | 解决所有约束 |
| `export_step` | `assembly_name` | 多体 STEP 导出 |
| `export_gltf` | `assembly_name` | GLTF/GLB 导出 |
| `export_vrml` | `assembly_name` | VRML 导出 |
### 第10层：`cam` — CAM & 制造
生成用于CNC加工的G代码并为3D打印准备模型。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `profile_cam` | `step_filename`, `tool_diameter?` (3.0), `feed_rate?` (1000), `plunge_rate?` | 2D轮廓G代码 |
| `pocket_cam` | `step_filename`, `tool_diameter?` (3.0), `stepover?` | 型腔清理G代码 |
| `drill_cam` | `step_filename`, `hole_diameter?`, `depth?` | 钻孔循环G代码 |
| `slice_3mf` | `step_filename` | 导出为3MF用于3D打印 |
| `slice_svg` | `step_filename`, `height?` (0) | 导出2D切片为SVG |
> **注意：** CAM操作基于包围盒几何体生成简化的G代码。对于生产CAM，请使用输出作为参考，并用专用CAM工具进行改进。
### 第11层：`parts` — 参数化零件库
标准机械部件，具有合理的默认值。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `bolt` | `diameter?` (6), `length?` (30), `thread_pitch?` (1.0) | 六角头螺栓（头部+杆） |
| `nut` | `diameter?` (6), `thickness?` (5) | 六角螺母 |
| `washer` | `inner_d?` (6.5), `outer_d?` (14), `thickness?` (1.5) | 平垫圈 |
| `bearing` | `inner_d?` (10), `outer_d?` (26), `width?` (8) | 球轴承（简化） |
| `i_beam` | `height?` (100), `flange_width?` (50), `web_thickness?` (5), `flange_thickness?` (8), `length?` (1000) | 工字梁截面 |
| `c_channel` | `height?` (80), `width?` (40), `thickness?` (5), `length?` (1000) | C型槽截面 |
| `angle_iron` | `leg_length?` (50), `thickness?` (5), `length?` (1000) | 角铁（L型截面） |
| `spring` | `wire_d?` (2), `coil_d?` (20), `num_coils?` (8), `height?` (50) | 螺旋压缩弹簧（样条扫描） |
### 第12层：`fem` — 有限元及仿真准备
从CAD模型生成有限元网格并导出为求解器格式。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `mesh_2d_tri` | `step_filename`, `element_size?` (5.0) | 2D三角形表面网格 |
| `mesh_2d_quad` | `step_filename`, `element_size?` (5.0) | 2D四边形主导表面网格 |
| `mesh_3d_tet` | `step_filename`, `element_size?` (5.0) | 3D四面体体积网格 |
| `mesh_3d_hex` | `step_filename`, `element_size?` (5.0) | 3D六面体体积网格 |
| `export_abaqus` | `step_filename`, `element_size?`, `mesh_file?` | 导出为Abaqus INP格式 |
| `export_ansys` | `step_filename`, `element_size?`, `mesh_file?` | 导出为Ansys CDB格式 |
| `export_nastran` | `step_filename`, `element_size?`, `mesh_file?` | 导出为Nastran BDF格式 |
| `export_vtk` | `step_filename`, `element_size?`, `mesh_file?` | 导出为VTK/VTU格式 |
| `export_xdmf` | `step_filename`, `element_size?`, `mesh_file?` | 导出为XDMF格式 |
使用[gmsh](https://gmsh.info)进行网格划分，使用[meshio](https://github.com/nschloe/meshio)进行格式转换。
### 第13层：`templates` — 现实世界模板生成器 ⭐
**此版本新增！** 常见现实世界零件的预建参数化生成器。这些是完整、生产就绪的模板，具有合理的默认值 — 而不仅仅是基本形状。
| 操作 | 参数 | 描述 |
|-----------|-----------|-------------|
| `fan_shroud` | `fan_size?` (60.5), `opening?` (fan_size), `wall?` (3.0), `depth?` (28.0), `screw_spacing?` (50.0), `screw_diameter?` (3.2), `boss_diameter?` (7.0), `fillet?` (1.5) | 方形开口风扇支架，4×螺柱+孔，可选圆角。输出：STEP/STL |
| `duct_transition` | `inlet_width?` (60.5), `inlet_height?` (60.5), `outlet_width?` (49.1), `outlet_height?` (44.8), `length?` (35.0), `wall?` (2.4), `fillet?` (0.8) | 空心矩形至矩形过渡管道，通过 loft。 |
| `rounded_rect_frame` | `width?` (70.0), `height?` (70.0), `thickness?` (5.0), `opening_width?` (60.5), `opening_height?` (60.5), `fillet?` (2.0) | 圆角矩形框架/安装件，中心切出。 |
| `screw_mount_plate` | `width?` (70.0), `height?` (70.0), `thickness?` (3.0), `screw_spacing_x?` (50.0), `screw_spacing_y?` (50.0), `screw_diameter?` (3.2), `fillet?` (1.0) | 扁平安装板，4×矩形螺钉图案。 |
| `gasket` | `width?` (70.0), `height?` (70.0), `thickness?` (1.2), `opening_width?` (60.5), `opening_height?` (60.5), `screw_spacing?` (50.0), `screw_diameter?` (3.2) | 薄垫圈/间隔框架，可选螺钉孔。 |
| `standoff_grid` | `width?` (70.0), `height?` (70.0), `base_thickness?` (3.0), `standoff_height?` (8.0), `standoff_diameter?` (7.0), `hole_diameter?` (3.2), `spacing_x?` (50.0), `spacing_y?` (50.0) | 基板，4×圆柱形支架/凸台网格，带螺钉孔。 |
**示例：GPU风扇支架**
```python
cad_run("templates", "fan_shroud", {
"fan_size": 60.5,
"opening": 55.0,
"depth": 28.0,
"screw_spacing": 50.0,
"screw_diameter": 3.2,
"fillet": 2.0,
"name": "gpu_fan_shroud"
})
```
**示例：空气流动管道过渡**
```python
cad_run("templates", "duct_transition", {
"inlet_width": 60.5,
"inlet_height": 60.5,
"outlet_width": 49.1,
"outlet_height": 44.8,
"length": 35.0,
"wall": 2.4,
"name": "fan_duct_transition"
})
```
---
## 完整层级总结
| # | 层级 | 操作 | 适合 |
|---|------|-----------|----------|
| 1 | `primitive` | 7 | 盒子，圆柱体，球体，圆锥，环形 |
| 2 | `sketch_2d` | 8 | 2D轮廓，挤出徽标，齿轮，槽 |
| 3 | `boolean_3d` | 11 | 切割，融合，圆角，镜像，壳体 |
| 4 | `stl` | 5 | 导入扫描网格，转换，合并 |
| 5 | `sketch_draw` | 16 | 自定义2D线轮廓（线，弧，样条）→ 3D |
| 6 | `analysis` | 8 | 体积，面积，质心，包围盒，水密检查 |
| 7 | `mesh` | 12 | 网格修复，简化，光滑，切片，布尔运算 |
| 8 | `conversion` | 10 | STEP↔STL↔OBJ↔GLB↔PLY↔3MF↔DXF↔SVG |
| 9 | `assembly` | 8 | 多部分装配，约束，GLTF导出 |
| 10 | `cam` | 5 | G代码生成，3MF打印，切片SVG |
| 11 | `parts` | 8 | 螺栓，螺母，垫圈，轴承，梁，弹簧 |
| 12 | `fem` | 9 | 四面体/六面体网格划分，Abaqus/Ansys/Nastran导出 |
| 13 | **`templates`** | **6** | **风扇支架，管道，框架，板，垫圈，支架** |
**总计：** 13层 **81个操作**。
---
## 工作流程示例
### 完整零件创建 → 分析 → 导出管道
```
# 1. 探索可用层级
cad_help()
# 2. 查看"templates"层级的内容
cad_help("templates")
# 3. 生成风扇支架
cad_run("templates", "fan_shroud", {
"fan_size": 60.5,
"opening": 55.0,
"depth": 28.0,
"screw_spacing": 50.0,
"name": "my_shroud"
})
# 4. 检查输出
cad_manage("list")
# 5. 分析质量属性
cad_run("analysis", "mass_properties",
{"step_filename": "my_shroud.step"})
# 6. 导出为SVG
cad_run("conversion", "export_svg",
{"step_filename": "my_shroud.step", "name": "my_shroud_svg"})
# 7. 生成G代码
cad_run("cam", "profile_cam", {
"step_filename": "my_shroud.step",
"tool_diameter": 3.0,
"name": "my_shroud_gcode"
})
```
### STL扫描 → 修复 → 简化 → 有限元
```
# 1. 导入3D扫描
cad_run("stl", "import_stl", {"stl_filename": "scan_raw.stl"})
# 2. 修复法线
cad_run("stl", "stl_fix_normals", {"stl_filename": "scan_raw.stl"})
# 3. 完整修复 + 简化
cad_run("mesh", "mesh_repair", {"stl_filename": "scan_raw.stl"})
cad_run("mesh", "mesh_simplify", {"stl_filename": "scan_raw.stl", "target_faces": 5000})
# 4. 转换为STEP用于CAD
cad_run("conversion", "convert_stl_step", {"input_filename": "scan_raw_simplified.stl"})
# 5. 有限元网格
cad_run("fem", "mesh_3d_tet", {"step_filename": "scan_raw_simplified.step", "element_size": 2.0})
# 6. 导出Ansys
cad_run("fem", "export_ansys", {"step_filename": "scan_raw_simplified.step", "element_size": 2.0})
```
### 多部分装配工作流
```
# 1. 创建基本形状
cad_run("primitive", "box", {"width": 100, "depth": 50, "height": 20, "name": "base_plate"})
cad_run("primitive", "cylinder", {"radius": 10, "height": 50, "name": "support_pillar"})
# 2. 新装配
cad_run("assembly", "new_assembly", {"name": "my_assembly"})
# 3. 添加部件
cad_run("assembly", "add_part", {
"name": "my_assembly",
"step_filename": "base_plate"})
# 3. 添加部件
cad_run("assembly", "add_part", {
"name": "my_assembly",
"step_filename": "base_plate.step",
"loc_z": 0,
"part_name": "base"
})
cad_run("assembly", "add_part", {
"name": "my_assembly",
"step_filename": "support_pillar.step",
"loc_x": 30, "loc_y": 20, "loc_z": 10,
"part_name": "pillar"
})
# 4. 导出装配体
cad_run("assembly", "export_step", {"name": "my_assembly"})
cad_run("assembly", "export_gltf", {"name": "my_assembly"})
```
### 零件库 + 分析
```
# 生成硬件
cad_run("parts", "bolt", {"diameter": 8, "length": 40, "name": "m8_bolt"})
cad_run("parts", "nut", {"diameter": 8, "thickness": 6, "name": "m8_nut"})
cad_run("parts", "washer", {"inner_d": 8.5, "outer_d": 16, "name": "m8_washer"})
# 查询质量属性
cad_run("analysis", "mass_properties", {"step_filename": "m8_bolt.step"})
```
---
## 输出目录和格式支持
导出文件写入到 [`./cad_output/`](./cad_output) （在容器内映射到 `/app/cad_output`）。
### 支持的导出格式
| 格式 | 扩展名 | 层级 | 备注 |
|--------|-----------|---------|-------|
| STEP | `.step` | 全部 | 主要CAD交换格式（AP203/214） |
| STL | `.stl` | 全部 | 3D打印网格格式 |
| OBJ | `.obj` | `conversion` | Wavefront网格格式 |
| PLY | `.ply` | `conversion`, `mesh` | Stanford Polygon格式 |
| GLB | `.glb` | `conversion`, `assembly` | 二进制glTF用于网页/3D查看器 |
| OFF | `.off` | `conversion` | 对象文件格式 |
| 3MF | `.3mf` | `conversion`, `cam` | 3D制造格式 |
| COLLADA | `.dae` | `conversion` | 互操作性格式 |
| SVG | `.svg` | `conversion`, `cam`, `mesh` | 2D矢量导出 |
| DXF | `.dxf` | `conversion` | 2D CAD交换 |
| G代码 | `.gcode` | `cam` | CNC加工 |
| GMSH | `.msh` | `fem` | Gmsh网格格式 |
| Abaqus | `.inp` | `fem` | Abaqus/FEA输入 |
| Ansys | `.cdb` | `fem` | Ansys求解器格式 |
| Nastran | `.bdf` | `fem` | Nastran批量数据 |
| VTK/VTU | `.vtu` | `fem` | 可视化工具包 |
| XDMF | `.xdmf` | `fem` | 基于HDF5的网格格式 |
| VRML | `.wrl` | `assembly` | VRML导出 |
| GLTF | `.gltf` | `assembly` | JSON glTF导出 |
### 示例输出
`cad_output/` 目录包含生成的示例：
- [`TeslaP100_adapter.stl`](cad_output/TeslaP100_adapter.stl) & [`.dwg`](cad_output/TeslaP100_adapter.dwg) — GPU适配器支架
- [`p100_side_60mm_fan_shroud_v1.step`](cad_output/p100_side_60mm_fan_shroud_v1.step) — 风扇支架来自templates层级
- [`p100_side_transition_probe.step`](cad_output/p100_side_transition_probe.step) — 管道过渡探头
- [`alqc_locus_core_seed.step`](cad_output/alqc_locus_core_seed.step) — ALQC locus几何体
- [`alqc_shadow_locus_ring.step`](cad_output/alqc_shadow_locus_ring.step) — ALQC环形几何体
---
## 健康检查
```
curl http://localhost:8012/health
# → {"status":"ok"}
```
健康端点由 `supergateway` 提供服务，并确认MCP服务器进程处于活动状态。
---
## Docker参考
### [`Dockerfile`](Dockerfile)
- 基础：`python:3.11-slim`
- 系统依赖：OpenCASCADE，libGL，libspatialindex，构建工具
- Python包：cadquery，mcp，trimesh，manifold3d，pymeshlab，meshio，gmsh，ezdxf，pygltflib，ifcopenshell，scikit-image等
- 运行时：`supergateway` 通过 `--stdio` 包装 `python cadquery_mcp.py`
### [`docker-compose.yml`](docker-compose.yml)
```yaml
services:
cadquery-mcp:
build: .
ports:
- "8012:8012"
environment:
CAD_OUTPUT_DIR: "/app/cad_output"
volumes:
- ./cad_output:/app/cad_output
healthcheck:
test: ["CMD", "curl", "-fsS", "http://localhost:8012/health"]
```
---
## 远程部署
### 使用rsync + docker compose
```bash
# 将文件推送到远程VPS
rsync -avz --progress ./ user@your-server:~/cadquery-mcp/
# SSH登录并部署
ssh user@your-server
cd ~/cadquery-mcp
docker compose up -d --build
# 验证
curl http://localhost:8012/health
```
### 使用部署脚本
部署工作流程可能使用相同的模式 — 同步文件，重新构建容器，验证健康状况。
---
## STL元数据（二进制扫描）
`cad_stl_info` 操作 (`cad_manage("stl_info", "file.stl")`) 直接解析 **二进制STL头部** — 读取80字节的ASCII头部注释，三角形计数，扫描顶点数据以计算包围盒。这适用于大小高达数GB的文件，无需将整个网格加载到内存中，从而支持高达数千兆字节的文件。
对于大文件，包围盒从前5,000个三角形采样，提供快速（毫秒级）的尺寸估计。
---
## 扩展新的层级
添加新的功能层级非常简单：
1. **添加一个 `TIERS` 条目**，包含标签，描述和操作名称：
```python
TIERS["pcb"] = {
"label": "PCB设计",
"description": "生成PCB轮廓，安装孔，保留区",
"operations": {
"outline": "从尺寸生成板轮廓",
"mounting_holes": "在位置添加安装孔",
"keepout": "添加保留区",
},
}
TIER_ORDER.insert(-1, "pcb") # 在templates之前
```
2. 在 `cad_run()` 中添加处理程序：
```python
if tier == "pcb":
if op == "outline":
w = _extract_float(params, "width")
h = _extract_float(params, "height")
return _export(cq.Workplane("XY").rect(w, h).extrude(1.6), name, export_format)
```
3. **重建** — 模型自动发现新的层级，通过 `cad_help()`。
无需修改模型的工具配置。
---
## 项目文件
| 文件 | 用途 |
|------|---------|
| [`cadquery_mcp.py`](cadquery_mcp.py) | MCP服务器 — 13层路由器，具有81个操作 |
| [`Dockerfile`](Dockerfile) | 容器构建（python:3.11-slim + apt + pip + supergateway） |
| [`docker-compose.yml`](docker-compose.yml) | 带有绑定挂载 + 健康检查的编排 |
| [`environment.yml`](environment.yml) | 参考conda环境（stub — pip依赖项在Dockerfile中） |
| [`README.md`](README.md) | 本文件 |
| `cad_output/` | 生成的STEP，STL，OBJ，GLB，SVG，DXF导出文件 |
---
## 故障排除
| 症状 | 可能原因 | 解决方案 |
|---------|-------------|----------|
| `curl: connection refused` | 容器未运行 | 先运行 `docker compose up -d` |
| `File not found in output directory` | 文件名或路径错误 | 使用 `cad_manage("list")` 查看可用文件；仅传递文件名 |
| `cad_help("unknown")` → "Unknown tier" | 层级名称错误 | 使用 `cad_help()` 查看有效层级名称 |
| `gmsh not available` | gmsh未安装在主机上 | 使用Docker（已预安装gmsh）或 `pip install gmsh` |
| `pymeshlab not available` | pymeshlab未安装 | `pip install pymeshlab` 或使用Docker |
| STL导入失败 | 网格非流形或损坏 | 尝试先运行 `mesh_repair` |
| `export_glb` 返回 `.gltf` | cadquery导出GLTF文本格式 | 复制并重命名 — 部分查看器接受 `.glb` |
| Supergateway端口冲突 | 端口8012已被占用 | 更改 `ports:` 在docker-compose.yml中 |
### FAQ
**Q：为什么是3个工具而不是80+个？**
A：LLMs有有限的工具预算。公开80+个工具会占用整个上下文窗口用于工具定义。层级路由器模式保持模型的工具命名空间为3，同时通过 `cad_help()` 提供可发现性。
**Q：我可以在不使用Docker的情况下运行吗？**
A：是的。安装手动pip列出的依赖项并通过 `supergateway` 运行。参见 [安装选项2](#option-2-manual-pip-ubuntu/debian)。
**Q：我可以导入哪些CAD格式？**
A：STEP（主要），STL。STL → STEP转换启用基于网格的工作流程。
**Q：如何更改输出目录？**
A：设置 `CAD_OUTPUT_DIR` 环境变量（默认为 `/app/cad_output`）。
**Q：服务器在每次调用之间是否保留状态？**
A：文件在输出目录中持久化。草图和装配状态在服务器进程生命周期内在内存中持久化。
**Q：我可以在不修改核心文件的情况下添加自定义操作吗？**
A：目前，层级在 [`cadquery_mcp.py`](cadquery_mcp.py) 中定义。代码设计为易于扩展 — 添加一个层级条目 + 处理器块。
---
## 许可证
该项目作为开源MCP服务器实现提供。CadQuery根据Apache 2.0许可。查看第三方依赖项的个别软件包许可证。
---
* 使用 [CadQuery](https://cadquery.readthedocs.io)， [trimesh](https://trimsh.org)， [gmsh](https://gmsh.info)， [meshio](https://github.com/nschloe/meshio)， [pymeshlab](https://pymeshlab.readthedocs.io)， [supergateway](https://github.com/supercorp/supergateway)，以及 [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) 构建。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器