caid MCP

CAiD MCP服务器

每个几何操作都通过CAiD的ForgeResult系统进行验证，该系统跟踪体积、表面积和诊断。如果布尔值静默失败（OCCT常见），验证层会捕获它并告诉原因。

You: "Make a box with rounded edges and a hole through the top, show me a preview"
Claude → create_box → fillet_solid_edges → add_hole → preview_object → export_stl
Result: SVG preview + ~/cadquery-output/my_part.stl

可用工具（13个类别中的54个）

使用 discover_tools() 浏览，或 discover_tools(category="query") 对于一个特定的类别。

项目结构

caid-mcp/
├── server.py                    # Entry point
├── caid_mcp/
│   ├── __init__.py
│   ├── core.py                  # Scene state, shared utilities
│   ├── types.py                 # Pydantic result models (v0.6.0+)
│   └── tools/
│       ├── primitives.py        # Shape creation (7 tools)
│       ├── modify.py            # Holes, fillets, chamfers, shell (4 tools)
│       ├── transforms.py        # Translate, rotate, scale, mirror (4 tools)
│       ├── booleans.py          # Union, cut, intersect, combine (4 tools)
│       ├── query.py             # Geometry inspection and measurement (6 tools)
│       ├── view.py              # Section and exploded views (2 tools)
│       ├── scene.py             # Workspace management (5 tools)
│       ├── export.py            # STL, STEP, SVG preview (5 tools)
│       ├── heal.py              # Validation and repair (3 tools)
│       ├── io.py                # BREP/STEP import-export (3 tools)
│       ├── assembly.py          # Multi-part assemblies (5 tools)
│       ├── compound.py          # Belt/pulley systems (3 tools)
│       └── advanced.py          # Scripting, patterns, tool router (3 tools)
├── examples/
│   ├── quickstart.py               # Install verification script
│   ├── GALLERY.md                   # Example gallery with prompts
│   └── images/                      # Rendered example images
├── tests/
│   └── test_cadquery_mcp.py
├── pyproject.toml
├── LLM_GUIDE.md                 # LLM-specific usage guide
├── CHANGELOG.md
└── LICENSE

______________________________________________________________________

设置

先决条件

• Python 3.11+

安装

# 1. Create a virtual environment
python -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows

# 2. Install CAiD (brings in OCP and all dependencies)
pip install caid

# 3. Clone and install this server
git clone https://github.com/dreliq9/caid-mcp.git
cd caid-mcp
pip install -e ".[dev]"

验证

source .venv/bin/activate
python -c "import caid; import mcp; print('All dependencies OK')"
pytest tests/ -v

连接到克劳德代码

claude mcp add-json caid '{"type":"stdio","command":"/FULL/PATH/TO/.venv/bin/python","args":["/FULL/PATH/TO/caid-mcp/server.py"]}' --scope user

替换 /FULL/PATH/TO/ 使用venv Python和server.py文件的实际绝对路径。

或编辑 ~/.claude.json 直接：

{
  "mcpServers": {
    "caid": {
      "type": "stdio",
      "command": "/FULL/PATH/TO/.venv/bin/python",
      "args": ["/FULL/PATH/TO/caid-mcp/server.py"]
    }
  }
}

克劳德桌面版

将相同的配置添加到您的Claude Desktop配置文件中：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

验证连接

claude mcp list       # from terminal
/mcp                  # inside Claude Code

______________________________________________________________________

主要特点

结构化工具输出（v0.6.0+）

工具在 primitives 和 query 返回Pydantic模型。每个响应都携带 两者都是人类可读的文本块（通过 __str__)和一个打字 structuredContent JSON有效载荷。代理可以读取以下字段 result.volume_mm3 或 result.bounding_box.xlen 直接--不再使用正则表达式 "OK Created..." 串。

create_box("lid", 50, 30, 5)
  text:        "OK Created box 'lid' | volume=7500.0mm3 | bbox=50.00x30.00x5.00mm"
  structured:  {ok: true, name: "lid", kind: "box", volume_mm3: 7500.0, bbox: {...}}

只阅读文本的旧客户端仍然可以工作——这是加法，而不是电汇。

几何查询与测量

查询工具允许LLM在修改之前检查它构建的内容，从而解决了LLM猜测目标边缘的“盲圆角”问题。

list_edges("box")           → every edge with index, endpoints, length, type
list_faces("box")           → every face with index, area, center, normal
find_edges_near_point(...)  → "what edges are near (10, 5, 2.5)?"
measure_distance(a, b)      → min distance between two objects

基于索引的边缘/面部选择

而不是像这样猜测选择器字符串 ">Z"，法学硕士现在可以：

1. 呼叫 list_edges 查看所有边及其索引
2. 呼叫 fillet_solid_edges(name, radius, edge_indices="[2, 5, 8]") 精确地瞄准这些边缘

