Публика: особа која инсталира и покреће 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, планер, миграције, HQbird fbagent и кластер 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 на овом рачунару или у LAN §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 s), па примењује. Одбија се: промена 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).
  • Закључајте фасциклу: само SYSTEM и Administrators смеју да пишу у C:\fbmcp (скрипта исписује команду 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" — забележите пин 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>"]. Пин проверава кључ сервера, па самопотписаном сертификату није потребно подешавање 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, …) користе HQbird fbagent Local API на истом хосту. Искључени су док 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. Сервиси кластера (switchover, failover, rejoin): 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 (имена, извори, Tier; никада вредности)
Уклањање особе обришите унос identities:, затим fbmcpctl secret drop --dir <dir> NAME
Обнова сертификата fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ... (пин непромењен, без поновног покретања)
Провера ланца ревизије 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 s Ништа

Језгро отказује затворено за све што не може да докаже нетакнутим. Петља поновног покретања је налаз: читајте дневник.

13. Поступци за инциденте

13.1 Нешто није у реду са базом

  1. fbmcpctl doctor --config <file>: конфигурација, тајне, пријаве на Firebird, фасцикле, posture, распореди. Сваки ред 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 h: fb_backup_start + fb_restore_test, и прозор
Управљање сервисом одбијено Недостаје posture.verified (fbmcpctl setup --write-posture) или налог нема права на сервис Firebird
fb_config_set: не може да пише Налог можда не сме да мења тај фајл (Linux јединица ProtectSystem=strict; Windows ACL). Уредите ручно, или видите remote.md §8
Трака не приказује ништа Приказује само захтеве којима треба оператор; проверите права корисника траке на директоријум стања и tray.log тамо
401 (удаљено) Погрешан кључ, или га сервер није учитао: apikey list, doctor --remote
403 (удаљено) Изворни IP није у allow_from / заштитном зиду, или заглавље Origin није у allowed_origins
429 (удаљено) Ограничења; сачекајте Retry-After
Пин се не поклапа Кључ сервера се променио; нови пин узмите од администратора сервера
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 s
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 хост, свежа VM, Windows сервис): findings/phase12-lab-2026-11-03.md.