AI-ассистент HQbird MCP
AI-ассистент под контролем человека
HQbird MCP подключает Firebird к AI-ассистенту. Вы пишете обычными словами, ассистент сам выбирает инструменты. Читает он свободно. Каждое изменение ждёт вашего «да», а опасное — подтверждения на самом сервере.
- 122 инструмента
- 56 только читают
- Firebird 2.5–5 Windows и Linux
- 2 канала подтверждения
- журнал с цепочкой хэшей
Пример
Разговор с ассистентом
Пользователи жалуются, что база тормозит. Ассистент читает данные, находит причину, предлагает действие и ждёт вашего решения. Имена и числа в примере условные.
Подходит любой MCP-клиент: Claude Desktop, Claude Code, Cursor, Codex, ZCode и другие.
Политика · подтверждение
Четыре уровня опасности
У каждого инструмента есть уровень. MCP-сервер сам проверяет уровень и условия до выполнения. Вызов изменения возвращает не результат, а запрос на подтверждение. Ассистент не может обойти эту проверку.
Выберите инструмент и посмотрите, какой путь проходит его вызов.
| Уровень | Инструментов | Примеры | Как подтверждается |
|---|---|---|---|
| 0 · Чтение | 51 | сессии, транзакции, план запроса, gstat, firebird.log, отчёты агента | Не нужно. Транзакция только для чтения. |
| 1 · Изменение | 31 | DML и DDL, бэкап, проверка восстановления, sweep, пользователи и права, завершение сессии | В чате: номер запроса и токен, затем fb_confirm. |
| 2 · Опасная операция | 14 | замена базы из бэкапа, правка firebird.conf, остановка и перезапуск Firebird | Только на сервере: команда fbmcp ctl approve. На Windows можно отдельно поставить окно в трее. |
| 3 · Отключено | 1 | удаление базы | Не выполняется. |
- ПредпросмотрКаждый инструмент с подтверждением принимает
mode: preview. Он показывает, что будет сделано, и ничего не делает. - Условия для уровня 2Для каждой операции уровня 2 нужно открытое окно обслуживания на этой базе. Замена базы из бэкапа, монопольное окно и опасный SQL требуют ещё проверенный бэкап не старше 24 часов. Отказ говорит, чего не хватает.
- Только доступные инструментыКлиент видит в списке только то, что ему разрешено: без уровня 3 и без уровней выше максимума его ключа. Прямой вызов скрытого инструмента получает отказ.
- Запрос живёт 15 минутПопытка подтвердить не тем каналом его не расходует.
fb_cancelудаляет запрос. - Нет страницы одобренияИ не будет: страница, до которой может дойти модель, сломала бы защиту. Одобряет только человек на сервере: командой
fbmcp ctl approveили в окне в трее, если его поставили.
Чтение идёт в транзакции только для чтения: запись запрещает сам Firebird. Для второй защиты задайте отдельного пользователя только для чтения, без прав на запись.
Мониторинг · бэкапы · права
Для DBA
Ассистент делает то же, что DBA делает руками: смотрит сессии и транзакции, читает журналы, делает бэкап и проверяет его восстановлением, управляет пользователями. Базы он называет по id, а не по пути к файлу.
| Задача | Инструменты | Уровень |
|---|---|---|
| Всё ли работает | fb_ping, fb_db_list, fb_db_health, fb_service_status | 0 |
| Сессии и долгие транзакции | fb_sessions, fb_transactions; завершить сессию — fb_session_kill | 0 · 1 |
| Журналы и статистика | fb_firebird_log, fb_gstat, fb_lwmonitoring, fb_trends | 0 |
| Бэкап и проверка | fb_backup_start (gbak), fb_backup_nbackup, fb_restore_test | 1 |
| Старые бэкапы | fb_retention_run: сначала пробный прогон; удаляет только проверенные бэкапы из своего каталога | 1 |
| Sweep и проверка базы | fb_sweep, fb_validate (только находки, без исправления) | 1 |
| Пользователи и права | fb_user_create, fb_grant, fb_revoke; SYSDBA и свои учётные записи удалить нельзя | 1 |
| Трассы | fb_trace_start только по шаблонам: audit-lite, performance, errors | 1 |
| firebird.conf | fb_config_get, fb_config_diff; правка — fb_config_set, Firebird не перезапускается | 0 · 2 |
| Служба и замена базы | fb_service_restart; fb_restore_replace, старый файл остаётся как .pre-restore | 2 |
Ночная проверка бэкапа
Расписание подтверждается один раз, при создании. Дальше оно работает без человека. Каждую ночь получается проверенный бэкап. Он нужен, например, для замены базы из бэкапа.
- 1Расписание
fb_schedule_create, цельnightly_verify; подтверждение один раз - 2Бэкапgbak в папку бэкапов
- 3Тестовое восстановлениев рабочую папку; исходная база не трогается
- 4✓ Бэкап проверенотметка в каталоге бэкапов
Замену базы из бэкапа и операции уровня 3 нельзя поставить в расписание.
Готовые сценарии
Сценарии подсказывают ассистенту порядок шагов. Изменения он сам не применяет.
Запросы · индексы · миграции
Для разработчиков
Ассистент в Cursor или Claude Code знает вашу схему, проверяет запрос до выполнения и показывает результат таблицей прямо в чате.
- 1Задачачто нужно, одним предложением
- 2Факты
fb_schema_list,fb_describe: только существующие таблицы и колонки - 3Черновикодин SELECT с ORDER BY
- 4Проверка
fb_query_check: компиляция без выполнения - 5✓ Таблица в чате
fb_query: строки, план и статистика
Результат как таблица
В клиентах с поддержкой MCP Apps результат fb_query показывается таблицей с сортировкой. Другие клиенты получают те же данные текстом.
По умолчанию 100 строк, не больше 1000. Таблица хранится в памяти 30 минут и видна только тому, кто её запросил. Нажмите на заголовок столбца, чтобы отсортировать.
SELECT full_name, dept_no, salary FROM employee WHERE salary > 60000 ORDER BY salary DESC
Совет по индексу
Находит полное чтение таблицы и предлагает CREATE INDEX с оценкой пользы. Сам индекс не создаёт: это делает fb_write с подтверждением. После создания перепроверяет план.
Сравнение баз
Схема двух баз или базы и её снимка: что создать, изменить, удалить. Данные сравниваются по первичному ключу; большую таблицу (по умолчанию больше 100 000 строк) инструмент не сравнивает.
Миграции
План показывает уровень каждого оператора. Все миграции применяются после одного подтверждения; изменился файл — нужен новый запрос. План отката строится из того, что записано при применении.
fb_write определяет уровень каждого оператора скрипта. Скрипт, в котором смешаны операторы разных уровней, отклоняется.
fbagent · Local API · 127.0.0.1
Данные агента fbagent
На сервере HQbird уже работает агент fbagent. Через MCP ассистент получает всё, что собрал агент: отчёт о здоровье, LWM (Light-weight Monitoring), gstat, трассы, deadlock, состояние бэкапов. Он также запускает задания агента и меняет их настройки, под теми же уровнями и подтверждениями.
| Что | Инструменты | Уровень |
|---|---|---|
| Отчёт о здоровье сервера | fb_agent_status | 0 |
| LWM, gstat, метрики баз, трассы, deadlock | fb_agent_artifact_get, fb_agent_perf_report | 0 |
| Настройки бэкапов, sweep, восстановления | fb_agent_backup_config; пароли и токены скрыты | 0 |
| Запустить задание агента | fb_agent_job_run; бэкап, восстановление и SQL-скрипт — уровень 2 | 1 · 2 |
| Изменить настройку задания | fb_agent_config_set; учётные данные, id и команды менять нельзя | 2 |
| Перезапуск Firebird через агента | fb_agent_restart, fb_agent_stop, fb_agent_start | 2 |
| Лицензия и обновления | fb_agent_license, fb_agent_license_set, fb_agent_update_apply, fb_agent_product_update_apply | 0 · 1 · 2 |
- Только локальноАгент принимает запросы только на 127.0.0.1. Адрес агента берётся из конфигурации MCP-сервера, а не из чата.
- Токен не виденТокен агента не попадает в вывод инструментов и в журнал аудита.
- Поиск агентов
fb_agent_discoverнаходит агентов на сервере по службам Windows или юнитам systemd. Токены он не читает. - КластерЕсли на сервере стоит узел кластера,
fb_agent_restart,fb_agent_stopиfb_agent_startпо умолчанию отказывают: перезапуском управляет узел.fb_service_restartэто не проверяет, на узле кластера его не используйте.
Двойной контроль. MCP-сервер одобряет запрос, а выполняет задание сам агент, по своим правилам. Журнал MCP показывает, кто попросил; журналы агента показывают, как выполнено.
HQbird Cluster · RCM
Кластер репликации через ассистента
Ассистент собирает кластер репликации по шагам: включает RCM, открывает окно сопряжения, связывает хосты, берёт базы под управление и делает копию для реплики. Он работает через агента и RCM. Входить на серверы по SSH не нужно.
Правила те же, что и везде. Чтение идёт без подтверждения. Изменение подтверждается в чате. Перезапуск Firebird, копия базы на реплику, вывод сервера из кластера, switchover, failover и возврат старого мастера подтверждаются на сервере.
| Что | Инструменты | Уровень |
|---|---|---|
| Состояние кластера на сервере | fb_agent_cluster: свободен, в кластере или владелец RCM; слот и порты | 0 |
| Обзор кластера в RCM | fb_cluster_status: узлы, базы, команды, оповещения | 0 |
| Проверить хосты перед связью | fb_cluster_probe: строка на агента, отпечаток сертификата | 0 |
| Сверить мастер и реплику | fb_cluster_verify: число строк каждой таблицы | 0 |
| Включить RCM на сервере | fb_agent_cluster_rcm | 1 |
| Окно сопряжения | fb_agent_cluster_pairing: состояние, открыть на 1–24 часа, закрыть | 0 · 1 |
| Связать хосты | fb_cluster_link; запрос показывает отпечатки для сверки | 1 |
| Базы и публикация | fb_cluster_replica_folder, fb_cluster_enroll, fb_cluster_publication | 1 |
| Пароль RCM | fb_cluster_rcm_password: новый случайный пароль, в чат не выводится | 1 |
| Копия базы на реплику | fb_cluster_reinit | 2 |
| Перезапуск Firebird узла | fb_cluster_firebird_restart | 2 |
| Вывести сервер из кластера | fb_cluster_unlink | 2 |
| Сервисы: где мастер | fb_cluster_service: мастер, реплики, роутеры, проблемы, идущая операция | 0 |
| Описать сервис и правило | fb_cluster_service_put, fb_cluster_service_policy: описание сервиса, правило автоматического failover | 1 |
| Resume и отмена операции | fb_cluster_resume, fb_cluster_operation_cancel; отмена только до точки невозврата | 1 |
| Switchover | fb_cluster_switchover: плановый перенос мастера, ждёт конца операции | 2 |
| Failover | fb_cluster_failover: только с явным согласием на потерю данных | 2 |
| Вернуть старый мастер | fb_cluster_rejoin | 2 |
| Удалить сервис | fb_cluster_service_delete: удаляется только запись в RCM | 2 |
- Готовый сценарий«Собери кластер»: ассистент идёт по шагам и на каждом показывает, что будет сделано.
- ОтпечаткиПеред связью ассистент показывает отпечаток сертификата каждого сервера. Сравните его со строкой из итога установки.
- Сухой запускПеред тем как взять папку с базами под управление, ассистент показывает, какие базы найдёт RCM.
- Switchover и failoverАссистент запускает перенос мастера и следит за шагами операции. Запуск подтверждает человек на сервере. Failover требует ещё и явного согласия на потерю данных. Подробнее на странице кластера.
HTTPS · API-ключи · аудит
Удалённый режим, установка и журнал
Ассистент работает на ПК администратора, а MCP-сервер — на сервере базы данных. Между ними HTTPS и API-ключ. У каждого человека свой ключ и свой максимальный уровень.
- Ключ для каждого
fbmcp ctl apikey new <имя> --max-tier 2. Значение показывается один раз. После смены ключа старый перестаёт работать через несколько секунд. - ЛимитыНа каждый ключ: одновременные вызовы, вызовы в минуту, открытые сессии. Сверх лимита — ответ 429.
- Руководство на португальскомПолное руководство по установке и работе есть и на бразильском португальском.
- Автономные агентыПрофиль
autonomous: по умолчанию только чтение. Изменение ждёт оператора на сервере,fb_confirmот агента отклоняется. 10 вызовов в минуту. Агента запускают внутри сети компании. - АдресаКлюч можно привязать к адресам (
allow_from). Другой адрес получает 403 и запись в журнале.
Установка в HQbird
Установщик HQbird ставит MCP-сервер по умолчанию. Один сервер обслуживает все линии Firebird на машине. Всё настраивает одна команда, её можно запускать повторно.
- 1Установщик HQbirdWindows или Linux
- 2fbmcp ctl hqbird-installодна команда, без ручной правки YAML
- 3Линии Firebirdнаходит каждую линию и её агента
- 4Базыалиасы databases.conf и базы, к которым недавно подключались
- 5✓ Службазапуск, проверка, файл connect.txt для клиентов
Удалённый режим включается, когда выполнены три условия: задан список адресов администраторов (--allow-from), работает файрвол и создан хотя бы один API-ключ. Ключ создаётся отдельно. После этого запустите fbmcp ctl hqbird-install ещё раз. Порт по умолчанию 8650.
Цепочка хэшей
Каждое решение (разрешено, ждёт, одобрено, отклонено) записано в журнал. Каждая запись связана с предыдущей. Подмену или удаление записи видно при проверке цепочки.
Обрезан журнал — сервер стоит
Если журнал обрезан или его конец не совпадает с контрольной записью, MCP-сервер не запускается. Это признак вмешательства, и его нужно разобрать. Всю цепочку проверяет команда fbmcp ctl verify.
Через агента
fbagent обновляет MCP-сервер: остановка, замена, запуск, проверка, откат при сбое. На Linux сборка без подписи не ставится. Конфигурация и ключи не меняются.