fbmcp: installazione e uso
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 stessodb) 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_cancella 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).
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-trayBinari Linux (cross-compilazione da Windows, oppure compilazione su Linux
senza 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/fbmcpctlChecksum: 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:
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 backupsSecret. 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.
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:
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp- Il servizio esegue
fbmcp -servecome LocalSystem, si riavvia in caso di errore e si ferma in modo pulito all’arresto del servizio. - Usate
secrets.dirper le password (§5). - Bloccate la cartella: solo SYSTEM e Administrators possono scrivere in
C:\fbmcp(lo script stampa il comandoicacls). Una cartella creata sottoC:\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 infbmcp-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):
- Binari e
fbmcp.yamlinC:\fbmcp\(modello: 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"— annotate il pinsha256:....- 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.yamlaggiunge anche la voceidentities:e usasecrets.dir. - Password e token degli agent:
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, poi senza-WhatIf. Crea il servizio, la regola firewall, le ACL delle cartelle e i diritti del servizio Firebird.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.- Area di notifica per chi approva:
.\packaging\windows\install-tray.ps1.
Server Linux (root): copiate fbmcp, fbmcpctl e packaging/linux/, poi
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/24Lo 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:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(la chiave che avete ricevuto).- 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. - Claude Code può anche collegarsi direttamente via HTTP (
.mcp.json"type": "http", intestazioneAuthorization: Bearer ${FBMCP_KEY_SRV1},NODE_EXTRA_CA_CERTSper un certificato autofirmato). Non passate la chiave conclaude mcp add --header: viene salvata in chiaro. - Prova:
fb_pingmostra 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.
- Nel client: “
fb_agent_discover”. Elenca gli agent locali conbase_url,instance_ide il nome di token suggerito. Non legge mai i token. - L’operatore memorizza il
local_api.tokendell’agent (nonagent.auth_token):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Non digitate mai un token nella chat. - Nel client: “
fb_agent_registerper quell’agent” → approvate nell’area di notifica. fbmcp aggiunge la voceagents:, ricarica e controlla l’identità. - 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:
fb_cluster_rcm_password: sostituire la prima password RCM (Tier 1).- 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. - Servizi del cluster (switchover, failover, rejoin):
fb_cluster_serviceli 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
fbmcpctl doctor --config <file>: config, secret, accessi Firebird, cartelle, posture, pianificazioni. Ogni riga FAIL ha unFix:.fb_db_list→fb_db_health <db>;fb_service_statusper l’istanza.fb_sessions,fb_transactionsper problemi di attachment o di divario OAT;fb_firebird_logper gli errori del motore.
13.2 Sospetta manomissione o corruzione: prima l’audit
fbmcpctl verify --config <file>→audit chain OK: N entriesoBROKENcon il motivo.- Se fallisce: conservate l’intera directory di stato (è la prova), poi indagate. Non cancellate
audit.jsonlper far partire il kernel.
13.3 Esercitazione di ripristino (ogni trimestre)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ il backup è verificato.fb_window_openper il database.fb_restore_replace→ approvate fuori canale. Fermo fino al ritorno online.- Controllo:
fb_db_health, poi una lettura reale (fb_schema_list,fb_info). - Il vecchio file resta come
<db>.pre-restorefinché non lo cancellate.
13.4 Il client non riesce a connettersi
fbmcpctl ping --config <file>,fbmcpctl status --config <file>.- Leggete il log MCP del client (stdio) o
<state_dir>\fbmcp.log/journalctl -u fbmcp(servizio). - “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.