Metadata-Version: 2.4
Name: caid-mcp
Version: 0.6.0
Summary: MCP server giving AI agents validated 3D modeling via CAiD + OCCT
Author: Adam Steen
Author-email: "Claude (Anthropic)" <noreply@anthropic.com>
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.25
Requires-Dist: pydantic>=2.7
Requires-Dist: Pillow>=10.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Dynamic: license-file

# CAiD MCP Server

<!-- mcp-name: io.github.dreliq9/caid-mcp -->

An MCP server that gives AI agents **validated 3D CAD modeling** via [CAiD](https://github.com/dreliq9/CAiD) and [OCP (OpenCASCADE)](https://github.com/CadQuery/OCP). No GUI needed — the modeling engine IS the server.

Every geometry operation is validated through CAiD's ForgeResult system, which tracks volume, surface area, and diagnostics. If a boolean silently fails (common with OCCT), the validation layer catches it and tells you why.

```
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
```

## Available Tools (54 across 13 categories)

Use `discover_tools()` to browse, or `discover_tools(category="query")` for a specific category.

| Category | Count | What it does |
|---|---|---|
| **primitives** | 7 | Box, cylinder, sphere, cone, torus, extruded polygon, revolved profile |
| **modify** | 4 | Holes, fillets, chamfers, shell — with index-based edge/face selection |
| **transforms** | 4 | Translate, rotate, scale, mirror |
| **booleans** | 4 | Union, cut, intersect, multi-combine |
| **query** | 6 | List edges/faces, measure objects/distances, find nearest edges/faces |
| **view** | 2 | Section cuts, exploded assembly views |
| **scene** | 5 | List, info, delete, duplicate, clear |
| **export** | 5 | SVG preview, STL, STEP, batch STL |
| **heal** | 3 | Validity checking, shape repair, face simplification |
| **io** | 3 | BREP export, STEP/BREP import |
| **assembly** | 5 | Create, add parts, move, rotate, merge |
| **compound** | 3 | Belt wires, curve arrays, pulley assemblies |
| **advanced** | 3 | CAiD scripting, linear patterns, tool discovery |

## Project Structure

```
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
```

---

## Setup

### Prerequisites

- Python 3.11+

### Install

```bash
# 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]"
```

### Verify

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

### Connect to Claude Code

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

Replace `/FULL/PATH/TO/` with the actual absolute paths to your venv Python and the server.py file.

Or edit `~/.claude.json` directly:

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

### Claude Desktop

Add the same config to your Claude Desktop config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

### Verify connection

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

---

## Key Features

### Structured tool outputs (v0.6.0+)

Tools in `primitives` and `query` return Pydantic models. Each response carries
both a human-readable text block (via `__str__`) and a typed `structuredContent`
JSON payload. Agents can read fields like `result.volume_mm3` or
`result.bounding_box.xlen` directly — no more regex on `"OK Created..."` strings.

```
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: {...}}
```

Old clients that only read text still work — this is additive, not a wire change.

### Geometry Query and Measurement

The query tools let the LLM inspect what it built before modifying it — solving the "blind fillet" problem where the LLM guesses which edge to target.

```
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
```

### Index-Based Edge/Face Selection

Instead of guessing selector strings like `">Z"`, the LLM can now:
1. Call `list_edges` to see all edges with their indices
2. Call `fillet_solid_edges(name, radius, edge_indices="[2, 5, 8]")` to target exactly those edges

Same for `add_hole(face_index=3)` and `shell_object(face_index=0)`.

### Section and Exploded Views

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

### Validated Operations

Every CAiD operation returns a ForgeResult with volume tracking. If a boolean union doesn't increase volume, you get a warning with a hint (shapes may not overlap). Silent OCCT failures are caught automatically.

### CAiD Scripting Escape Hatch

When built-in tools can't do the job, `run_cadquery_script` (name kept for API compatibility) gives full access to CAiD and OCP:

```python
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)
"""
```

> **Security note:** `run_cadquery_script` executes arbitrary Python in a subprocess with no sandboxing. The subprocess has full filesystem and network access. This is safe when the MCP server is used locally with trusted clients (e.g., Claude Code on your own machine). Do not expose this server to untrusted users without adding sandboxing — see [Planned Fixes](#planned-fixes) below.

---

## Output Files

All exports go to `~/cadquery-output/` by default (directory name kept for backward compatibility). Override with:

```bash
export CAID_OUTPUT_DIR=/your/path
```

Or in the MCP config:
```json
{
  "env": { "CAID_OUTPUT_DIR": "/your/stl/folder" }
}
```

---

## Examples

Real parts built through CAiD MCP tools. Each example highlights validated geometry, query-before-modify, and section views — things other CAD-for-AI tools can't do. See the [full gallery](examples/GALLERY.md) for tool sequences and workflow breakdowns.

<table>
<tr>
<td align="center"><img src="examples/images/pi_case.png" width="300"><br><b>Raspberry Pi Case</b><br>Shell, port cutouts, section view verification</td>
<td align="center"><img src="examples/images/headphone_stand.png" width="300"><br><b>Headphone Stand</b><br>Primitives, booleans, overlap validation</td>
</tr>
<tr>
<td align="center"><img src="examples/images/hex_bolt_nut.png" width="300"><br><b>Hex Bolt & Nut</b><br>Extruded polygon, chamfers, multi-part scene</td>
<td align="center"><img src="examples/images/cable_clip.png" width="300"><br><b>Cable Clip</b><br>Boolean subtract, snap-fit slot, 30-second build</td>
</tr>
</table>

### Sample Prompts

- *"Design a Pi case with port cutouts, then section it to verify wall thickness"*
- *"Make a headphone stand — measure the total height when you're done"*
- *"Model an M10 bolt and nut, chamfer the edges, place them side by side"*
- *"List the edges on this part, then fillet just the inner joint by index"*
- *"Section view through the middle to check the internal hole dimensions"*

---

## Architecture

```
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
```

---

## Troubleshooting

**"CAiD is not installed"** — Make sure you installed CAiD in the same venv: `pip install caid`

**"OCP is not installed"** — OCP is installed automatically as a dependency of CAiD. If missing: `pip install OCP`

**Claude Code doesn't show tools** — `claude mcp list` to check registration. Make sure the path to your venv's Python binary is absolute. Restart Claude Code.

**SVG preview is blank** — Object might have zero volume. Use `list_objects` to check dimensions.

**Fillet/chamfer fails** — Try `heal_object` first, then retry with a smaller radius. Use `list_edges` to verify the shortest edge length.

**Tests failing** — Make sure you're in the venv: `source .venv/bin/activate && pytest tests/ -v`

---

## Planned Fixes

- **Sandbox `run_cadquery_script`** — The scripting escape hatch currently runs arbitrary Python with no restrictions. Planned: restricted imports whitelist, filesystem jailing to `OUTPUT_DIR`, network access disabled. Until then, only use with trusted MCP clients.
- **Windows path handling** — Fixed in v0.4.1. Subprocess scripts previously used f-string path interpolation that broke on Windows backslashes.

---

## Acknowledgments

CAiD MCP was co-developed by Adam Steen and [Claude](https://claude.ai) (Anthropic).

## License

MIT — see [LICENSE](LICENSE).
