Initial implementation

2026-04-13 14:22:37 +02:00
commit a0c1b6ed93
26 changed files with 4125 additions and 0 deletions
@@ -0,0 +1,92 @@
+# 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