Zielgruppe: die Person, die fbmcp installiert und betreibt und ihn nicht gebaut hat. Kenntnisse der Interna von Go oder Firebird sind nicht nötig. Stand vom 2026-11-16, Version 2027.2.24 (lokaler und entfernter Modus, HQbird-Installation, fbagent-Brücke, HQbird-Cluster, Ergebnisraster).

Kurzfassungen, nicht auf dieser Website: quickstart-en.md, quickstart-ru.md, quickstart-pt.md. Einzelheiten, auf Englisch: remote.md (entfernter Modus), agent-bridge.md (fbagent), tool-reference.md (jedes Werkzeug, sein Tier und seine Argumente), claude-desktop.md (Anbindung des Clients auf dem Entwicklungsrechner), ADRs in decisions/.


1. Was fbmcp ist

fbmcp ist ein MCP-Server für Firebird 2.5–5.0 unter Windows und Linux. Ein MCP-Client (Claude Desktop, Claude Code, Cursor, Codex, ZCode und andere) nutzt ihn, um als DBA zu arbeiten: Überwachung, Sicherungen und geprüfte Wiederherstellungen, SQL/DDL/DCL, Indizes, Benutzer und Rechte, firebird.conf, ein Planer, Migrationen, der fbagent von HQbird und der HQbird-Cluster. Er hat 122 Werkzeuge: 56 nur zum Lesen (Tier 0), 44 Tier 1, 21 Tier 2, 1 Tier 3 (deaktiviert). fb_demo_write ist nur da, wenn der Server mit FBMCP_DEMO_TOOLS=1 läuft.

Ein Client sieht nur die Werkzeuge, die er verwenden darf. Die Werkzeugliste blendet aus: Tier 3, Werkzeuge über dem maximalen Tier der Identität, fb_confirm und fb_cancel für eine Identität nur zum Lesen, die fbagent-Werkzeuge, solange agents: leer ist (fb_agent_discover und fb_agent_register bleiben), die Migrationswerkzeuge, solange keine Datenbank migrations_dir hat, und die Cluster-Werkzeuge, solange fbmcp.yaml keinen Abschnitt rcm: hat. Wenn ein Neuladen der Konfiguration diese Menge ändert, bekommt der Client eine neue Liste. Ein direkter Aufruf eines verborgenen Werkzeugs erhält eine klare Ablehnung.

Binärdatei Rolle
fbmcp Der Server. Standard: MCP über stdio (ein Client startet ihn). -serve: kein stdio, läuft als Dienst (Planer, Attach-Socket, HTTPS-Listener, falls konfiguriert). fbmcp bridge: ein stdio-Client für ein entferntes fbmcp
fbmcpctl Operator-CLI: doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. Dasselbe Programm wie fbmcp ctl
fbmcp-tray Windows-Tray: Popup Genehmigen/Ablehnen für Anforderungen, die einen Operator brauchen

Ein Kernel pro Zustandsverzeichnis. Ein zweiter Client mit derselben Konfiguration startet keinen zweiten Kernel: er hängt sich an den laufenden.

2. Sicherheitsmodell

Jeder Aufruf durchläuft Richtlinie → menschliche Bestätigung → geprüfte Ausführung.

Tier Was Wie es bestätigt wird
0 Lesezugriffe (von der Engine erzwungene Transaktionen nur zum Lesen) Nicht nötig
1 Routinemäßige Änderungen: DML/DDL, Sicherung, Benutzer, Rechte Im Kanal: der Client zeigt eine Anforderungs-ID und einen Token; die Person stimmt zu; der Client ruft fb_confirm auf
2 Hohe Auswirkung: Dienststeuerung, Wiederherstellung mit Ersetzen, firebird.conf, exklusives Fenster, Registrierung, Agent-Neustarts Nur außerhalb des Kanals: der Tray oder fbmcpctl approve. Der Client kann es nie genehmigen
3 Kritisch (fb_db_drop) Absichtlich deaktiviert
  • Tier 2 braucht gewöhnlich ein offenes Wartungsfenster (fb_window_open, auf derselben db) und eine geprüfte Sicherung, die jünger als 24 Stunden ist. Die Ablehnung sagt, was fehlt.
  • Eine ausstehende Anforderung läuft nach 15 Minuten ab. Ein Versuch über den falschen Kanal verbraucht sie nicht; fb_cancel entfernt sie.
  • Jedes Werkzeug mit Freigabe akzeptiert mode: preview: es zeigt die Auswirkung und tut nichts.
  • Jede Entscheidung (erlaubt, ausstehend, genehmigt, abgelehnt) geht in das audit.jsonl mit Hash-Kette.
  • Es gibt keine Webseite zur Genehmigung, und es darf nie eine geben: eine Seite, die das Modell erreichen kann, würde den Entwurf brechen.

