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 misma db) 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_cancel la 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.jsonl con 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).

Command
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-tray

Binarios para Linux (compilación cruzada desde Windows, o compilar en Linux sin GOOS):

Command
$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/fbmcpctl

Sumas 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:

yaml
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 backups

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

Command
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:

Command
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp
  • El servicio ejecuta fbmcp -serve como LocalSystem, se reinicia ante un fallo y se detiene de forma limpia al parar el servicio.
  • Use secrets.dir para las contraseñas (§5).
  • Bloquee la carpeta: solo SYSTEM y Administrators pueden escribir en C:\fbmcp (el script imprime el comando icacls). Una carpeta creada bajo C:\ 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 en fbmcp-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):

  1. Binarios y fbmcp.yaml en C:\fbmcp\ (plantilla: remote.md §3: listen, tls, identities, allowed_origins, secrets.dir).
  2. C:\fbmcp\fbmcpctl.exe tls selfsign --out C:\fbmcp\tls --dns srv1 --ip 10.0.0.5 --grant "NT SERVICE\fbmcp" — anote el pin sha256:....
  3. 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.yaml también añade la entrada identities: y usa secrets.dir.
  4. Contraseñas y tokens del agente: fbmcpctl secret set --dir C:\ProgramData\fbmcp\secrets NAME.
  5. .\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.
  6. 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.
  7. Bandeja para quien aprueba: .\packaging\windows\install-tray.ps1.

Servidor Linux (root): copie fbmcp, fbmcpctl y packaging/linux/, y luego

Command
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/24

El 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:

  1. C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1 (la clave que recibió).
  2. 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.
  3. Claude Code también puede conectarse directamente por HTTP (.mcp.json "type": "http", cabecera Authorization: Bearer ${FBMCP_KEY_SRV1}, NODE_EXTRA_CA_CERTS para un certificado autofirmado). No pase la clave con claude mcp add --header: se guarda en texto sin formato.
  4. Prueba: fb_ping muestra 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.

  1. En el cliente: “fb_agent_discover”. Lista los agentes locales con base_url, instance_id y el nombre de token sugerido. Nunca lee tokens.
  2. El operador guarda el local_api.token del agente (no agent.auth_token): fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Nunca escriba un token en el chat.
  3. En el cliente: “fb_agent_register para ese agente” → apruebe en la bandeja. fbmcp añade la entrada agents:, recarga y comprueba la identidad.
  4. 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:

  1. fb_cluster_rcm_password: sustituya la primera contraseña de RCM (Tier 1).
  2. 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.
  3. Servicios del cluster (switchover, failover, rejoin): fb_cluster_service los 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

  1. fbmcpctl doctor --config <file>: configuración, secretos, inicios de sesión de Firebird, carpetas, postura, programaciones. Cada línea FAIL tiene un Fix:.
  2. fb_db_list → fb_db_health <db>; fb_service_status para la instancia.
  3. fb_sessions, fb_transactions para problemas de conexión o de hueco de OAT; fb_firebird_log para errores del motor.

13.2 Sospecha de manipulación o corrupción: primero la auditoría

  1. fbmcpctl verify --config <file> → audit chain OK: N entries o BROKEN con el motivo.
  2. Si falla: conserve todo el directorio de estado (es la prueba) y luego investigue. No borre audit.jsonl para hacer arrancar el kernel.

13.3 Simulacro de restauración (cada trimestre)

  1. fb_backup_start → fb_job_status = succeeded.
  2. fb_restore_test → la copia está verificada.
  3. fb_window_open para la base de datos.
  4. fb_restore_replace → apruebe fuera del canal. Tiempo de inactividad hasta quedar en línea.
  5. Comprobación: fb_db_health, luego una lectura real (fb_schema_list, fb_info).
  6. El archivo antiguo permanece como <db>.pre-restore hasta que lo borre.

13.4 El cliente no puede conectar

  1. fbmcpctl ping --config <file>, fbmcpctl status --config <file>.
  2. Lea el registro MCP del cliente (stdio) o <state_dir>\fbmcp.log / journalctl -u fbmcp (servicio).
  3. “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.