Destinatari: la persona che installa e fa funzionare fbmcp, e che non l’ha compilato. Non serve conoscere gli interni di Go o di Firebird. Stato al 2026-11-16, versione 2027.2.24 (modalità locale e remota, installazione HQbird, ponte fbagent, cluster HQbird, griglia dei risultati).

Versioni brevi, non presenti su questo sito: quickstart-en.md, quickstart-ru.md, quickstart-pt.md. Dettagli, in inglese: remote.md (modalità remota), agent-bridge.md (fbagent), tool-reference.md (ogni strumento, il suo Tier e i suoi argomenti), claude-desktop.md (collegamento del client sull’host di sviluppo), ADR in decisions/.


1. Che cos’è fbmcp

fbmcp è un server MCP per Firebird 2.5–5.0 su Windows e Linux. Un client MCP (Claude Desktop, Claude Code, Cursor, Codex, ZCode, altri) lo usa per lavorare come DBA: monitoraggio, backup e ripristini verificati, SQL/DDL/DCL, indici, utenti e privilegi, firebird.conf, un pianificatore, migrazioni, il fbagent HQbird e il cluster HQbird. Ha 122 strumenti: 56 in sola lettura (Tier 0), 44 Tier 1, 21 Tier 2, 1 Tier 3 (disabilitato). fb_demo_write è presente solo quando il server gira con FBMCP_DEMO_TOOLS=1.

Un client vede solo gli strumenti che può usare. L’elenco degli strumenti nasconde: il Tier 3, gli strumenti sopra il Tier massimo dell’identità, fb_confirm e fb_cancel per un’identità in sola lettura, gli strumenti fbagent finché agents: è vuoto (fb_agent_discover e fb_agent_register restano), gli strumenti di migrazione finché nessun database ha migrations_dir, e gli strumenti di cluster finché fbmcp.yaml non ha una sezione rcm:. Quando un ricaricamento della config cambia questo insieme, il client riceve un nuovo elenco. Una chiamata diretta a uno strumento nascosto riceve un rifiuto chiaro.

Binario Ruolo
fbmcp Il server. Predefinito: MCP su stdio (un client lo avvia). -serve: niente stdio, gira come servizio (pianificatore, socket di attach, listener HTTPS se configurato). fbmcp bridge: un client stdio per un fbmcp remoto
fbmcpctl CLI dell’operatore: doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. Lo stesso programma di fbmcp ctl
fbmcp-tray Area di notifica di Windows: finestra Approve/Deny per le richieste che richiedono un operatore

Un kernel per directory di stato. Un secondo client con la stessa config non avvia un secondo kernel: si aggancia a quello in esecuzione.

2. Modello di sicurezza

Ogni chiamata passa per politica → conferma umana → esecuzione auditata.

Tier Cosa Come viene confermato
0 Letture (transazioni in sola lettura imposte dal motore) Non necessaria
1 Modifiche di routine: DML/DDL, backup, utenti, privilegi Nel canale: il client mostra un id di richiesta e un token; la persona accetta; il client chiama fb_confirm
2 Alto impatto: controllo del servizio, ripristino-sostituzione, firebird.conf, finestra esclusiva, registrazione, riavvii dell’agent Solo fuori canale: l’area di notifica o fbmcpctl approve. Il client non può mai approvarlo
3 Critico (fb_db_drop) Disabilitato per progettazione
  • Il Tier 2 di solito richiede una finestra di manutenzione aperta (fb_window_open, sullo stesso db) e un backup verificato più recente di 24 ore. Il rifiuto dice che cosa manca.
  • Una richiesta in sospeso scade dopo 15 minuti. Un tentativo sul canale sbagliato non la consuma; fb_cancel la rimuove.
  • Ogni strumento sotto controllo accetta mode: preview: mostra l’impatto e non fa nulla.
  • Ogni decisione (consenso, in sospeso, approvata, negata) va in audit.jsonl, a catena di hash.
  • Non esiste una pagina web di approvazione, e non deve mai esisterne una: una pagina che il modello può raggiungere romperebbe il disegno.

3. Scegliere una configurazione

