# CLAUDE.md – Arbeitsanweisung für mcp-synology-container

## Deine Aufgabe

Implementiere das Projekt `mcp-synology-container` vollständig gemäß `SPEC.md`.

Lies `SPEC.md` jetzt vollständig, bevor du anfängst.

---

## Referenzmaterial

Im Ordner `reference/` findest du zwei Referenzprojekte. Nutze sie aktiv:

### `reference/cmeans/`
Geklontes Repo von `cmeans/mcp-synology` (GitHub).
Übernimm daraus die Implementierungsmuster für:
- Auth-Flow und 2FA-Device-Token-Flow (`auth.py`)
- OS-Keyring-Integration (`keyring` library)
- CLI-Struktur mit `click` (`cli.py`)
- Config laden/speichern mit YAML (`config.py`)
- Credential-Auflösungsreihenfolge (env vars → config → keyring)
- `setup`-Wizard mit `rich` für formatierte Ausgabe
- Generierung des Claude-Desktop-Config-Snippets

Passe alle übernommenen Muster an unseren Use-Case an.
Kopiere keinen Code blind – verstehe ihn und adaptiere ihn.

### `reference/n4s4/docker_api.py`
Einzelne Datei aus `N4S4/synology-api` (GitHub).
Nutze sie als Referenz für die konkreten DSM API-Calls:
- Wie `SYNO.Docker.Project` aufgerufen wird (list, start, stop)
- Wie `SYNO.Docker.Container` aufgerufen wird (list, logs, exec)
- Wie `SYNO.Docker.Image` aufgerufen wird (list)
- Welche Parameter und Response-Strukturen die APIs erwarten

Implementiere **keinen** eigenen Wrapper um `synology-api` –
baue einen eigenen schlanken HTTP-Client in `dsm_client.py` mit `httpx`.

---

## Reihenfolge der Implementierung

Arbeite in dieser Reihenfolge. Schließe jeden Schritt vollständig ab bevor du weitermachst:

1. **Projektstruktur anlegen** – alle Ordner und leere `__init__.py`-Dateien, `pyproject.toml`
2. **`config.py`** – Config laden, speichern, validieren
3. **`auth.py`** – Keyring-Integration, Login gegen DSM API, 2FA-Device-Token-Flow
4. **`dsm_client.py`** – HTTP-Client mit Session-Management, Auto-Re-Login
5. **`cli.py`** – `setup`, `check`, `serve` Befehle
6. **`modules/projects.py`** – SYNO.Docker.Project Tools
7. **`modules/containers.py`** – SYNO.Docker.Container Tools
8. **`modules/compose.py`** – Compose-Datei lesen/schreiben via FileStation API
9. **`modules/images.py`** – SYNO.Docker.Image Tools
10. **Tests** – für jeden Schritt
11. **`README.md`** – Installationsanleitung und Tool-Übersicht
12. **`docs/setup.md`** und **`docs/tools.md`**

---

## Wichtige Implementierungsregeln

- **Confirmation vor destruktiven Operationen:** `stop_project`, `redeploy_project`,
  `exec_in_container`, `update_image_tag`, `update_env_var`, `update_compose` müssen
  eine Bestätigung vom Nutzer einholen bevor sie ausgeführt werden. Nutze dafür den
  MCP-eigenen `confirm`-Mechanismus.

- **Nach Compose-Änderungen:** Immer automatisch `redeploy_project` vorschlagen.

- **Fehlerbehandlung:** Alle DSM API-Fehler sauber abfangen und als verständliche
  Fehlermeldung zurückgeben. Keine Python-Stacktraces zum Nutzer.

- **Keine Secrets in Logs:** Passwörter, Tokens und Session-IDs niemals in
  stderr-Ausgaben schreiben.

- **HTTPS:** `verify_ssl: true` ist der Standard. Nur auf expliziten Wunsch deaktivierbar.

- **Compose-Pfade:** Beide Varianten erkennen – `docker-compose.yml` und `compose.yml`.

- **Type Hints:** Konsequent in allen Funktionen verwenden.

- **Docstrings:** Für alle öffentlichen Funktionen und Klassen.

---

## Projekt-Konventionen

- Sprache: Python 3.12+
- Formatter: `ruff format`
- Linter: `ruff check`
- Tests: `pytest`
- Alle Texte (Docstrings, Kommentare, README): Englisch