93 lines
3.4 KiB
Markdown
93 lines
3.4 KiB
Markdown
# 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
|