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.

    Rota da chamada: assistente, política fbmcp, quatro níveis, log de auditoria
    NívelFerramentasExemplosComo é aprovado
    0 · Leitura51sessões, transações, plano de consulta, gstat, firebird.log, relatórios do agenteNão é necessário. Transação somente leitura.
    1 · Alteração31DML e DDL, backup, teste de restauração, sweep, usuários e permissões, encerramento de sessãoNo chat: número do pedido e token, depois fb_confirm.
    2 · Operação perigosa14substituir o banco de dados por um backup, editar o firebird.conf, parar e reiniciar o FirebirdSomente no servidor: o comando fbmcp ctl approve. No Windows, também é possível instalar uma janela na bandeja.
    3 · Desativado1excluir o banco de dadosNã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_cancel exclui 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 approve ou 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.

    TarefaFerramentasNível
    Está tudo funcionandofb_ping, fb_db_list, fb_db_health, fb_service_status0
    Sessões e transações longasfb_sessions, fb_transactions; encerrar sessão — fb_session_kill0 · 1
    Logs e estatísticasfb_firebird_log, fb_gstat, fb_lwmonitoring, fb_trends0
    Backup e verificaçãofb_backup_start (gbak), fb_backup_nbackup, fb_restore_test1
    Backups antigosfb_retention_run: primeiro uma execução de teste; exclui só backups verificados do próprio catálogo1
    Sweep e validação do bancofb_sweep, fb_validate (só achados, sem correção)1
    Usuários e permissõesfb_user_create, fb_grant, fb_revoke; não é possível excluir o SYSDBA nem as próprias contas1
    Tracesfb_trace_start só com modelos: audit-lite, performance, errors1
    firebird.conffb_config_get, fb_config_diff; edição — fb_config_set, o Firebird não é reiniciado0 · 2
    Serviço e substituição do bancofb_service_restart; fb_restore_replace, o arquivo antigo fica como .pre-restore2

    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.

    1. 1Agendamentofb_schedule_create, objetivo nightly_verify; aprovação uma vez
    2. 2Backupgbak na pasta de backups
    3. 3Restauração de testeem uma pasta de trabalho; o banco de origem não é tocado
    4. 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.

    Verificação de saúde Otimização Auditoria de segurança Revisão de DDL Plano de migração Prontidão para desastres Construtor de consultas

    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.

    1. 1Tarefao que é preciso, em uma frase
    2. 2Fatosfb_schema_list, fb_describe: só tabelas e colunas existentes
    3. 3Rascunhoum SELECT com ORDER BY
    4. 4Verificaçãofb_query_check: compilação sem execução
    5. 5✓ Tabela no chatfb_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
    6 linhas · PLAN SORT (EMPLOYEE NATURAL) · somente leitura
    fb_index_advice

    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.

    fb_diff_schema · fb_diff_data

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

    fb_migration_*

    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êFerramentasNível
    Relatório de saúde do servidorfb_agent_status0
    LWM, gstat, métricas dos bancos, traces, deadlocksfb_agent_artifact_get, fb_agent_perf_report0
    Configurações de backup, sweep e restauraçãofb_agent_backup_config; senhas e tokens ficam ocultos0
    Executar um job do agentefb_agent_job_run; backup, restauração e script SQL são nível 21 · 2
    Alterar uma configuração do jobfb_agent_config_set; não é possível alterar credenciais, ids e comandos2
    Reiniciar o Firebird pelo agentefb_agent_restart, fb_agent_stop, fb_agent_start2
    Licença e atualizaçõesfb_agent_license, fb_agent_license_set, fb_agent_update_apply, fb_agent_product_update_apply0 · 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 agentesfb_agent_discover encontra 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_stop e fb_agent_start recusam por padrão: quem controla o reinício é o nó. fb_service_restart nã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êFerramentasNível
    Estado do cluster no servidorfb_agent_cluster: livre, no cluster ou dono do RCM; slot e portas0
    Visão geral do cluster no RCMfb_cluster_status: nós, bancos de dados, comandos, alertas0
    Verificar os hosts antes de vincularfb_cluster_probe: uma linha por agente, impressão digital do certificado0
    Comparar master e réplicafb_cluster_verify: número de linhas de cada tabela0
    Ligar o RCM no servidorfb_agent_cluster_rcm1
    Janela de pareamentofb_agent_cluster_pairing: estado, abrir por 1–24 horas, fechar0 · 1
    Vincular os hostsfb_cluster_link; o pedido mostra as impressões digitais para conferência1
    Bancos de dados e publicaçãofb_cluster_replica_folder, fb_cluster_enroll, fb_cluster_publication1
    Senha do RCMfb_cluster_rcm_password: nova senha aleatória, não aparece no chat1
    Cópia do banco de dados para a réplicafb_cluster_reinit2
    Reinício do Firebird do nófb_cluster_firebird_restart2
    Retirar o servidor do clusterfb_cluster_unlink2
    Serviços: onde está o masterfb_cluster_service: master, réplicas, roteadores, problemas, operação em andamento0
    Descrever o serviço e a regrafb_cluster_service_put, fb_cluster_service_policy: descrição do serviço, regra do failover automático1
    Resume e cancelamento da operaçãofb_cluster_resume, fb_cluster_operation_cancel; cancelamento só antes do ponto sem retorno1
    Switchoverfb_cluster_switchover: mudança planejada do master, espera o fim da operação2
    Failoverfb_cluster_failover: só com aceite explícito da perda de dados2
    Trazer de volta o master antigofb_cluster_rejoin2
    Excluir o serviçofb_cluster_service_delete: só o registro no RCM é excluído2
    • 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.

    PC do admin com cliente MCP e fbmcp bridge, HTTPS pelo firewall até o serviço fbmcp no servidor; o fbmcp acessa o Firebird e o fbagent; pedidos perigosos são aprovados por uma pessoa no servidor
    Modo remoto. A ponte no PC pega a chave do cofre do sistema operacional e verifica o certificado do servidor por pin. Senhas e caminhos dos bancos não chegam ao chat: os bancos são indicados por id.
    • Uma chave para cada pessoafbmcp 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_confirm vindo 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.

    1. 1Instalador do HQbirdWindows ou Linux
    2. 2fbmcp ctl hqbird-installum comando, sem editar YAML à mão
    3. 3Linhas do Firebirdencontra cada linha e o seu agente
    4. 4Bancos de dadosaliases do databases.conf e bancos conectados recentemente
    5. 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.

    audit.jsonl

    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.

    Falha — parada

    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.

    Atualização

    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.

    ← Voltar à visão geral do HQbird 2027