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 dezelfde db) 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_cancel verwijdert 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).

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-binaries (kruiscompilatie vanaf Windows, of bouwen op Linux zonder 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

Controlesommen: 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:

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

Geheimen. 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.

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)

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:

Command
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp
  • De service draait fbmcp -serve als LocalSystem, herstart bij een fout en stopt netjes bij een servicestop.
  • Gebruik secrets.dir voor wachtwoorden (§5).
  • Vergrendel de map: alleen SYSTEM en Administrators mogen schrijven in C:\fbmcp (het script toont het icacls-commando). Een map onder C:\ 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 in fbmcp-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):

  1. Binaries en fbmcp.yaml in C:\fbmcp\ (sjabloon: 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" — noteer de pin sha256:....
  3. 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.yaml voegt hij ook de identities:-vermelding toe en gebruikt hij secrets.dir.
  4. Wachtwoorden en agent-tokens: 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, daarna zonder -WhatIf. Het maakt de service, de firewallregel, de map-ACL’s en de Firebird-servicerechten.
  6. 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.
  7. Systeemvak voor de goedkeurder: .\packaging\windows\install-tray.ps1.

Linux-server (root): kopieer fbmcp, fbmcpctl en packaging/linux/, en dan

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

Het 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:

  1. C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1 (de sleutel die u hebt gekregen).
  2. 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.
  3. Claude Code kan ook rechtstreeks via HTTP verbinden (.mcp.json "type": "http", header Authorization: Bearer ${FBMCP_KEY_SRV1}, NODE_EXTRA_CA_CERTS voor een zelfondertekend certificaat). Geef de sleutel niet mee met claude mcp add --header: hij wordt in leesbare tekst opgeslagen.
  4. Test: fb_ping toont 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.

  1. In de client: “fb_agent_discover”. Het somt de lokale agents op met base_url, instance_id en de voorgestelde tokennaam. Het leest nooit tokens.
  2. De operator slaat het local_api.token van de agent op (niet agent.auth_token): fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Typ nooit een token in de chat.
  3. In de client: “fb_agent_register voor die agent” → keur goed in het systeemvak. fbmcp voegt de agents:-vermelding toe, herlaadt en controleert de identiteit.
  4. 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:

  1. fb_cluster_rcm_password: het eerste RCM-wachtwoord vervangen (Tier 1).
  2. 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.
  3. Clusterservices (switchover, failover, rejoin): fb_cluster_service toont 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

  1. fbmcpctl doctor --config <file>: config, geheimen, Firebird-aanmeldingen, mappen, posture, planningen. Elke FAIL-regel heeft een Fix:.
  2. fb_db_list → fb_db_health <db>; fb_service_status voor de instance.
  3. fb_sessions, fb_transactions voor attachment- of OAT-kloofproblemen; fb_firebird_log voor enginefouten.

13.2 Vermoedelijke knoeierij of corruptie: eerst de audit

  1. fbmcpctl verify --config <file> → audit chain OK: N entries of BROKEN met de reden.
  2. Als het mislukt: bewaar de hele statusmap (dat is het bewijs) en onderzoek daarna. Verwijder audit.jsonl niet om de kernel te laten starten.

13.3 Hersteloefening (elk kwartaal)

  1. fb_backup_start → fb_job_status = succeeded.
  2. fb_restore_test → de back-up is geverifieerd.
  3. fb_window_open voor de database.
  4. fb_restore_replace → keur buiten het kanaal goed. Stilstand tot online.
  5. Controle: fb_db_health, daarna een echte leesactie (fb_schema_list, fb_info).
  6. Het oude bestand blijft als <db>.pre-restore totdat u het verwijdert.

13.4 De client kan niet verbinden

  1. fbmcpctl ping --config <file>, fbmcpctl status --config <file>.
  2. Lees het MCP-log van de client (stdio) of <state_dir>\fbmcp.log / journalctl -u fbmcp (service).
  3. “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.