Asistente de IA HQbird MCP
Asistente de IA bajo control humano
HQbird MCP conecta Firebird con un asistente de IA. Escribes con palabras sencillas y el asistente elige las herramientas por sí mismo. Lee libremente. Cada cambio espera tu «sí», y uno peligroso espera aprobación en el propio servidor.
- 122 herramientas
- 56 de solo lectura
- Firebird 2.5–5 Windows y Linux
- 2 canales para aprobación
- registro de auditoría con cadena de hashes
Ejemplo
Una conversación con el asistente
Los usuarios se quejan de que la base de datos va lenta. El asistente lee los datos, encuentra la causa, sugiere una acción y espera tu decisión. Los nombres y números del ejemplo son inventados.
Funciona cualquier cliente MCP: Claude Desktop, Claude Code, Cursor, Codex, ZCode y otros.
Política · aprobación
Cuatro niveles de peligro
Cada herramienta tiene un nivel. El servidor MCP comprueba el nivel y las condiciones por sí mismo antes de que se ejecute la llamada. Una llamada que cambia algo devuelve una solicitud de aprobación, no un resultado. El asistente no puede saltarse esta comprobación.
Elige una herramienta y mira qué camino sigue su llamada.
| Nivel | Herramientas | Ejemplos | Cómo se aprueba |
|---|---|---|---|
| 0 · Lectura | 51 | sesiones, transacciones, plan de consulta, gstat, firebird.log, informes del agente | No es necesario. Transacción de solo lectura. |
| 1 · Cambio | 31 | DML y DDL, copia de seguridad, restauración de prueba, sweep, usuarios y permisos, finalizar una sesión | En el chat: número de solicitud y token, luego fb_confirm. |
| 2 · Operación peligrosa | 14 | reemplazar una base de datos desde una copia de seguridad, editar firebird.conf, detener y reiniciar Firebird | Solo en el servidor: el comando fbmcp ctl approve. En Windows también puedes instalar una ventana en la bandeja del sistema. |
| 3 · Deshabilitado | 1 | eliminar una base de datos | Nunca se ejecuta. |
- Vista previaCada herramienta que necesita aprobación acepta
mode: preview. Muestra lo que se hará y no hace nada. - Condiciones para el nivel 2Cada operación de nivel 2 necesita una ventana de mantenimiento abierta en esa base de datos. Reemplazar una base de datos desde una copia de seguridad, una ventana exclusiva y SQL peligroso también necesitan una copia de seguridad verificada de no más de 24 horas. Una negativa indica qué falta.
- Solo herramientas permitidasEl cliente ve en la lista solo lo que puede usar: ni el nivel 3 ni niveles superiores al máximo de su clave. Una llamada directa a una herramienta oculta se rechaza.
- Una solicitud dura 15 minutosUn intento de aprobarla por el canal equivocado no la consume.
fb_cancelelimina la solicitud. - Sin página de aprobaciónY no la habrá: una página a la que el modelo pueda llegar rompería la protección. Solo una persona en el servidor aprueba: con el comando
fbmcp ctl approveo en la ventana de la bandeja del sistema, si está instalada.
Las lecturas se ejecutan en una transacción de solo lectura: Firebird mismo bloquea las escrituras. Para una segunda capa de protección, configura un usuario separado de solo lectura sin derechos de escritura.
Monitorización · copias de seguridad · permisos
Para DBAs
El asistente hace lo que un DBA hace a mano: comprueba sesiones y transacciones, lee los registros, hace una copia de seguridad y la verifica con una restauración, gestiona usuarios. Nombra las bases de datos por id, no por ruta de archivo.
| Tarea | Herramientas | Nivel |
|---|---|---|
| ¿Todo funciona? | fb_ping, fb_db_list, fb_db_health, fb_service_status | 0 |
| Sesiones y transacciones largas | fb_sessions, fb_transactions; para finalizar una sesión — fb_session_kill | 0 · 1 |
| Registros y estadísticas | fb_firebird_log, fb_gstat, fb_lwmonitoring, fb_trends | 0 |
| Copia de seguridad y verificación | fb_backup_start (gbak), fb_backup_nbackup, fb_restore_test | 1 |
| Copias de seguridad antiguas | fb_retention_run: primero simulación; elimina solo copias de seguridad verificadas de su propio catálogo | 1 |
| Sweep y validación de la base de datos | fb_sweep, fb_validate (solo hallazgos, sin reparación) | 1 |
| Usuarios y permisos | fb_user_create, fb_grant, fb_revoke; SYSDBA y sus propias cuentas no se pueden eliminar | 1 |
| Traces | fb_trace_start solo con plantillas: audit-lite, performance, errors | 1 |
| firebird.conf | fb_config_get, fb_config_diff; para editar — fb_config_set, Firebird no se reinicia | 0 · 2 |
| Servicio y reemplazo de base de datos | fb_service_restart; fb_restore_replace, el archivo antiguo se conserva como .pre-restore | 2 |
Comprobación nocturna de copias de seguridad
La programación se aprueba una vez, cuando se crea. Después se ejecuta sin una persona. Cada noche obtienes una copia de seguridad verificada. La necesitas, por ejemplo, para reemplazar una base de datos desde una copia de seguridad.
- 1Programación
fb_schedule_create, objetivonightly_verify; aprobada una vez - 2Copia de seguridadgbak a la carpeta de copias de seguridad
- 3Restauración de pruebaen una carpeta de trabajo; la base de datos de origen no se toca
- 4✓ Copia de seguridad verificadauna marca en el catálogo de copias de seguridad
El reemplazo de una base de datos desde una copia de seguridad y las operaciones de nivel 3 no se pueden programar.
Escenarios predefinidos
Los escenarios sugieren al asistente el orden de los pasos. No aplica cambios por sí mismo.
Consultas · índices · migraciones
Para desarrolladores
El asistente en Cursor o Claude Code conoce tu esquema, comprueba una consulta antes de ejecutarla y muestra el resultado como una tabla directamente en el chat.
- 1Tarealo que necesitas, en una frase
- 2Datos
fb_schema_list,fb_describe: solo tablas y columnas existentes - 3Borradorun SELECT con ORDER BY
- 4Comprobación
fb_query_check: compilar sin ejecutar - 5✓ Tabla en el chat
fb_query: filas, plan y estadísticas
Resultado como tabla
En los clientes compatibles con MCP Apps, el resultado de fb_query se muestra como una tabla ordenable. Otros clientes reciben los mismos datos como texto.
100 filas por defecto, 1000 como máximo. La tabla permanece en memoria durante 30 minutos y solo la puede ver la persona que la solicitó. Haz clic en el encabezado de una columna para ordenar.
SELECT full_name, dept_no, salary FROM employee WHERE salary > 60000 ORDER BY salary DESC
Recomendaciones de índices
Detecta escaneos completos de tablas y sugiere CREATE INDEX con una estimación del beneficio. No crea el índice por sí mismo: fb_write lo hace, con aprobación. Una vez creado el índice, vuelve a comprobar el plan.
Comparación de bases de datos
Esquema de dos bases de datos, o de una base de datos y su instantánea: qué crear, cambiar y eliminar. Los datos se comparan por clave primaria; la herramienta no compara una tabla grande (por defecto, más de 100.000 filas).
Migraciones
El plan muestra el nivel de cada sentencia. Todas las migraciones se aplican tras una única aprobación; si un archivo cambia, se necesita una nueva solicitud. El plan de reversión se construye a partir de lo registrado cuando se aplicaron las migraciones.
fb_write detecta el nivel de cada sentencia de un script. Un script que mezcla sentencias de distintos niveles se rechaza.
fbagent · API local · 127.0.0.1
Datos de fbagent
El agente fbagent ya se ejecuta en el servidor HQbird. A través de MCP, el asistente obtiene todo lo que el agente ha recopilado: el informe de estado, LWM (Light-weight Monitoring), gstat, trazas, bloqueos mutuos y el estado de las copias de seguridad. También ejecuta tareas del agente y cambia su configuración, bajo los mismos niveles y aprobaciones.
| Qué | Herramientas | Nivel |
|---|---|---|
| Informe de estado del servidor | fb_agent_status | 0 |
| LWM, gstat, métricas de la base de datos, trazas, bloqueos mutuos | fb_agent_artifact_get, fb_agent_perf_report | 0 |
| Configuración de copia de seguridad, sweep y restauración | fb_agent_backup_config; las contraseñas y los tokens están ocultos | 0 |
| Ejecutar una tarea del agente | fb_agent_job_run; la copia de seguridad, la restauración y el script SQL son de nivel 2 | 1 · 2 |
| Cambiar la configuración de una tarea | fb_agent_config_set; las credenciales, los ids y los comandos no se pueden cambiar | 2 |
| Reiniciar Firebird a través del agente | fb_agent_restart, fb_agent_stop, fb_agent_start | 2 |
| Licencia y actualizaciones | fb_agent_license, fb_agent_license_set, fb_agent_update_apply, fb_agent_product_update_apply | 0 · 1 · 2 |
- Solo localEl agente acepta solicitudes únicamente en 127.0.0.1. La dirección del agente proviene de la configuración del servidor MCP, no del chat.
- El token permanece ocultoEl token del agente no aparece en la salida de las herramientas ni en el registro de auditoría.
- Descubrimiento de agentes
fb_agent_discoverencuentra agentes en el servidor mediante servicios de Windows o unidades de systemd. No lee tokens. - ClústerSi hay un nodo de clúster instalado en el servidor,
fb_agent_restart,fb_agent_stopyfb_agent_startse niegan por defecto: el nodo controla los reinicios.fb_service_restartno comprueba esto, así que no lo use en un nodo de clúster.
Doble control. El servidor MCP aprueba la solicitud, y el propio agente ejecuta la tarea según sus propias reglas. El registro de MCP muestra quién lo solicitó; los registros del agente muestran cómo se hizo.
HQbird Cluster · RCM
Clúster de replicación a través del asistente
El asistente construye un clúster de replicación paso a paso: activa RCM, abre la ventana de emparejamiento, vincula los hosts, pone bases de datos bajo gestión y hace una copia para la réplica. Funciona a través del agente y de RCM. No es necesario iniciar sesión en los servidores por SSH.
Las reglas son las mismas que en todas partes. Las lecturas no requieren confirmación. Un cambio se confirma en el chat. Un reinicio de Firebird, una copia de la base de datos a la réplica, la eliminación de un servidor del clúster, el switchover, el failover y el retorno del antiguo maestro se confirman en el servidor.
| Qué | Herramientas | Nivel |
|---|---|---|
| Estado del clúster en el servidor | fb_agent_cluster: libre, en un clúster o propietario de RCM; slot y puertos | 0 |
| Visión general del clúster en RCM | fb_cluster_status: nodos, bases de datos, comandos, alertas | 0 |
| Comprobar hosts antes de vincular | fb_cluster_probe: una fila por agente, huella del certificado | 0 |
| Comparar maestro y réplica | fb_cluster_verify: recuento de filas de cada tabla | 0 |
| Activar RCM en el servidor | fb_agent_cluster_rcm | 1 |
| Ventana de emparejamiento | fb_agent_cluster_pairing: estado, abierta de 1 a 24 horas, cerrar | 0 · 1 |
| Vincular hosts | fb_cluster_link; la solicitud muestra las huellas para comparar | 1 |
| Bases de datos y publicación | fb_cluster_replica_folder, fb_cluster_enroll, fb_cluster_publication | 1 |
| Contraseña de RCM | fb_cluster_rcm_password: una nueva contraseña aleatoria, no se muestra en el chat | 1 |
| Copia de la base de datos a la réplica | fb_cluster_reinit | 2 |
| Reiniciar el Firebird de un nodo | fb_cluster_firebird_restart | 2 |
| Eliminar un servidor del clúster | fb_cluster_unlink | 2 |
| Servicios: dónde está el maestro | fb_cluster_service: maestro, réplicas, routers, problemas, operación en curso | 0 |
| Describir un servicio y su regla | fb_cluster_service_put, fb_cluster_service_policy: descripción del servicio, regla de failover automático | 1 |
| Reanudar y cancelar una operación | fb_cluster_resume, fb_cluster_operation_cancel; cancelar solo antes del punto de no retorno | 1 |
| Switchover | fb_cluster_switchover: movimiento planificado del maestro, espera al final de la operación | 2 |
| Failover | fb_cluster_failover: solo con consentimiento explícito a la pérdida de datos | 2 |
| Recuperar el antiguo maestro | fb_cluster_rejoin | 2 |
| Eliminar un servicio | fb_cluster_service_delete: solo se elimina el registro en RCM | 2 |
- Escenario predefinido«Construir un clúster»: el asistente avanza paso a paso y en cada paso muestra lo que hará.
- HuellasAntes de vincular, el asistente muestra la huella del certificado de cada servidor. Compárela con la línea del resumen de la instalación.
- SimulaciónAntes de poner bajo gestión una carpeta con bases de datos, el asistente muestra qué bases de datos encontrará RCM.
- Switchover y failoverEl asistente inicia el movimiento del maestro y sigue los pasos de la operación. Una persona en el servidor confirma el inicio. El failover también requiere consentimiento explícito a la pérdida de datos. Más información en la página del clúster.
HTTPS · claves de API · auditoría
Modo remoto, instalación y registro de auditoría
El asistente se ejecuta en el PC del administrador, y el servidor MCP se ejecuta en el servidor de base de datos. Entre ellos hay HTTPS y una clave de API. Cada persona tiene su propia clave y su propio nivel máximo.
- Una clave para cada persona
fbmcp ctl apikey new <name> --max-tier 2. El valor se muestra una sola vez. Tras un cambio de clave, la clave antigua deja de funcionar en unos segundos. - LímitesPor clave: llamadas concurrentes, llamadas por minuto, sesiones abiertas. Por encima del límite, la respuesta es 429.
- Guía en portuguésLa guía completa de instalación y uso también está disponible en portugués de Brasil.
- Agentes autónomosEl perfil
autonomous: solo lectura por defecto. Un cambio espera a un operador en el servidor;fb_confirmdel agente se rechaza. 10 llamadas por minuto. Ejecute estos agentes dentro de la red de la empresa. - DireccionesUna clave se puede vincular a direcciones (
allow_from). Otra dirección recibe 403 y una entrada en el registro.
Instalación en HQbird
El instalador de HQbird instala el servidor MCP por defecto. Un solo servidor atiende todas las líneas de Firebird de la máquina. Un único comando lo configura todo, y puede ejecutarlo de nuevo.
- 1Instalador de HQbirdWindows o Linux
- 2fbmcp ctl hqbird-installun solo comando, sin editar YAML a mano
- 3Líneas de Firebirdencuentra cada línea y su agente
- 4Bases de datosalias de databases.conf y bases de datos conectadas recientemente
- 5✓ Servicioarchivo start, check, connect.txt para clientes
El modo remoto se activa cuando se cumplen tres condiciones: se establece una lista de direcciones de administrador (--allow-from), el firewall está en ejecución y existe al menos una clave API. La clave se crea por separado. Después de eso, ejecute fbmcp ctl hqbird-install de nuevo. El puerto predeterminado es 8650.
Cadena de hashes
Cada decisión (permitida, pendiente, aprobada, rechazada) se escribe en el registro. Cada entrada está vinculada a la anterior. Una verificación de la cadena muestra si una entrada fue modificada o eliminada.
Registro truncado — el servidor permanece detenido
Si el registro está truncado o su final no coincide con la entrada de control, el servidor MCP no se inicia. Esto es una señal de manipulación y debe investigarlo. El comando fbmcp ctl verify verifica toda la cadena.
A través del agente
fbagent actualiza el servidor MCP: detener, reemplazar, iniciar, verificar, revertir en caso de fallo. En Linux no se instala una compilación sin firma. La configuración y las claves no cambian.