Configurazione Dove gira fbmcp Usarla quando Sezione
A. Stdio locale Il vostro PC; il client lo avvia Un amministratore, Firebird su questo PC o nella LAN §6
B. Servizio locale Servizio Windows sull’host del database (-serve) Le pianificazioni devono girare quando nessun client è aperto §7
C. Remoto Servizio sul server dei database, HTTPS + chiavi API Più amministratori, un server distante, agenti autonomi §8

Nella configurazione A il kernel vive solo mentre un client è in esecuzione, quindi le pianificazioni scattano solo allora. Usate B o C per le pianificazioni non presidiate (nightly_verify).

fbmcp in HQbird. Le installazioni HQbird 2027 e fbagent installano fbmcp per impostazione predefinita: un servizio per server per tutte le linee Firebird, predisposto da fbmcp ctl hqbird-install. Su un tale server non seguite §6–§8; leggete hqbird.md (disposizione, modalità remota con --allow-from, chiavi API).

4. Ottenere i binari

Requisiti: Go ≥ 1.26.11 (un Go più vecchio, 1.21 o successivo, scarica go1.26.11 da solo alla prima compilazione; serve Internet), CGO non serve; Firebird 2.5–5.0; fbagent ≥ 2.67 con la Local API per gli strumenti agent (facoltativo); fbagent 3.1.0+ e RCM 2027.5.11+ per gli strumenti cluster (facoltativo).

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