3. Eine Einrichtung wählen

Einrichtung Wo fbmcp läuft Wann verwenden Abschnitt
A. Lokales stdio Ihr PC; der Client startet ihn Ein Administrator, Firebird auf diesem PC oder im LAN §6
B. Lokaler Dienst Windows-Dienst auf dem DB-Host (-serve) Zeitpläne müssen laufen, auch wenn kein Client offen ist §7
C. Entfernt Dienst auf dem Datenbankserver, HTTPS + API-Schlüssel Mehrere Administratoren, ein entfernter Server, autonome Agenten §8

In Einrichtung A lebt der Kernel nur, solange ein Client läuft, daher starten Zeitpläne nur dann. Verwenden Sie B oder C für unbeaufsichtigte Zeitpläne (nightly_verify).

fbmcp in HQbird. Einrichtungen von HQbird 2027 und fbagent installieren fbmcp standardmäßig: ein Dienst pro Server für alle Firebird-Linien, eingerichtet durch fbmcp ctl hqbird-install. Auf einem solchen Server folgen Sie nicht §6–§8; lesen Sie hqbird.md (Aufbau, entfernter Modus mit --allow-from, API-Schlüssel).

4. Die Binärdateien beschaffen

Voraussetzungen: Go ≥ 1.26.11 (ein älteres Go 1.21+ lädt go1.26.11 beim ersten Build von selbst herunter; dafür braucht es Internet), CGO ist nicht nötig; Firebird 2.5–5.0; fbagent ≥ 2.67 mit der Local API für die Agent-Werkzeuge (optional); fbagent 3.1.0+ und RCM 2027.5.11+ für die Cluster-Werkzeuge (optional).

Command
git clone https://github.com/alexeykovyazin/hqbirdmcp.git
cd hqbirdmcp
$env:CGO_ENABLED = "0"
go build -trimpath -ldflags "-s -w" -o dist/fbmcp.exe ./cmd/fbmcp
go build -trimpath -ldflags "-s -w" -o dist/fbmcpctl.exe ./cmd/fbmcpctl
go build -trimpath -ldflags "-s -w -H=windowsgui" -o dist/fbmcp-tray.exe ./cmd/fbmcp-tray

Linux-Binärdateien (Cross-Build von Windows, oder Build auf Linux ohne GOOS):

Command
$env:GOOS = "linux"; $env:GOARCH = "amd64"
go build -trimpath -ldflags "-s -w" -o dist/fbmcp ./cmd/fbmcp
go build -trimpath -ldflags "-s -w" -o dist/fbmcpctl ./cmd/fbmcpctl

