CAD_MCP

# Forge A local **MCP server** that turns an AI agent into a parametric CAD operator. The agent describes intent ("a phone stand", "make it taller", "add four M3 holes") and Forge turns that into a typed, validated, replayable **operation graph** that compiles to real, printable CAD geometry (STL/STEP) plus rendered previews. The LLM never generates executable Python — it emits JSON conforming to a Pydantic schema. Forge validates it, then compiles it to [CadQuery](https://github.com/CadQuery/cadquery) internally. Every model is persisted as JSON on disk and keyed by `model_id`, so edits across turns are deterministic changes to a saved structure. ## Requirements - **Python 3.12** (not 3.14 — CadQuery/OCP and PyVista/VTK wheels lag new CPython releases). The pin lives in `.python-version` and `pyproject.toml`. - [uv](https://github.com/astral-sh/uv). ## Install ```bash uv python install 3.12 # if you don't have 3.12 uv sync uv run python -c "import cadquery" # sanity-check the native stack resolved ``` ## Run ```bash uv run forge ``` The server speaks MCP over stdio and blocks until the client disconnects (Ctrl-C to exit). ### Connect from an MCP client Point your client (Claude Code, Cursor, etc.) at the `forge` command. Example stdio config: ```json { "mcpServers": { "forge": { "command": "uv", "args": ["run", "forge"], "cwd": "/path/to/forge" } } } ``` ## Tools All tools take and return an explicit `model_id`. Failures come back as structured `{"ok": false, "error": {"code", "detail"}}` payloads (never raised exceptions), so an agent can read and recover. | Tool | Purpose | Key output | |---|---|---| | `create_model` | Create a model from an initial operation graph. | `model_id`, `bounding_box`, `num_operations` | | `modify_model` | Edit the graph: `append` / `update` / `remove` ops. Old state is preserved if the edit is invalid. | `bounding_box`, `applied_edits` | | `preview_model` | Render an isometric PNG (also returned inline for vision-capable agents). | `image_path` | | `validate_model` | Printability report (watertight, positive volume, bed fit). | `printable`, `errors`, `warnings`, `stats` | | `measure_model` | Exact BREP metrics. | `bounding_box`, `volume_mm3`, `surface_area_mm2`, `center_of_mass`, `num_solids` | | `export_model` | Write `model.stl` / `model.step`; STL is re-checked watertight. | `file_path`, `mesh_ok` | ### Operations The graph is an ordered list; op #1 must be a primitive. Supported ops: `box`, `cylinder`, `sphere`, `translate`, `boolean` (union/cut/intersect), `fillet`, `chamfer`, `hole`. Units are millimeters everywhere. Example — a phone stand: ```json [ { "id": "op1", "type": "box", "width": 80, "depth": 60, "height": 8 }, { "id": "op2", "type": "box", "width": 80, "depth": 10, "height": 70 }, { "id": "op3", "type": "fillet", "radius": 2.0, "edges": "all" } ] ``` ## Workspace Models and artifacts live under a workspace directory, one subdir per model: ``` <workspace>/<model_id>/ model.json # the operation graph — the single source of truth preview.png # from preview_model model.stl # from export_model model.step ``` The workspace defaults to `./forge_workspace/` and is overridable via the `FORGE_WORKSPACE` environment variable. ## Headless rendering `preview_model` uses PyVista/VTK offscreen. On macOS this works natively. On Linux (e.g. CI) VTK needs a GL context — install `libgl1` and run under `xvfb-run`, or call `pyvista.start_xvfb()` before rendering. ## Development ```bash uv run pytest -q ``` Tests mirror modules 1:1 plus `tests/test_tools.py` (tool-level integration) and a golden determinism snapshot in `tests/golden/`.