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, планер, миграције,
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+ за алате кластера (опционо).
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-trayLinux бинарни фајлови (унакрсна изградња са 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 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 са повишеним правима:
.\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 сервер (са повишеним правима):
- Бинарни фајлови и
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"— забележите пинsha256:....- Један кључ по особи или агенту:
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>"]. Пин проверава кључ сервера, па самопотписаном сертификату није потребно подешавање 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, …) користе HQbird
fbagent Local API на истом хосту.
Искључени су док 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. - Сервиси кластера (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 Нешто није у реду са базом
fbmcpctl doctor --config <file>: конфигурација, тајне, пријаве на Firebird, фасцикле, posture, распореди. Сваки ред 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 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.