fbmcp: installatie en gebruik
Doelgroep: de persoon die fbmcp installeert en draait, en het niet heeft gebouwd. Kennis van de interne details van Go of Firebird is niet nodig. Stand van 2026-11-16, versie 2027.2.24 (lokale en externe modus, HQbird-installatie, fbagent-brug, HQbird-cluster, resultatenraster).
Korte versies, niet op deze site: quickstart-en.md, quickstart-ru.md,
quickstart-pt.md. Details, in het Engels: remote.md (externe
modus), agent-bridge.md (fbagent),
tool-reference.md (elke tool, de Tier en de argumenten),
claude-desktop.md (clientkoppeling op de ontwikkelhost),
ADR’s in decisions/.
1. Wat fbmcp is
fbmcp is een MCP-server voor Firebird 2.5–5.0 op Windows en Linux. Een
MCP-client (Claude Desktop, Claude Code, Cursor, Codex, ZCode, andere)
gebruikt hem om als DBA te werken: bewaking, back-ups en geverifieerde
herstelacties, SQL/DDL/DCL, indexen, gebruikers en rechten, firebird.conf, een
planner, migraties, de HQbird-fbagent en de HQbird-cluster. Hij heeft
122 tools: 56 alleen-lezen (Tier 0), 44 Tier 1, 21 Tier 2, 1 Tier 3
(uitgeschakeld). fb_demo_write is er alleen wanneer de server draait met
FBMCP_DEMO_TOOLS=1.
Een client ziet alleen de tools die hij kan gebruiken. De toollijst verbergt:
Tier 3, tools boven de maximale Tier van de identiteit, fb_confirm en
fb_cancel voor een alleen-lezen identiteit, de fbagent-tools zolang
agents: leeg is (fb_agent_discover en fb_agent_register blijven), de
migratietools zolang geen database migrations_dir heeft, en de clustertools
zolang fbmcp.yaml geen sectie rcm: heeft. Wanneer een herlaad van de
config deze verzameling wijzigt, krijgt de client een nieuwe lijst. Een
directe aanroep van een verborgen tool krijgt een duidelijke weigering.
| Binair bestand | Rol |
|---|---|
fbmcp |
De server. Standaard: MCP over stdio (een client start hem). -serve: geen stdio, draait als een service (planner, attach-socket, HTTPS-listener indien geconfigureerd). fbmcp bridge: een stdio-client voor een externe fbmcp |
fbmcpctl |
Operator-CLI: doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. Hetzelfde programma als fbmcp ctl |
fbmcp-tray |
Windows-systeemvak: Approve/Deny-pop-up voor verzoeken die een operator nodig hebben |
Eén kernel per statusmap. Een tweede client met dezelfde config start geen tweede kernel: hij koppelt aan de draaiende.
2. Veiligheidsmodel
Elke aanroep doorloopt beleid → menselijke bevestiging → geaudite uitvoering.
| Tier | Wat | Hoe het wordt bevestigd |
|---|---|---|
| 0 | Lezen (alleen-lezen transacties, afgedwongen door de engine) | Niet nodig |
| 1 | Routinematige wijzigingen: DML/DDL, back-up, gebruikers, rechten | In het kanaal: de client toont een verzoek-id en een token; de persoon stemt in; de client roept fb_confirm aan |
| 2 | Grote impact: servicebeheer, herstel-vervanging, firebird.conf, exclusief venster, registratie, agent-herstarts |
Alleen buiten het kanaal: het systeemvak of fbmcpctl approve. De client kan het nooit goedkeuren |
| 3 | Kritiek (fb_db_drop) |
Uitgeschakeld door het ontwerp |
- Tier 2 heeft meestal een open onderhoudsvenster nodig (
fb_window_open, op dezelfdedb) en een geverifieerde back-up jonger dan 24 uur. De weigering zegt wat ontbreekt. - Een openstaand verzoek verloopt na 15 minuten. Een poging via het verkeerde kanaal verbruikt het niet;
fb_cancelverwijdert het. - Elke bewaakte tool accepteert
mode: preview: hij toont de impact en doet niets. - Elke beslissing (toegestaan, in afwachting, goedgekeurd, geweigerd) gaat naar de hash-geketende
audit.jsonl. - Er is geen goedkeuringswebpagina, en die mag er nooit komen: een pagina die het model kan bereiken zou het ontwerp breken.
3. Een opzet kiezen
| Opzet | Waar fbmcp draait | Gebruik hem wanneer | Sectie |
|---|---|---|---|
| A. Lokale stdio | Uw pc; de client start hem | Eén beheerder, Firebird op deze pc of in het LAN | §6 |
| B. Lokale service | Windows-service op de databasehost (-serve) |
Planningen moeten lopen als er geen client open is | §7 |
| C. Extern | Service op de databaseserver, HTTPS + API-sleutels | Meerdere beheerders, een verre server, autonome agents | §8 |
In opzet A leeft de kernel alleen zolang een client draait, dus de
planningen gaan alleen dan af. Gebruik B of C voor onbeheerde planningen
(nightly_verify).
fbmcp in HQbird. HQbird 2027-installaties en fbagent installeren fbmcp
standaard: één service per server voor alle Firebird-lijnen, ingericht door
fbmcp ctl hqbird-install. Op zo’n server volgt u §6–§8 niet; lees
hqbird.md (indeling, externe modus met --allow-from, API-sleutels).
4. De binaire bestanden ophalen
Vereisten: Go ≥ 1.26.11 (een oudere Go, 1.21 of nieuwer, downloadt go1.26.11 zelf bij de eerste build; dit vereist internet), CGO is niet nodig; Firebird 2.5–5.0; fbagent ≥ 2.67 met de Local API voor de agent-tools (optioneel); fbagent 3.1.0+ en RCM 2027.5.11+ voor de clustertools (optioneel).
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-binaries (kruiscompilatie vanaf Windows, of bouwen op Linux zonder
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/fbmcpctlControlesommen: Get-FileHash dist/* of sha256sum dist/*. Meer
doelplatformen: packaging/README.md. Zet de binaries in een eigen map
(de voorbeelden gebruiken C:\fbmcp\): mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\
(Linux: install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/).
fbmcp ctl en fbmcpctl zijn hetzelfde programma. fbmcpctl help somt de
commando’s op. Commando’s die de config lezen nemen --config <file>; zonder
gebruiken ze FBMCP_CONFIG, daarna fbmcp.yaml in de huidige map, daarna
naast het programma, daarna de HQbird-standaard
(C:\HQbirdData\fbmcp\fbmcp.yaml, /etc/fbmcp/fbmcp.yaml), en tonen
using config <path>.
5. fbmcp.yaml configureren
Volledig voorbeeld: packaging/fbmcp.yaml.example.
Minimale Windows-configuratie:
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 backupsGeheimen. De YAML bevat alleen de namen van variabelen. fbmcp zoekt
elke waarde in deze volgorde: omgevingsvariabele → bestand
<secrets.dir>/<NAME> → sleutelring van het besturingssysteem van het
account dat fbmcp draait.
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)De waarde wordt van stdin gelezen (typ hem, dan Ctrl+Z, Enter; Linux Ctrl+D).
Een serviceaccount (LocalSystem, NT SERVICE\...) kan uw sleutelring niet
zien: gebruik secrets.dir voor services. Een gewijzigd geheim-bestand geldt
binnen enkele seconden, zonder herstart.
Alleen-lezen gebruiker. Maak een aparte Firebird-gebruiker voor
ro_user (SQL: quickstart-en.md:
CREATE USER FBMCP_RO, GRANT SELECT op elke tabel, en op Firebird 4.0+
een rol met MONITOR_ANY_ATTACHMENT zodat fb_sessions alle verbindingen
ziet). SYSDBA als RO-gebruiker is alleen voor ontwikkeling; doctor
waarschuwt ervoor.
Live herladen. fbmcp past wijzigingen in fbmcp.yaml zelf toe
(bestandsbewaking), of bij fb_config_reload. Geen herstart van client of
proces. Een herlaad wacht op jobs op de gewijzigde databases (30 s) en past
dan toe. Geweigerd: een wijziging van state.dir, dubbele databasepaden,
een onveilige externe config.
Controle: C:\fbmcp\fbmcpctl.exe doctor moet eindigen met doctor: green
(externe modus: doctor --remote, geen FAIL-regels). Het maakt een
ontbrekende statusmap, meldt zich aan bij elke database met beide
gebruikers, en elke FAIL-regel eindigt met Fix: en het commando om uit te
voeren.
6. Opzet A — lokale stdio
Gebruik absolute paden. Stel listen niet in. Herstart de client na een
configuratiewijziging: clients laden servers alleen bij de start.
| Client | Waar | Ingang |
|---|---|---|
| Claude Desktop | Instellingen → Ontwikkelaar → Configuratie bewerken (%APPDATA%\Claude\claude_desktop_config.json) |
"mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}} |
| Claude Code | opdrachtregel | claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml" |
| Cursor | %USERPROFILE%\.cursor\mcp.json of .cursor\mcp.json in het project |
dezelfde JSON als Claude Desktop |
| Codex | codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml of %USERPROFILE%\.codex\config.toml |
[mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml'] |
| ZCode | .zcode\config.json in het project |
"mcp": {"servers": {"fbmcp": { ...same command and args... }}} |
Wachtwoorden staan in de sleutelring (§5), dus geen env-blok nodig. Als u
toch een wachtwoord in een env-blok van de client zet, houd dat bestand
buiten git.
Start daarna het systeemvak voor Tier 2-goedkeuringen:
C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml (bij elke aanmelding:
.\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).
Rooktest in de client: “roep fb_ping aan” (toont de servernaam en uw
identiteit met de maximale Tier), daarna “fb_db_list”, daarna
“fb_db_health voor main”.
7. Opzet B — lokale Windows-service
Verhoogde PowerShell:
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp- De service draait
fbmcp -serveals LocalSystem, herstart bij een fout en stopt netjes bij een servicestop. - Gebruik
secrets.dirvoor wachtwoorden (§5). - Vergrendel de map: alleen SYSTEM en Administrators mogen schrijven in
C:\fbmcp(het script toont heticacls-commando). Een map onderC:\laat elke gebruiker de bestanden wijzigen, en de service voert ze uit als SYSTEM. - De systeemvakgebruiker en lokale stdio-clients hebben lezen/schrijven nodig op de statusmap:
icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M". Een stdio-client met dezelfde config koppelt dan aan de servicekernel. - Gereedheid:
C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml. - Log:
<state_dir>\fbmcp.log(5 × 10 MiB; crashes infbmcp-crash.log).
Voor een service die beheerders over het netwerk bereiken, gebruik opzet C.
8. Opzet C — extern (HTTPS + API-sleutels)
Volledige procedure: remote.md. Korte vorm:
Windows-server (verhoogd):
- Binaries en
fbmcp.yamlinC:\fbmcp\(sjabloon: 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"— noteer de pinsha256:....- Eén sleutel per persoon of agent:
C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets(één keer afgedrukt). Met--config C:\fbmcp\fbmcp.yamlvoegt hij ook deidentities:-vermelding toe en gebruikt hijsecrets.dir. - Wachtwoorden en agent-tokens:
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, daarna zonder-WhatIf. Het maakt de service, de firewallregel, de map-ACL’s en de Firebird-servicerechten.C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml→ geen FAIL;curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz→ok.- Systeemvak voor de goedkeurder:
.\packaging\windows\install-tray.ps1.
Linux-server (root): kopieer fbmcp, fbmcpctl en packaging/linux/, en dan
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/24Het script maakt de mappen, het certificaat, een eerste config met een
admin-sleutel (één keer afgedrukt), de systemd-unit, de sudo-regel voor de
Firebird-unit en de ufw-regel, en voert daarna doctor --remote uit. Voeg
databases: en agents: toe aan /etc/fbmcp/fbmcp.yaml. Goedkeuringen op
Linux (geen systeemvak): sudo -u firebird fbmcpctl approve [id]. Het vindt
/etc/fbmcp/fbmcp.yaml zelf, vraagt y/N (--yes vraagt niet), en
--deny <id> --reason "..." weigert.
Beheerders-pc:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(de sleutel die u hebt gekregen).- Elke stdio-client (Claude Desktop, Cursor, Codex, ZCode): de vermelding uit §6 met deze
args:["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. De pin controleert de serversleutel, dus een zelfondertekend certificaat heeft geen CA-inrichting nodig. - Claude Code kan ook rechtstreeks via HTTP verbinden (
.mcp.json"type": "http", headerAuthorization: Bearer ${FBMCP_KEY_SRV1},NODE_EXTRA_CA_CERTSvoor een zelfondertekend certificaat). Geef de sleutel niet mee metclaude mcp add --header: hij wordt in leesbare tekst opgeslagen. - Test:
fb_pingtoont de servernaam en uw identiteit.
Autonome agents (OpenClaw en vergelijkbaar): een aparte sleutel met
apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32.
Standaard alleen-lezen; elk Tier 1-verzoek wacht op een operator, en
fb_confirm van de agent wordt geweigerd. Limieten: remote.md §6–7.
9. fbagent-brug en HQbird-cluster (optioneel)
De agent-tools (fb_agent_status, fb_agent_job_run, …) gebruiken de
HQbird fbagent Local API op dezelfde host.
Ze staan uit totdat agents: een vermelding heeft.
- In de client: “
fb_agent_discover”. Het somt de lokale agents op metbase_url,instance_iden de voorgestelde tokennaam. Het leest nooit tokens. - De operator slaat het
local_api.tokenvan de agent op (nietagent.auth_token):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Typ nooit een token in de chat. - In de client: “
fb_agent_registervoor die agent” → keur goed in het systeemvak. fbmcp voegt deagents:-vermelding toe, herlaadt en controleert de identiteit. - Test:
fb_agent_status,fb_agent_instances.
fb_agent_config_set (jobinstellingen wijzigen: back-up, sweep, …) heeft ook config_path op de vermelding nodig, leestoegang tot het actieve agent_config.json, en aanmaakrechten op de map. Dat bestand bevat het token en de Firebird-gegevens, dus deze toekenning is de beslissing van de operator (agent-bridge.md). Als de agentcontrole mislukt, schrijft de tool niets.
HQbird-cluster (RCM). De clustertools roepen de HQbird-clustermanager (hqbirdrcm) aan op dezelfde host. Ze worden alleen getoond wanneer fbmcp.yaml een sectie rcm: heeft (url, ca_file, user, password_env). Op een Linux HQbird-server schrijft fbmcp ctl hqbird-install die vanuit /opt/hqbirdrcm/rcm.json en slaat het eerste RCM-wachtwoord op in het geheim FBMCP_RCM_PASSWORD; elders voegt u de sectie met de hand toe (tool-reference.md). Daarna:
fb_cluster_rcm_password: het eerste RCM-wachtwoord vervangen (Tier 1).- Een nieuwe cluster: open het koppelvenster op elke host (
fb_agent_cluster_pairing), start de RCM op de master (fb_agent_cluster_rcm), koppel de hosts (fb_cluster_link), maak de replica’s (fb_cluster_reinit, Tier 2) en vergelijk de gegevens (fb_cluster_verify). Stappen:prompts/cluster-setup.md. - Clusterservices (switchover, failover, rejoin):
fb_cluster_servicetoont ze en de controles; de verplaatsingen zijn Tier 2. Stappen:prompts/cluster-services.md.
10. Dagelijks gebruik
Vraag de client in gewone woorden; hij kiest de tools. Voorbeelden:
| Taak | Tools |
|---|---|
| Staat alles aan? | fb_ping, fb_db_list, fb_db_health, fb_service_status |
| Gegevens lezen | fb_query (alleen-lezen, rijen + plan + statistieken per tabel; een raster in MCP-Apps-clients); controleer een concept met fb_query_check |
| Sessies, lange transacties | fb_sessions, fb_transactions, fb_session_kill (Tier 1) |
| Trage query | fb_analyze_query, fb_index_advice → toepassen met fb_write; fb_agent_perf_report |
| Back-up | fb_backup_start → job-id → fb_job_status |
| Een back-up verifiëren | fb_restore_test (herstelt in work_dir, markeert de back-up als geverifieerd) |
| Nachtelijke back-up + verificatie | fb_schedule_create met target=nightly_verify (eenmaal bevestigd; opzet B of C) |
| Schema / DDL | fb_schema_list, fb_describe, fb_write (elke instructie wordt geclassificeerd en aan een Tier toegewezen), fb_diff_schema |
| Migraties | fb_migration_status, fb_migration_plan, fb_migration_apply |
| Serverconfig | fb_config_get, fb_config_diff, fb_config_set (Tier 2) |
| Logboeken | fb_firebird_log |
| Capaciteit | fb_trends, fb_gstat, fb_index_stats |
| Clusterstatus | fb_cluster_status, fb_cluster_service |
| De master verplaatsen | fb_cluster_switchover (geen gegevensverlies) of fb_cluster_failover (master verloren), daarna fb_cluster_rejoin (Tier 2) |
Jobs zijn asynchroon: indienen → fb_job_status. Jobs op één database lopen
één voor één. Een job overleeft een herstart van fbmcp alleen als
interrupted: dien hem opnieuw in als hij nog nodig is.
fb_config_set wijzigt alleen de eigen regel in firebird.conf (commentaar,
inspringing en regeleinden blijven), bewaart het oude bestand als
firebird.conf.prev en herstart Firebird nooit. Herstart met
fb_service_restart (Tier 2): het wacht tot de service gestopt is en weer
draait.
11. Operatortaken
| Taak | Commando |
|---|---|
| Verzoeken tonen / goedkeuren / weigeren | fbmcpctl approve; fbmcpctl approve <id>; fbmcpctl approve --deny <id> --reason "..." (of het systeemvak) |
| Een sleutel roteren | fbmcpctl apikey rotate alice --config <fbmcp.yaml> (de oude sleutel stopt binnen seconden) |
| Sleutels tonen | fbmcpctl apikey list (namen, bronnen, Tier; nooit de waarden) |
| Een persoon verwijderen | verwijder de identities:-vermelding, daarna fbmcpctl secret drop --dir <dir> NAME |
| Het certificaat vernieuwen | fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ... (pin ongewijzigd, geen herstart) |
| De auditketen controleren | fbmcpctl verify |
| Leeft de kernel? | fbmcpctl ping; fbmcpctl status (offline lezen van de status) |
| Servicebeheer toestaan | packaging/posture/verify.ps1 of verify.sh, daarna fbmcpctl setup --write-posture |
| Upgrade | stop de service (of de clients), vervang de binaries, start, doctor |
| Verwijderen | Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux: remote.md §10. Bewaar de statusmap (audit) tenzij de eigenaar anders zegt |
Alleen op de ontwikkelhost: .\packaging\rebuild-install.ps1 -Force herbouwt
dist\, stopt en vervangt de draaiende binaries (de oude blijven als
*.exe~), voegt clientconfiguraties samen en voert doctor uit.
12. Herstel na crash en herstart
Gecontroleerd door het chaos-harnas (internal/killharness).
| Na een crash of kill | Bij herstart | Actie van de operator |
|---|---|---|
| Een job draaide of stond in de wachtrij | Gemarkeerd als interrupted; nooit hervat |
Opnieuw indienen indien nodig |
| Openstaand verzoek, niet bevestigd | Hersteld uit state.json (TTL geldt nog) |
Bevestigen of laten verlopen |
fb_restore_replace bezig |
Rondt af: herstel, validatie, database online; <db>.pre-restore bewaard |
Controleer fb_db_health; verwijder .pre-restore later |
fb_shutdown_window bezig |
Rondt de stap gfix -online af |
Controleer of de database online is |
Verouderde instance.lock |
Automatisch overgenomen | Geen |
state.json corrupt |
De kernel weigert te starten; kopie bewaard als state.json.corrupt-<ts> |
Inspecteren; state.json bewust repareren of verwijderen (fbmcpctl repair herbouwt planningsrechten vanuit de audit) |
audit.jsonl corrupt of afgekapt |
De kernel weigert te starten | §13.2: behandel het als een knoeisignaal |
| Klok teruggedraaid | De planner slaat over; geen dubbele run | Geen |
| Windows-serviceproces gedood | SCM herstart het in ongeveer 5 s | Geen |
De kernel faalt gesloten bij alles waarvan hij niet kan bewijzen dat het intact is. Een herstartlus is een bevinding: lees het log.
13. Incidentdraaiboeken
13.1 Er is iets mis met een database
fbmcpctl doctor --config <file>: config, geheimen, Firebird-aanmeldingen, mappen, posture, planningen. Elke FAIL-regel heeft eenFix:.fb_db_list→fb_db_health <db>;fb_service_statusvoor de instance.fb_sessions,fb_transactionsvoor attachment- of OAT-kloofproblemen;fb_firebird_logvoor enginefouten.
13.2 Vermoedelijke knoeierij of corruptie: eerst de audit
fbmcpctl verify --config <file>→audit chain OK: N entriesofBROKENmet de reden.- Als het mislukt: bewaar de hele statusmap (dat is het bewijs) en onderzoek daarna. Verwijder
audit.jsonlniet om de kernel te laten starten.
13.3 Hersteloefening (elk kwartaal)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ de back-up is geverifieerd.fb_window_openvoor de database.fb_restore_replace→ keur buiten het kanaal goed. Stilstand tot online.- Controle:
fb_db_health, daarna een echte leesactie (fb_schema_list,fb_info). - Het oude bestand blijft als
<db>.pre-restoretotdat u het verwijdert.
13.4 De client kan niet verbinden
fbmcpctl ping --config <file>,fbmcpctl status --config <file>.- Lees het MCP-log van de client (stdio) of
<state_dir>\fbmcp.log/journalctl -u fbmcp(service). - “another fbmcp instance is active”: één kernel per statusmap. Clients via een pipe koppelen vanzelf; een tweede kernel faalt meteen, door het ontwerp.
In de commando’s hierboven kunt u --config weglaten wanneer het opzoeken
in §4 het bestand vindt.
14. Probleemoplossing
| Symptoom | Betekenis / oplossing |
|---|---|
| Tools verschijnen niet | JSON-syntaxis, absolute paden, volledige herstart van de client; het MCP-log van de client |
| Eén tool ontbreekt in de lijst | Met opzet verborgen (§1): boven uw maximale Tier, geen agents:-vermelding, geen migrations_dir, of geen sectie rcm: |
| De server stopt meteen | fbmcpctl doctor; een ontbrekend geheim; een service kan uw sleutelring niet lezen (gebruik secrets.dir) |
| Tier 2 “confirmation rejected: channel policy” | Verwacht in de chat. Keur goed in het systeemvak of met fbmcpctl approve |
| Tier 2 “no open maintenance window” | fb_window_open voor dezelfde db die u aan de tool meegeeft |
fb_restore_replace geweigerd: precondities |
Vereist een geverifieerde back-up < 24 u: fb_backup_start + fb_restore_test, en een venster |
| Servicebeheer geweigerd | posture.verified ontbreekt (fbmcpctl setup --write-posture) of het account heeft geen rechten op de Firebird-service |
fb_config_set: kan niet schrijven |
Het account mag dat bestand niet wijzigen (Linux-unit ProtectSystem=strict; Windows-ACL). Bewerk met de hand, of zie remote.md §8 |
| Het systeemvak toont niets | Het toont alleen verzoeken die een operator nodig hebben; controleer de rechten van de systeemvakgebruiker op de statusmap en tray.log daar |
| 401 (extern) | Verkeerde sleutel, of de server heeft hem niet geladen: apikey list, doctor --remote |
| 403 (extern) | Bron-IP niet in allow_from / firewall, of een Origin-header niet in allowed_origins |
| 429 (extern) | Limieten; wacht op Retry-After |
| Pin komt niet overeen | De serversleutel is gewijzigd; haal de nieuwe pin bij de serverbeheerder |
agent-unreachable |
Agentservice gestopt, local_api.enabled: false, of verkeerde base_url (standaard 127.0.0.1:(10000 + firebird port)) |
agent-auth |
Het opgeslagen token is niet het local_api.token van de agent; stel hem opnieuw in |
agent-timeout bij herstarts |
agents[].timeout_seconds (130) moet groter zijn dan de restart_timeout_seconds van de agent (120) |
Error loading plugin MySQLEngine … bij het aankoppelen |
Op HQbird betekent dit meestal dat het bestand niet bestaat; controleer het pad |
Kale DROP INDEX in fb_write heeft een venster nodig |
Daar is het Tier 2; gebruik fb_index_drop (Tier 1; weigert constraintindexen) |
| Nieuwe index niet gebruikt | Voer statistieken uit (fb_index_rebuild action=statistics); ORDER BY … DESC heeft een DESCENDING-index nodig |
| Tools falen voor slechts één database | Hij is offline (fb_db_health); tools degraderen per database |
15. Naslag van de statusmap
| Pad | Betekenis |
|---|---|
state.json (+ .tmp, .corrupt-*) |
Openstaande verzoeken, jobs, back-upcatalogus, workflows, planningen. Corrupt ⇒ weigert te starten |
audit.jsonl (+ .head) |
Hash-geketend auditlog; .head detecteert afkapping |
events.jsonl |
Jobgebeurtenissen (job.succeeded, job.failed met het bericht) |
approvals\, denials\ |
Beslissingen buiten het kanaal (systeemvak / fbmcpctl approve), gebruikt binnen ~2 s |
instance.lock |
Vergrendeling voor één kernel |
attach.addr, attach.token |
Attach-eindpunt voor extra stdio-clients |
fbmcp.log, fbmcp-crash.log |
Servicelog (geroteerd) en crashuitvoer |
query-log.jsonl |
Elke fb_query-aanroep |
trends\ |
Samplerhistorie voor fb_trends |
config-journal\ |
Geschiedenis van fb_config_set (oude en nieuwe waarde) |
posture.verified |
Markering die servicebeheer toestaat |
tray.log |
Systeemvakfouten |
16. Status van de doorloop
Openstaand (M1): een doorloop op een verse Windows-host met alleen deze gids.
Bevindingen gaan terug in dit bestand. Labresultaten voor de externe modus
(Linux-host, verse VM, Windows-service):
findings/phase12-lab-2026-11-03.md.