synology-chat-hermes-mcp

English · 繁體中文

Ein eingeschränkter FastMCP HTTP-Server, der einen festgelegten Synology NAS SMB-Freigabe für KI-Agenten als Lese-/Schreib-Dateiwerkzeuge bereitstellt – mit strenger Pfadisolierung, Größenbeschränkungen und eingebauter Ablehnung von aktiven Inhalten.

Ursprünglich als Dateikanal für eine familiäre Hermes-Bereitstellung (Steuerungsagent → MCP → SMB3 → NAS) entwickelt. Funktioniert mit jedem MCP-Client (Hermes, Claude usw.).

Warum es das gibt

KI-Agenten mit Dateizugriff sind nur sicher, wenn der Zugriff begrenzt ist. Dieser Server:

• Isoliert jeden Pfad auf eine festgelegte Freigabe (NAS_SHARE). Pfad-Traversal (.., absolute Pfade, Symlink/Reparse-Point-Escape) wird vor jedem SMB-Aufruf abgelehnt.

• Lehnt öffentliche WAN-Server ab — NAS_SERVER muss eine private, link-lokale oder Tailscale (100.64.0.0/10) Literal-IP sein. DNS-Namen und öffentliche IPs werden abgelehnt.

• Speichert niemals Anmeldedaten — das SMB-Passwort wird beim Start aus einer Docker-Secret-Datei gelesen (NAS_PASSWORD_FILE), niemals aus Umgebungsvariablen oder Code.

• Blockiert aktive Inhalte — DOCX/XLSX/PDF-Schreiber erstellen nur bereinigte Dokumente; Binär-Uploads werden auf Makros, externe Verknüpfungen und Skripte geprüft; Erweiterungs-/Medientyp-Konflikte werden abgelehnt.

• Begrenzt alles — Dateigröße, Binärgröße, Dokumentzeichen, Tabellenzellen, Bildpixel, Suchergebnisse haben alle feste Grenzen.

• Prüft Operationen — jede Änderung wird an ein JSONL-Prüfprotokoll angehängt.

Related MCP server: MCP File System Server

Architektur

Hermes (or any MCP client)
  → HTTP :8000/mcp (FastMCP, streamable HTTP)
    → NasService (validation, limits, audit)
      → SMBBackend (smbprotocol, SMB3, encryption+signing required)
        → Synology NAS share

Werkzeuge

Bekannte Einschränkung: create_directory prüft das Elternverzeichnis vor makedirs, daher gibt ein mehrstufiger Pfad, dessen erstes Segment nicht existiert, not_found zurück, selbst mit parents=True. Erstellen Sie jeweils eine Ebene.

Schnellstart

cp .env.example .env   # set NAS_SERVER (Tailscale/private IP), NAS_USERNAME
# provide the SMB password as a docker secret:
printf '%s' 'YOUR_SMB_PASSWORD' > ./synology_password
chmod 600 ./synology_password

docker build -t nas-mcp .
docker run -d --name nas-mcp \
  --env-file .env \
  -v "$PWD/synology_password:/run/secrets/synology_password:ro" \
  -v nas-mcp-audit:/var/log/nas-mcp \
  -p 8000:8000 \
  nas-mcp

Gesundheitsprüfung:

curl -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"health","arguments":{}}}'

Hermes MCP-Konfiguration

mcp_servers:
  nas-mcp:
    type: http
    url: http://nas-mcp:8000/mcp

Tests ausführen

python -m nas_mcp.smoke   # exercises the full tool chain against the live share

Umgebungsreferenz

Sicherheitshinweise

• Das SMB-Passwort ist das einzige Geheimnis im System und befindet sich nur in der Docker-Secret-Datei. Nichts ist fest codiert, nichts wird im Klartext in .env gespeichert, außer nicht-geheimen Tuning-Werten (und .env wird von git ignoriert).

• In der Produktion an eine private Schnittstelle binden; :8000 nicht öffentlich zugänglich machen.

• Der Freigabename und der SMB-Benutzer sind Konfiguration (NAS_SHARE, NAS_USERNAME) – setzen Sie sie pro Bereitstellung; nichts im Code nimmt einen bestimmten Wert an.

Lizenz

MIT