fbmcp: instalação e uso
Para quem instala e opera o fbmcp e não o compilou. Não é preciso conhecer Go nem os detalhes internos do Firebird. Estado em 2026-11-16, versão 2027.2.24 (modo local e remoto, instalação no HQbird, ponte fbagent, cluster HQbird, grade de resultados).
Versões curtas: quickstart-en.md | quickstart-ru.md |
quickstart-pt.md. Detalhes (em inglês):
remote.md (modo remoto), agent-bridge.md
(fbagent), tool-reference.md (todas as ferramentas, tier
e argumentos), claude-desktop.md (conexão do cliente no
host de desenvolvimento), ADRs em decisions/.
1. O que é o fbmcp
O fbmcp é um servidor MCP para Firebird 2.5–5.0 no Windows e no Linux. Um
cliente MCP (Claude Desktop, Claude Code, Cursor, Codex, ZCode e outros) o
usa para trabalhar como um DBA: monitoramento, backups e restores
verificados, SQL/DDL/DCL, índices, usuários e permissões, firebird.conf,
agendador, migrações, o fbagent do HQbird e o cluster HQbird. Ele tem
122 ferramentas: 56 somente leitura (Tier 0), 44 Tier 1, 21 Tier 2,
1 Tier 3 (desativada).
fb_demo_write só existe quando o servidor roda com FBMCP_DEMO_TOOLS=1.
O cliente vê apenas as ferramentas que pode usar. A lista de ferramentas
esconde: Tier 3, ferramentas acima do tier máximo da identidade,
fb_confirm e fb_cancel para uma identidade somente leitura, as
ferramentas do fbagent enquanto agents: estiver vazio
(fb_agent_discover e fb_agent_register continuam visíveis), as
ferramentas de migração enquanto nenhum banco tiver migrations_dir e as
ferramentas de cluster enquanto o fbmcp.yaml não tiver a seção rcm:. Quando
um reload da configuração muda esse conjunto, o cliente recebe uma nova
lista. Uma chamada direta a uma ferramenta escondida recebe uma recusa clara.
| Binário | Função |
|---|---|
fbmcp |
O servidor. Padrão: MCP via stdio (o cliente o inicia). -serve: sem stdio, roda como serviço (agendador, socket de attach, listener HTTPS se configurado). fbmcp bridge: cliente stdio para um fbmcp remoto |
fbmcpctl |
CLI do operador: doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. É o mesmo programa que fbmcp ctl |
fbmcp-tray |
Bandeja do Windows: janela Aprovar/Negar para pedidos que precisam de um operador |
Um kernel por pasta de estado (state). Um segundo cliente com a mesma configuração não inicia um segundo kernel: ele se conecta (attach) ao que já está rodando.
2. Modelo de segurança
Toda chamada passa por política → confirmação humana → execução auditada.
| Tier | O quê | Como é confirmado |
|---|---|---|
| 0 | Leituras (transações somente leitura garantidas pelo engine) | Não precisa |
| 1 | Mudanças de rotina: DML/DDL, backup, usuários, permissões | No chat: o cliente mostra um id de pedido e um token; a pessoa concorda; o cliente chama fb_confirm |
| 2 | Alto impacto: controle do serviço, restore-replace, firebird.conf, janela exclusiva, registro, reinício de agentes |
Somente fora do chat: a bandeja ou fbmcpctl approve. O cliente nunca pode aprovar |
| 3 | Crítico (fb_db_drop) |
Desativado por projeto |
- Tier 2 normalmente precisa de uma janela de manutenção aberta
(
fb_window_open, no mesmodb) e de um backup verificado com menos de 24 horas. A recusa diz o que falta. - Um pedido pendente expira em 15 minutos. Uma tentativa pelo canal
errado não o consome;
fb_cancelo remove. - Toda ferramenta com confirmação aceita
mode: preview: mostra o impacto e não faz nada. - Toda decisão (permitido, pendente, aprovado, negado) vai para o
audit.jsonl, com cadeia de hashes. - Não existe página web de aprovação, e nunca deve existir: uma página que o modelo consegue acessar quebraria o projeto.
3. Escolha uma instalação
| Instalação | Onde o fbmcp roda | Quando usar | Seção |
|---|---|---|---|
| A. Local stdio | No seu PC; o cliente o inicia | Um administrador, Firebird neste PC ou na rede local | §6 |
| B. Serviço local | Serviço Windows no host do banco (-serve) |
Agendamentos precisam rodar sem cliente aberto | §7 |
| C. Remoto | Serviço no servidor do banco, HTTPS + chaves de API | Vários administradores, servidor distante, agentes autônomos | §8 |
Na instalação A o kernel vive só enquanto um cliente roda, então os
agendamentos só disparam nesse período. Use B ou C para agendamentos sem
supervisão (nightly_verify).
fbmcp no HQbird. As instalações do HQbird 2027 e o fbagent instalam o
fbmcp por padrão: um serviço por servidor para todas as linhas do Firebird,
configurado por fbmcp ctl hqbird-install. Nesse servidor não siga §6–§8;
leia hqbird.md (estrutura, modo remoto com --allow-from,
chaves de API).
4. Obter os binários
Requisitos: Go ≥ 1.26.11 (um Go mais antigo, 1.21+, baixa o go1.26.11 sozinho na primeira compilação; isso precisa de internet), CGO não é necessário; Firebird 2.5–5.0; fbagent ≥ 2.67 com a Local API para as ferramentas de agente (opcional); fbagent 3.1.0+ e RCM 2027.5.11+ para as ferramentas de cluster (opcional).
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-trayBinários para Linux (compilação cruzada no Windows, ou compile no Linux sem
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/fbmcpctlChecksums: Get-FileHash dist/* ou sha256sum dist/*. Outras plataformas:
packaging/README.md. Coloque os binários em uma
pasta só deles (os exemplos usam 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 são o mesmo programa. fbmcpctl help lista os
comandos. Os comandos que leem a configuração aceitam --config <arquivo>;
sem ele, usam FBMCP_CONFIG, depois fbmcp.yaml na pasta atual, depois ao
lado do programa, depois o padrão do HQbird
(C:\HQbirdData\fbmcp\fbmcp.yaml, /etc/fbmcp/fbmcp.yaml), e mostram
using config <caminho>.
5. Configurar o fbmcp.yaml
Exemplo completo: packaging/fbmcp.yaml.example.
Configuração mínima no Windows:
state:
dir: C:\ProgramData\fbmcp\state
# secrets:
# dir: C:\ProgramData\fbmcp\secrets # instalações B e C
instances:
- id: fb5
addr: localhost:3050
bin_dir: C:\Program Files\Firebird\Firebird_5_0 # pasta com gbak, gfix, gstat
version: "5.0"
service: FirebirdServerDefaultInstance # Linux: firebird.opt_fb50
service_user: SYSDBA # ferramentas da instância (fb_firebird_log, ...)
service_secret_env: FBMCP_FB5_SERVICE_PW
databases:
- id: main # ferramentas e chats usam o id, nunca o caminho
instance: fb5
path: D:\Data\main.fdb
backup_dir: D:\fbmcp\backups
work_dir: D:\fbmcp\work # testes de restore; Linux: fora de /tmp
ro_user: FBMCP_RO # um usuário Firebird somente leitura
ro_secret_env: FBMCP_MAIN_RO_PW
admin_user: SYSDBA
admin_secret_env: FBMCP_MAIN_ADMIN_PW
notify:
webhook_url: "" # opcional: webhook de chat para pedidos pendentes
retention:
keep_days: 0 # 0 = nunca apagar backupsSegredos. O YAML guarda só os nomes das variáveis. O fbmcp procura
cada valor nesta ordem: variável de ambiente → arquivo
<secrets.dir>/<NOME> → keyring do sistema da conta que roda o fbmcp.
C:\fbmcp\fbmcpctl.exe secret set FBMCP_MAIN_RO_PW # keyring do usuário atual (instalação A)
C:\fbmcp\fbmcpctl.exe secret set --dir C:\ProgramData\fbmcp\secrets FBMCP_MAIN_RO_PW # pasta de segredos (instalações B, C)O valor é lido da entrada padrão (digite, depois Ctrl+Z, Enter; no Linux
Ctrl+D). Uma conta de serviço (LocalSystem, NT SERVICE\...) não enxerga o
seu keyring: use secrets.dir para serviços. Um arquivo de segredo alterado
vale em poucos segundos, sem reiniciar.
Usuário somente leitura. Crie um usuário Firebird separado para
ro_user (SQL:
quickstart-pt.md:
CREATE USER FBMCP_RO, GRANT SELECT em todas as tabelas e, no Firebird
4.0+, um role com MONITOR_ANY_ATTACHMENT para que fb_sessions veja todas
as conexões). SYSDBA como usuário somente leitura é só para desenvolvimento;
o doctor avisa sobre isso.
Reload ao vivo. O fbmcp aplica sozinho as mudanças no fbmcp.yaml
(observa o arquivo), ou com fb_config_reload. Não é preciso reiniciar o
cliente nem o processo. Um reload espera os jobs dos bancos alterados (30 s)
e depois aplica. Recusados: mudança de state.dir, caminhos de banco
duplicados, configuração remota insegura.
Verificação: C:\fbmcp\fbmcpctl.exe doctor deve terminar com
doctor: green (modo remoto: doctor --remote, sem linhas FAIL). Ele cria
a pasta state que faltar, faz login em cada banco com os dois usuários, e
cada linha FAIL termina com Fix: e o comando a executar.
6. Instalação A — local stdio
Use caminhos absolutos. Não defina listen. Reinicie o cliente depois de
mudar a configuração dele: os clientes carregam os servidores só ao iniciar.
| Cliente | Onde | Entrada |
|---|---|---|
| Claude Desktop | Settings → Developer → Edit Config (%APPDATA%\Claude\claude_desktop_config.json) |
"mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}} |
| Claude Code | linha de comando | claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml" |
| Cursor | %USERPROFILE%\.cursor\mcp.json ou .cursor\mcp.json no projeto |
o mesmo JSON do Claude Desktop |
| Codex | codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml ou %USERPROFILE%\.codex\config.toml |
[mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml'] |
| ZCode | .zcode\config.json no projeto |
"mcp": {"servers": {"fbmcp": { ...mesmo command e args... }}} |
As senhas estão no keyring (§5), então não é preciso um bloco env. Se
mesmo assim você colocar uma senha no bloco env do cliente, mantenha esse
arquivo fora do git.
Depois inicie a bandeja para as aprovações Tier 2:
C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml (a cada logon:
.\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).
Teste rápido no cliente: “chame fb_ping” (mostra o nome do servidor e a
sua identidade com o tier máximo), depois “fb_db_list”, depois
“fb_db_health para main”.
7. Instalação B — serviço Windows local
PowerShell como administrador:
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp- O serviço roda
fbmcp -servecomo LocalSystem, reinicia em caso de falha e para de forma limpa quando o serviço é parado. - Use
secrets.dirpara as senhas (§5). - Proteja a pasta: só SYSTEM e Administrators podem escrever em
C:\fbmcp(o script mostra o comandoicacls). Uma pasta criada emC:\deixa qualquer usuário alterar os arquivos, e o serviço os executa como SYSTEM. - O usuário da bandeja e os clientes stdio locais precisam de leitura e
escrita na pasta state:
icacls C:\ProgramData\fbmcp\state /grant "<usuário>:(OI)(CI)M". Um cliente stdio com a mesma configuração então se conecta ao kernel do serviço. - Prontidão:
C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml. - Log:
<state_dir>\fbmcp.log(5 × 10 MiB; travamentos emfbmcp-crash.log).
Para um serviço que os administradores acessam pela rede, use a instalação C.
8. Instalação C — remota (HTTPS + chaves de API)
Procedimento completo: remote.md. Forma curta:
Servidor Windows (como administrador):
- Binários e
fbmcp.yamlemC:\fbmcp\(modelo: 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"— anote o pinsha256:....- Uma chave por pessoa ou agente:
C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets(mostrada uma única vez). Com--config C:\fbmcp\fbmcp.yamlele também adiciona a entrada emidentities:e usasecrets.dir. - Senhas e tokens de agente:
fbmcpctl secret set --dir C:\ProgramData\fbmcp\secrets NOME. .\packaging\windows\install-remote.ps1 -Port 8443 -AllowFrom 10.0.0.0/24 -FirebirdService FirebirdServerDefaultInstance -WhatIf, depois sem-WhatIf. Ele cria o serviço, a regra de firewall, as ACLs das pastas e os direitos sobre o serviço do Firebird.C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml→ nenhum FAIL;curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz→ok.- Bandeja para quem aprova:
.\packaging\windows\install-tray.ps1.
Servidor Linux (root): copie fbmcp, fbmcpctl e packaging/linux/, depois
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/24O script cria as pastas, o certificado, uma primeira configuração com uma
chave admin (mostrada uma única vez), a unit do systemd, a regra de sudo
para a unit do Firebird e a regra do ufw, e depois roda doctor --remote.
Adicione databases: e agents: em /etc/fbmcp/fbmcp.yaml. Aprovações no
Linux (sem bandeja): sudo -u firebird fbmcpctl approve [id]. Ele encontra
/etc/fbmcp/fbmcp.yaml sozinho, pergunta y/N (--yes não pergunta), e
--deny <id> --reason "..." recusa.
PC do administrador:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(a chave que você recebeu).- Qualquer cliente stdio (Claude Desktop, Cursor, Codex, ZCode): a entrada
da §6 com estes
args:["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. O pin confere a chave do servidor, então um certificado autoassinado não precisa de configuração de CA. - O Claude Code também pode se conectar direto por HTTP (
.mcp.json"type": "http", cabeçalhoAuthorization: Bearer ${FBMCP_KEY_SRV1},NODE_EXTRA_CA_CERTSpara um certificado autoassinado). Não passe a chave comclaude mcp add --header: ela fica gravada em texto puro. - Teste:
fb_pingmostra o nome do servidor e a sua identidade.
Agentes autônomos (OpenClaw e similares): uma chave separada com
apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32.
Somente leitura por padrão; todo pedido Tier 1 espera um operador, e
fb_confirm vindo do agente é recusado. Limites: remote.md §6–7.
9. Ponte fbagent e cluster HQbird (opcional)
As ferramentas de agente (fb_agent_status, fb_agent_job_run, …) usam
a Local API do fbagent do HQbird no mesmo host. Elas ficam desligadas até
agents: ter uma entrada.
- No cliente: “
fb_agent_discover”. Lista os agentes locais combase_url,instance_ide o nome sugerido para o token. Nunca lê tokens. - O operador guarda o
local_api.tokendo agente (não oagent.auth_token):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<porta>. Nunca digite um token no chat. - No cliente: “
fb_agent_registerpara esse agente” → aprove na bandeja. O fbmcp adiciona a entrada emagents:, recarrega e confere a identidade. - Teste:
fb_agent_status,fb_agent_instances.
fb_agent_config_set (mudar configurações de jobs: backup, sweep, …)
também precisa de config_path na entrada e de acesso de leitura ao
agent_config.json em uso, além de direito de criar arquivos na pasta dele.
Esse arquivo contém o token e as credenciais do Firebird, então essa
permissão é decisão do operador (agent-bridge.md). Quando
a verificação do agente falha, a ferramenta não grava nada.
Cluster HQbird (RCM). As ferramentas de cluster chamam o gerenciador de
cluster do HQbird (hqbirdrcm) no mesmo host. Elas só aparecem quando o
fbmcp.yaml tem a seção rcm: (url, ca_file, user,
password_env). Em um servidor HQbird Linux, fbmcp ctl hqbird-install a
escreve a partir de /opt/hqbirdrcm/rcm.json e guarda a primeira senha do
RCM no segredo FBMCP_RCM_PASSWORD; nos outros casos, adicione a seção à
mão (tool-reference.md). Depois:
fb_cluster_rcm_password: troque a primeira senha do RCM (Tier 1).- Um cluster novo: abra a janela de pareamento em cada host
(
fb_agent_cluster_pairing), inicie o RCM no master (fb_agent_cluster_rcm), ligue os hosts (fb_cluster_link), crie as réplicas (fb_cluster_reinit, Tier 2) e compare os dados (fb_cluster_verify). Passos (em inglês):prompts/cluster-setup.md. - Serviços do cluster (switchover, failover, rejoin):
fb_cluster_servicemostra os serviços e as verificações; as mudanças são Tier 2. Passos (em inglês):prompts/cluster-services.md.
10. Uso diário
Peça ao cliente em linguagem comum; ele escolhe as ferramentas. Exemplos:
| Tarefa | Ferramentas |
|---|---|
| Está tudo no ar? | fb_ping, fb_db_list, fb_db_health, fb_service_status |
| Ler dados | fb_query (somente leitura, linhas + plano + estatísticas por tabela; uma grade em clientes MCP-Apps); confira um rascunho com fb_query_check |
| Sessões, transações longas | fb_sessions, fb_transactions, fb_session_kill (Tier 1) |
| Consulta lenta | fb_analyze_query, fb_index_advice → aplique com fb_write; fb_agent_perf_report |
| Backup | fb_backup_start → id do job → fb_job_status |
| Verificar um backup | fb_restore_test (restaura em work_dir, marca o backup como verificado) |
| Backup noturno + verificação | fb_schedule_create com target=nightly_verify (confirmado uma vez; instalação B ou C) |
| Esquema / DDL | fb_schema_list, fb_describe, fb_write (cada comando é classificado e recebe um tier), fb_diff_schema |
| Migrações | fb_migration_status, fb_migration_plan, fb_migration_apply |
| Configuração do servidor | fb_config_get, fb_config_diff, fb_config_set (Tier 2) |
| Logs | fb_firebird_log |
| Capacidade | fb_trends, fb_gstat, fb_index_stats |
| Estado do cluster | fb_cluster_status, fb_cluster_service |
| Mudar o master | fb_cluster_switchover (sem perda de dados) ou fb_cluster_failover (master perdido), depois fb_cluster_rejoin (Tier 2) |
Os jobs são assíncronos: envie → fb_job_status. Os jobs de um banco rodam
um de cada vez. Um job sobrevive a um reinício do fbmcp apenas como
interrupted: envie de novo se ainda for necessário.
fb_config_set muda só a própria linha no firebird.conf (comentários,
indentação e fins de linha ficam iguais), guarda o arquivo antigo como
firebird.conf.prev e nunca reinicia o Firebird. Reinicie com
fb_service_restart (Tier 2): ele espera o serviço parar e voltar a rodar.
11. Tarefas do operador
| Tarefa | Comando |
|---|---|
| Listar / aprovar / negar pedidos | fbmcpctl approve; fbmcpctl approve <id>; fbmcpctl approve --deny <id> --reason "..." (ou a bandeja) |
| Trocar uma chave | fbmcpctl apikey rotate alice --config <fbmcp.yaml> (a chave antiga para em segundos) |
| Listar chaves | fbmcpctl apikey list (nomes, origens, tiers; nunca valores) |
| Remover uma pessoa | apague a entrada em identities:, depois fbmcpctl secret drop --dir <pasta> NOME |
| Renovar o certificado | fbmcpctl tls selfsign --renew --out <pasta> --dns ... --ip ... (pin igual, sem reiniciar) |
| Conferir a cadeia de auditoria | fbmcpctl verify |
| O kernel está vivo? | fbmcpctl ping; fbmcpctl status (leitura offline do estado) |
| Permitir controle do serviço | packaging/posture/verify.ps1 ou verify.sh, depois fbmcpctl setup --write-posture |
| Atualizar | pare o serviço (ou os clientes), troque os binários, inicie, rode doctor |
| Remover | Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux: remote.md §10. Mantenha a pasta state (auditoria), a menos que o responsável decida outra coisa |
Só no host de desenvolvimento: .\packaging\rebuild-install.ps1 -Force
recompila dist\, para e troca os binários em execução (os antigos ficam
como *.exe~), mescla as configurações dos clientes e roda doctor.
12. Recuperação após falha e reinício
Verificado pelo harness de caos (internal/killharness).
| Depois de uma falha ou kill | No reinício | Ação do operador |
|---|---|---|
| Job rodando ou na fila | Marcado interrupted; nunca é retomado |
Envie de novo se necessário |
| Pedido pendente, não confirmado | Restaurado do state.json (o TTL continua valendo) |
Confirme ou deixe expirar |
fb_restore_replace em andamento |
Termina: restore, validação, banco online; <db>.pre-restore é mantido |
Confira fb_db_health; apague .pre-restore depois |
fb_shutdown_window em andamento |
Termina o passo gfix -online |
Confira se está online |
instance.lock antigo |
Assumido automaticamente | Nenhuma |
state.json corrompido |
O kernel se recusa a iniciar; cópia guardada como state.json.corrupt-<ts> |
Inspecione; conserte ou remova o state.json de propósito (fbmcpctl repair reconstrói as permissões dos agendamentos a partir da auditoria) |
audit.jsonl corrompido ou cortado |
O kernel se recusa a iniciar | §13.2: trate como sinal de adulteração |
| Relógio voltou no tempo | O agendador pula; sem execução dupla | Nenhuma |
| Processo do serviço Windows morto | O SCM o reinicia em cerca de 5 s | Nenhuma |
O kernel falha fechado em tudo o que não consegue provar intacto. Um loop de reinícios é um achado: leia o log.
13. Roteiros para incidentes
13.1 Algo está errado com um banco
fbmcpctl doctor --config <arquivo>: configuração, segredos, logins no Firebird, pastas, postura, agendamentos. Cada linha FAIL tem umFix:.fb_db_list→fb_db_health <db>;fb_service_statuspara a instância.fb_sessions,fb_transactionspara problemas de conexões ou de distância da OAT;fb_firebird_logpara erros do engine.
13.2 Suspeita de adulteração ou corrupção: auditoria primeiro
fbmcpctl verify --config <arquivo>→audit chain OK: N entriesouBROKENcom o motivo.- Se falhar: guarde a pasta state inteira (ela é a evidência) e depois
investigue. Não apague o
audit.jsonlpara fazer o kernel iniciar.
13.3 Treino de restore (a cada trimestre)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ o backup fica verificado.fb_window_openpara o banco.fb_restore_replace→ aprove fora do chat. Indisponível até ficar online.- Confira:
fb_db_health, depois uma leitura real (fb_schema_list,fb_info). - O arquivo antigo fica como
<db>.pre-restoreaté você apagá-lo.
13.4 O cliente não conecta
fbmcpctl ping --config <arquivo>,fbmcpctl status --config <arquivo>.- Leia o log MCP do cliente (stdio) ou
<state_dir>\fbmcp.log/journalctl -u fbmcp(serviço). - “another fbmcp instance is active”: um kernel por pasta state. Clientes via pipe se conectam sozinhos; um segundo kernel falha rápido por projeto.
Nos comandos acima, --config pode ser omitido quando a busca da §4
encontra o arquivo.
14. Problemas comuns
| Sintoma | Significado / solução |
|---|---|
| As ferramentas não aparecem | Sintaxe do JSON, caminhos absolutos, reinício completo do cliente; o log MCP do cliente |
| Falta uma ferramenta na lista | Escondida de propósito (§1): acima do seu tier máximo, sem entrada em agents:, sem migrations_dir ou sem a seção rcm: |
| O servidor sai na hora | fbmcpctl doctor; um segredo faltando; um serviço não lê o seu keyring (use secrets.dir) |
| Tier 2 “confirmation rejected: channel policy” | Esperado no chat. Aprove na bandeja ou com fbmcpctl approve |
| Tier 2 “no open maintenance window” | fb_window_open para o mesmo db que você passa para a ferramenta |
fb_restore_replace negado: preconditions |
Precisa de um backup verificado < 24 h: fb_backup_start + fb_restore_test, e de uma janela |
| Controle do serviço negado | Falta posture.verified (fbmcpctl setup --write-posture) ou a conta não tem direitos sobre o serviço do Firebird |
fb_config_set: não consegue gravar |
A conta não pode alterar esse arquivo (unit Linux com ProtectSystem=strict; ACL no Windows). Edite à mão, ou veja remote.md §8 |
| A bandeja não mostra nada | Ela mostra só pedidos que precisam de um operador; confira os direitos do usuário da bandeja na pasta state e o tray.log lá |
| 401 (remoto) | Chave errada, ou o servidor não a carregou: apikey list, doctor --remote |
| 403 (remoto) | IP de origem fora de allow_from / firewall, ou cabeçalho Origin fora de allowed_origins |
| 429 (remoto) | Limites; espere o Retry-After |
| Pin não confere | A chave do servidor mudou; peça o novo pin ao administrador do servidor |
agent-unreachable |
Serviço do agente parado, local_api.enabled: false, ou base_url errado (padrão 127.0.0.1:(10000 + porta do firebird)) |
agent-auth |
O token guardado não é o local_api.token do agente; grave de novo |
agent-timeout em reinícios |
agents[].timeout_seconds (130) deve ser maior que o restart_timeout_seconds do agente (120) |
Error loading plugin MySQLEngine … no attach |
No HQbird isso normalmente significa que o arquivo do banco não existe; confira o caminho |
DROP INDEX puro em fb_write pede janela |
Lá ele é Tier 2; use fb_index_drop (Tier 1; recusa índices de constraints) |
| Índice novo não é usado | Atualize as estatísticas (fb_index_rebuild action=statistics); ORDER BY … DESC precisa de um índice DESCENDING |
| Ferramentas falham só para um banco | Ele está offline (fb_db_health); as ferramentas degradam por banco |
15. Referência da pasta state
| Caminho | Significado |
|---|---|
state.json (+ .tmp, .corrupt-*) |
Pedidos pendentes, jobs, catálogo de backups, workflows, agendamentos. Corrompido ⇒ recusa iniciar |
audit.jsonl (+ .head) |
Log de auditoria com cadeia de hashes; .head detecta truncamento |
events.jsonl |
Eventos de jobs (job.succeeded, job.failed com a mensagem) |
approvals\, denials\ |
Decisões fora do chat (bandeja / fbmcpctl approve), usadas em ~2 s |
instance.lock |
Trava de um kernel só |
attach.addr, attach.token |
Ponto de attach para clientes stdio extras |
fbmcp.log, fbmcp-crash.log |
Log do serviço (rotacionado) e saída de travamentos |
query-log.jsonl |
Toda chamada de fb_query |
trends\ |
Histórico do amostrador para fb_trends |
config-journal\ |
Histórico do fb_config_set (valor antigo e novo) |
posture.verified |
Marcador que permite o controle do serviço |
tray.log |
Erros da bandeja |
16. Status do roteiro de teste
Pendente (M1): percorrer este guia em um host Windows novo, usando só ele.
Os achados voltam para a versão em inglês.
Resultados de laboratório do modo remoto (host Linux, VM nova, serviço
Windows): findings/phase12-lab-2026-11-03.md.