cadquery/README.md

# CadQuery MCP Server

Ein MCP-Server (Model Context Protocol), der Claude ermöglicht, parametrische
3D-Modelle direkt über CadQuery-Python-Code zu erstellen und als STL-Dateien zu exportieren.
Zusätzlich ist CQ-editor als GUI-Vorschau-Tool integriert.

---

## Inhaltsverzeichnis

1. [Voraussetzungen](#1-voraussetzungen)
2. [Installation](#2-installation)
3. [Claude Desktop einbinden](#3-claude-desktop-einbinden)
4. [CQ-editor starten](#4-cq-editor-starten)
5. [Verwendung in Claude](#5-verwendung-in-claude)
6. [Projektstruktur](#6-projektstruktur)
7. [Fehlerbehebung](#7-fehlerbehebung)

---

## 1. Voraussetzungen

| Anforderung | Version | Hinweis |
|---|---|---|
| Windows 10/11 | 64-Bit | Getestet auf Windows 11 |
| Python | ≥ 3.10 | [python.org](https://www.python.org/downloads/) – „Add to PATH" aktivieren |
| Claude Desktop | aktuell | [claude.ai/download](https://claude.ai/download) |
| Git | optional | Für Versionsverwaltung |

> **Hinweis:** Python 3.13 wird vollständig unterstützt (CadQuery 2.7.0 liefert fertige Wheels).

---

## 2. Installation

### 2.1 Projektverzeichnis anlegen

```powershell
mkdir C:\Users\<Benutzername>\Documents\Claude\cadquery
cd    C:\Users\<Benutzername>\Documents\Claude\cadquery
```

### 2.2 Python Virtual Environment erstellen

```powershell
python -m venv .venv
```

Das erzeugt einen isolierten Python-Interpreter unter `.venv\`.

### 2.3 CadQuery, MCP-Server und CQ-editor installieren

```powershell
.venv\Scripts\pip install cadquery mcp[cli] cq-editor
```

Installierte Pakete (Auswahl):

| Paket | Version | Zweck |
|---|---|---|
| `cadquery` | 2.7.0 | Parametrisches CAD in Python (OpenCASCADE) |
| `cadquery-ocp` | 7.8.1 | OpenCASCADE Python-Bindings |
| `mcp` | 1.26.0 | Model Context Protocol SDK (FastMCP) |
| `cq-editor` | 0.6.2 | GUI-Editor mit Live-Vorschau (PyQt5) |

> **Downloadgröße:** ca. 150 MB (cadquery-ocp ~52 MB, PyQt5-Qt5 ~50 MB, casadi ~51 MB)
> Bei Verbindungsunterbrechung einfach erneut ausführen – pip setzt den Download fort.

### 2.4 Installation prüfen

```powershell
.venv\Scripts\python -c "import cadquery as cq; print('cadquery', cq.__version__)"
# Ausgabe: cadquery 2.7.0

.venv\Scripts\python -c "import cq_editor; print('cq-editor OK')"
# Ausgabe: cq-editor OK
```

### 2.5 Test-STL erzeugen

```powershell
.venv\Scripts\python -c "
import cadquery as cq
from cadquery import exporters
from pathlib import Path

output = Path.home() / '3d-models'
output.mkdir(exist_ok=True)
result = cq.Workplane('XY').box(20, 20, 10)
exporters.export(result, str(output / 'test_box.stl'))
print('OK:', output / 'test_box.stl')
"
```

Die STL-Datei wird in `C:\Users\<Benutzername>\3d-models\` gespeichert.

---

## 3. Claude Desktop einbinden

### 3.1 Konfigurationsdatei öffnen

```
%APPDATA%\Claude\claude_desktop_config.json
```

Unter Windows typischerweise:
```
C:\Users\<Benutzername>\AppData\Roaming\Claude\claude_desktop_config.json
```

### 3.2 CadQuery-Server eintragen

Den folgenden Block in `"mcpServers"` einfügen:

```json
{
  "mcpServers": {
    "cadquery": {
      "command": "C:\\Users\\<Benutzername>\\Documents\\Claude\\cadquery\\.venv\\Scripts\\python.exe",
      "args":    ["C:\\Users\\<Benutzername>\\Documents\\Claude\\cadquery\\server.py"]
    }
  }
}
```

> **Wichtig:** `<Benutzername>` durch den tatsächlichen Windows-Benutzernamen ersetzen.
> Backslashes müssen in JSON doppelt escapt werden (`\\`).

Vollständiges Beispiel mit OpenSCAD-Server:

```json
{
  "mcpServers": {
    "openscad": {
      "command": "C:\\Users\\thors\\Documents\\Claude\\openscad-mcp\\.venv\\Scripts\\python.exe",
      "args":    ["C:\\Users\\thors\\Documents\\Claude\\openscad-mcp\\server.py"]
    },
    "cadquery": {
      "command": "C:\\Users\\thors\\Documents\\Claude\\cadquery\\.venv\\Scripts\\python.exe",
      "args":    ["C:\\Users\\thors\\Documents\\Claude\\cadquery\\server.py"]
    }
  }
}
```

### 3.3 Claude Desktop neu starten

Nach dem Speichern der Config muss Claude Desktop **vollständig neu gestartet** werden.
Die MCP-Tools erscheinen dann automatisch in der Werkzeugliste.

---

## 4. CQ-editor starten

CQ-editor ist ein Qt-basierter GUI-Editor mit Live-3D-Vorschau.

### Starten über die Kommandozeile

```powershell
# Direkt über die installierte Executable:
C:\Users\<Benutzername>\Documents\Claude\cadquery\.venv\Scripts\cq-editor.exe

# Alternativ über Python:
.venv\Scripts\python -m cq_editor
```

### Startskript (optional)

Für einfacheres Starten kann eine Datei `start-cq-editor.bat` im Projektverzeichnis
angelegt werden:

```batch
@echo off
C:\Users\<Benutzername>\Documents\Claude\cadquery\.venv\Scripts\cq-editor.exe
```

### Workflow mit CQ-editor

1. CQ-editor starten
2. CadQuery-Code im Editor schreiben
3. **F5** drücken → Live-Vorschau rechts aktualisiert sich
4. Datei → Export → STL zum Speichern

---

## 5. Verwendung in Claude

### 5.1 Verfügbare MCP-Tools

Nach dem Neustart von Claude Desktop stehen drei Tools zur Verfügung:

#### `mcp__cadquery__render_stl`
Führt CadQuery-Python-Code aus und exportiert eine STL-Datei.

```
Parameter:
  code     : str  – CadQuery-Python-Code
  filename : str  – Ausgabedateiname (Standard: "model.stl")
```

#### `mcp__cadquery__preview_png`
Exportiert eine SVG-Vorschau des Modells.

```
Parameter:
  code     : str  – CadQuery-Python-Code
  filename : str  – Ausgabedateiname (Standard: "preview.png")
```

#### `mcp__cadquery__list_models`
Listet alle STL-Dateien im Output-Verzeichnis auf.

### 5.2 Code-Konventionen

Der MCP-Server erkennt das CadQuery-Ergebnis auf zwei Wegen:

**Option A — `show_object()` aufrufen (empfohlen, CQ-editor-kompatibel):**
```python
import cadquery as cq

result = cq.Workplane("XY").box(20, 20, 10)
show_object(result)
```

**Option B — Variable `result` verwenden:**
```python
import cadquery as cq

result = cq.Workplane("XY").box(20, 20, 10)
# "result" wird automatisch erkannt
```

### 5.3 Beispiele

**Einfacher Quader:**
```python
import cadquery as cq

result = cq.Workplane("XY").box(30, 20, 10)
show_object(result)
```

**Zylinder mit Bohrung:**
```python
import cadquery as cq

result = (
    cq.Workplane("XY")
    .cylinder(height=30, radius=15)
    .faces(">Z")
    .hole(10)
)
show_object(result)
```

**Parametrisches Modell:**
```python
import cadquery as cq

breite   = 40
hoehe    = 20
tiefe    = 10
radius   = 3

result = (
    cq.Workplane("XY")
    .box(breite, tiefe, hoehe)
    .edges("|Z")
    .fillet(radius)
)
show_object(result)
```

**Assembly (Baugruppe):**
```python
import cadquery as cq

box      = cq.Workplane("XY").box(20, 20, 10)
zylinder = cq.Workplane("XY").cylinder(15, 5)

asm = (
    cq.Assembly()
    .add(box,      name="basis",    loc=cq.Location((0, 0, 0)))
    .add(zylinder, name="zapfen",   loc=cq.Location((0, 0, 10)))
)
show_object(asm)
```

### 5.4 Output-Verzeichnis

STL-Dateien werden gespeichert in:
```
C:\Users\<Benutzername>\3d-models\
```

Diesen Pfad kann man über die Umgebungsvariable `CADQUERY_OUTPUT_DIR` überschreiben.

---

## 6. Projektstruktur

```
cadquery/
├── .venv/               # Python Virtual Environment (nicht ins Git)
├── server.py            # MCP-Server (FastMCP)
└── README.md            # Diese Datei
```

### server.py – Übersicht

```
_run_cadquery(code)      Führt CadQuery-Code aus, fängt show_object() ab
render_stl(code, fn)     Tool: exportiert STL über cadquery.exporters
preview_png(code, fn)    Tool: exportiert SVG-Vorschau
list_models()            Tool: listet STL-Dateien in OUTPUT_DIR
```

---

## 7. Fehlerbehebung

### „Kein CadQuery-Objekt gefunden"

Der Server konnte kein Ergebnis aus dem Code extrahieren.

**Lösung:** Am Ende des Codes explizit `show_object(result)` aufrufen oder das Ergebnis
in eine Variable namens `result` speichern.

### STL-Datei wird nicht erstellt

- Output-Verzeichnis prüfen: `C:\Users\<Benutzername>\3d-models\`
- Schreibrechte auf das Verzeichnis prüfen

### Claude Desktop zeigt keine MCP-Tools

1. `claude_desktop_config.json` auf korrekte Pfade und JSON-Syntax prüfen
2. Claude Desktop vollständig beenden (Taskleiste → Rechtsklick → Beenden)
3. Claude Desktop neu starten

### Download bricht ab (cadquery-ocp / PyQt5-Qt5)

Beide Pakete sind ca. 50 MB groß. Bei Abbruch einfach wiederholen:

```powershell
.venv\Scripts\pip install cadquery mcp[cli] cq-editor --retries 5
```

### CQ-editor startet nicht

```powershell
# Fehlerausgabe anzeigen:
.venv\Scripts\python -m cq_editor
```

Häufige Ursache: Fehlende Qt-Laufzeitbibliotheken → Visual C++ Redistributable
installieren: [aka.ms/vs/17/release/vc_redist.x64.exe](https://aka.ms/vs/17/release/vc_redist.x64.exe)

---

## Lizenz

MIT License — freie Nutzung, Modifikation und Weitergabe erlaubt.