Binari Linux (cross-compilazione da Windows, oppure compilazione su Linux senza 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

Checksum: Get-FileHash dist/* o sha256sum dist/*. Altri target: packaging/README.md. Mettete i binari in una cartella dedicata (gli esempi usano C:\fbmcp\): mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\ (Linux: install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/).

fbmcp ctl e fbmcpctl sono lo stesso programma. fbmcpctl help elenca i comandi. I comandi che leggono la config accettano --config <file>; senza, usano FBMCP_CONFIG, poi fbmcp.yaml nella cartella corrente, poi accanto al programma, poi il predefinito HQbird (C:\HQbirdData\fbmcp\fbmcp.yaml, /etc/fbmcp/fbmcp.yaml), e stampano using config <path>.

5. Configurare fbmcp.yaml

Esempio completo: packaging/fbmcp.yaml.example. Configurazione Windows minima:

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

Secret. Lo YAML contiene solo i nomi delle variabili. fbmcp cerca ogni valore in quest’ordine: variabile d’ambiente → file <secrets.dir>/<NAME> → portachiavi del sistema operativo dell’account che esegue fbmcp.

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)

Il valore viene letto da stdin (digitatelo, poi Ctrl+Z, Invio; Linux Ctrl+D). Un account di servizio (LocalSystem, NT SERVICE\...) non vede il vostro portachiavi: usate secrets.dir per i servizi. Un file di secret modificato si applica in pochi secondi, senza riavvio.

Utente in sola lettura. Create un utente Firebird separato per ro_user (SQL: quickstart-en.md: CREATE USER FBMCP_RO, GRANT SELECT su ogni tabella, e su Firebird 4.0+ un ruolo con MONITOR_ANY_ATTACHMENT così fb_sessions vede tutte le connessioni). SYSDBA come utente RO è solo per lo sviluppo; doctor avvisa in proposito.

Ricaricamento a caldo. fbmcp applica da solo le modifiche a fbmcp.yaml (osservazione del file), oppure su fb_config_reload. Nessun riavvio del client o del processo. Un ricaricamento attende i job sui database modificati (30 s), poi applica. Rifiutato: un cambio di state.dir, percorsi di database duplicati, una config remota non sicura.

Controllo: C:\fbmcp\fbmcpctl.exe doctor deve finire con doctor: green (modalità remota: doctor --remote, nessuna riga FAIL). Crea la cartella di stato mancante, accede a ogni database con entrambi gli utenti, e ogni riga FAIL finisce con Fix: e il comando da eseguire.

6. Configurazione A — stdio locale

Usate percorsi assoluti. Non impostate listen. Riavviate il client dopo una modifica della config: i client caricano i server solo all’avvio.

Client Dove Voce
Claude Desktop Impostazioni → Sviluppatore → Modifica configurazione (%APPDATA%\Claude\claude_desktop_config.json) "mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}}
Claude Code riga di comando claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml"
Cursor %USERPROFILE%\.cursor\mcp.json o .cursor\mcp.json nel progetto lo stesso JSON di Claude Desktop
Codex codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml o %USERPROFILE%\.codex\config.toml [mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml']
ZCode .zcode\config.json nel progetto "mcp": {"servers": {"fbmcp": { ...same command and args... }}}

Le password sono nel portachiavi (§5), quindi non serve un blocco env. Se comunque mettete una password in un blocco env del client, tenete quel file fuori da git.

Poi avviate l’area di notifica per le approvazioni Tier 2: C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml (a ogni accesso: .\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).

Prova rapida nel client: “chiamate fb_ping” (mostra il nome del server e la vostra identità con il suo Tier massimo), poi “fb_db_list”, poi “fb_db_health per main”.

7. Configurazione B — servizio Windows locale

PowerShell con privilegi elevati:

Command
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp
  • Il servizio esegue fbmcp -serve come LocalSystem, si riavvia in caso di errore e si ferma in modo pulito all’arresto del servizio.
  • Usate secrets.dir per le password (§5).
  • Bloccate la cartella: solo SYSTEM e Administrators possono scrivere in C:\fbmcp (lo script stampa il comando icacls). Una cartella creata sotto C:\ lascia ogni utente modificare i file, e il servizio li esegue come SYSTEM.
  • L’utente dell’area di notifica e i client stdio locali hanno bisogno di lettura/scrittura sulla directory di stato: icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M". Un client stdio con la stessa config si aggancia allora al kernel del servizio.
  • Prontezza: C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml.
  • Log: <state_dir>\fbmcp.log (5 × 10 MiB; i crash in fbmcp-crash.log).

Per un servizio che gli amministratori raggiungono via rete, usate la configurazione C.

8. Configurazione C — remoto (HTTPS + chiavi API)

Procedura completa: remote.md. Forma breve:

Server Windows (con privilegi elevati):

  1. Binari e fbmcp.yaml in C:\fbmcp\ (modello: 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" — annotate il pin sha256:....
  3. Una chiave per persona o agente: C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets (stampata una sola volta). Con --config C:\fbmcp\fbmcp.yaml aggiunge anche la voce identities: e usa secrets.dir.
  4. Password e token degli agent: 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, poi senza -WhatIf. Crea il servizio, la regola firewall, le ACL delle cartelle e i diritti del servizio Firebird.
  6. C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml → nessun FAIL; curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz → ok.
  7. Area di notifica per chi approva: .\packaging\windows\install-tray.ps1.

Server Linux (root): copiate fbmcp, fbmcpctl e packaging/linux/, poi

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

Lo script crea le cartelle, il certificato, una prima config con una chiave admin (stampata una sola volta), l’unità systemd, la regola sudo per l’unità Firebird e la regola ufw, poi esegue doctor --remote. Aggiungete databases: e agents: a /etc/fbmcp/fbmcp.yaml. Approvazioni su Linux (nessuna area di notifica): sudo -u firebird fbmcpctl approve [id]. Trova /etc/fbmcp/fbmcp.yaml da solo, chiede y/N (--yes non chiede), e --deny <id> --reason "..." rifiuta.

PC dell’amministratore:

  1. C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1 (la chiave che avete ricevuto).
  2. Qualsiasi client stdio (Claude Desktop, Cursor, Codex, ZCode): la voce del §6 con questi args: ["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. Il pin controlla la chiave del server, quindi un certificato autofirmato non richiede la configurazione di una CA.
  3. Claude Code può anche collegarsi direttamente via HTTP (.mcp.json "type": "http", intestazione Authorization: Bearer ${FBMCP_KEY_SRV1}, NODE_EXTRA_CA_CERTS per un certificato autofirmato). Non passate la chiave con claude mcp add --header: viene salvata in chiaro.
  4. Prova: fb_ping mostra il nome del server e la vostra identità.

Agenti autonomi (OpenClaw e simili): una chiave separata con apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32. Sola lettura per impostazione predefinita; ogni richiesta Tier 1 attende un operatore, e fb_confirm dall’agent viene rifiutato. Limiti: remote.md §6–7.

9. Ponte fbagent e cluster HQbird (facoltativo)

Gli strumenti agent (fb_agent_status, fb_agent_job_run, …) usano la Local API fbagent di HQbird sullo stesso host. Restano spenti finché agents: non ha una voce.

  1. Nel client: “fb_agent_discover”. Elenca gli agent locali con base_url, instance_id e il nome di token suggerito. Non legge mai i token.
  2. L’operatore memorizza il local_api.token dell’agent (non agent.auth_token): fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Non digitate mai un token nella chat.
  3. Nel client: “fb_agent_register per quell’agent” → approvate nell’area di notifica. fbmcp aggiunge la voce agents:, ricarica e controlla l’identità.
  4. Prova: fb_agent_status, fb_agent_instances.

fb_agent_config_set (cambiare le impostazioni dei job: backup, sweep, …) richiede anche config_path sulla voce, l’accesso in lettura al agent_config.json attivo e il diritto di creare nella sua cartella. Quel file contiene il token e le credenziali Firebird, quindi questa concessione è una decisione dell’operatore (agent-bridge.md). Se il controllo dell’agent fallisce, lo strumento non scrive nulla.

Cluster HQbird (RCM). Gli strumenti cluster chiamano il gestore del cluster HQbird (hqbirdrcm) sullo stesso host. Vengono mostrati solo quando fbmcp.yaml ha una sezione rcm: (url, ca_file, user, password_env). Su un server HQbird Linux, fbmcp ctl hqbird-install la scrive da /opt/hqbirdrcm/rcm.json e memorizza la prima password RCM nel secret FBMCP_RCM_PASSWORD; altrove aggiungete la sezione a mano (tool-reference.md). Poi:

  1. fb_cluster_rcm_password: sostituire la prima password RCM (Tier 1).
  2. Un nuovo cluster: aprite la finestra di accoppiamento su ogni host (fb_agent_cluster_pairing), avviate l’RCM sul master (fb_agent_cluster_rcm), collegate gli host (fb_cluster_link), create le repliche (fb_cluster_reinit, Tier 2) e confrontate i dati (fb_cluster_verify). Passi: prompts/cluster-setup.md.
  3. Servizi del cluster (switchover, failover, rejoin): fb_cluster_service li mostra insieme ai controlli; gli spostamenti sono Tier 2. Passi: prompts/cluster-services.md.

10. Uso quotidiano

Chiedete al client in parole semplici; sceglie lui gli strumenti. Esempi:

Compito Strumenti
È tutto in funzione? fb_ping, fb_db_list, fb_db_health, fb_service_status
Leggere dati fb_query (sola lettura, righe + piano + statistiche per tabella; una griglia nei client MCP-Apps); controllare una bozza con fb_query_check
Sessioni, transazioni lunghe fb_sessions, fb_transactions, fb_session_kill (Tier 1)
Query lenta fb_analyze_query, fb_index_advice → applicare con fb_write; fb_agent_perf_report
Backup fb_backup_start → id del job → fb_job_status
Verificare un backup fb_restore_test (ripristina in work_dir, marca il backup come verificato)
Backup notturno + verifica fb_schedule_create con target=nightly_verify (confermato una volta; configurazione B o C)
Schema / DDL fb_schema_list, fb_describe, fb_write (ogni istruzione viene classificata e assegnata a un Tier), fb_diff_schema
Migrazioni fb_migration_status, fb_migration_plan, fb_migration_apply
Config del server fb_config_get, fb_config_diff, fb_config_set (Tier 2)
Log fb_firebird_log
Capacità fb_trends, fb_gstat, fb_index_stats
Stato del cluster fb_cluster_status, fb_cluster_service
Spostare il master fb_cluster_switchover (senza perdita di dati) o fb_cluster_failover (master perso), poi fb_cluster_rejoin (Tier 2)

I job sono asincroni: inviare → fb_job_status. I job su un database girano uno alla volta. Un job sopravvive a un riavvio di fbmcp solo come interrupted: inviatelo di nuovo se serve ancora.

fb_config_set cambia solo la propria riga in firebird.conf (commenti, indentazione e fine riga restano), conserva il vecchio file come firebird.conf.prev e non riavvia mai Firebird. Riavviate con fb_service_restart (Tier 2): attende che il servizio sia fermo e di nuovo in esecuzione.

11. Compiti dell’operatore

Compito Comando
Elencare / approvare / negare le richieste fbmcpctl approve; fbmcpctl approve <id>; fbmcpctl approve --deny <id> --reason "..." (o l’area di notifica)
Ruotare una chiave fbmcpctl apikey rotate alice --config <fbmcp.yaml> (la vecchia chiave smette in pochi secondi)
Elencare le chiavi fbmcpctl apikey list (nomi, origini, Tier; mai i valori)
Rimuovere una persona cancellate la voce identities:, poi fbmcpctl secret drop --dir <dir> NAME
Rinnovare il certificato fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ... (pin invariato, nessun riavvio)
Controllare la catena di audit fbmcpctl verify
Il kernel è vivo? fbmcpctl ping; fbmcpctl status (lettura offline dello stato)
Consentire il controllo del servizio packaging/posture/verify.ps1 o verify.sh, poi fbmcpctl setup --write-posture
Aggiornamento fermate il servizio (o i client), sostituite i binari, avviate, doctor
Rimuovere Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux: remote.md §10. Conservate la directory di stato (audit) salvo diversa indicazione del proprietario

Solo sull’host di sviluppo: .\packaging\rebuild-install.ps1 -Force ricostruisce dist\, ferma e sostituisce i binari in esecuzione (i vecchi restano come *.exe~), unisce le config dei client ed esegue doctor.

12. Ripristino dopo crash e riavvio

Verificato dall’harness del caos (internal/killharness).

Dopo un crash o un kill Al riavvio Azione dell’operatore
Un job era in esecuzione o in coda Marcato interrupted; mai ripreso Inviare di nuovo se serve
Richiesta in sospeso, non confermata Ripristinata da state.json (il TTL vale ancora) Confermare o lasciare scadere
fb_restore_replace in corso Finisce: ripristino, validazione, database online; <db>.pre-restore conservato Controllare fb_db_health; cancellare .pre-restore più tardi
fb_shutdown_window in corso Completa il passo gfix -online Controllare che sia online
instance.lock stantio Preso in carico automaticamente Nessuna
state.json corrotto Il kernel rifiuta di avviarsi; copia conservata come state.json.corrupt-<ts> Ispezionare; riparare o rimuovere state.json di proposito (fbmcpctl repair ricostruisce le concessioni delle pianificazioni dall’audit)
audit.jsonl corrotto o tagliato Il kernel rifiuta di avviarsi §13.2: trattatelo come un segnale di manomissione
Orologio spostato indietro Il pianificatore salta; nessuna esecuzione doppia Nessuna
Processo del servizio Windows ucciso SCM lo riavvia in circa 5 s Nessuna

Il kernel fallisce in modo chiuso su tutto ciò di cui non può provare l’integrità. Un ciclo di riavvii è un rilievo: leggete il log.

13. Procedure per gli incidenti

13.1 Qualcosa non va in un database

  1. fbmcpctl doctor --config <file>: config, secret, accessi Firebird, cartelle, posture, pianificazioni. Ogni riga FAIL ha un Fix:.
  2. fb_db_list → fb_db_health <db>; fb_service_status per l’istanza.
  3. fb_sessions, fb_transactions per problemi di attachment o di divario OAT; fb_firebird_log per gli errori del motore.

13.2 Sospetta manomissione o corruzione: prima l’audit

  1. fbmcpctl verify --config <file> → audit chain OK: N entries o BROKEN con il motivo.
  2. Se fallisce: conservate l’intera directory di stato (è la prova), poi indagate. Non cancellate audit.jsonl per far partire il kernel.

13.3 Esercitazione di ripristino (ogni trimestre)

  1. fb_backup_start → fb_job_status = succeeded.
  2. fb_restore_test → il backup è verificato.
  3. fb_window_open per il database.
  4. fb_restore_replace → approvate fuori canale. Fermo fino al ritorno online.
  5. Controllo: fb_db_health, poi una lettura reale (fb_schema_list, fb_info).
  6. Il vecchio file resta come <db>.pre-restore finché non lo cancellate.

13.4 Il client non riesce a connettersi

  1. fbmcpctl ping --config <file>, fbmcpctl status --config <file>.
  2. Leggete il log MCP del client (stdio) o <state_dir>\fbmcp.log / journalctl -u fbmcp (servizio).
  3. “another fbmcp instance is active”: un kernel per directory di stato. I client collegati tramite pipe si agganciano da soli; un secondo kernel fallisce subito, per progettazione.

Nei comandi sopra potete omettere --config quando la ricerca del §4 trova il file.

14. Risoluzione dei problemi

Sintomo Significato / rimedio
Gli strumenti non compaiono Sintassi JSON, percorsi assoluti, riavvio completo del client; il log MCP del client
Uno strumento manca dall’elenco Nascosto di proposito (§1): sopra il vostro Tier massimo, nessuna voce agents:, nessun migrations_dir, oppure nessuna sezione rcm:
Il server esce subito fbmcpctl doctor; un secret mancante; un servizio non può leggere il vostro portachiavi (usate secrets.dir)
Tier 2 “confirmation rejected: channel policy” Atteso nella chat. Approvate nell’area di notifica oppure con fbmcpctl approve
Tier 2 “no open maintenance window” fb_window_open per lo stesso db che passate allo strumento
fb_restore_replace negato: precondizioni Richiede un backup verificato < 24 h: fb_backup_start + fb_restore_test, e una finestra
Controllo del servizio negato posture.verified mancante (fbmcpctl setup --write-posture) oppure l’account non ha diritti sul servizio Firebird
fb_config_set: non può scrivere L’account non può modificare quel file (unità Linux ProtectSystem=strict; ACL Windows). Modificate a mano, oppure vedete remote.md §8
L’area di notifica non mostra nulla Mostra solo le richieste che richiedono un operatore; controllate i diritti di quell’utente sulla directory di stato e tray.log che vi si trova
401 (remoto) Chiave sbagliata, oppure il server non l’ha caricata: apikey list, doctor --remote
403 (remoto) IP di origine non in allow_from / firewall, oppure un’intestazione Origin non in allowed_origins
429 (remoto) Limiti; attendete Retry-After
Pin non corrispondente La chiave del server è cambiata; ottenete il nuovo pin dall’amministratore del server
agent-unreachable Servizio dell’agent fermo, local_api.enabled: false, oppure base_url errato (predefinito 127.0.0.1:(10000 + firebird port))
agent-auth Il token memorizzato non è il local_api.token dell’agent; impostatelo di nuovo
agent-timeout ai riavvii agents[].timeout_seconds (130) deve essere maggiore del restart_timeout_seconds dell’agent (120)
Error loading plugin MySQLEngine … all’attach Su HQbird di solito significa che il file non esiste; controllate il percorso
DROP INDEX nudo in fb_write richiede una finestra Lì è Tier 2; usate fb_index_drop (Tier 1; rifiuta gli indici di vincolo)
Nuovo indice non usato Eseguite le statistiche (fb_index_rebuild action=statistics); ORDER BY … DESC richiede un indice DESCENDING
Gli strumenti falliscono per un solo database È offline (fb_db_health); gli strumenti degradano per database

15. Riferimento della directory di stato

Percorso Significato
state.json (+ .tmp, .corrupt-*) Richieste in sospeso, job, catalogo dei backup, workflow, pianificazioni. Corrotto ⇒ rifiuta di avviarsi
audit.jsonl (+ .head) Log di audit a catena di hash; .head rileva il troncamento
events.jsonl Eventi dei job (job.succeeded, job.failed con il messaggio)
approvals\, denials\ Decisioni fuori canale (area di notifica / fbmcpctl approve), usate entro ~2 s
instance.lock Blocco di un solo kernel
attach.addr, attach.token Endpoint di attach per client stdio aggiuntivi
fbmcp.log, fbmcp-crash.log Log del servizio (ruotato) e output di crash
query-log.jsonl Ogni chiamata fb_query
trends\ Cronologia del campionatore per fb_trends
config-journal\ Cronologia di fb_config_set (valore vecchio e nuovo)
posture.verified Marcatore che consente il controllo del servizio
tray.log Errori dell’area di notifica

16. Stato della procedura

In sospeso (M1): una procedura su un host Windows nuovo usando solo questa guida. I rilievi tornano in questo file. Risultati di laboratorio per la modalità remota (host Linux, VM nuova, servizio Windows): findings/phase12-lab-2026-11-03.md.