# 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 Code einbinden](#3-claude-code-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 Code | aktuell | CLI-Tool von Anthropic |
| 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 Output-Verzeichnis anlegen

```powershell
mkdir models
```

STL-Dateien und Vorschauen werden in `cadquery\models\` gespeichert.

---

## 3. Claude Code einbinden

**Claude Code** (CLI) nutzt `settings.json` — **nicht** `claude_desktop_config.json`.

### 3.1 Konfigurationsdatei

```
C:\Users\<Benutzername>\.claude\settings.json
```

### 3.2 CadQuery-Server eintragen

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

```json
{
  "mcpServers": {
    "cadquery": {
      "type": "stdio",
      "command": "C:/Users/<Benutzername>/Documents/Claude/cadquery/.venv/Scripts/python.exe",
      "args": ["C:/Users/<Benutzername>/Documents/Claude/cadquery/server.py"],
      "env": {
        "CADQUERY_OUTPUT_DIR": "C:/Users/<Benutzername>/Documents/Claude/cadquery/models"
      }
    }
  }
}
```

> **Wichtig:** `<Benutzername>` durch den tatsächlichen Windows-Benutzernamen ersetzen.
> Pfade in `settings.json` werden mit Forward-Slashes (`/`) geschrieben.

### 3.3 Claude Code neu starten

Nach Änderungen an `settings.json` muss Claude Code **vollständig** neu gestartet werden
(nicht nur eine neue Konversation öffnen — die App selbst beenden und neu starten).
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:
.venv\Scripts\cq-editor.exe

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

### Workflow mit CQ-editor

1. CQ-editor starten
2. Datei aus `models\` öffnen (z.B. `box.py`)
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 Code stehen drei Tools zur Verfügung:

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

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

#### `mcp__cadquery__preview_png`
Exportiert eine SVG-Vorschau des Modells nach `models\`.

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

#### `mcp__cadquery__list_models`
Listet alle STL-Dateien in `models\` 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

**Offene Box mit parametrischen Maßen (siehe `models/box.py`):**
```python
import cadquery as cq

# Maße
breite      = 30   # mm (X)
tiefe       = 30   # mm (Y)
hoehe       = 20   # mm (Z)
wandstaerke = 2    # mm

result = (
    cq.Workplane("XY")
    .box(breite, tiefe, hoehe)
    .faces(">Z")
    .shell(-wandstaerke)
)

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)
```

**Quader mit abgerundeten Kanten:**
```python
import cadquery as cq

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

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

### 5.4 Output-Verzeichnis

STL-Dateien und SVG-Vorschauen werden gespeichert in:
```
cadquery\models\
```

Der Pfad wird über `CADQUERY_OUTPUT_DIR` in `settings.json` gesetzt.
Fallback (wenn nicht gesetzt): `cadquery\models\` relativ zu `server.py`.

---

## 6. Projektstruktur

```
cadquery/
├── .venv/               # Python Virtual Environment (nicht ins Git)
├── models/              # Generierte STL- und SVG-Dateien + Python-Modelle
│   └── box.py           # Beispiel: offene Box mit parametrischen Maßen
├── 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: `cadquery\models\` muss existieren
- Schreibrechte auf das Verzeichnis prüfen

### Claude Code zeigt keine MCP-Tools

1. `settings.json` auf korrekte Pfade und JSON-Syntax prüfen
2. Claude Code **vollständig** beenden (nicht nur Konversation schließen)
3. Claude Code neu starten
4. MCP-Server-Log prüfen: `%APPDATA%\Claude\logs\mcp-server-cadquery.log`

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