freecad-tool-server: Instructions file for Codex

AGENTS.md — FreeCAD Tool Server: Agent Quickstart

This file is the operating manual for any AI agent driving the FreeCAD tool server. It is intentionally named AGENTS.md (agent-agnostic). A copy is provided as CLAUDE.md so Claude Code picks it up automatically. Replace <PROJECT_DIR> with the absolute path where you cloned this repo.

This is an HTTP tool server that lets AI agents build 3D CAD geometry by calling REST endpoints. The server runs inside FreeCAD's bundled Python — not system Python.

---

Setup

Install dependencies (once)

"C:\Program Files\FreeCAD 1.1\bin\python.exe" -m pip install fastapi "uvicorn[standard]" "pydantic>=2.7"

Start the server

cd <PROJECT_DIR>
start.bat

Server runs at http://localhost:8000 · Swagger UI at http://localhost:8000/docs

Health check

GET http://localhost:8000/health

Returns {"success": true, "data": {"freecad_available": true, ...}}.

---

Every response has this envelope

{
  "success": true,
  "message": "Human-readable summary",
  "data": { ... },
  "warnings": [],
  "errors": []
}

Always check success before using data. On failure, errors[0] contains the reason.

---

Required first call

POST /document/create
{"name": "MyModel"}

Every geometry tool requires an active document. Call this before anything else.

---

Core modeling loop

create_document
  → add primitives (add_box / add_cylinder / add_cone / add_wing)
  → boolean ops (boolean_union / boolean_cut / make_hole)
  → inspect (get_shape_info / bounding_box)
  → finish (fillet_edges / chamfer_edges)
  → export (export_step)
  → validate (validate_step)

---

Most important endpoints

Path	What it does
POST /document/create	Open a document (required first)
POST /shapes/add_box	Box primitive
POST /shapes/add_cylinder	Cylinder (axis: x/y/z)
POST /shapes/add_wing	NACA 4-digit airfoil loft
POST /operations/boolean_union	Fuse two shapes
POST /operations/boolean_cut	Subtract one shape from another
POST /operations/make_hole	Drill a cylindrical hole
POST /operations/mirror	Mirror across xy/xz/yz plane (case-insensitive)
POST /operations/fillet_edges	Round edges (all, top, bottom, all_vertical)
POST /model/get_shape_info	Volume, faces, edge count for a named shape
POST /model/check_interference	Intersection volume of two shapes — detects unwanted collisions or missing engagement
POST /model/check_min_distance	Minimum surface-to-surface gap — verifies clearances
POST /model/screenshot	PNG render of a shape or the whole document (base64 or file)
GET /model/bounding_box	Axis-aligned bounding box of all shapes
POST /model/export_step	Export named shape as STEP file
POST /model/validate_step	Import STEP, verify solid count + watertight
POST /model/export_assembly	Combine multiple STEP files into one assembly
GET /document/status	List all shapes in session