fbmcp: Installation und Betrieb
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 derselbendb) 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_cancelentfernt 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.jsonlmit 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).
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-trayLinux-Binärdateien (Cross-Build von Windows, oder Build auf Linux ohne
GOOS):
$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/fbmcpctlPrü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:
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 backupsGeheimnisse. 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.
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:
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp- Der Dienst führt
fbmcp -serveals LocalSystem aus, startet bei einem Fehler neu und beendet sich sauber beim Dienststopp. - Verwenden Sie
secrets.dirfür Kennwörter (§5). - Sperren Sie den Ordner: nur SYSTEM und Administrators dürfen nach
C:\fbmcpschreiben (das Skript gibt den Befehlicaclsaus). Ein unterC:\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 infbmcp-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):
- Binärdateien und
fbmcp.yamlinC:\fbmcp\(Vorlage: remote.md §3:listen,tls,identities,allowed_origins,secrets.dir). C:\fbmcp\fbmcpctl.exe tls selfsign --out C:\fbmcp\tls --dns srv1 --ip 10.0.0.5 --grant "NT SERVICE\fbmcp"— notieren Sie den Pinsha256:....- 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.yamlfügt er auch den Eintragidentities:hinzu und verwendetsecrets.dir. - Kennwörter und Agent-Token:
fbmcpctl secret set --dir C:\ProgramData\fbmcp\secrets NAME. .\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.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.- Tray für die genehmigende Person:
.\packaging\windows\install-tray.ps1.
Linux-Server (root): kopieren Sie fbmcp, fbmcpctl und packaging/linux/, dann
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/24Das 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:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(der Schlüssel, den Sie erhalten haben).- 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. - Claude Code kann sich auch direkt über HTTP verbinden (
.mcp.json"type": "http", HeaderAuthorization: Bearer ${FBMCP_KEY_SRV1},NODE_EXTRA_CA_CERTSfür ein selbst signiertes Zertifikat). Geben Sie den Schlüssel nicht mitclaude mcp add --headerweiter: er wird im Klartext gespeichert. - Test:
fb_pingzeigt 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.
- Im Client: “
fb_agent_discover”. Es listet die lokalen Agenten mitbase_url,instance_idund dem vorgeschlagenen Token-Namen. Es liest nie Token. - Der Operator speichert das
local_api.tokendes Agenten (nichtagent.auth_token):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Geben Sie nie einen Token in den Chat ein. - Im Client: “
fb_agent_registerfür diesen Agenten” → genehmigen Sie im Tray. fbmcp fügt den Eintragagents:hinzu, lädt neu und prüft die Identität. - 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:
fb_cluster_rcm_password: ersetzen Sie das erste RCM-Kennwort (Tier 1).- 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. - Cluster-Dienste (Switchover, Failover, Rejoin):
fb_cluster_servicezeigt 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
fbmcpctl doctor --config <file>: Konfiguration, Geheimnisse, Firebird-Anmeldungen, Ordner, Lage, Zeitpläne. Jede FAIL-Zeile hat einFix:.fb_db_list→fb_db_health <db>;fb_service_statusfür die Instanz.fb_sessions,fb_transactionsbei Problemen mit Attachments oder einer OAT-Lücke;fb_firebird_logbei Engine-Fehlern.
13.2 Verdacht auf Manipulation oder Beschädigung: zuerst das Audit
fbmcpctl verify --config <file>→audit chain OK: N entriesoderBROKENmit dem Grund.- Wenn es fehlschlägt: behalten Sie das ganze Zustandsverzeichnis (es ist der Beweis) und
untersuchen Sie dann. Löschen Sie
audit.jsonlnicht, um den Kernel zum Starten zu bringen.
13.3 Wiederherstellungsübung (jedes Quartal)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ die Sicherung ist geprüft.fb_window_openfür die Datenbank.fb_restore_replace→ außerhalb des Kanals genehmigen. Ausfallzeit bis online.- Prüfung:
fb_db_health, dann ein echtes Lesen (fb_schema_list,fb_info). - Die alte Datei bleibt als
<db>.pre-restore, bis Sie sie löschen.
13.4 Der Client kann sich nicht verbinden
fbmcpctl ping --config <file>,fbmcpctl status --config <file>.- Lesen Sie das MCP-Protokoll des Clients (stdio) oder
<state_dir>\fbmcp.log/journalctl -u fbmcp(Dienst). - “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.