同样适用于 add_hole(face_index=3) 和 shell_object(face_index=0).

剖面图和分解图

section_view("part", axis="X", offset=5.0)  → cut and preview cross-section
exploded_view("assembly", scale=2.5)        → push parts outward for inspection

已验证的操作

每个CAiD操作都会返回一个带有卷跟踪的ForgeResult。如果布尔并集没有增加体积，则会收到带有提示的警告（形状可能不会重叠）。自动捕获无声的OCCT故障。

CAiD脚本逃逸图案

当内置工具无法完成工作时， run_cadquery_script （保留名称以与API兼容）允许完全访问CAiD和OCP：

script = """
from caid.vector import Vector
from OCP.BRepPrimAPI import BRepPrimAPI_MakeBox
from OCP.gp import gp_Pnt

# Use CAiD helpers or raw OCP calls
result = caid.make_box(20, 20, 10)
"""

安全说明： run_cadquery_script 在没有沙盒的子进程中执行任意Python。子进程具有完整的文件系统和网络访问权限。当MCP服务器在本地与受信任的客户端（例如，您自己的计算机上的Claude Code）一起使用时，这是安全的。在不添加沙盒的情况下，不要将此服务器暴露给不受信任的用户——请参阅 计划修复 在......下面

______________________________________________________________________

输出文件

所有出口都转到 ~/cadquery-output/ 默认情况下（保留目录名以保持向后兼容性）。覆盖：

export CAID_OUTPUT_DIR=/your/path

或者在MCP配置中：

{
  "env": { "CAID_OUTPUT_DIR": "/your/stl/folder" }
}

______________________________________________________________________

示例

通过CAiD MCP工具构建的真实零件。每个示例都突出显示了经过验证的几何图形、修改前的查询和剖面图——这是其他CAD for AI工具无法做到的。请参阅 完整画廊 用于工具序列和工作流程分解。

Raspberry Pi Case Shell, port cutouts, section view verification

Headphone Stand Primitives, booleans, overlap validation

Hex Bolt & Nut Extruded polygon, chamfers, multi-part scene

Cable Clip Boolean subtract, snap-fit slot, 30-second build

示例提示

• *“设计一个带有端口切口的Pi外壳，然后将其切开以验证壁厚”*
• *“制作耳机支架——完成后测量总高度”*
• *“模拟M10螺栓和螺母，将边缘倒角，并排放置”*
• *列出此零件的边缘，然后按索引仅对内部接缝进行圆角处理*
• *“通过中间的剖面图检查内部孔尺寸”*

______________________________________________________________________

建筑

Claude Code / Claude Desktop / any MCP client
        │
        │  stdio (JSON-RPC)
        ▼
   MCP Server (server.py)
        │
        ├── tools/primitives — create shapes
        ├── tools/modify — holes, fillets, chamfers, shell
        ├── tools/transforms — move, rotate, scale, mirror
        ├── tools/booleans — union, cut, intersect
        ├── tools/query — geometry inspection and measurement
        ├── tools/view — section cuts, exploded views
        ├── tools/scene — workspace management
        ├── tools/export — STL, STEP, SVG preview
        ├── tools/heal — validation, repair, simplification
        ├── tools/io — BREP/STEP import-export
        ├── tools/assembly — multi-part assemblies
        ├── tools/compound — belt/pulley systems
        └── tools/advanced — scripting, patterns, tool router
              │
              ▼
        CAiD → OCP (OpenCASCADE) kernel
              │
              ▼
        STL / STEP / BREP / SVG files

______________________________________________________________________

故障排除

“未安装CAiD” --确保您在同一个venv中安装了CAiD： pip install caid

“未安装OCP” --OCP作为CAiD的依赖项自动安装。如果缺失： pip install OCP

Claude Code不显示工具 — claude mcp list 检查注册。确保venv的Python二进制文件的路径是绝对的。重新启动克劳德代码。

SVG预览为空 --对象的体积可能为零。使用 list_objects 检查尺寸。

圆角/倒角失败 --试试看 heal_object 首先，然后用较小的半径重试。使用 list_edges 以验证最短边长。

测试失败 --确保你在venv： source .venv/bin/activate && pytest tests/ -v

______________________________________________________________________

计划修复

• 沙盒 run_cadquery_script --脚本转义舱口当前运行任意Python，没有任何限制。计划：限制导入白名单，文件系统监禁 OUTPUT_DIR，网络访问已禁用。在此之前，只能与受信任的MCP客户端一起使用。
• Windows路径处理 --已在v0.4.1中修复。子进程脚本以前使用的f字符串路径插值在Windows反斜杠上中断。

______________________________________________________________________

致谢

CAiD MCP由Adam Steen和 克劳德 （人类学）。

许可证

麻省理工学院——见 许可证.