HQbird MCP AI-асистент
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 блокує записи. Для другого шару захисту задайте окремого користувача лише для читання без прав на запис.
Моніторинг · резервні копії · права
Для адміністраторів БД
Асистент робить те, що адміністратор БД робить вручну: перевіряє сесії та транзакції, читає журнали, створює резервну копію й перевіряє її відновленням, керує користувачами. Він називає бази даних за 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 · Локальний API · 127.0.0.1
Дані fbagent
Агент fbagent уже працює на сервері HQbird. Через MCP асистент отримує все, що зібрав агент: звіт про стан, LWM (Light-weight Monitoring), gstat, трасування, взаємоблокування, стан резервного копіювання. Він також запускає завдання агента та змінює їхні налаштування — за тими самими рівнями та затвердженнями.
| Що | Інструменти | Рівень |
|---|---|---|
| Звіт про стан сервера | fb_agent_status | 0 |
| LWM, gstat, метрики бази даних, трасування, взаємоблокування | 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; облікові дані, ідентифікатори та команди змінити не можна | 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 |
| Відновлення та скасування операції | 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 <name> --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 непідписана збірка не встановлюється. Конфігурація та ключі не змінюються.