fbmcp: встановлення та використання
Аудиторія: людина, яка встановлює і запускає fbmcp і не збирала його. Знання внутрішньої будови Go чи Firebird не потрібне. Стан на 2026-11-16, версія 2027.2.24 (локальний і віддалений режим, встановлення HQbird, міст fbagent, кластер HQbird, сітка результатів).
Короткі версії, не на цьому сайті: quickstart-en.md, quickstart-ru.md,
quickstart-pt.md. Подробиці, англійською: remote.md (віддалений
режим), agent-bridge.md (fbagent),
tool-reference.md (кожен інструмент, його Tier і аргументи),
claude-desktop.md (підключення клієнта на хості розробки),
ADR у decisions/.
1. Що таке fbmcp
fbmcp — сервер MCP для Firebird 2.5–5.0 на Windows і Linux. Клієнт
MCP (Claude Desktop, Claude Code, Cursor, Codex, ZCode та інші) використовує його,
щоб працювати як DBA: моніторинг, резервні копії та перевірені
відновлення, SQL/DDL/DCL, індекси, користувачі та права, firebird.conf,
планувальник, міграції, fbagent HQbird і кластер HQbird. У ньому 122 інструменти:
56 лише для читання (Tier 0), 44 Tier 1, 21 Tier 2, 1 Tier 3 (вимкнений).
fb_demo_write є лише тоді, коли сервер працює з FBMCP_DEMO_TOOLS=1.
Клієнт бачить лише ті інструменти, якими може користуватися. Список інструментів приховує:
Tier 3, інструменти вище максимального Tier ідентичності, fb_confirm і
fb_cancel для ідентичності лише для читання, інструменти fbagent, доки
agents: порожній (fb_agent_discover і fb_agent_register лишаються),
інструменти міграцій, доки жодна база не має migrations_dir, та інструменти
кластера, доки в fbmcp.yaml немає секції rcm:. Коли перезавантаження
конфігурації змінює цей набір, клієнт отримує новий список. Прямий
виклик прихованого інструмента закінчується чіткою відмовою.
| Двійковий файл | Роль |
|---|---|
fbmcp |
Сервер. Типово: MCP через stdio (його запускає клієнт). -serve: без stdio, працює як служба (планувальник, сокет приєднання, прослуховувач HTTPS, якщо налаштований). fbmcp bridge: клієнт stdio для віддаленого fbmcp |
fbmcpctl |
CLI оператора: doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. Та сама програма, що й fbmcp ctl |
fbmcp-tray |
Трей Windows: спливне вікно Підтвердити/Відхилити для запитів, яким потрібен оператор |
Одне ядро на теку стану. Другий клієнт із тією самою конфігурацією не запускає друге ядро: він приєднується до вже працюючого.
2. Модель безпеки
Кожен виклик проходить політику → підтвердження людиною → виконання із записом в аудит.
| Tier | Що | Як підтверджується |
|---|---|---|
| 0 | Читання (транзакції лише для читання, примусово задані рушієм) | Не потрібно |
| 1 | Звичайні зміни: DML/DDL, резервна копія, користувачі, права | У каналі: клієнт показує ідентифікатор запиту і токен; людина погоджується; клієнт викликає fb_confirm |
| 2 | Високий вплив: керування службою, відновлення із заміною, firebird.conf, монопольне вікно, реєстрація, перезапуски агента |
Лише поза каналом: трей або fbmcpctl approve. Клієнт ніколи не може це підтвердити |
| 3 | Критичне (fb_db_drop) |
Вимкнено за задумом |
- Tier 2 зазвичай потребує відкритого вікна обслуговування (
fb_window_open, на тій самійdb) і перевіреної резервної копії молодшої за 24 години. Відмова повідомляє, чого не вистачає. - Очікуваний запит спливає через 15 хвилин. Спроба не тим каналом
його не витрачає;
fb_cancelйого видаляє. - Кожен інструмент, що потребує підтвердження, приймає
mode: preview: показує наслідки і нічого не робить. - Кожне рішення (дозвіл, очікування, підтвердження, відмова) потрапляє в
audit.jsonlіз ланцюжком хешів. - Вебсторінки підтвердження немає, і її ніколи не повинно бути: сторінка, до якої може дістатися модель, зламала б задум.
3. Вибір схеми
| Схема | Де працює fbmcp | Коли використовувати | Розділ |
|---|---|---|---|
| A. Локальний stdio | Ваш ПК; клієнт його запускає | Один адміністратор, Firebird на цьому ПК або в локальній мережі | §6 |
| B. Локальна служба | Служба Windows на хості БД (-serve) |
Розклади мають виконуватися, коли жоден клієнт не відкритий | §7 |
| C. Віддалений | Служба на сервері БД, HTTPS + ключі API | Кілька адміністраторів, віддалений сервер, автономні агенти | §8 |
У схемі A ядро живе лише поки працює клієнт, тому розклади
спрацьовують лише тоді. Для розкладів без нагляду (nightly_verify)
використовуйте B або C.
fbmcp в HQbird. Встановлення HQbird 2027 і fbagent встановлюють fbmcp
типово: одна служба на сервер для всіх лінійок Firebird, її налаштовує
fbmcp ctl hqbird-install. На такому сервері не йдіть за §6–§8; читайте
hqbird.md (розташування, віддалений режим із --allow-from, ключі API).
4. Отримання двійкових файлів
Вимоги: Go ≥ 1.26.11 (старіший Go 1.21+ сам завантажує go1.26.11 під час першої збірки; для цього потрібен інтернет), CGO не потрібен; Firebird 2.5–5.0; fbagent ≥ 2.67 з Local API для інструментів агента (необов’язково); fbagent 3.1.0+ і RCM 2027.5.11+ для інструментів кластера (необов’язково).
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Двійкові файли для Linux (крос-збірка з Windows або збірка
на Linux без 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/fbmcpctlКонтрольні суми: Get-FileHash dist/* або sha256sum dist/*. Інші цілі:
packaging/README.md. Покладіть двійкові файли в окрему теку (у прикладах
C:\fbmcp\): mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\
(Linux: install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/).
fbmcp ctl і fbmcpctl — одна й та сама програма. fbmcpctl help перелічує
команди. Команди, які читають конфігурацію, приймають --config <file>;
без нього вони використовують FBMCP_CONFIG, потім fbmcp.yaml у поточній теці,
потім поруч із програмою, потім типовий шлях HQbird (C:\HQbirdData\fbmcp\fbmcp.yaml,
/etc/fbmcp/fbmcp.yaml) і друкують using config <path>.
5. Налаштування fbmcp.yaml
Повний приклад: packaging/fbmcp.yaml.example.
Мінімальна конфігурація 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 backupsСекрети. YAML зберігає лише імена змінних. fbmcp шукає кожне
значення в такому порядку: змінна середовища → файл <secrets.dir>/<NAME> →
зв’язка ключів ОС облікового запису, від якого працює 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)Значення читається зі stdin (введіть його, потім Ctrl+Z, Enter; у Linux Ctrl+D).
Обліковий запис служби (LocalSystem, NT SERVICE\...) не бачить вашу зв’язку ключів:
для служб використовуйте secrets.dir. Змінений файл секрету застосовується
за кілька секунд без перезапуску.
Користувач лише для читання. Створіть окремого користувача Firebird для
ro_user (SQL: quickstart-en.md:
CREATE USER FBMCP_RO, GRANT SELECT на кожну таблицю, а у Firebird 4.0+
роль із MONITOR_ANY_ATTACHMENT, щоб fb_sessions бачив усі з’єднання).
SYSDBA як користувач RO — лише для розробки; doctor попереджає про це.
Живе перезавантаження. fbmcp сам застосовує зміни fbmcp.yaml (спостерігач
файлу) або за fb_config_reload. Без перезапуску клієнта чи процесу. Перезавантаження
чекає на завдання на змінених базах (30 с), потім застосовує. Відмова:
зміна state.dir, повторювані шляхи баз, небезпечна віддалена конфігурація.
Перевірка: C:\fbmcp\fbmcpctl.exe doctor має закінчитися на doctor: green
(віддалений режим: doctor --remote, без рядків FAIL). Він створює відсутню теку
стану, входить у кожну базу обома користувачами, і кожен рядок FAIL
закінчується на Fix: і команду, яку треба виконати.
6. Схема A — локальний stdio
Використовуйте абсолютні шляхи. Не задавайте listen. Після зміни конфігурації
перезапустіть клієнт: клієнти завантажують сервери лише під час старту.
| Клієнт | Де | Запис |
|---|---|---|
| Claude Desktop | Параметри → Розробник → Змінити конфігурацію (%APPDATA%\Claude\claude_desktop_config.json) |
"mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}} |
| Claude Code | командний рядок | claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml" |
| Cursor | %USERPROFILE%\.cursor\mcp.json або .cursor\mcp.json у проєкті |
той самий JSON, що в Claude Desktop |
| Codex | codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml або %USERPROFILE%\.codex\config.toml |
[mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml'] |
| ZCode | .zcode\config.json у проєкті |
"mcp": {"servers": {"fbmcp": { ...same command and args... }}} |
Паролі лежать у зв’язці ключів (§5), тож блок env не потрібен. Якщо
ви все ж помістите пароль у блок env клієнта, тримайте цей файл поза git.
Потім запустіть трей для підтверджень Tier 2:
C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml (при кожному вході:
.\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).
Димовий тест у клієнті: «викличте fb_ping» (показує ім’я сервера і вашу
ідентичність із її максимальним Tier), потім «fb_db_list», потім «fb_db_health для main».
7. Схема B — локальна служба Windows
PowerShell із підвищеними правами:
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp- Служба запускає
fbmcp -serveвід LocalSystem, перезапускається після збою і чисто зупиняється при зупинці служби. - Паролі через
secrets.dir(§5). - Закрийте теку: писати в
C:\fbmcpможуть лише SYSTEM і Administrators (скрипт друкує командуicacls). Тека, створена підC:\, дозволяє будь-якому користувачеві змінювати файли, а служба запускає їх як SYSTEM. - Користувачу трея і локальним клієнтам stdio потрібні читання і запис
у теці стану:
icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M". Клієнт stdio з тією самою конфігурацією тоді приєднується до ядра служби. - Готовність:
C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml. - Журнал:
<state_dir>\fbmcp.log(5 × 10 MiB; збої вfbmcp-crash.log).
Для служби, до якої адміністратори звертаються через мережу, використовуйте схему C.
8. Схема C — віддалений (HTTPS + ключі API)
Повна процедура: remote.md. Стисло:
Сервер Windows (із підвищеними правами):
- Двійкові файли і
fbmcp.yamlуC:\fbmcp\(шаблон: 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"— запишіть pinsha256:....- Один ключ на людину або агента:
C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets(друкується один раз). З--config C:\fbmcp\fbmcp.yamlвін також додає записidentities:і використовуєsecrets.dir. - Паролі і токени агента:
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, потім без-WhatIf. Він створює службу, правило брандмауера, ACL тек і права на службу Firebird.C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml→ без FAIL;curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz→ok.- Трей для того, хто підтверджує:
.\packaging\windows\install-tray.ps1.
Сервер Linux (root): скопіюйте fbmcp, fbmcpctl і packaging/linux/, потім
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Скрипт створює теки, сертифікат, першу конфігурацію з ключем
admin (друкується один раз), юніт systemd, правило sudo для юніта
Firebird і правило ufw, потім запускає doctor --remote. Додайте
databases: і agents: до /etc/fbmcp/fbmcp.yaml. Підтвердження в Linux
(без трея): sudo -u firebird fbmcpctl approve [id]. Він сам знаходить
/etc/fbmcp/fbmcp.yaml, питає y/N (--yes не питає), а
--deny <id> --reason "..." відмовляє.
ПК адміністратора:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(ключ, який ви отримали).- Будь-який клієнт stdio (Claude Desktop, Cursor, Codex, ZCode): запис із §6
з такими
args:["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. Pin перевіряє ключ сервера, тому самопідписаному сертифікату не потрібне налаштування CA. - Claude Code може також підключатися напряму через HTTP (
.mcp.json"type": "http", заголовокAuthorization: Bearer ${FBMCP_KEY_SRV1},NODE_EXTRA_CA_CERTSдля самопідписаного сертифіката). Не передавайте ключ черезclaude mcp add --header: він зберігається відкритим текстом. - Перевірка:
fb_pingпоказує ім’я сервера і вашу ідентичність.
Автономні агенти (OpenClaw і подібні): окремий ключ через
apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32.
Типово лише для читання; кожен запит Tier 1 чекає на оператора, а
fb_confirm від агента відхиляється. Обмеження: remote.md §6–7.
9. Міст fbagent і кластер HQbird (необов’язково)
Інструменти агента (fb_agent_status, fb_agent_job_run, …) використовують
Local API fbagent HQbird на тому самому хості.
Вони вимкнені, доки в agents: немає запису.
- У клієнті: «
fb_agent_discover». Він перелічує локальних агентів ізbase_url,instance_idі запропонованим ім’ям токена. Токени він не читає. - Оператор зберігає
local_api.tokenагента (неagent.auth_token):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Ніколи не вводьте токен у чат. - У клієнті: «
fb_agent_registerдля цього агента» → підтвердьте в треї. fbmcp додає записagents:, перезавантажується і перевіряє ідентичність. - Перевірка:
fb_agent_status,fb_agent_instances.
fb_agent_config_set (зміна налаштувань завдань: резервна копія, sweep, …)
також потребує config_path у записі і доступу на читання до живого agent_config.json
плюс права створення в його теці. У цьому файлі лежать токен і облікові дані
Firebird, тому таке надання прав — рішення оператора
(agent-bridge.md). Якщо перевірка агента не проходить, інструмент
нічого не записує.
Кластер HQbird (RCM). Інструменти кластера викликають менеджер кластера
HQbird (hqbirdrcm) на тому самому хості. Вони показуються лише коли
в fbmcp.yaml є секція rcm: (url, ca_file, user,
password_env). На сервері Linux з HQbird fbmcp ctl hqbird-install записує
її з /opt/hqbirdrcm/rcm.json і зберігає перший пароль RCM у секреті
FBMCP_RCM_PASSWORD; в інших випадках додайте секцію вручну
(tool-reference.md). Далі:
fb_cluster_rcm_password: замініть перший пароль RCM (Tier 1).- Новий кластер: відкрийте вікно парування на кожному хості
(
fb_agent_cluster_pairing), запустіть RCM на майстрі (fb_agent_cluster_rcm), з’єднайте хости (fb_cluster_link), створіть репліки (fb_cluster_reinit, Tier 2) і порівняйте дані (fb_cluster_verify). Кроки:prompts/cluster-setup.md. - Служби кластера (перемикання, аварійний перехід, повторне приєднання):
fb_cluster_serviceпоказує їх і перевірки; переміщення — Tier 2. Кроки:prompts/cluster-services.md.
10. Щоденне використання
Просіть клієнта звичайними словами; він сам обирає інструменти. Приклади:
| Завдання | Інструменти |
|---|---|
| Чи все працює? | fb_ping, fb_db_list, fb_db_health, fb_service_status |
| Читання даних | fb_query (лише для читання, рядки + план + статистика по таблицях; сітка в клієнтах MCP-Apps); чернетку перевірте через fb_query_check |
| Сеанси, довгі транзакції | fb_sessions, fb_transactions, fb_session_kill (Tier 1) |
| Повільний запит | fb_analyze_query, fb_index_advice → застосуйте через fb_write; fb_agent_perf_report |
| Резервна копія | fb_backup_start → ідентифікатор завдання → fb_job_status |
| Перевірка резервної копії | fb_restore_test (відновлює в work_dir, позначає копію перевіреною) |
| Нічна копія + перевірка | fb_schedule_create з target=nightly_verify (підтверджується один раз; схема B або C) |
| Схема / DDL | fb_schema_list, fb_describe, fb_write (кожен оператор класифікується і отримує Tier), fb_diff_schema |
| Міграції | fb_migration_status, fb_migration_plan, fb_migration_apply |
| Конфігурація сервера | fb_config_get, fb_config_diff, fb_config_set (Tier 2) |
| Журнали | fb_firebird_log |
| Ємність | fb_trends, fb_gstat, fb_index_stats |
| Стан кластера | fb_cluster_status, fb_cluster_service |
| Перенесення майстра | fb_cluster_switchover (без втрати даних) або fb_cluster_failover (майстра втрачено), потім fb_cluster_rejoin (Tier 2) |
Завдання асинхронні: надішліть → fb_job_status. Завдання на одній базі
виконуються по одному. Завдання переживає перезапуск fbmcp лише як
interrupted: надішліть його знову, якщо воно все ще потрібне.
fb_config_set змінює лише свій рядок у firebird.conf (коментарі,
відступи і кінці рядків лишаються), зберігає старий файл як firebird.conf.prev
і ніколи не перезапускає Firebird. Перезапуск через fb_service_restart (Tier 2):
він чекає, доки служба не зупиниться і не запрацює знову.
11. Завдання оператора
| Завдання | Команда |
|---|---|
| Список / підтвердження / відмова за запитами | fbmcpctl approve; fbmcpctl approve <id>; fbmcpctl approve --deny <id> --reason "..." (або трей) |
| Ротація ключа | fbmcpctl apikey rotate alice --config <fbmcp.yaml> (старий ключ перестає діяти за секунди) |
| Список ключів | fbmcpctl apikey list (імена, джерела, рівні; ніколи значення) |
| Видалення людини | видаліть запис identities:, потім fbmcpctl secret drop --dir <dir> NAME |
| Оновлення сертифіката | fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ... (pin без змін, без перезапуску) |
| Перевірка ланцюжка аудиту | fbmcpctl verify |
| Ядро живе? | fbmcpctl ping; fbmcpctl status (читання стану офлайн) |
| Дозволити керування службою | packaging/posture/verify.ps1 або verify.sh, потім fbmcpctl setup --write-posture |
| Оновлення версії | зупиніть службу (або клієнтів), замініть двійкові файли, запустіть, doctor |
| Видалення | Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux: remote.md §10. Збережіть теку стану (аудит), якщо власник не скаже інше |
Лише хост розробки: .\packaging\rebuild-install.ps1 -Force перезбирає dist\,
зупиняє і замінює працюючі двійкові файли (старі лишаються як *.exe~),
зливає конфігурації клієнтів і запускає doctor.
12. Відновлення після збою і перезапуску
Перевірено хаос-тестом (internal/killharness).
| Після збою або примусового завершення | Під час перезапуску | Дія оператора |
|---|---|---|
| Завдання виконувалося або стояло в черзі | Позначено interrupted; ніколи не відновлюється |
Надішліть знову, якщо потрібно |
| Очікуваний запит, не підтверджений | Відновлений із state.json (TTL і далі діє) |
Підтвердьте або дайте спливти |
fb_restore_replace у процесі |
Завершує: відновлення, перевірка, база онлайн; <db>.pre-restore лишається |
Перевірте fb_db_health; .pre-restore видаліть пізніше |
fb_shutdown_window у процесі |
Завершує крок gfix -online |
Перевірте, що база онлайн |
Застарілий instance.lock |
Перехоплюється автоматично | Немає |
state.json пошкоджений |
Ядро відмовляється запускатися; копія лишається як state.json.corrupt-<ts> |
Огляньте; полагодьте або навмисно видаліть state.json (fbmcpctl repair наново збирає дозволи розкладів з аудиту) |
audit.jsonl пошкоджений або обрізаний |
Ядро відмовляється запускатися | §13.2: вважайте це сигналом втручання |
| Годинник переведено назад | Планувальник пропускає; подвійного запуску немає | Немає |
| Процес служби Windows завершено примусово | SCM перезапускає його приблизно за 5 с | Немає |
Ядро переходить у стан закрито для всього, цілісність чого воно не може довести. Цикл перезапусків — це сигнал: читайте журнал.
13. Сценарії інцидентів
13.1 Із базою щось не так
fbmcpctl doctor --config <file>: конфігурація, секрети, входи Firebird, теки, захисна позиція, розклади. Кожен рядок FAIL маєFix:.fb_db_list→fb_db_health <db>;fb_service_statusдля екземпляра.fb_sessions,fb_transactionsпри проблемах зі з’єднаннями або розривом OAT;fb_firebird_logпри помилках рушія.
13.2 Підозра на втручання або пошкодження: спочатку аудит
fbmcpctl verify --config <file>→audit chain OK: N entriesабоBROKENз причиною.- Якщо перевірка не проходить: збережіть усю теку стану (це доказ), потім
розбирайтеся. Не видаляйте
audit.jsonl, щоб змусити ядро запуститися.
13.3 Навчальне відновлення (щокварталу)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ копію перевірено.fb_window_openдля бази.fb_restore_replace→ підтвердьте поза каналом. Простій до виходу в онлайн.- Перевірка:
fb_db_health, потім реальне читання (fb_schema_list,fb_info). - Старий файл лишається як
<db>.pre-restore, доки ви його не видалите.
13.4 Клієнт не може підключитися
fbmcpctl ping --config <file>,fbmcpctl status --config <file>.- Читайте журнал MCP клієнта (stdio) або
<state_dir>\fbmcp.log/journalctl -u fbmcp(служба). - «another fbmcp instance is active»: одне ядро на теку стану. Клієнти через канал приєднуються самі; друге ядро швидко завершується помилкою за задумом.
У командах вище --config можна опустити, коли пошук із §4
знаходить файл.
14. Усунення несправностей
| Симптом | Значення / виправлення |
|---|---|
| Інструменти не з’являються | синтаксис JSON, абсолютні шляхи, повний перезапуск клієнта; журнал MCP клієнта |
| Одного інструмента немає в списку | Прихований навмисно (§1): вище вашого максимального Tier, немає запису agents:, немає migrations_dir або немає секції rcm: |
| Сервер одразу завершується | fbmcpctl doctor; відсутній секрет; служба не може прочитати вашу зв’язку ключів (використовуйте secrets.dir) |
| Tier 2 «confirmation rejected: channel policy» | Очікувано в чаті. Підтвердьте в треї або через fbmcpctl approve |
| Tier 2 «no open maintenance window» | fb_window_open для тієї самої db, яку ви передаєте інструменту |
fb_restore_replace відмова: передумови |
Потрібна перевірена копія < 24 год: fb_backup_start + fb_restore_test і вікно |
| Відмова в керуванні службою | немає posture.verified (fbmcpctl setup --write-posture) або обліковий запис не має прав на службу Firebird |
fb_config_set: не може записати |
Обліковий запис не може змінити цей файл (юніт Linux ProtectSystem=strict; ACL Windows). Правте вручну або див. remote.md §8 |
| Трей нічого не показує | Він показує лише запити, яким потрібен оператор; перевірте права користувача трея на теку стану і tray.log у ній |
| 401 (віддалений) | Невірний ключ, або сервер його не завантажив: apikey list, doctor --remote |
| 403 (віддалений) | Вихідний IP не в allow_from / брандмауері, або заголовок Origin не в allowed_origins |
| 429 (віддалений) | Обмеження; чекайте Retry-After |
| Незбіг pin | Ключ сервера змінився; візьміть новий pin в адміністратора сервера |
agent-unreachable |
Служба агента не працює, local_api.enabled: false або невірний base_url (типово 127.0.0.1:(10000 + firebird port)) |
agent-auth |
Збережений токен — не local_api.token агента; задайте його знову |
agent-timeout при перезапусках |
agents[].timeout_seconds (130) має бути більшим за restart_timeout_seconds агента (120) |
Error loading plugin MySQLEngine … при підключенні |
У HQbird це зазвичай означає, що файлу бази не існує; перевірте шлях |
Голий DROP INDEX у fb_write потребує вікна |
Там це Tier 2; використовуйте fb_index_drop (Tier 1; відмовляє індексам обмежень) |
| Новий індекс не використовується | Зберіть статистику (fb_index_rebuild action=statistics); ORDER BY … DESC потребує індекс DESCENDING |
| Інструменти відмовляють лише для однієї бази | Вона офлайн (fb_db_health); інструменти деградують по базах |
15. Довідник теки стану
| Шлях | Значення |
|---|---|
state.json (+ .tmp, .corrupt-*) |
Очікувані запити, завдання, каталог копій, робочі процеси, розклади. Пошкодження ⇒ відмова запуску |
audit.jsonl (+ .head) |
Журнал аудиту з ланцюжком хешів; .head виявляє обрізання |
events.jsonl |
Події завдань (job.succeeded, job.failed з повідомленням) |
approvals\, denials\ |
Рішення поза каналом (трей / fbmcpctl approve), використовуються протягом ~2 с |
instance.lock |
Блокування одного ядра |
attach.addr, attach.token |
Точка приєднання для додаткових клієнтів stdio |
fbmcp.log, fbmcp-crash.log |
Журнал служби (з ротацією) і вивід при збої |
query-log.jsonl |
Кожен виклик fb_query |
trends\ |
Історія семплера для fb_trends |
config-journal\ |
Історія fb_config_set (старе і нове значення) |
posture.verified |
Маркер, який дозволяє керування службою |
tray.log |
Помилки трея |
16. Статус проходження
Очікується (M1): проходження на новому хості Windows лише за цим посібником.
Знахідки повертаються в цей файл. Результати лабораторії для віддаленого режиму (хост Linux,
нова ВМ, служба Windows): findings/phase12-lab-2026-11-03.md.