Assistente AI HQbird MCP
Assistente AI sotto il controllo umano
HQbird MCP collega Firebird a un assistente AI. Scrivi in parole semplici e l'assistente sceglie da solo gli strumenti. Legge liberamente. Ogni modifica attende il tuo "sì", e una modifica pericolosa attende l'approvazione sul server stesso.
- 122 strumenti
- 56 in sola lettura
- Firebird 2.5–5 Windows e Linux
- 2 canali per l'approvazione
- log di audit con catena di hash
Esempio
Una conversazione con l'assistente
Gli utenti si lamentano che il database è lento. L'assistente legge i dati, trova la causa, suggerisce un'azione e attende la tua decisione. Nomi e numeri nell'esempio sono inventati.
Funziona qualsiasi client MCP: Claude Desktop, Claude Code, Cursor, Codex, ZCode e altri.
Policy · approval
Quattro livelli di pericolosità
Ogni strumento ha un livello. Il server MCP verifica da solo il livello e le condizioni prima che la chiamata venga eseguita. Una chiamata che modifica qualcosa restituisce una richiesta di approvazione, non un risultato. L'assistente non può aggirare questo controllo.
Scegli uno strumento e vedi quale percorso segue la sua chiamata.
| Livello | Strumenti | Esempi | Come viene approvato |
|---|---|---|---|
| 0 · Lettura | 51 | sessioni, transazioni, piano di query, gstat, firebird.log, report dell'agente | Non necessaria. Transazione in sola lettura. |
| 1 · Modifica | 31 | DML e DDL, backup, restore di prova, sweep, utenti e grant, chiusura di una sessione | In chat: numero della richiesta e token, poi fb_confirm. |
| 2 · Operazione pericolosa | 14 | sostituire un database da un backup, modificare firebird.conf, fermare e riavviare Firebird | Solo sul server: il comando fbmcp ctl approve. Su Windows puoi anche installare una finestra nella tray. |
| 3 · Disabilitato | 1 | eliminare un database | Non viene mai eseguito. |
- AnteprimaOgni strumento che richiede approvazione accetta
mode: preview. Mostra cosa verrà fatto e non esegue nulla. - Condizioni per il livello 2Ogni operazione di livello 2 richiede una finestra di manutenzione aperta su quel database. Sostituire un database da un backup, una finestra esclusiva e SQL pericoloso richiedono anche un backup verificato non più vecchio di 24 ore. Un rifiuto indica cosa manca.
- Solo strumenti consentitiIl client vede nell'elenco solo ciò che è autorizzato a usare: nessun livello 3 e nessun livello superiore al massimo della sua chiave. Una chiamata diretta a uno strumento nascosto viene rifiutata.
- Una richiesta dura 15 minutiUn tentativo di approvarla tramite il canale sbagliato non la consuma.
fb_cancelelimina la richiesta. - Nessuna pagina di approvazioneE non ce ne sarà: una pagina che il modello può raggiungere comprometterebbe la protezione. Solo una persona sul server approva: con il comando
fbmcp ctl approveo nella finestra della tray, se installata.
Le letture vengono eseguite in una transazione in sola lettura: Firebird stesso blocca le scritture. Per un secondo livello di protezione, imposta un utente separato in sola lettura senza diritti di scrittura.
Monitoraggio · backup · grant
Per i DBA
L'assistente fa ciò che un DBA fa a mano: controlla sessioni e transazioni, legge i log, esegue un backup e lo verifica con un restore, gestisce gli utenti. Identifica i database per id, non per percorso del file.
| Attività | Strumenti | Livello |
|---|---|---|
| Tutto funziona? | fb_ping, fb_db_list, fb_db_health, fb_service_status | 0 |
| Sessioni e transazioni lunghe | fb_sessions, fb_transactions; per chiudere una sessione — fb_session_kill | 0 · 1 |
| Log e statistiche | fb_firebird_log, fb_gstat, fb_lwmonitoring, fb_trends | 0 |
| Backup e verifica | fb_backup_start (gbak), fb_backup_nbackup, fb_restore_test | 1 |
| Backup vecchi | fb_retention_run: prima una prova; elimina solo i backup verificati dal proprio catalogo | 1 |
| Sweep e validazione del database | fb_sweep, fb_validate (solo rilevamento, nessuna riparazione) | 1 |
| Utenti e grant | fb_user_create, fb_grant, fb_revoke; SYSDBA e i propri account non possono essere eliminati | 1 |
| Trace | fb_trace_start solo con template: audit-lite, performance, errors | 1 |
| firebird.conf | fb_config_get, fb_config_diff; per modificare — fb_config_set, Firebird non viene riavviato | 0 · 2 |
| Servizio e sostituzione del database | fb_service_restart; fb_restore_replace, il vecchio file resta come .pre-restore | 2 |
Verifica notturna del backup
La pianificazione viene approvata una volta sola, al momento della creazione. Dopo di che viene eseguita senza intervento umano. Ogni notte ottieni un backup verificato. Ti serve, ad esempio, per sostituire un database da un backup.
- 1Pianificazione
fb_schedule_create, obiettivonightly_verify; approvata una volta - 2Backupgbak nella cartella dei backup
- 3Restore di provain una cartella di lavoro; il database di origine non viene toccato
- 4✓ Backup verificatoun contrassegno nel catalogo dei backup
La sostituzione di un database da un backup e le operazioni di livello 3 non possono essere pianificate.
Scenari pronti
Gli scenari suggeriscono all'assistente l'ordine dei passi. Non applicano modifiche da soli.
Query · indici · migrazioni
Per gli sviluppatori
L'assistente in Cursor o Claude Code conosce il tuo schema, verifica una query prima di eseguirla e mostra il risultato come tabella direttamente in chat.
- 1Attivitàciò che ti serve, in una frase
- 2Fatti
fb_schema_list,fb_describe: solo tabelle e colonne esistenti - 3Bozzauna SELECT con ORDER BY
- 4Verifica
fb_query_check: compila senza eseguire - 5✓ Tabella in chat
fb_query: righe, piano e statistiche
Risultato come tabella
Nei client che supportano MCP Apps, il risultato di fb_query viene mostrato come tabella ordinabile. Gli altri client ricevono gli stessi dati come testo.
100 righe per impostazione predefinita, al massimo 1000. La tabella resta in memoria per 30 minuti e solo chi l'ha richiesta può vederla. Clicca sull'intestazione di una colonna per ordinare.
SELECT full_name, dept_no, salary FROM employee WHERE salary > 60000 ORDER BY salary DESC
Consigli sugli indici
Individua le scansioni complete della tabella e suggerisce CREATE INDEX con una stima del beneficio. Non crea l'indice stesso: lo fa fb_write, con approvazione. Dopo la creazione dell'indice, controlla di nuovo il piano.
Confronto dei database
Schema di due database, o di un database e della sua snapshot: cosa creare, modificare, eliminare. I dati vengono confrontati per chiave primaria; lo strumento non confronta una tabella di grandi dimensioni (per impostazione predefinita, più di 100.000 righe).
Migrazioni
Il piano mostra il livello di ogni istruzione. Tutte le migrazioni vengono applicate dopo una sola approvazione; se un file cambia, è necessaria una nuova richiesta. Il piano di rollback viene costruito da ciò che è stato registrato al momento dell'applicazione delle migrazioni.
fb_write trova il livello di ogni istruzione in uno script. Uno script che mescola istruzioni di livelli diversi viene rifiutato.
fbagent · API locale · 127.0.0.1
Dati di fbagent
L'agente fbagent è già in esecuzione sul server HQbird. Tramite MCP l'assistente ottiene tutto ciò che l'agente ha raccolto: il report sullo stato di salute, LWM (Light-weight Monitoring), gstat, le tracce, i deadlock, lo stato dei backup. Esegue anche i job dell'agente e ne modifica le impostazioni, con gli stessi livelli e le stesse approvazioni.
| Cosa | Strumenti | Livello |
|---|---|---|
| Report sullo stato di salute del server | fb_agent_status | 0 |
| LWM, gstat, metriche del database, tracce, deadlock | fb_agent_artifact_get, fb_agent_perf_report | 0 |
| Impostazioni di backup, sweep e restore | fb_agent_backup_config; password e token sono nascosti | 0 |
| Eseguire un job dell'agente | fb_agent_job_run; backup, restore e script SQL sono di livello 2 | 1 · 2 |
| Modificare l'impostazione di un job | fb_agent_config_set; credenziali, id e comandi non possono essere modificati | 2 |
| Riavviare Firebird tramite l'agente | fb_agent_restart, fb_agent_stop, fb_agent_start | 2 |
| Licenza e aggiornamenti | fb_agent_license, fb_agent_license_set, fb_agent_update_apply, fb_agent_product_update_apply | 0 · 1 · 2 |
- Solo localeL'agente accetta richieste solo su 127.0.0.1. L'indirizzo dell'agente proviene dalla configurazione del server MCP, non dalla chat.
- Il token resta nascostoIl token dell'agente non compare nell'output degli strumenti né nel registro di audit.
- Rilevamento dell'agente
fb_agent_discovertrova gli agenti sul server tramite i servizi Windows o le unit systemd. Non legge i token. - ClusterSe sul server è installato un nodo del cluster,
fb_agent_restart,fb_agent_stopefb_agent_startrifiutano per impostazione predefinita: è il nodo a controllare i riavvii.fb_service_restartnon effettua questo controllo, quindi non usarlo su un nodo del cluster.
Doppio controllo. Il server MCP approva la richiesta, e l'agente stesso esegue il job, secondo le proprie regole. Il log MCP mostra chi ha fatto la richiesta; i log dell'agente mostrano come è stata eseguita.
HQbird Cluster · RCM
Cluster di replica tramite l'assistente
L'assistente costruisce un cluster di replica passo dopo passo: attiva RCM, apre la finestra di pairing, collega gli host, prende i database in gestione e crea una copia per la replica. Funziona tramite l'agente e RCM. Non è necessario accedere ai server via SSH.
Le regole sono le stesse ovunque. Le letture non richiedono conferma. Una modifica viene confermata in chat. Un riavvio di Firebird, una copia del database sulla replica, la rimozione di un server dal cluster, lo switchover, il failover e il ritorno del vecchio master vengono confermati sul server.
| Cosa | Strumenti | Livello |
|---|---|---|
| Stato del cluster sul server | fb_agent_cluster: libero, in un cluster o proprietario RCM; slot e porte | 0 |
| Panoramica del cluster in RCM | fb_cluster_status: nodi, database, comandi, avvisi | 0 |
| Verificare gli host prima del collegamento | fb_cluster_probe: una riga per agente, fingerprint del certificato | 0 |
| Confrontare master e replica | fb_cluster_verify: conteggio delle righe di ogni tabella | 0 |
| Attivare RCM sul server | fb_agent_cluster_rcm | 1 |
| Finestra di pairing | fb_agent_cluster_pairing: stato, aperta per 1–24 ore, chiusura | 0 · 1 |
| Collegare gli host | fb_cluster_link; la richiesta mostra i fingerprint da confrontare | 1 |
| Database e pubblicazione | fb_cluster_replica_folder, fb_cluster_enroll, fb_cluster_publication | 1 |
| Password RCM | fb_cluster_rcm_password: una nuova password casuale, non mostrata in chat | 1 |
| Copia del database sulla replica | fb_cluster_reinit | 2 |
| Riavviare il Firebird di un nodo | fb_cluster_firebird_restart | 2 |
| Rimuovere un server dal cluster | fb_cluster_unlink | 2 |
| Servizi: dov'è il master | fb_cluster_service: master, repliche, router, problemi, operazione in corso | 0 |
| Descrivere un servizio e la sua regola | fb_cluster_service_put, fb_cluster_service_policy: descrizione del servizio, regola di failover automatico | 1 |
| Riprendere e annullare un'operazione | fb_cluster_resume, fb_cluster_operation_cancel; annullare solo prima del punto di non ritorno | 1 |
| Switchover | fb_cluster_switchover: spostamento pianificato del master, attende la fine dell'operazione | 2 |
| Failover | fb_cluster_failover: solo con consenso esplicito alla perdita di dati | 2 |
| Riportare il vecchio master | fb_cluster_rejoin | 2 |
| Eliminare un servizio | fb_cluster_service_delete: viene eliminato solo il record in RCM | 2 |
- Scenario pronto“Crea un cluster”: l'assistente procede passo dopo passo e a ogni passo mostra cosa farà.
- FingerprintPrima del collegamento, l'assistente mostra il fingerprint del certificato di ogni server. Confrontalo con la riga del riepilogo dell'installazione.
- Dry runPrima di prendere in gestione una cartella con i database, l'assistente mostra quali database troverà RCM.
- Switchover e failoverL'assistente avvia lo spostamento del master e segue i passi dell'operazione. Una persona sul server conferma l'avvio. Il failover richiede anche il consenso esplicito alla perdita di dati. Maggiori informazioni nella pagina del cluster.
HTTPS · chiavi API · audit
Modalità remota, installazione e registro di audit
L'assistente viene eseguito sul PC dell'amministratore, e il server MCP viene eseguito sul server del database. Tra di essi ci sono HTTPS e una chiave API. Ogni persona ha la propria chiave e il proprio livello massimo.
- Una chiave per ogni persona
fbmcp ctl apikey new <name> --max-tier 2. Il valore viene mostrato una sola volta. Dopo un cambio di chiave, la vecchia chiave smette di funzionare entro pochi secondi. - LimitiPer chiave: chiamate simultanee, chiamate al minuto, sessioni aperte. Oltre il limite, la risposta è 429.
- Guida in portogheseLa guida completa all'installazione e all'uso è disponibile anche in portoghese brasiliano.
- Agenti autonomiIl profilo
autonomous: solo lettura per impostazione predefinita. Una modifica attende un operatore sul server;fb_confirmda parte dell'agente viene rifiutato. 10 chiamate al minuto. Esegui tali agenti all'interno della rete aziendale. - IndirizziUna chiave può essere associata a indirizzi (
allow_from). Un altro indirizzo riceve 403 e una voce nel log.
Installazione in HQbird
L'installer di HQbird installa il server MCP per impostazione predefinita. Un solo server serve tutte le linee Firebird sulla macchina. Un solo comando configura tutto, e puoi eseguirlo di nuovo.
- 1Installer di HQbirdWindows o Linux
- 2fbmcp ctl hqbird-installun solo comando, nessuna modifica manuale dei file YAML
- 3Linee Firebirdtrova ogni linea e il suo agente
- 4Databasealias di databases.conf e database collegati di recente
- 5✓ Servizioavvia, controlla, connetti il file .txt per i client
La modalità remota si attiva quando sono soddisfatte tre condizioni: è impostato un elenco di indirizzi amministratore (--allow-from), il firewall è in esecuzione ed esiste almeno una chiave API. La chiave viene creata separatamente. Successivamente, esegui di nuovo fbmcp ctl hqbird-install. La porta predefinita è 8650.
Catena di hash
Ogni decisione (consentita, in sospeso, approvata, rifiutata) viene scritta nel log. Ogni voce è collegata alla precedente. Un controllo della catena mostra se una voce è stata modificata o eliminata.
Log troncato — il server resta spento
Se il log è troncato o la sua fine non corrisponde alla voce di controllo, il server MCP non si avvia. Questo è un segno di manomissione e devi indagare. Il comando fbmcp ctl verify controlla l'intera catena.
Tramite l'agente
fbagent aggiorna il server MCP: arresta, sostituisce, avvia, controlla, esegue il rollback in caso di errore. Su Linux una build non firmata non viene installata. La configurazione e le chiavi non cambiano.