mcp-synology-container/SPEC.md

Projektspezifikation: mcp-synology-container

Ziel

Ein MCP-Server (Model Context Protocol) für die Verwaltung von Docker-Projekten auf einer Synology DiskStation via Container Manager. Der Server ermöglicht es Claude Desktop, Container-Projekte direkt zu verwalten – inklusive Lesen und Bearbeiten von docker-compose.yml-Dateien sowie Lifecycle-Management der Projekte und Container.

---

Technologie-Stack

Komponente	Entscheidung
Sprache	Python 3.12+
Package Manager	uv
MCP Framework	mcp (Anthropic MCP SDK)
HTTP-Client	httpx
Credential Storage	OS-Keyring (keyring library)
Config Format	YAML
Logging	stderr only (kein File-Logging)

---

Projektstruktur

mcp-synology-container/
├── src/
│   └── mcp_synology_container/
│       ├── __init__.py
│       ├── cli.py              # CLI-Einstiegspunkt: setup, check, serve
│       ├── config.py           # Config laden/speichern (YAML)
│       ├── auth.py             # Keyring-Integration, 2FA-Device-Token-Flow
│       ├── dsm_client.py       # HTTP-Client gegen Synology DSM API
│       └── modules/
│           ├── __init__.py
│           ├── projects.py     # SYNO.Docker.Project
│           ├── containers.py   # SYNO.Docker.Container
│           ├── compose.py      # Compose-Datei lesen/schreiben via FileStation API
│           └── images.py       # SYNO.Docker.Image
├── tests/
│   ├── __init__.py
│   ├── test_config.py
│   ├── test_auth.py
│   └── test_modules/
│       ├── test_projects.py
│       ├── test_containers.py
│       ├── test_compose.py
│       └── test_images.py
├── docs/
│   ├── setup.md
│   └── tools.md
├── pyproject.toml
├── README.md
└── CHANGELOG.md

---

pyproject.toml

[project]
name = "mcp-synology-container"
version = "0.1.0"
description = "MCP server for Synology Container Manager"
requires-python = ">=3.12"
dependencies = [
    "mcp>=1.0.0",
    "httpx>=0.27.0",
    "pyyaml>=6.0",
    "keyring>=25.0.0",
    "click>=8.1.0",
    "rich>=13.0.0",
]

[project.scripts]
mcp-synology-container = "mcp_synology_container.cli:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

---

Konfigurationsdatei

Pfad: ~/.config/mcp-synology-container/config.yaml

schema_version: 1
alias: HomeNAS                          # optionaler Anzeigename in Claude Desktop
connection:
  host: dsm.gecheckt.de
  port: 443
  https: true
  verify_ssl: true
compose_base_path: /volume1/docker      # Basis-Pfad für alle Compose-Projekte auf der NAS

Credentials (Host, Username, Password, optional Device-Token für 2FA) werden nicht in der Config-Datei gespeichert, sondern ausschließlich im OS-Keyring.

Credential-Auflösungsreihenfolge:

1. Umgebungsvariablen (SYNOLOGY_HOST, SYNOLOGY_USERNAME, SYNOLOGY_PASSWORD)
2. Config-Datei (nur nicht-sensitive Werte)
3. OS-Keyring (Credentials)

---

CLI-Befehle

mcp-synology-container setup

Interaktiver Setup-Wizard:

1. Fragt Host, Port, HTTPS, Benutzername, Passwort ab
2. Prüft ob 2FA aktiv ist – wenn ja: OTP abfragen, Device-Token speichern
3. Speichert Credentials im OS-Keyring
4. Schreibt config.yaml
5. Gibt fertiges Claude-Desktop-Config-Snippet aus:

{
  "mcpServers": {
    "synology-container": {
      "command": "mcp-synology-container",
      "args": ["serve"]
    }
  }
}

mcp-synology-container check

• Lädt Config und Credentials
• Stellt Testverbindung zur DSM API her
• Gibt Verbindungsstatus, DSM-Version und verfügbare APIs aus
• Exit-Code 0 = OK, 1 = Fehler

mcp-synology-container serve

• Startet den MCP-Server im stdio-Modus
• Registriert alle Tools
• Läuft bis SIGTERM/SIGINT

---

MCP-Tools

Projekte (projects.py)

Tool	Beschreibung	Confirmation required
list_projects	Alle Container-Manager-Projekte mit Status auflisten	nein
get_project_status	Detaillierten Status eines Projekts abrufen	nein
start_project	Projekt starten	nein
stop_project	Projekt stoppen	ja
redeploy_project	Projekt neu deployen (pull + down + up)	ja

Redeploy-Ablauf:

1. Compose-Datei lesen
2. docker compose pull (neues Image ziehen)
3. docker compose down
4. docker compose up -d
5. Deploy-Output streamen und zurückgeben

Container (containers.py)

Tool	Beschreibung	Confirmation required
list_containers	Alle Container eines Projekts auflisten	nein
get_container_status	Status, Uptime, Ressourcennutzung eines Containers	nein
get_container_logs	Log-Ausgabe abrufen (mit optionalem tail-Parameter)	nein
exec_in_container	Befehl in laufendem Container ausführen	ja

Compose-Datei (compose.py)

Compose-Dateien liegen unter {compose_base_path}/{projektname}/docker-compose.yml (oder compose.yml – beide Varianten werden erkannt).

Tool	Beschreibung	Confirmation required
read_compose	Compose-Datei eines Projekts lesen	nein
update_image_tag	Image-Tag eines Services aktualisieren	ja
update_env_var	Umgebungsvariable eines Services hinzufügen oder ändern	ja
update_compose	Beliebige Änderung an der Compose-Datei (vollständiger neuer Inhalt)	ja

Wichtig: Nach Änderungen an der Compose-Datei schlägt der Server automatisch vor, das Projekt neu zu deployen (redeploy_project).

Images (images.py)

Tool	Beschreibung	Confirmation required
check_image_updates	Verfügbare Updates für alle Images eines Projekts prüfen	nein

---

Authentifizierung & Session-Management

• Login via SYNO.API.Auth (DSM Web API)
• Session-Token wird in-memory gehalten (kein persistentes Speichern)
• Automatischer Re-Login bei abgelaufener Session (401-Response)
• 2FA: Device-Token-Flow
  • Device-Token wird im OS-Keyring gespeichert
  • Kein OTP-Prompt im laufenden Betrieb
  • Re-Bootstrap via setup wenn Token revoked

---

DSM API-Endpunkte

Funktion	API
Auth	SYNO.API.Auth
Projekte	SYNO.Docker.Project (list, start, stop, start_stream)
Container	SYNO.Docker.Container (list, start, stop, logs)
Container exec	SYNO.Docker.Container (exec)
Images	SYNO.Docker.Image (list)
Compose-Dateien lesen	SYNO.FileStation.Download
Compose-Dateien schreiben	SYNO.FileStation.Upload

---

Sicherheitsregeln

• Credentials niemals in Config-Datei, nur im OS-Keyring
• Confirmation-Pflicht für alle destruktiven Operationen (stop, redeploy, exec, compose-update)
• HTTPS mit Zertifikatsvalidierung standardmäßig aktiv (verify_ssl: true)
• Keine Secrets in stderr-Ausgaben

---

Referenzprojekte (zur Orientierung bei der Implementierung)

Projekt	Zweck
cmeans/mcp-synology (GitHub)	Referenz für Auth-Flow, Keyring-Integration, CLI-Struktur, Config-System
N4S4/synology-api docker_api.py (GitHub)	Referenz für DSM API-Calls (SYNO.Docker.*)