⚒️ Hephaestus

AI-driven CAD design for 3D printing. Describe a part in plain English — Claude generates CadQuery Python, the server executes it, and you get a printable STL/3MF in seconds.

---

Architecture

Hephaestus/
├── server/          # Python: FastMCP + FastAPI + CadQuery + Bedrock
└── web/             # Next.js 15 + Three.js + Zustand + Tailwind

User prompt
  → FastAPI POST /api/design
    → AWS Bedrock (Claude) → CadQuery Python script
      → subprocess executor (30s timeout)
        ✓ success  → STL file → /outputs/*.stl
        ✗ error    → feed error to Claude → retry (up to 3×)
  → Next.js UI → Three.js STL viewer
  → POST /api/export → 3MF (Bambu-ready)

MCP Tools (for AI clients like Cursor)

Tool	Input	Output
design_part	description: str	{ script, stl_path, stl_url, attempts }
refine_part	script: str, change_request: str	{ script, stl_path, stl_url, attempts }
export_3mf	stl_path: str	{ threemf_path, threemf_url }

---

Prerequisites

• Python 3.11+
• Node.js 20+
• AWS account with Bedrock access and Claude Sonnet 4 enabled
• CadQuery — see install note below

CadQuery Install Note

CadQuery depends on OCCT and is best installed via conda:

conda create -n hephaestus python=3.11
conda activate hephaestus
conda install -c conda-forge cadquery
pip install -r server/requirements.txt

Or via pip (may require system OCCT libraries):

pip install cadquery

---

Quick Start

1. Clone & configure

git clone <repo>
cd Hephaestus

# Server config
cp server/.env.example server/.env
# Edit server/.env — fill in your AWS credentials and BEDROCK_MODEL_ID

2. Start the Python server

cd server
pip install -r requirements.txt   # or use conda env above
python -m server.main
# → listening on http://localhost:8000

3. Start the web UI

cd web
npm install
npm run dev
# → http://localhost:3000

Open http://localhost:3000 — the forge is hot.

---

Environment Variables (server/.env)

Variable	Default	Description
AWS_REGION	us-east-1	AWS region
AWS_ACCESS_KEY_ID	—	AWS credentials
AWS_SECRET_ACCESS_KEY	—	AWS credentials
BEDROCK_MODEL_ID	us.anthropic.claude-sonnet-4-5-20250514-v1:0	Bedrock inference profile ARN or model ID
OUTPUTS_DIR	outputs	Directory for STL/3MF output (relative to workspace root)
MAX_RETRIES	3	Max LLM self-correction attempts per generation
EXECUTOR_TIMEOUT	30	CadQuery subprocess timeout in seconds
API_HOST	0.0.0.0	FastAPI bind host
API_PORT	8000	FastAPI bind port

---

API Reference

POST /api/design

Generate a new CadQuery script from a natural-language description.

// Request
{ "description": "A 40mm cube with rounded corners and a 10mm through-hole" }

// Response
{
  "script": "import cadquery as cq\n...",
  "stl_url": "/outputs/abc123.stl",
  "stl_path": "/abs/path/outputs/abc123.stl",
  "attempts": 1
}

POST /api/refine

Apply a change request to an existing script.

// Request
{ "script": "import cadquery as cq\n...", "change_request": "Add a 2mm fillet to all edges" }

POST /api/export

Convert STL to Bambu-compatible 3MF.

// Request
{ "stl_path": "/abs/path/outputs/abc123.stl" }

// Response
{ "threemf_url": "/outputs/def456.3mf", "threemf_path": "..." }

GET /outputs/{filename}

Download a generated STL or 3MF file.

GET /api/health

{ "status": "ok", "forge": "hot" }

---

Using with Cursor (MCP client)

Add to your Cursor MCP config:

{
  "mcpServers": {
    "hephaestus": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Then in Cursor chat: "Use design_part to create a 50mm gear with 16 teeth"

---

Self-Correction Loop

When CadQuery execution fails, the error is fed back to Claude automatically:

Attempt 1: Claude generates script → subprocess fails
           Error: "AttributeError: 'Workplane' has no attribute 'extrude'"
Attempt 2: Claude sees error + original script → corrects → re-executes
Attempt 3: (if still failing) → final attempt
           → RuntimeError returned to UI if all attempts fail

The number of retries is controlled by MAX_RETRIES (default: 3).

---

Tech Stack

Layer	Technology
CAD engine	CadQuery
LLM	AWS Bedrock / Claude Sonnet 4
MCP server	FastMCP
REST API	FastAPI + Uvicorn
3MF packaging	trimesh + zipfile
Web framework	Next.js 15
3D viewer	React Three Fiber + Drei
State	Zustand
Animation	Framer Motion
Styling	Tailwind CSS