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

Related MCP server: openscad-mcp

Install

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

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:

{
  "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.

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:

[
  { "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

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/.