fbmcp: instalación y uso
Destinatario: la persona que instala y opera fbmcp y no lo construyó. No hace falta conocer los detalles internos de Go ni de Firebird. Estado al 2026-11-16, versión 2027.2.24 (modo local y remoto, instalación de HQbird, puente fbagent, cluster HQbird, cuadrícula de resultados).
Versiones breves, que no están en este sitio: quickstart-en.md, quickstart-ru.md,
quickstart-pt.md. Detalles, en inglés: remote.md (modo
remoto), agent-bridge.md (fbagent),
tool-reference.md (cada herramienta, su Tier y sus argumentos),
claude-desktop.md (conexión del cliente en el equipo de desarrollo),
ADR en decisions/.
1. Qué es fbmcp
fbmcp es un servidor MCP para Firebird 2.5–5.0 en Windows y Linux. Un cliente
MCP (Claude Desktop, Claude Code, Cursor, Codex, ZCode y otros) lo usa
para trabajar como DBA: supervisión, copias de seguridad y restauraciones verificadas, SQL/DDL/DCL,
índices, usuarios y permisos, firebird.conf, un planificador, migraciones,
el fbagent de HQbird y el cluster HQbird. Tiene 122 herramientas: 56 de solo lectura (Tier 0), 44 Tier 1,
21 Tier 2, 1 Tier 3 (desactivada). fb_demo_write está solo cuando
el servidor se ejecuta con FBMCP_DEMO_TOOLS=1.
Un cliente ve solo las herramientas que puede usar. La lista de herramientas oculta: Tier 3,
herramientas por encima del Tier máximo de la identidad, fb_confirm y fb_cancel para una
identidad de solo lectura, las herramientas de fbagent mientras agents: está vacío
(fb_agent_discover y fb_agent_register siguen), las herramientas de migración
mientras ninguna base tiene migrations_dir, y las herramientas de cluster mientras
fbmcp.yaml no tiene una sección rcm:. Cuando una recarga de la configuración cambia este
conjunto, el cliente recibe una lista nueva. Una llamada directa a una herramienta oculta recibe
un rechazo claro.
| Binario | Función |
|---|---|
fbmcp |
El servidor. Predeterminado: MCP por stdio (lo inicia un cliente). -serve: sin stdio, se ejecuta como servicio (planificador, socket de attach, escucha HTTPS si está configurada). fbmcp bridge: un cliente stdio para un fbmcp remoto |
fbmcpctl |
CLI del operador: doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. El mismo programa que fbmcp ctl |
fbmcp-tray |
Bandeja de Windows: ventana emergente Aprobar/Denegar para solicitudes que necesitan un operador |
Un kernel por directorio de estado. Un segundo cliente con la misma configuración no inicia un segundo kernel: se engancha al que ya está en ejecución.
2. Modelo de seguridad
Cada llamada pasa por política → confirmación humana → ejecución auditada.
| Tier | Qué | Cómo se confirma |
|---|---|---|
| 0 | Lecturas (transacciones de solo lectura impuestas por el motor) | No hace falta |
| 1 | Cambios rutinarios: DML/DDL, copia de seguridad, usuarios, permisos | En el canal: el cliente muestra un id de solicitud y un token; la persona acepta; el cliente llama a fb_confirm |
| 2 | Alto impacto: control del servicio, restauración con reemplazo, firebird.conf, ventana exclusiva, registro, reinicios del agente |
Solo fuera del canal: la bandeja o fbmcpctl approve. El cliente nunca puede aprobarlo |
| 3 | Crítico (fb_db_drop) |
Desactivado a propósito |
- Tier 2 suele necesitar una ventana de mantenimiento abierta (
fb_window_open, en la mismadb) y una copia verificada de menos de 24 horas. El rechazo indica qué falta. - Una solicitud pendiente caduca a los 15 minutos. Un intento por el canal incorrecto
no la consume;
fb_cancella quita. - Toda herramienta sujeta a confirmación acepta
mode: preview: muestra el impacto y no hace nada. - Toda decisión (permitir, pendiente, aprobado, denegado) va al
audit.jsonlcon cadena de hashes. - No hay una página web de aprobación, y nunca debe haberla: una página a la que el modelo pueda llegar rompería el diseño.
3. Elegir una instalación
| Instalación | Dónde se ejecuta fbmcp | Cuándo usarla | Sección |
|---|---|---|---|
| A. stdio local | Su PC; el cliente lo inicia | Un administrador, Firebird en este PC o en la LAN | §6 |
| B. Servicio local | Servicio de Windows en el host de la base (-serve) |
Las programaciones deben ejecutarse aunque no haya un cliente abierto | §7 |
| C. Remota | Servicio en el servidor de la base, HTTPS + claves de API | Varios administradores, un servidor distante, agentes autónomos | §8 |
En la instalación A el kernel vive solo mientras se ejecuta un cliente, así que las programaciones se disparan
solo entonces. Use B o C para programaciones desatendidas (nightly_verify).
fbmcp en HQbird. Las instalaciones de HQbird 2027 y fbagent instalan fbmcp
de forma predeterminada: un servicio por servidor para todas las líneas de Firebird, configurado por
fbmcp ctl hqbird-install. En un servidor así no siga §6–§8; lea
hqbird.md (disposición, modo remoto con --allow-from, claves de API).
4. Obtener los binarios
Requisitos: Go ≥ 1.26.11 (un Go más antiguo, 1.21+, descarga go1.26.11 por sí mismo en la primera compilación; esto necesita internet), CGO no hace falta; Firebird 2.5–5.0; fbagent ≥ 2.67 con la Local API para las herramientas del agente (opcional); fbagent 3.1.0+ y RCM 2027.5.11+ para las herramientas del 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-trayBinarios para Linux (compilación cruzada desde Windows, o compilar en Linux sin
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/fbmcpctlSumas de comprobación: Get-FileHash dist/* o sha256sum dist/*. Más destinos:
packaging/README.md. Ponga los binarios en una carpeta propia
(los ejemplos usan C:\fbmcp\): mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\
(Linux: install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/).
fbmcp ctl y fbmcpctl son el mismo programa. fbmcpctl help lista los
comandos. Los comandos que leen la configuración toman --config <file>; sin él
usan FBMCP_CONFIG, luego fbmcp.yaml en la carpeta actual, luego junto
al programa, luego el valor predeterminado de HQbird (C:\HQbirdData\fbmcp\fbmcp.yaml,
/etc/fbmcp/fbmcp.yaml) e imprimen using config <path>.
5. Configurar fbmcp.yaml
Ejemplo completo: packaging/fbmcp.yaml.example.
Configuración mínima de Windows:
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 backupsSecretos. El YAML guarda solo los nombres de las variables. fbmcp busca cada
valor en este orden: variable de entorno → archivo <secrets.dir>/<NAME> →
keyring del sistema de la cuenta que ejecuta 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)El valor se lee de stdin (escríbalo y luego Ctrl+Z, Enter; en Linux Ctrl+D).
Una cuenta de servicio (LocalSystem, NT SERVICE\...) no ve su keyring:
use secrets.dir para los servicios. Un archivo de secreto modificado se aplica en unos
segundos sin reinicio.
Usuario de solo lectura. Cree un usuario de Firebird aparte para ro_user (SQL:
quickstart-en.md:
CREATE USER FBMCP_RO, GRANT SELECT en cada tabla y, en Firebird 4.0+,
un rol con MONITOR_ANY_ATTACHMENT para que fb_sessions vea todas las conexiones).
SYSDBA como usuario RO es solo para desarrollo; doctor advierte de ello.
Recarga en vivo. fbmcp aplica los cambios de fbmcp.yaml por sí mismo (vigilancia
del archivo), o con fb_config_reload. Sin reinicio del cliente ni del proceso. Una recarga
espera a los trabajos de las bases cambiadas (30 s) y luego aplica. Rechazado:
un cambio de state.dir, rutas de base duplicadas, una configuración remota insegura.
Comprobación: C:\fbmcp\fbmcpctl.exe doctor debe terminar con doctor: green
(modo remoto: doctor --remote, ninguna línea FAIL). Crea la carpeta de estado
que falte, inicia sesión en cada base con ambos usuarios, y cada línea FAIL termina
con Fix: y el comando a ejecutar.
6. Instalación A — stdio local
Use rutas absolutas. No establezca listen. Reinicie el cliente tras un cambio de configuración:
los clientes cargan los servidores solo al inicio.
| Cliente | Dónde | Entrada |
|---|---|---|
| Claude Desktop | Ajustes → Desarrollador → Editar configuración (%APPDATA%\Claude\claude_desktop_config.json) |
"mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}} |
| Claude Code | línea de comandos | claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml" |
| Cursor | %USERPROFILE%\.cursor\mcp.json o .cursor\mcp.json en el proyecto |
el mismo JSON que en 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 en el proyecto |
"mcp": {"servers": {"fbmcp": { ...same command and args... }}} |
Las contraseñas están en el keyring (§5), así que no hace falta un bloque env. Si aun así pone
una contraseña en un bloque env del cliente, mantenga ese archivo fuera de git.
Luego inicie la bandeja para las aprobaciones de Tier 2:
C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml (en cada inicio de sesión:
.\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).
Prueba de humo en el cliente: “llame a fb_ping” (muestra el nombre del servidor y su
identidad con su Tier máximo), luego “fb_db_list”, luego “fb_db_health para main”.
7. Instalación B — servicio local de Windows
PowerShell elevado:
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp- El servicio ejecuta
fbmcp -servecomo LocalSystem, se reinicia ante un fallo y se detiene de forma limpia al parar el servicio. - Use
secrets.dirpara las contraseñas (§5). - Bloquee la carpeta: solo SYSTEM y Administrators pueden escribir en
C:\fbmcp(el script imprime el comandoicacls). Una carpeta creada bajoC:\permite a cada usuario cambiar los archivos, y el servicio los ejecuta como SYSTEM. - El usuario de la bandeja y los clientes stdio locales necesitan lectura y escritura en el directorio de estado:
icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M". Un cliente stdio con la misma configuración se engancha entonces al kernel del servicio. - Disponibilidad:
C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml. - Registro:
<state_dir>\fbmcp.log(5 × 10 MiB; caídas enfbmcp-crash.log).
Para un servicio al que los administradores llegan por la red, use la instalación C.
8. Instalación C — remota (HTTPS + claves de API)
Procedimiento completo: remote.md. Forma breve:
Servidor Windows (elevado):
- Binarios y
fbmcp.yamlenC:\fbmcp\(plantilla: 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 el pinsha256:....- Una clave por persona o agente:
C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets(se imprime una vez). Con--config C:\fbmcp\fbmcp.yamltambién añade la entradaidentities:y usasecrets.dir. - Contraseñas y tokens del agente:
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, luego sin-WhatIf. Crea el servicio, la regla de firewall, las ACL de las carpetas y los derechos del servicio Firebird.C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml→ ningún FAIL;curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz→ok.- Bandeja para quien aprueba:
.\packaging\windows\install-tray.ps1.
Servidor Linux (root): copie fbmcp, fbmcpctl y packaging/linux/, y luego
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/24El script crea las carpetas, el certificado, una primera configuración con una
clave admin (se imprime una vez), la unidad de systemd, la regla de sudo para la
unidad de Firebird y la regla de ufw, y luego ejecuta doctor --remote. Añada
databases: y agents: a /etc/fbmcp/fbmcp.yaml. Aprobaciones en Linux
(sin bandeja): sudo -u firebird fbmcpctl approve [id]. Encuentra
/etc/fbmcp/fbmcp.yaml por sí mismo, pregunta y/N (--yes no pregunta), y
--deny <id> --reason "..." rechaza.
PC del administrador:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(la clave que recibió).- Cualquier cliente stdio (Claude Desktop, Cursor, Codex, ZCode): la entrada del §6
con estos
args:["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. El pin comprueba la clave del servidor, así que un certificado autofirmado no necesita configurar una CA. - Claude Code también puede conectarse directamente por HTTP (
.mcp.json"type": "http", cabeceraAuthorization: Bearer ${FBMCP_KEY_SRV1},NODE_EXTRA_CA_CERTSpara un certificado autofirmado). No pase la clave conclaude mcp add --header: se guarda en texto sin formato. - Prueba:
fb_pingmuestra el nombre del servidor y su identidad.
Agentes autónomos (OpenClaw y similares): una clave aparte con
apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32.
De solo lectura de forma predeterminada; cada solicitud de Tier 1 espera a un operador, y
fb_confirm del agente se rechaza. Límites: remote.md §6–7.
9. Puente fbagent y cluster HQbird (opcional)
Las herramientas del agente (fb_agent_status, fb_agent_job_run, …) usan la Local API
del fbagent de HQbird en el mismo host.
Están apagadas hasta que agents: tenga una entrada.
- En el cliente: “
fb_agent_discover”. Lista los agentes locales conbase_url,instance_idy el nombre de token sugerido. Nunca lee tokens. - El operador guarda el
local_api.tokendel agente (noagent.auth_token):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Nunca escriba un token en el chat. - En el cliente: “
fb_agent_registerpara ese agente” → apruebe en la bandeja. fbmcp añade la entradaagents:, recarga y comprueba la identidad. - Prueba:
fb_agent_status,fb_agent_instances.
fb_agent_config_set (cambio de ajustes de trabajos: copia, sweep, …) también necesita
config_path en la entrada y acceso de lectura al agent_config.json en uso,
más derecho de creación en su carpeta. Ese archivo guarda el token y las credenciales de Firebird,
así que esta concesión es decisión del operador
(agent-bridge.md). Si falla la comprobación del agente, la herramienta
no escribe nada.
Cluster HQbird (RCM). Las herramientas del cluster llaman al gestor del cluster HQbird
(hqbirdrcm) en el mismo host. Se muestran solo cuando
fbmcp.yaml tiene una sección rcm: (url, ca_file, user,
password_env). En un servidor HQbird con Linux, fbmcp ctl hqbird-install la escribe
a partir de /opt/hqbirdrcm/rcm.json y guarda la primera contraseña de RCM en el
secreto FBMCP_RCM_PASSWORD; en los demás casos añada la sección a mano
(tool-reference.md). Luego:
fb_cluster_rcm_password: sustituya la primera contraseña de RCM (Tier 1).- Un cluster nuevo: abra la ventana de emparejamiento en cada host
(
fb_agent_cluster_pairing), inicie el RCM en el master (fb_agent_cluster_rcm), enlace los hosts (fb_cluster_link), cree las réplicas (fb_cluster_reinit, Tier 2) y compare los datos (fb_cluster_verify). Pasos:prompts/cluster-setup.md. - Servicios del cluster (switchover, failover, rejoin):
fb_cluster_servicelos muestra y las comprobaciones; los movimientos son Tier 2. Pasos:prompts/cluster-services.md.
10. Uso diario
Pregunte al cliente con palabras sencillas; él elige las herramientas. Ejemplos:
| Tarea | Herramientas |
|---|---|
| ¿Está todo en marcha? | fb_ping, fb_db_list, fb_db_health, fb_service_status |
| Leer datos | fb_query (de solo lectura, filas + plan + estadísticas por tabla; una cuadrícula en clientes MCP-Apps); compruebe un borrador con fb_query_check |
| Sesiones, transacciones largas | fb_sessions, fb_transactions, fb_session_kill (Tier 1) |
| Consulta lenta | fb_analyze_query, fb_index_advice → aplicar con fb_write; fb_agent_perf_report |
| Copia de seguridad | fb_backup_start → id del trabajo → fb_job_status |
| Verificar una copia | fb_restore_test (restaura en work_dir y marca la copia como verificada) |
| Copia nocturna + verificación | fb_schedule_create con target=nightly_verify (confirmado una vez; instalación B o C) |
| Esquema / DDL | fb_schema_list, fb_describe, fb_write (cada sentencia se clasifica y recibe un Tier), fb_diff_schema |
| Migraciones | fb_migration_status, fb_migration_plan, fb_migration_apply |
| Configuración del servidor | fb_config_get, fb_config_diff, fb_config_set (Tier 2) |
| Registros | fb_firebird_log |
| Capacidad | fb_trends, fb_gstat, fb_index_stats |
| Estado del cluster | fb_cluster_status, fb_cluster_service |
| Mover el master | fb_cluster_switchover (sin pérdida de datos) o fb_cluster_failover (master perdido), luego fb_cluster_rejoin (Tier 2) |
Los trabajos son asíncronos: envíe → fb_job_status. Los trabajos de una base se ejecutan de uno
en uno. Un trabajo sobrevive a un reinicio de fbmcp solo como interrupted: envíelo
de nuevo si todavía hace falta.
fb_config_set cambia en firebird.conf solo su propia línea (los comentarios,
la sangría y los finales de línea se quedan), conserva el archivo antiguo como firebird.conf.prev
y nunca reinicia Firebird. Reinicie con fb_service_restart (Tier 2): espera
hasta que el servicio esté parado y vuelva a ejecutarse.
11. Tareas del operador
| Tarea | Comando |
|---|---|
| Listar / aprobar / denegar solicitudes | fbmcpctl approve; fbmcpctl approve <id>; fbmcpctl approve --deny <id> --reason "..." (o la bandeja) |
| Rotar una clave | fbmcpctl apikey rotate alice --config <fbmcp.yaml> (la clave antigua deja de valer en segundos) |
| Listar claves | fbmcpctl apikey list (nombres, orígenes, Tiers; nunca valores) |
| Quitar a una persona | borre la entrada identities: y luego fbmcpctl secret drop --dir <dir> NAME |
| Renovar el certificado | fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ... (pin sin cambio, sin reinicio) |
| Comprobar la cadena de auditoría | fbmcpctl verify |
| ¿Está vivo el kernel? | fbmcpctl ping; fbmcpctl status (lectura offline del estado) |
| Permitir el control del servicio | packaging/posture/verify.ps1 o verify.sh, luego fbmcpctl setup --write-posture |
| Actualización | detenga el servicio (o los clientes), sustituya los binarios, inicie, doctor |
| Quitar | Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux: remote.md §10. Conserve el directorio de estado (auditoría) salvo que el propietario diga lo contrario |
Solo el equipo de desarrollo: .\packaging\rebuild-install.ps1 -Force reconstruye dist\,
detiene y sustituye los binarios en ejecución (los antiguos se conservan como *.exe~),
fusiona las configuraciones de los clientes y ejecuta doctor.
12. Recuperación tras caída y reinicio
Verificado por el arnés de caos (internal/killharness).
| Tras una caída o un kill | Al reiniciar | Acción del operador |
|---|---|---|
| El trabajo estaba en ejecución o en cola | Marcado interrupted; nunca se reanuda |
Envíe de nuevo si hace falta |
| Solicitud pendiente, no confirmada | Restaurado desde state.json (el TTL sigue vigente) |
Confirme o deje que caduque |
fb_restore_replace en curso |
Termina: restauración, validación, base en línea; <db>.pre-restore se conserva |
Compruebe fb_db_health; borre .pre-restore más tarde |
fb_shutdown_window en curso |
Termina el paso gfix -online |
Compruebe que está en línea |
instance.lock obsoleto |
Tomado automáticamente | Ninguna |
state.json dañado |
El kernel se niega a arrancar; la copia se conserva como state.json.corrupt-<ts> |
Inspeccione; repare o quite state.json a propósito (fbmcpctl repair reconstruye las concesiones de las programaciones a partir de la auditoría) |
audit.jsonl dañado o cortado |
El kernel se niega a arrancar | §13.2: trátelo como señal de manipulación |
| El reloj se movió hacia atrás | El planificador omite; no hay doble ejecución | Ninguna |
| Proceso del servicio de Windows terminado | El SCM lo reinicia en unos 5 s | Ninguna |
El kernel falla cerrado ante todo lo que no pueda demostrar intacto. Un bucle de reinicios es un hallazgo: lea el registro.
13. Guías de incidentes
13.1 Algo va mal en una base de datos
fbmcpctl doctor --config <file>: configuración, secretos, inicios de sesión de Firebird, carpetas, postura, programaciones. Cada línea FAIL tiene unFix:.fb_db_list→fb_db_health <db>;fb_service_statuspara la instancia.fb_sessions,fb_transactionspara problemas de conexión o de hueco de OAT;fb_firebird_logpara errores del motor.
13.2 Sospecha de manipulación o corrupción: primero la auditoría
fbmcpctl verify --config <file>→audit chain OK: N entriesoBROKENcon el motivo.- Si falla: conserve todo el directorio de estado (es la prueba) y luego
investigue. No borre
audit.jsonlpara hacer arrancar el kernel.
13.3 Simulacro de restauración (cada trimestre)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ la copia está verificada.fb_window_openpara la base de datos.fb_restore_replace→ apruebe fuera del canal. Tiempo de inactividad hasta quedar en línea.- Comprobación:
fb_db_health, luego una lectura real (fb_schema_list,fb_info). - El archivo antiguo permanece como
<db>.pre-restorehasta que lo borre.
13.4 El cliente no puede conectar
fbmcpctl ping --config <file>,fbmcpctl status --config <file>.- Lea el registro MCP del cliente (stdio) o
<state_dir>\fbmcp.log/journalctl -u fbmcp(servicio). - “another fbmcp instance is active”: un kernel por directorio de estado. Los clientes por tubería se enganchan solos; un segundo kernel falla de inmediato a propósito.
En los comandos de arriba puede omitir --config cuando la búsqueda del §4 encuentra
el archivo.
14. Resolución de problemas
| Síntoma | Significado / corrección |
|---|---|
| Las herramientas no aparecen | Sintaxis JSON, rutas absolutas, reinicio completo del cliente; el registro MCP del cliente |
| Falta una herramienta en la lista | Oculta a propósito (§1): por encima de su Tier máximo, sin entrada agents:, sin migrations_dir o sin sección rcm: |
| El servidor sale de inmediato | fbmcpctl doctor; falta un secreto; un servicio no puede leer su keyring (use secrets.dir) |
| Tier 2 “confirmation rejected: channel policy” | Esperado en el chat. Apruebe en la bandeja o con fbmcpctl approve |
| Tier 2 “no open maintenance window” | fb_window_open para la misma db que pasa a la herramienta |
fb_restore_replace denegado: precondiciones |
Necesita una copia verificada < 24 h: fb_backup_start + fb_restore_test, y una ventana |
| Control del servicio denegado | Falta posture.verified (fbmcpctl setup --write-posture), o la cuenta no tiene derechos sobre el servicio Firebird |
fb_config_set: no puede escribir |
La cuenta no puede cambiar ese archivo (unidad Linux ProtectSystem=strict; ACL de Windows). Edite a mano, o vea remote.md §8 |
| La bandeja no muestra nada | Muestra solo solicitudes que necesitan un operador; compruebe los derechos del usuario de la bandeja sobre el directorio de estado y tray.log allí |
| 401 (remoto) | Clave incorrecta, o el servidor no la cargó: apikey list, doctor --remote |
| 403 (remoto) | La IP de origen no está en allow_from / el firewall, o una cabecera Origin no está en allowed_origins |
| 429 (remoto) | Límites; espere a Retry-After |
| El pin no coincide | La clave del servidor cambió; pida el pin nuevo al administrador del servidor |
agent-unreachable |
Servicio del agente caído, local_api.enabled: false, o base_url incorrecta (predeterminado 127.0.0.1:(10000 + firebird port)) |
agent-auth |
El token guardado no es el local_api.token del agente; vuelva a establecerlo |
agent-timeout en los reinicios |
agents[].timeout_seconds (130) debe ser mayor que restart_timeout_seconds del agente (120) |
Error loading plugin MySQLEngine … al hacer attach |
En HQbird esto suele significar que el archivo no existe; compruebe la ruta |
Un DROP INDEX suelto en fb_write necesita una ventana |
Allí es Tier 2; use fb_index_drop (Tier 1; rechaza índices de restricción) |
| El índice nuevo no se usa | Calcule las estadísticas (fb_index_rebuild action=statistics); ORDER BY … DESC necesita un índice DESCENDING |
| Las herramientas fallan solo en una base | Está fuera de línea (fb_db_health); las herramientas se degradan por base |
15. Referencia del directorio de estado
| Ruta | Significado |
|---|---|
state.json (+ .tmp, .corrupt-*) |
Solicitudes pendientes, trabajos, catálogo de copias, flujos de trabajo, programaciones. Dañado ⇒ se niega a arrancar |
audit.jsonl (+ .head) |
Registro de auditoría con cadena de hashes; .head detecta un truncado |
events.jsonl |
Eventos de trabajos (job.succeeded, job.failed con el mensaje) |
approvals\, denials\ |
Decisiones fuera del canal (bandeja / fbmcpctl approve), usadas en unos 2 s |
instance.lock |
Bloqueo de un solo kernel |
attach.addr, attach.token |
Extremo de attach para clientes stdio adicionales |
fbmcp.log, fbmcp-crash.log |
Registro del servicio (rotado) y salida de la caída |
query-log.jsonl |
Cada llamada a fb_query |
trends\ |
Historial del muestreador para fb_trends |
config-journal\ |
Historial de fb_config_set (valor antiguo y nuevo) |
posture.verified |
Marca que permite el control del servicio |
tray.log |
Errores de la bandeja |
16. Estado del recorrido
Pendiente (M1): un recorrido en un host Windows limpio usando solo esta guía.
Los hallazgos vuelven a este archivo. Resultados de laboratorio del modo remoto (host Linux,
VM nueva, servicio de Windows): findings/phase12-lab-2026-11-03.md.