Аудитория: человек, который устанавливает и запускает 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.