Zum Inhalt

MCP – Recovery-Paket

Stand 08.09.2026: Für einen Neuaufbau von CT 108 liegt ein geprüftes, secret-freies Recovery-Paket direkt im Wiki-Repository.

Download

Das Archiv wird mit dem Wiki versioniert und durch Cloudflare Pages zusammen mit der Dokumentation bereitgestellt.

Enthalten

Das Paket enthält den für den aktuellen produktiven MCP benötigten Anwendungscode und die zugehörigen Service-Dateien:

/opt/mcp-shell/
  index.js
  tool-registry.js
  tool-config.json
  package.json
  package-lock.json
  lib/
  tools/
  rules/

/opt/mcp-admin/
  server.js
  policy-routes.js
  policy-client.js
  admin.html
  admin.css

/opt/mcp-audit-writer/
  audit-writer.js

/etc/systemd/system/
  mcp-shell.service
  mcp-admin.service
  mcp-audit-writer.service
  mcp-shell.service.d/30-ha-upstream.conf

Außerdem enthält das Archiv:

  • install.sh mit Vorprüfungen, Backup und Rollback bei Fehlern;
  • SHA256SUMS für alle enthaltenen Payload-Dateien;
  • README.md mit dem Restore-Ablauf;
  • templates/ha-upstream.env.example ohne echten Secret-Pfad.

Bewusst nicht enthalten

Folgende Daten gehören nicht in ein versioniertes Recovery-Paket und wurden vor dem Commit ausdrücklich ausgeschlossen:

  • /etc/mcp-shell/ha-upstream.env mit der echten HA-MCP-URL und dem Secret-Pfad;
  • SSH-Private-Keys;
  • known_hosts;
  • Cloudflare-Service-Tokens oder andere Zugangsdaten;
  • shell_execute.enabled;
  • Audit-Logs;
  • /root/-Backups und alte Deployment-Verzeichnisse;
  • node_modules;
  • das Wiki-Repository selbst.

Vor Erstellung des Archivs wurde zusätzlich nach privaten SSH-Key-Markern, JWT-artigen Tokens und einer echten HA_MCP_URL gesucht. Das Paket wurde danach erneut entpackt und gegen sein internes SHA256SUMS geprüft.

Voraussetzungen für einen Restore

Vor Ausführung des Installers muss der neue CT 108 vorbereitet sein:

  1. Debian, Node.js und npm sind installiert.
  2. Benutzer mcp besitzt UID 999.
  3. Primäre Gruppe mcp besitzt GID 991.
  4. /etc/mcp-shell/ha-upstream.env wurde separat und sicher wiederhergestellt.
  5. Die Secret-Datei gehört root:root und hat Modus 0600.
  6. SSH-Schlüssel und known_hosts wurden separat wiederhergestellt.
  7. Netzwerk und DNS funktionieren.

UID und GID

Der produktive Benutzer mcp hat UID 999, seine primäre Gruppe aber GID 991. Der Audit-Writer verwendet diese Gruppen-ID für den geschützten Unix-Socket. Ein Neuaufbau mit automatisch erzeugter GID 999 wäre deshalb nicht identisch zum Produktivsystem.

Restore

Archiv auf CT 108 übertragen und als root ausführen:

tar -xzf mcp-server-recovery-20260908-r1.tar.gz
cd mcp-server-recovery-20260908-r1
sha256sum -c SHA256SUMS
bash install.sh

Der Installer:

  1. prüft root, Node.js/npm, Benutzer/Gruppe und HA-MCP-Secret-Datei;
  2. verifiziert das interne SHA256-Manifest;
  3. sichert vorhandene MCP-, Admin-, Writer- und systemd-Dateien unter /root/mcp-recovery-preinstall-<Zeitstempel>;
  4. installiert den gesicherten Produktivcode root-owned;
  5. führt npm ci --omit=dev aus;
  6. prüft die zentralen JavaScript-Dateien mit node --check;
  7. stellt /var/log/mcp-audit/ mit root:mcp und Modus 0750 bereit;
  8. aktiviert und startet mcp-audit-writer, mcp-shell und mcp-admin;
  9. prüft, dass alle drei Dienste aktiv sind.

Bei einem Fehler nach Beginn des Austauschs versucht der Installer, die vorher gesicherten Dateien wiederherzustellen.

Was danach noch geprüft werden muss

Das Paket ersetzt keinen vollständigen Recovery-Test. Nach der Installation mindestens prüfen:

  • Cloudflare-Zugriff auf /mcp und /admin;
  • normales MCP-Lese-Tool;
  • Audit-v2-Eintrag;
  • Wiki-Zugriff;
  • Proxmox-/MikroTik-Lesezugriffe;
  • ha_search_tools über den zentralen MCP;
  • harmloser ha_call_read_tool-Aufruf;
  • Caller-Zuordnung im HA-Bridge-Audit;
  • Shell-Gate bleibt ohne menschliche Freigabe geschlossen.

Pflege

Das Recovery-Paket ist eine Momentaufnahme des produktiven Anwendungscodes. Nach Änderungen an MCP-Code, Admin-Oberfläche, Audit-Writer, systemd-Units oder HA-Bridge muss ein neues versioniertes Paket erzeugt und diese Seite auf die neue Revision aktualisiert werden.

Das alte Paket sollte als historische Wiederherstellungsversion im Git-Verlauf erhalten bleiben; der Download-Link auf dieser Seite zeigt jeweils auf die aktuell empfohlene Version.

Siehe auch: MCP-Neuinstallation, MCP-Server und Home Assistant Bridge.