Prüfsummen: Get-FileHash dist/* oder sha256sum dist/*. Weitere Ziele: packaging/README.md. Legen Sie die Binärdateien in einen eigenen Ordner (die Beispiele verwenden C:\fbmcp\): mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\ (Linux: install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/).

fbmcp ctl und fbmcpctl sind dasselbe Programm. fbmcpctl help listet die Befehle. Befehle, die die Konfiguration lesen, nehmen --config <file>; ohne ihn verwenden sie FBMCP_CONFIG, dann fbmcp.yaml im aktuellen Ordner, dann neben dem Programm, dann den HQbird-Standard (C:\HQbirdData\fbmcp\fbmcp.yaml, /etc/fbmcp/fbmcp.yaml) und geben using config <path> aus.

5. fbmcp.yaml konfigurieren

Vollständiges Beispiel: packaging/fbmcp.yaml.example. Minimale Windows-Konfiguration:

yaml
state:
  dir: C:\ProgramData\fbmcp\state
# secrets:
#   dir: C:\ProgramData\fbmcp\secrets   # setups B and C
instances:
  - id: fb5
    addr: localhost:3050
    bin_dir: C:\Program Files\Firebird\Firebird_5_0   # folder with gbak, gfix, gstat
    version: "5.0"
    service: FirebirdServerDefaultInstance            # Linux: firebird.opt_fb50
    service_user: SYSDBA                              # instance tools (fb_firebird_log, ...)
    service_secret_env: FBMCP_FB5_SERVICE_PW
databases:
  - id: main                 # tools and chats use the id, never the path
    instance: fb5
    path: D:\Data\main.fdb
    backup_dir: D:\fbmcp\backups
    work_dir: D:\fbmcp\work  # restore tests; Linux: not under /tmp
    ro_user: FBMCP_RO        # a read-only Firebird user
    ro_secret_env: FBMCP_MAIN_RO_PW
    admin_user: SYSDBA
    admin_secret_env: FBMCP_MAIN_ADMIN_PW
notify:
  webhook_url: ""            # optional: a chat webhook for pending requests
retention:
  keep_days: 0               # 0 = never delete backups

Geheimnisse. Das YAML enthält nur die Namen der Variablen. fbmcp sucht jeden Wert in dieser Reihenfolge: Umgebungsvariable → Datei <secrets.dir>/<NAME> → OS-Keyring des Kontos, unter dem fbmcp läuft.

Command
C:\fbmcp\fbmcpctl.exe secret set FBMCP_MAIN_RO_PW                                     # keyring of the current user (setup A)
C:\fbmcp\fbmcpctl.exe secret set --dir C:\ProgramData\fbmcp\secrets FBMCP_MAIN_RO_PW  # secrets dir (setups B, C)

Der Wert wird von stdin gelesen (tippen Sie ihn ein, dann Strg+Z, Enter; unter Linux Strg+D). Ein Dienstkonto (LocalSystem, NT SERVICE\...) sieht Ihren Keyring nicht: verwenden Sie secrets.dir für Dienste. Eine geänderte Geheimnisdatei gilt nach wenigen Sekunden ohne Neustart.

Benutzer nur zum Lesen. Legen Sie für ro_user einen eigenen Firebird-Benutzer an (SQL: quickstart-en.md: CREATE USER FBMCP_RO, GRANT SELECT auf jede Tabelle und unter Firebird 4.0+ eine Rolle mit MONITOR_ANY_ATTACHMENT, damit fb_sessions alle Verbindungen sieht). SYSDBA als RO-Benutzer ist nur für die Entwicklung; doctor warnt davor.

Live-Reload. fbmcp wendet Änderungen an fbmcp.yaml von selbst an (Dateiüberwachung), oder bei fb_config_reload. Kein Neustart von Client oder Prozess. Ein Reload wartet auf Jobs der geänderten Datenbanken (30 s) und wendet dann an. Abgelehnt: eine Änderung von state.dir, doppelte Datenbankpfade, eine unsichere Remote-Konfiguration.

Prüfung: C:\fbmcp\fbmcpctl.exe doctor muss mit doctor: green enden (entfernter Modus: doctor --remote, keine FAIL-Zeilen). Es legt einen fehlenden Zustands- ordner an, meldet sich an jeder Datenbank mit beiden Benutzern an, und jede FAIL-Zeile endet mit Fix: und dem auszuführenden Befehl.

6. Einrichtung A — lokales stdio

Verwenden Sie absolute Pfade. Setzen Sie listen nicht. Starten Sie den Client nach einer Konfigurationsänderung neu: Clients laden Server nur beim Start.

Client Wo Eintrag
Claude Desktop Einstellungen → Entwickler → Konfiguration bearbeiten (%APPDATA%\Claude\claude_desktop_config.json) "mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}}
Claude Code Befehlszeile claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml"
Cursor %USERPROFILE%\.cursor\mcp.json oder .cursor\mcp.json im Projekt dasselbe JSON wie bei Claude Desktop
Codex codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml oder %USERPROFILE%\.codex\config.toml [mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml']
ZCode .zcode\config.json im Projekt "mcp": {"servers": {"fbmcp": { ...same command and args... }}}

Die Kennwörter liegen im Keyring (§5), daher ist kein Block env nötig. Wenn Sie ein Kennwort trotzdem in einen Block env des Clients schreiben, halten Sie diese Datei aus git heraus.

Starten Sie danach den Tray für Genehmigungen der Tier 2: C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml (bei jeder Anmeldung: .\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).

Rauchtest im Client: “rufen Sie fb_ping auf” (zeigt den Servernamen und Ihre Identität mit ihrem maximalen Tier), dann “fb_db_list”, dann “fb_db_health für main”.

7. Einrichtung B — lokaler Windows-Dienst

PowerShell mit erhöhten Rechten:

Command
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp
  • Der Dienst führt fbmcp -serve als LocalSystem aus, startet bei einem Fehler neu und beendet sich sauber beim Dienststopp.
  • Verwenden Sie secrets.dir für Kennwörter (§5).
  • Sperren Sie den Ordner: nur SYSTEM und Administrators dürfen nach C:\fbmcp schreiben (das Skript gibt den Befehl icacls aus). Ein unter C:\ angelegter Ordner lässt jeden Benutzer die Dateien ändern, und der Dienst führt sie als SYSTEM aus.
  • Der Tray-Benutzer und lokale stdio-Clients brauchen Lesen und Schreiben auf dem Zustandsverzeichnis: icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M". Ein stdio- Client mit derselben Konfiguration hängt sich dann an den Dienst-Kernel.
  • Bereitschaft: C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml.
  • Protokoll: <state_dir>\fbmcp.log (5 × 10 MiB; Abstürze in fbmcp-crash.log).

Für einen Dienst, den Administratoren über das Netz erreichen, verwenden Sie Einrichtung C.

8. Einrichtung C — entfernt (HTTPS + API-Schlüssel)

Vollständiges Verfahren: remote.md. Kurzform:

Windows-Server (erhöht):

  1. Binärdateien und fbmcp.yaml in C:\fbmcp\ (Vorlage: remote.md §3: listen, tls, identities, allowed_origins, secrets.dir).
  2. C:\fbmcp\fbmcpctl.exe tls selfsign --out C:\fbmcp\tls --dns srv1 --ip 10.0.0.5 --grant "NT SERVICE\fbmcp" — notieren Sie den Pin sha256:....
  3. Ein Schlüssel pro Person oder Agent: C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets (einmal ausgegeben). Mit --config C:\fbmcp\fbmcp.yaml fügt er auch den Eintrag identities: hinzu und verwendet secrets.dir.
  4. Kennwörter und Agent-Token: fbmcpctl secret set --dir C:\ProgramData\fbmcp\secrets NAME.
  5. .\packaging\windows\install-remote.ps1 -Port 8443 -AllowFrom 10.0.0.0/24 -FirebirdService FirebirdServerDefaultInstance -WhatIf, dann ohne -WhatIf. Es legt den Dienst, die Firewall-Regel, die Ordner-ACLs und die Rechte des Firebird-Dienstes an.
  6. C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml → kein FAIL; curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz → ok.
  7. Tray für die genehmigende Person: .\packaging\windows\install-tray.ps1.

Linux-Server (root): kopieren Sie fbmcp, fbmcpctl und packaging/linux/, dann

Command
install -m 0755 fbmcp fbmcpctl /usr/local/bin/
sh packaging/linux/install-remote.sh --user firebird --port 8443 --allow-from 10.0.0.0/24 --dry-run
sh packaging/linux/install-remote.sh --user firebird --port 8443 --allow-from 10.0.0.0/24

Das Skript legt die Ordner an, das Zertifikat, eine erste Konfiguration mit einem Schlüssel admin (einmal ausgegeben), die systemd-Unit, die sudo-Regel für die Firebird-Unit und die ufw-Regel, und führt dann doctor --remote aus. Fügen Sie databases: und agents: zu /etc/fbmcp/fbmcp.yaml hinzu. Genehmigungen unter Linux (kein Tray): sudo -u firebird fbmcpctl approve [id]. Es findet /etc/fbmcp/fbmcp.yaml von selbst, fragt y/N (--yes fragt nicht), und --deny <id> --reason "..." lehnt ab.

Admin-PC:

  1. C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1 (der Schlüssel, den Sie erhalten haben).
  2. Jeder stdio-Client (Claude Desktop, Cursor, Codex, ZCode): der Eintrag aus §6 mit diesen args: ["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. Der Pin prüft den Serverschlüssel, daher braucht ein selbst signiertes Zertifikat kein CA-Setup.
  3. Claude Code kann sich auch direkt über HTTP verbinden (.mcp.json "type": "http", Header Authorization: Bearer ${FBMCP_KEY_SRV1}, NODE_EXTRA_CA_CERTS für ein selbst signiertes Zertifikat). Geben Sie den Schlüssel nicht mit claude mcp add --header weiter: er wird im Klartext gespeichert.
  4. Test: fb_ping zeigt den Servernamen und Ihre Identität.

Autonome Agenten (OpenClaw und Ähnliche): ein eigener Schlüssel mit apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32. Standardmäßig nur zum Lesen; jede Anforderung der Tier 1 wartet auf einen Operator, und fb_confirm vom Agenten wird abgelehnt. Grenzen: remote.md §6–7.

9. fbagent-Brücke und HQbird-Cluster (optional)

Die Agent-Werkzeuge (fb_agent_status, fb_agent_job_run, …) nutzen die Local API des fbagent von HQbird auf demselben Host. Sie sind aus, bis agents: einen Eintrag hat.

  1. Im Client: “fb_agent_discover”. Es listet die lokalen Agenten mit base_url, instance_id und dem vorgeschlagenen Token-Namen. Es liest nie Token.
  2. Der Operator speichert das local_api.token des Agenten (nicht agent.auth_token): fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Geben Sie nie einen Token in den Chat ein.
  3. Im Client: “fb_agent_register für diesen Agenten” → genehmigen Sie im Tray. fbmcp fügt den Eintrag agents: hinzu, lädt neu und prüft die Identität.
  4. Test: fb_agent_status, fb_agent_instances.

fb_agent_config_set (Änderung der Job-Einstellungen: Sicherung, Sweep, …) braucht außerdem config_path am Eintrag und Lesezugriff auf die laufende agent_config.json sowie das Recht, in ihrem Ordner Dateien anzulegen. Diese Datei enthält den Token und die Firebird- Anmeldeinformationen, daher ist diese Freigabe die Entscheidung des Operators (agent-bridge.md). Wenn die Agent-Prüfung fehlschlägt, schreibt das Werkzeug nichts.

HQbird-Cluster (RCM). Die Cluster-Werkzeuge rufen den Cluster-Manager von HQbird (hqbirdrcm) auf demselben Host auf. Sie erscheinen nur, wenn fbmcp.yaml einen Abschnitt rcm: hat (url, ca_file, user, password_env). Auf einem Linux-Server mit HQbird schreibt fbmcp ctl hqbird-install ihn aus /opt/hqbirdrcm/rcm.json und speichert das erste RCM-Kennwort im Geheimnis FBMCP_RCM_PASSWORD; andernorts fügen Sie den Abschnitt von Hand hinzu (tool-reference.md). Dann:

  1. fb_cluster_rcm_password: ersetzen Sie das erste RCM-Kennwort (Tier 1).
  2. Ein neuer Cluster: öffnen Sie auf jedem Host das Kopplungsfenster (fb_agent_cluster_pairing), starten Sie den RCM auf dem Master (fb_agent_cluster_rcm), verbinden Sie die Hosts (fb_cluster_link), legen Sie die Replikate an (fb_cluster_reinit, Tier 2) und vergleichen Sie die Daten (fb_cluster_verify). Schritte: prompts/cluster-setup.md.
  3. Cluster-Dienste (Switchover, Failover, Rejoin): fb_cluster_service zeigt sie und die Prüfungen; die Wechsel sind Tier 2. Schritte: prompts/cluster-services.md.

10. Täglicher Betrieb

Fragen Sie den Client in einfachen Worten; er wählt die Werkzeuge. Beispiele:

Aufgabe Werkzeuge
Läuft alles? fb_ping, fb_db_list, fb_db_health, fb_service_status
Daten lesen fb_query (nur zum Lesen, Zeilen + Plan + Statistiken je Tabelle; ein Raster in MCP-Apps-Clients); einen Entwurf prüfen mit fb_query_check
Sitzungen, lange Transaktionen fb_sessions, fb_transactions, fb_session_kill (Tier 1)
Langsame Abfrage fb_analyze_query, fb_index_advice → anwenden mit fb_write; fb_agent_perf_report
Sicherung fb_backup_start → Job-ID → fb_job_status
Eine Sicherung prüfen fb_restore_test (stellt in work_dir wieder her, markiert die Sicherung als geprüft)
Nächtliche Sicherung + Prüfung fb_schedule_create mit target=nightly_verify (einmal bestätigt; Einrichtung B oder C)
Schema / DDL fb_schema_list, fb_describe, fb_write (jede Anweisung wird eingeordnet und einem Tier zugewiesen), fb_diff_schema
Migrationen fb_migration_status, fb_migration_plan, fb_migration_apply
Serverkonfiguration fb_config_get, fb_config_diff, fb_config_set (Tier 2)
Protokolle fb_firebird_log
Kapazität fb_trends, fb_gstat, fb_index_stats
Cluster-Zustand fb_cluster_status, fb_cluster_service
Den Master verschieben fb_cluster_switchover (ohne Datenverlust) oder fb_cluster_failover (Master verloren), dann fb_cluster_rejoin (Tier 2)

Jobs sind asynchron: einreichen → fb_job_status. Jobs einer Datenbank laufen einzeln nacheinander. Ein Job übersteht einen Neustart von fbmcp nur als interrupted: reichen Sie ihn erneut ein, wenn er noch nötig ist.

fb_config_set ändert in firebird.conf nur die eigene Zeile (Kommentare, Einrückung und Zeilenenden bleiben), behält die alte Datei als firebird.conf.prev und startet Firebird nie neu. Neustart mit fb_service_restart (Tier 2): es wartet, bis der Dienst gestoppt ist und wieder läuft.

11. Aufgaben des Operators

Aufgabe Befehl
Anforderungen auflisten / genehmigen / ablehnen fbmcpctl approve; fbmcpctl approve <id>; fbmcpctl approve --deny <id> --reason "..." (oder der Tray)
Einen Schlüssel rotieren fbmcpctl apikey rotate alice --config <fbmcp.yaml> (der alte Schlüssel endet innerhalb von Sekunden)
Schlüssel auflisten fbmcpctl apikey list (Namen, Quellen, Tiers; nie Werte)
Eine Person entfernen löschen Sie den Eintrag identities:, dann fbmcpctl secret drop --dir <dir> NAME
Das Zertifikat erneuern fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ... (Pin unverändert, kein Neustart)
Die Audit-Kette prüfen fbmcpctl verify
Lebt der Kernel? fbmcpctl ping; fbmcpctl status (Offline-Lesen des Zustands)
Dienststeuerung erlauben packaging/posture/verify.ps1 oder verify.sh, dann fbmcpctl setup --write-posture
Upgrade Dienst (oder die Clients) stoppen, die Binärdateien ersetzen, starten, doctor
Entfernen Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux: remote.md §10. Behalten Sie das Zustandsverzeichnis (Audit), sofern der Eigentümer nichts anderes sagt

Nur der Entwicklungsrechner: .\packaging\rebuild-install.ps1 -Force baut dist\ neu, stoppt und ersetzt die laufenden Binärdateien (die alten bleiben als *.exe~), führt die Client-Konfigurationen zusammen und führt doctor aus.

12. Wiederherstellung nach Absturz und Neustart

Geprüft durch den Chaos-Prüfstand (internal/killharness).

Nach einem Absturz oder Kill Beim Neustart Aktion des Operators
Der Job lief oder wartete in der Warteschlange Als interrupted markiert; wird nie fortgesetzt Erneut einreichen, falls nötig
Ausstehende Anforderung, nicht bestätigt Aus state.json wiederhergestellt (TTL gilt weiter) Bestätigen oder ablaufen lassen
fb_restore_replace läuft Wird zu Ende geführt: Wiederherstellung, Validierung, Datenbank online; <db>.pre-restore bleibt fb_db_health prüfen; .pre-restore später löschen
fb_shutdown_window läuft Führt den Schritt gfix -online zu Ende Prüfen, ob online
Veraltete instance.lock Automatisch übernommen Keine
state.json beschädigt Der Kernel verweigert den Start; Kopie bleibt als state.json.corrupt-<ts> Prüfen; state.json reparieren oder absichtlich entfernen (fbmcpctl repair baut die Zeitplan-Freigaben aus dem Audit neu)
audit.jsonl beschädigt oder abgeschnitten Der Kernel verweigert den Start §13.2: als Manipulationssignal behandeln
Uhr zurückgestellt Der Planer überspringt; kein doppelter Lauf Keine
Prozess des Windows-Dienstes beendet Der SCM startet ihn in etwa 5 s neu Keine

Der Kernel fällt bei allem, dessen Unversehrtheit er nicht belegen kann, geschlossen aus. Eine Neustartschleife ist ein Befund: lesen Sie das Protokoll.

13. Ablaufpläne bei Vorfällen

13.1 Mit einer Datenbank stimmt etwas nicht

  1. fbmcpctl doctor --config <file>: Konfiguration, Geheimnisse, Firebird-Anmeldungen, Ordner, Lage, Zeitpläne. Jede FAIL-Zeile hat ein Fix:.
  2. fb_db_list → fb_db_health <db>; fb_service_status für die Instanz.
  3. fb_sessions, fb_transactions bei Problemen mit Attachments oder einer OAT-Lücke; fb_firebird_log bei Engine-Fehlern.

13.2 Verdacht auf Manipulation oder Beschädigung: zuerst das Audit

  1. fbmcpctl verify --config <file> → audit chain OK: N entries oder BROKEN mit dem Grund.
  2. Wenn es fehlschlägt: behalten Sie das ganze Zustandsverzeichnis (es ist der Beweis) und untersuchen Sie dann. Löschen Sie audit.jsonl nicht, um den Kernel zum Starten zu bringen.

13.3 Wiederherstellungsübung (jedes Quartal)

  1. fb_backup_start → fb_job_status = succeeded.
  2. fb_restore_test → die Sicherung ist geprüft.
  3. fb_window_open für die Datenbank.
  4. fb_restore_replace → außerhalb des Kanals genehmigen. Ausfallzeit bis online.
  5. Prüfung: fb_db_health, dann ein echtes Lesen (fb_schema_list, fb_info).
  6. Die alte Datei bleibt als <db>.pre-restore, bis Sie sie löschen.

13.4 Der Client kann sich nicht verbinden

  1. fbmcpctl ping --config <file>, fbmcpctl status --config <file>.
  2. Lesen Sie das MCP-Protokoll des Clients (stdio) oder <state_dir>\fbmcp.log / journalctl -u fbmcp (Dienst).
  3. “another fbmcp instance is active”: ein Kernel pro Zustandsverzeichnis. Clients an einer Pipe hängen sich von selbst an; ein zweiter Kernel scheitert absichtlich sofort.

In den Befehlen oben können Sie --config weglassen, wenn die Suche in §4 die Datei findet.

14. Fehlersuche

Symptom Bedeutung / Abhilfe
Werkzeuge erscheinen nicht JSON-Syntax, absolute Pfade, vollständiger Neustart des Clients; das MCP-Protokoll des Clients
Ein Werkzeug fehlt in der Liste Absichtlich verborgen (§1): über Ihrem maximalen Tier, kein Eintrag agents:, kein migrations_dir oder kein Abschnitt rcm:
Der Server beendet sich sofort fbmcpctl doctor; ein fehlendes Geheimnis; ein Dienst kann Ihren Keyring nicht lesen (verwenden Sie secrets.dir)
Tier 2 “confirmation rejected: channel policy” Im Chat erwartet. Genehmigen Sie im Tray oder mit fbmcpctl approve
Tier 2 “no open maintenance window” fb_window_open für dieselbe db, die Sie dem Werkzeug übergeben
fb_restore_replace abgelehnt: Vorbedingungen Braucht eine geprüfte Sicherung < 24 h: fb_backup_start + fb_restore_test, und ein Fenster
Dienststeuerung abgelehnt posture.verified fehlt (fbmcpctl setup --write-posture), oder das Konto hat keine Rechte am Firebird-Dienst
fb_config_set: kann nicht schreiben Das Konto darf diese Datei nicht ändern (Linux-Unit ProtectSystem=strict; Windows-ACL). Von Hand bearbeiten, oder siehe remote.md §8
Der Tray zeigt nichts Er zeigt nur Anforderungen, die einen Operator brauchen; prüfen Sie die Rechte des Tray-Benutzers am Zustandsverzeichnis und tray.log dort
401 (entfernt) Falscher Schlüssel, oder der Server hat ihn nicht geladen: apikey list, doctor --remote
403 (entfernt) Quell-IP nicht in allow_from / der Firewall, oder ein Origin-Header nicht in allowed_origins
429 (entfernt) Grenzen; warten Sie auf Retry-After
Pin stimmt nicht Der Serverschlüssel hat sich geändert; holen Sie den neuen Pin beim Administrator des Servers
agent-unreachable Agent-Dienst ausgefallen, local_api.enabled: false, oder falsche base_url (Standard 127.0.0.1:(10000 + firebird port))
agent-auth Der gespeicherte Token ist nicht das local_api.token des Agenten; setzen Sie ihn erneut
agent-timeout bei Neustarts agents[].timeout_seconds (130) muss größer sein als restart_timeout_seconds des Agenten (120)
Error loading plugin MySQLEngine … beim Attach Auf HQbird bedeutet das meist, dass die Datei nicht existiert; prüfen Sie den Pfad
Ein bloßes DROP INDEX in fb_write braucht ein Fenster Dort ist es Tier 2; verwenden Sie fb_index_drop (Tier 1; lehnt Constraint-Indizes ab)
Neuer Index wird nicht benutzt Statistiken berechnen (fb_index_rebuild action=statistics); ORDER BY … DESC braucht einen Index DESCENDING
Werkzeuge scheitern nur bei einer Datenbank Sie ist offline (fb_db_health); die Werkzeuge fallen je Datenbank zurück

15. Referenz des Zustandsverzeichnisses

Pfad Bedeutung
state.json (+ .tmp, .corrupt-*) Ausstehende Anforderungen, Jobs, Sicherungskatalog, Workflows, Zeitpläne. Beschädigt ⇒ verweigert den Start
audit.jsonl (+ .head) Audit-Protokoll mit Hash-Kette; .head erkennt ein Abschneiden
events.jsonl Job-Ereignisse (job.succeeded, job.failed mit der Meldung)
approvals\, denials\ Entscheidungen außerhalb des Kanals (Tray / fbmcpctl approve), verwendet innerhalb von ~2 s
instance.lock Sperre für einen Kernel
attach.addr, attach.token Attach-Endpunkt für weitere stdio-Clients
fbmcp.log, fbmcp-crash.log Dienstprotokoll (rotiert) und Absturzausgabe
query-log.jsonl Jeder Aufruf von fb_query
trends\ Sampler-Verlauf für fb_trends
config-journal\ Verlauf von fb_config_set (alter und neuer Wert)
posture.verified Markierung, die die Dienststeuerung erlaubt
tray.log Tray-Fehler

16. Stand des Durchgangs

Offen (M1): ein Durchgang auf einem frischen Windows-Host allein nach diesem Leitfaden. Befunde fließen in diese Datei zurück. Laborergebnisse für den entfernten Modus (Linux-Host, frische VM, Windows-Dienst): findings/phase12-lab-2026-11-03.md.