Zum Inhalt

MCP v4 – vorbereitete Migration

Archivierter Vorbereitungsstand

Diese Seite beschreibt die Vorbereitung vor dem produktiven MCP-v4-Deployment. Der aktuelle MCP-Stand steht unter Infrastruktur → MCP-Server.

Stand: 09.08.2026

Status

Die MCP-v4-Migration ist vollständig vorbereitet, aber noch nicht produktiv eingespielt. Der laufende MCP-Server bleibt bis zum manuellen Deployment unverändert auf v3.

Das persistente Deployment-Paket liegt im Container 108 unter:

/home/mcp/mcp-v4-deploy/

Ziel der Migration

  • Monolithische index.js in klar getrennte Tool-Module aufteilen.
  • Zentralen Tool-Katalog mit Beschreibung, Kategorie und Risikostufe einführen.
  • Globale und subsystembezogene Arbeitsregeln aus dem Servercode auslagern.
  • Regeln zusätzlich als MCP Resources bereitstellen.
  • Admin-Seite um eine grafische Tool-Verwaltung erweitern.
  • Tools in der Admin-Seite einzeln aktivieren/deaktivieren können.
  • Audit-Logging so erweitern, dass nachvollziehbar ist, welche Tool-Aktionen eine KI tatsächlich ausgeführt hat.
  • Bestehendes Sicherheitsmodell unverändert beibehalten.

Neue Struktur

/opt/mcp-shell/
├── index.js
├── tool-registry.js
├── tools/
│   ├── infrastructure.js
│   ├── proxmox.js
│   ├── system.js
│   ├── files.js
│   ├── wiki.js
│   └── mikrotik.js
├── lib/
│   └── core.js
├── rules/
│   ├── global.md
│   ├── proxmox.md
│   └── mikrotik.md
├── tool-config.json
└── node_modules/

Die Admin-Anwendung bleibt getrennt unter /opt/mcp-admin/ und läuft weiterhin als root auf Port 3001.

Tool-Verwaltung

Der zentrale Tool-Katalog enthält alle derzeitigen 29 Tools. Für jedes Tool werden gespeichert:

  • Name
  • Kategorie
  • Beschreibung
  • Risikostufe (read, write, destructive, critical)

Die Admin-UI liest diesen Katalog und zeigt die Tools gruppiert mit Ein/Aus-Schaltern an.

Ein ausgeschaltetes Tool wird in tool-config.json unter disabled_tools eingetragen. Bei neuen MCP-Anfragen wird es nicht mehr registriert und damit nicht mehr angeboten. Zusätzlich bleibt die Laufzeitprüfung bestehen, sodass ein zwischenzeitlich deaktiviertes Tool serverseitig blockiert wird.

Das separate shell_execute-Gate bleibt unverändert bestehen. Ein Tool-Schalter ersetzt dieses Gate nicht.

Regeln und MCP Resources

Die bisherigen eingebetteten Arbeitsregeln werden nach rules/global.md ausgelagert und weiterhin als server.instructions übergeben.

Zusätzlich werden folgende MCP Resources angeboten:

  • diebrocks://rules/global
  • diebrocks://rules/proxmox
  • diebrocks://rules/mikrotik

Die veralteten IP-Hinweise aus den bisherigen eingebetteten Instructions werden entfernt. Aktuelle Infrastrukturwerte sollen über get_infrastructure bezogen werden.

Audit-Logging

Es gibt nur ein gemeinsames Audit-Log, kein separates Aktivitätslog.

Die Einträge werden als Tagesdateien gespeichert:

/var/log/mcp-audit/YYYY-MM-DD.jsonl

Pro Tool-Aufruf werden protokolliert:

  • Zeitstempel
  • Toolname
  • Status (ok, error, disabled)
  • Ausführungsdauer
  • aufrufende Identität/Client-Kontext
  • übergebene Parameter
  • Ergebnis bzw. Fehler

Sensible Felder wie secret, token, password, authorization, cookie, private key oder client secret werden automatisch als [REDACTED] maskiert.

Große Textwerte und Ergebnisse werden auf eine sinnvolle Maximalgröße begrenzt, damit einzelne Tool-Aufrufe das Log nicht unnötig aufblasen.

Die Tagesdateien werden automatisch bereinigt; Einträge älter als 7 Tage werden gelöscht.

Die Admin-Seite stellt das Audit-Log lesbar dar. Es kann zwischen 24 Stunden, 3 Tagen und 7 Tagen gewählt werden. Jeder Tool-Aufruf ist aufklappbar und zeigt Parameter, Ergebnis/Fehler, Dauer und Aufrufer.

Das MCP-Tool get_audit_logs bleibt vorhanden und liest die neuesten Einträge aus den Tagesdateien.

Sicherheitsmodell

Unverändert:

  • MCP-Prozess läuft als unprivilegierter Benutzer mcp.
  • Admin-UI läuft separat als root.
  • tool-config.json, shell_execute.enabled, MCP-Code und Admin-Code bleiben root-owned.
  • Die KI kann das vorbereitete Paket erstellen, aber nicht selbst produktiv installieren.
  • shell_execute bleibt nur durch menschlichen Admin freischaltbar.
  • Schreibpfad-Allowlist und Hard-Deny-Regeln bleiben erhalten.
  • Audit-Logging bleibt innerhalb des MCP-Servers gekapselt.

Deployment

Am Proxmox-Host kann die Migration mit einem einzelnen Befehl gestartet werden:

pct exec 108 -- bash /home/mcp/mcp-v4-deploy/deploy-mcp-v4.sh

Alternativ:

pct enter 108
bash /home/mcp/mcp-v4-deploy/deploy-mcp-v4.sh

Das Script:

  1. sichert den aktuellen v3-Code unter /root/mcp-v3-backup-<Zeitstempel>;
  2. prüft die JavaScript-Syntax;
  3. installiert die modularen MCP-Dateien;
  4. aktualisiert die Admin-UI;
  5. prüft den Tool-Katalog auf 29 Tools;
  6. startet mcp-shell und mcp-admin neu;
  7. prüft beide Services.

tool-config.json wird beim Deployment nicht überschrieben.

Nach dem Deployment prüfen

  • mcp-shell ist active.
  • mcp-admin ist active.
  • Admin-Seite unter https://mcp.diebrocks.com/admin erreichbar.
  • Tool-Liste enthält 29 Tools.
  • Testweise ein unkritisches Tool deaktivieren und prüfen, ob es bei einer neuen MCP-Verbindung nicht mehr angeboten wird.
  • Tool wieder aktivieren.
  • get_infrastructure, wiki_read und ein MikroTik-Lesetool testen.
  • Auf der Admin-Seite prüfen, ob diese Aufrufe im Audit-Log mit Parametern und Ergebnissen erscheinen.
  • Hauptdokumentation infrastruktur/mcp-server.md anschließend von v3 auf v4 aktualisieren.