Assistente de IA HQbird MCP
Assistente de IA sob controle humano
O HQbird MCP conecta o Firebird a um assistente de IA. Você escreve com palavras comuns, e o assistente escolhe as ferramentas sozinho. Ele lê livremente. Cada alteração espera o seu “sim”, e uma alteração perigosa espera a aprovação no próprio servidor.
- 122 ferramentas
- 56 só leem
- Firebird 2.5–5 Windows e Linux
- 2 canais de aprovação
- log com cadeia de hashes
Exemplo
Conversa com o assistente
Os usuários reclamam que o banco de dados está lento. O assistente lê os dados, encontra a causa, sugere uma ação e espera a sua decisão. Os nomes e números do exemplo são fictícios.
Qualquer cliente MCP serve: Claude Desktop, Claude Code, Cursor, Codex, ZCode e outros.
Política · aprovação
Quatro níveis de perigo
Cada ferramenta tem um nível. O próprio servidor MCP verifica o nível e as condições antes da execução. Uma chamada que altera algo não retorna um resultado, e sim um pedido de aprovação. O assistente não consegue contornar essa verificação.
Escolha uma ferramenta e veja o caminho que a chamada percorre.
| Nível | Ferramentas | Exemplos | Como é aprovado |
|---|---|---|---|
| 0 · Leitura | 51 | sessões, transações, plano de consulta, gstat, firebird.log, relatórios do agente | Não é necessário. Transação somente leitura. |
| 1 · Alteração | 31 | DML e DDL, backup, teste de restauração, sweep, usuários e permissões, encerramento de sessão | No chat: número do pedido e token, depois fb_confirm. |
| 2 · Operação perigosa | 14 | substituir o banco de dados por um backup, editar o firebird.conf, parar e reiniciar o Firebird | Somente no servidor: o comando fbmcp ctl approve. No Windows, também é possível instalar uma janela na bandeja. |
| 3 · Desativado | 1 | excluir o banco de dados | Não é executado. |
- Pré-visualizaçãoToda ferramenta com aprovação aceita
mode: preview. Esse modo mostra o que será feito e não faz nada. - Condições para o nível 2Toda operação de nível 2 exige uma janela de manutenção aberta nesse banco de dados. Substituir o banco por um backup, uma janela exclusiva e SQL perigoso exigem também um backup verificado com no máximo 24 horas. A recusa informa o que falta.
- Somente ferramentas permitidasO cliente vê na lista apenas o que lhe é permitido: sem o nível 3 e sem níveis acima do máximo da sua chave. Uma chamada direta a uma ferramenta oculta é recusada.
- O pedido vale 15 minutosUma tentativa de aprovar pelo canal errado não o consome.
fb_cancelexclui o pedido. - Sem página de aprovaçãoE não haverá: uma página que o modelo consiga alcançar quebraria a proteção. Só uma pessoa no servidor aprova: com o comando
fbmcp ctl approveou na janela da bandeja, se ela estiver instalada.
A leitura ocorre em uma transação somente leitura: o próprio Firebird bloqueia a escrita. Para uma segunda proteção, defina um usuário separado somente leitura, sem direitos de escrita.
Monitoramento · backups · permissões
Para DBAs
O assistente faz o que o DBA faz à mão: verifica sessões e transações, lê logs, faz backup e o verifica com uma restauração, gerencia usuários. Ele identifica os bancos de dados por id, não pelo caminho do arquivo.
| Tarefa | Ferramentas | Nível |
|---|---|---|
| Está tudo funcionando | fb_ping, fb_db_list, fb_db_health, fb_service_status | 0 |
| Sessões e transações longas | fb_sessions, fb_transactions; encerrar sessão — fb_session_kill | 0 · 1 |
| Logs e estatísticas | fb_firebird_log, fb_gstat, fb_lwmonitoring, fb_trends | 0 |
| Backup e verificação | fb_backup_start (gbak), fb_backup_nbackup, fb_restore_test | 1 |
| Backups antigos | fb_retention_run: primeiro uma execução de teste; exclui só backups verificados do próprio catálogo | 1 |
| Sweep e validação do banco | fb_sweep, fb_validate (só achados, sem correção) | 1 |
| Usuários e permissões | fb_user_create, fb_grant, fb_revoke; não é possível excluir o SYSDBA nem as próprias contas | 1 |
| Traces | fb_trace_start só com modelos: audit-lite, performance, errors | 1 |
| firebird.conf | fb_config_get, fb_config_diff; edição — fb_config_set, o Firebird não é reiniciado | 0 · 2 |
| Serviço e substituição do banco | fb_service_restart; fb_restore_replace, o arquivo antigo fica como .pre-restore | 2 |
Verificação noturna do backup
O agendamento é aprovado uma vez, na criação. Depois ele funciona sem uma pessoa. Toda noite você tem um backup verificado. Ele é necessário, por exemplo, para substituir o banco de dados por um backup.
- 1Agendamento
fb_schedule_create, objetivonightly_verify; aprovação uma vez - 2Backupgbak na pasta de backups
- 3Restauração de testeem uma pasta de trabalho; o banco de origem não é tocado
- 4✓ Backup verificadomarca no catálogo de backups
A substituição do banco por um backup e as operações de nível 3 não podem ser agendadas.
Cenários prontos
Os cenários sugerem ao assistente a ordem dos passos. Ele não aplica alterações sozinho.
Consultas · índices · migrações
Para desenvolvedores
O assistente no Cursor ou no Claude Code conhece o seu esquema, verifica a consulta antes da execução e mostra o resultado como tabela no próprio chat.
- 1Tarefao que é preciso, em uma frase
- 2Fatos
fb_schema_list,fb_describe: só tabelas e colunas existentes - 3Rascunhoum SELECT com ORDER BY
- 4Verificação
fb_query_check: compilação sem execução - 5✓ Tabela no chat
fb_query: linhas, plano e estatísticas
Resultado como tabela
Em clientes com suporte a MCP Apps, o resultado do fb_query aparece como uma tabela ordenável. Os outros clientes recebem os mesmos dados como texto.
Por padrão, 100 linhas, no máximo 1000. A tabela fica na memória por 30 minutos, e só quem a pediu pode vê-la. Clique no cabeçalho de uma coluna para ordenar.
SELECT full_name, dept_no, salary FROM employee WHERE salary > 60000 ORDER BY salary DESC
Sugestão de índice
Encontra leituras completas de tabela e sugere CREATE INDEX com uma estimativa do ganho. Não cria o índice: isso é feito pelo fb_write, com aprovação. Depois da criação, verifica o plano de novo.
Comparação de bancos
Esquema de dois bancos de dados, ou de um banco e seu snapshot: o que criar, alterar, excluir. Os dados são comparados pela chave primária; a ferramenta não compara uma tabela grande (por padrão, mais de 100.000 linhas).
Migrações
O plano mostra o nível de cada instrução. Todas as migrações são aplicadas após uma única aprovação; se um arquivo mudou, é preciso um novo pedido. O plano de rollback é montado a partir do que foi registrado na aplicação.
fb_write determina o nível de cada instrução do script. Um script que mistura instruções de níveis diferentes é recusado.
fbagent · Local API · 127.0.0.1
Dados do agente fbagent
O agente fbagent já roda no servidor HQbird. Pelo MCP, o assistente recebe tudo o que o agente coletou: relatório de saúde, LWM (Light-weight Monitoring), gstat, traces, deadlocks, estado dos backups. Ele também executa jobs do agente e altera as configurações deles, com os mesmos níveis e aprovações.
| O quê | Ferramentas | Nível |
|---|---|---|
| Relatório de saúde do servidor | fb_agent_status | 0 |
| LWM, gstat, métricas dos bancos, traces, deadlocks | fb_agent_artifact_get, fb_agent_perf_report | 0 |
| Configurações de backup, sweep e restauração | fb_agent_backup_config; senhas e tokens ficam ocultos | 0 |
| Executar um job do agente | fb_agent_job_run; backup, restauração e script SQL são nível 2 | 1 · 2 |
| Alterar uma configuração do job | fb_agent_config_set; não é possível alterar credenciais, ids e comandos | 2 |
| Reiniciar o Firebird pelo agente | fb_agent_restart, fb_agent_stop, fb_agent_start | 2 |
| Licença e atualizações | fb_agent_license, fb_agent_license_set, fb_agent_update_apply, fb_agent_product_update_apply | 0 · 1 · 2 |
- Somente localO agente aceita pedidos apenas em 127.0.0.1. O endereço do agente vem da configuração do servidor MCP, não do chat.
- Token ocultoO token do agente não aparece na saída das ferramentas nem no log de auditoria.
- Busca de agentes
fb_agent_discoverencontra os agentes no servidor pelos serviços do Windows ou pelas unidades do systemd. Ele não lê tokens. - ClusterSe o servidor tem um nó de cluster,
fb_agent_restart,fb_agent_stopefb_agent_startrecusam por padrão: quem controla o reinício é o nó.fb_service_restartnão verifica isso; não o use em um nó de cluster.
Controle duplo. O servidor MCP aprova o pedido, e o próprio agente executa o job, com as suas regras. O log do MCP mostra quem pediu; os logs do agente mostram como foi executado.
HQbird Cluster · RCM
Cluster de replicação pelo assistente
O assistente monta o cluster de replicação passo a passo: liga o RCM, abre a janela de pareamento, vincula os hosts, coloca os bancos de dados sob gerenciamento e faz a cópia para a réplica. Ele trabalha pelo agente e pelo RCM. Não é preciso entrar nos servidores por SSH.
As regras são as mesmas de todo o resto. A leitura não exige confirmação. Uma alteração é confirmada no chat. O reinício do Firebird, a cópia do banco de dados para a réplica, a retirada do servidor do cluster, o switchover, o failover e a volta do master antigo são confirmados no servidor.
| O quê | Ferramentas | Nível |
|---|---|---|
| Estado do cluster no servidor | fb_agent_cluster: livre, no cluster ou dono do RCM; slot e portas | 0 |
| Visão geral do cluster no RCM | fb_cluster_status: nós, bancos de dados, comandos, alertas | 0 |
| Verificar os hosts antes de vincular | fb_cluster_probe: uma linha por agente, impressão digital do certificado | 0 |
| Comparar master e réplica | fb_cluster_verify: número de linhas de cada tabela | 0 |
| Ligar o RCM no servidor | fb_agent_cluster_rcm | 1 |
| Janela de pareamento | fb_agent_cluster_pairing: estado, abrir por 1–24 horas, fechar | 0 · 1 |
| Vincular os hosts | fb_cluster_link; o pedido mostra as impressões digitais para conferência | 1 |
| Bancos de dados e publicação | fb_cluster_replica_folder, fb_cluster_enroll, fb_cluster_publication | 1 |
| Senha do RCM | fb_cluster_rcm_password: nova senha aleatória, não aparece no chat | 1 |
| Cópia do banco de dados para a réplica | fb_cluster_reinit | 2 |
| Reinício do Firebird do nó | fb_cluster_firebird_restart | 2 |
| Retirar o servidor do cluster | fb_cluster_unlink | 2 |
| Serviços: onde está o master | fb_cluster_service: master, réplicas, roteadores, problemas, operação em andamento | 0 |
| Descrever o serviço e a regra | fb_cluster_service_put, fb_cluster_service_policy: descrição do serviço, regra do failover automático | 1 |
| Resume e cancelamento da operação | fb_cluster_resume, fb_cluster_operation_cancel; cancelamento só antes do ponto sem retorno | 1 |
| Switchover | fb_cluster_switchover: mudança planejada do master, espera o fim da operação | 2 |
| Failover | fb_cluster_failover: só com aceite explícito da perda de dados | 2 |
| Trazer de volta o master antigo | fb_cluster_rejoin | 2 |
| Excluir o serviço | fb_cluster_service_delete: só o registro no RCM é excluído | 2 |
- Cenário pronto“Monte o cluster”: o assistente segue os passos e, em cada um, mostra o que será feito.
- Impressões digitaisAntes de vincular, o assistente mostra a impressão digital do certificado de cada servidor. Compare-a com a linha do resultado da instalação.
- Execução de testeAntes de colocar uma pasta com bancos de dados sob gerenciamento, o assistente mostra quais bancos o RCM vai encontrar.
- Switchover e failoverO assistente inicia a mudança do master e acompanha as etapas da operação. Uma pessoa confirma o início no servidor. O failover exige também o aceite explícito da perda de dados.Mais detalhes na página do cluster.
HTTPS · chaves de API · auditoria
Modo remoto, instalação e log
O assistente roda no PC do administrador, e o servidor MCP roda no servidor de banco de dados. Entre eles há HTTPS e uma chave de API. Cada pessoa tem a sua chave e o seu nível máximo.
- Uma chave para cada pessoa
fbmcp ctl apikey new <nome> --max-tier 2. O valor é mostrado uma vez. Após a troca da chave, a antiga para de funcionar em poucos segundos. - LimitesPor chave: chamadas simultâneas, chamadas por minuto, sessões abertas. Acima do limite, a resposta é 429.
- Guia em portuguêsO guia completo de instalação e uso também está disponível em português do Brasil.
- Agentes autônomosPerfil
autonomous: por padrão, somente leitura. Uma alteração espera um operador no servidor;fb_confirmvindo do agente é recusado. 10 chamadas por minuto. Esses agentes rodam dentro da rede da empresa. - EndereçosA chave pode ser vinculada a endereços (
allow_from). Outro endereço recebe 403 e um registro no log.
Instalação no HQbird
O instalador do HQbird instala o servidor MCP por padrão. Um servidor atende todas as linhas do Firebird na máquina. Um único comando configura tudo, e ele pode ser executado de novo.
- 1Instalador do HQbirdWindows ou Linux
- 2fbmcp ctl hqbird-installum comando, sem editar YAML à mão
- 3Linhas do Firebirdencontra cada linha e o seu agente
- 4Bancos de dadosaliases do databases.conf e bancos conectados recentemente
- 5✓ Serviçoinício, verificação, arquivo connect.txt para os clientes
O modo remoto é ativado quando três condições são atendidas: há uma lista de endereços de administradores (--allow-from), o firewall está ativo e existe pelo menos uma chave de API. A chave é criada separadamente. Depois disso, execute fbmcp ctl hqbird-install de novo. A porta padrão é 8650.
Cadeia de hashes
Cada decisão (permitido, pendente, aprovado, recusado) é gravada no log. Cada registro está ligado ao anterior. A verificação da cadeia mostra se um registro foi alterado ou excluído.
Log truncado — servidor parado
Se o log foi truncado ou o seu final não confere com o registro de controle, o servidor MCP não inicia. Isso indica interferência e precisa ser investigado. O comando fbmcp ctl verify verifica a cadeia inteira.
Pelo agente
O fbagent atualiza o servidor MCP: parada, substituição, início, verificação, rollback em caso de falha. No Linux, um build sem assinatura não é instalado. A configuração e as chaves não mudam.