Аудиторія: людина, яка встановлює і запускає 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+ для інструментів кластера (необов’язково).

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

Двійкові файли для Linux (крос-збірка з Windows або збірка на Linux без 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

Контрольні суми: 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:

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

Секрети. YAML зберігає лише імена змінних. fbmcp шукає кожне значення в такому порядку: змінна середовища → файл <secrets.dir>/<NAME> → зв’язка ключів ОС облікового запису, від якого працює 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)

Значення читається зі 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 із підвищеними правами:

Command
.\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 (із підвищеними правами):

  1. Двійкові файли і fbmcp.yaml у C:\fbmcp\ (шаблон: 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" — запишіть pin sha256:....
  3. Один ключ на людину або агента: C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets (друкується один раз). З --config C:\fbmcp\fbmcp.yaml він також додає запис identities: і використовує secrets.dir.
  4. Паролі і токени агента: 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, потім без -WhatIf. Він створює службу, правило брандмауера, ACL тек і права на службу Firebird.
  6. 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.
  7. Трей для того, хто підтверджує: .\packaging\windows\install-tray.ps1.

Сервер Linux (root): скопіюйте fbmcp, fbmcpctl і packaging/linux/, потім

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

Скрипт створює теки, сертифікат, першу конфігурацію з ключем 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 "..." відмовляє.

ПК адміністратора:

  1. C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1 (ключ, який ви отримали).
  2. Будь-який клієнт stdio (Claude Desktop, Cursor, Codex, ZCode): запис із §6 з такими args: ["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. Pin перевіряє ключ сервера, тому самопідписаному сертифікату не потрібне налаштування CA.
  3. Claude Code може також підключатися напряму через HTTP (.mcp.json "type": "http", заголовок Authorization: Bearer ${FBMCP_KEY_SRV1}, NODE_EXTRA_CA_CERTS для самопідписаного сертифіката). Не передавайте ключ через claude mcp add --header: він зберігається відкритим текстом.
  4. Перевірка: 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: немає запису.

  1. У клієнті: «fb_agent_discover». Він перелічує локальних агентів із base_url, instance_id і запропонованим ім’ям токена. Токени він не читає.
  2. Оператор зберігає local_api.token агента (не agent.auth_token): fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Ніколи не вводьте токен у чат.
  3. У клієнті: «fb_agent_register для цього агента» → підтвердьте в треї. fbmcp додає запис agents:, перезавантажується і перевіряє ідентичність.
  4. Перевірка: 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). Далі:

  1. fb_cluster_rcm_password: замініть перший пароль RCM (Tier 1).
  2. Новий кластер: відкрийте вікно парування на кожному хості (fb_agent_cluster_pairing), запустіть RCM на майстрі (fb_agent_cluster_rcm), з’єднайте хости (fb_cluster_link), створіть репліки (fb_cluster_reinit, Tier 2) і порівняйте дані (fb_cluster_verify). Кроки: prompts/cluster-setup.md.
  3. Служби кластера (перемикання, аварійний перехід, повторне приєднання): 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 Із базою щось не так

  1. fbmcpctl doctor --config <file>: конфігурація, секрети, входи Firebird, теки, захисна позиція, розклади. Кожен рядок FAIL має Fix:.
  2. fb_db_list → fb_db_health <db>; fb_service_status для екземпляра.
  3. fb_sessions, fb_transactions при проблемах зі з’єднаннями або розривом OAT; fb_firebird_log при помилках рушія.

13.2 Підозра на втручання або пошкодження: спочатку аудит

  1. fbmcpctl verify --config <file> → audit chain OK: N entries або BROKEN з причиною.
  2. Якщо перевірка не проходить: збережіть усю теку стану (це доказ), потім розбирайтеся. Не видаляйте audit.jsonl, щоб змусити ядро запуститися.

13.3 Навчальне відновлення (щокварталу)

  1. fb_backup_start → fb_job_status = succeeded.
  2. fb_restore_test → копію перевірено.
  3. fb_window_open для бази.
  4. fb_restore_replace → підтвердьте поза каналом. Простій до виходу в онлайн.
  5. Перевірка: fb_db_health, потім реальне читання (fb_schema_list, fb_info).
  6. Старий файл лишається як <db>.pre-restore, доки ви його не видалите.

13.4 Клієнт не може підключитися

  1. fbmcpctl ping --config <file>, fbmcpctl status --config <file>.
  2. Читайте журнал MCP клієнта (stdio) або <state_dir>\fbmcp.log / journalctl -u fbmcp (служба).
  3. «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.