mcp-synology-container/CLAUDE.md

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