fbmcp: instalace a použití
Určeno pro člověka, který fbmcp instaluje a provozuje a nesestavil ho. Znalost vnitřností Go ani Firebird není potřeba. Stav k 2026-11-16, verze 2027.2.24 (místní a vzdálený režim, instalace HQbird, most fbagent, cluster HQbird, mřížka výsledků).
Krátké verze, které na tomto webu nejsou: quickstart-en.md, quickstart-ru.md,
quickstart-pt.md. Podrobnosti, anglicky: remote.md (vzdálený
režim), agent-bridge.md (fbagent),
tool-reference.md (každý nástroj, jeho Tier a argumenty),
claude-desktop.md (zapojení klienta na vývojovém počítači),
ADR v decisions/.
1. Co je fbmcp
fbmcp je MCP server pro Firebird 2.5–5.0 na Windows a Linuxu. MCP
klient (Claude Desktop, Claude Code, Cursor, Codex, ZCode a další) ho používá
k práci jako DBA: monitorování, zálohy a ověřené obnovy, SQL/DDL/DCL,
indexy, uživatelé a oprávnění, firebird.conf, plánovač, migrace,
fbagent HQbird a cluster HQbird. Má 122 nástrojů: 56 jen pro čtení (Tier 0), 44 Tier 1,
21 Tier 2, 1 Tier 3 (vypnuto). fb_demo_write je k dispozici jen tehdy, když
server běží s FBMCP_DEMO_TOOLS=1.
Klient vidí jen nástroje, které smí použít. Seznam nástrojů skrývá: Tier 3,
nástroje nad maximálním Tier identity, fb_confirm a fb_cancel pro
identitu jen pro čtení, nástroje fbagent, dokud je agents: prázdné
(fb_agent_discover a fb_agent_register zůstávají), migrační nástroje,
dokud žádná databáze nemá migrations_dir, a nástroje clusteru, dokud
fbmcp.yaml nemá sekci rcm:. Když opětovné načtení konfigurace tuto
sadu změní, klient dostane nový seznam. Přímé volání skrytého nástroje dostane
jasné odmítnutí.
| Binárka | Role |
|---|---|
fbmcp |
Server. Výchozí: MCP přes stdio (spouští ho klient). -serve: bez stdio, běží jako služba (plánovač, socket pro attach, HTTPS listener, je-li nastaven). fbmcp bridge: stdio klient pro vzdálený fbmcp |
fbmcpctl |
CLI operátora: doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. Stejný program jako fbmcp ctl |
fbmcp-tray |
Oznamovací oblast Windows: vyskakovací okno Schválit/Zamítnout pro požadavky, které potřebují operátora |
Jeden kernel na adresář stavu. Druhý klient se stejnou konfigurací nespustí druhý kernel: připojí se k tomu, který už běží.
2. Model bezpečnosti
Každé volání prochází zásadou → potvrzením člověkem → auditovaným provedením.
| Tier | Co | Jak se potvrzuje |
|---|---|---|
| 0 | Čtení (transakce jen pro čtení vynucené enginem) | Není potřeba |
| 1 | Běžné změny: DML/DDL, záloha, uživatelé, oprávnění | V kanálu: klient ukáže id požadavku a token; osoba souhlasí; klient zavolá fb_confirm |
| 2 | Vysoký dopad: řízení služby, obnova s náhradou, firebird.conf, výhradní okno, registrace, restarty agenta |
Jen mimo kanál: tray nebo fbmcpctl approve. Klient to nikdy neschválí |
| 3 | Kritické (fb_db_drop) |
Vypnuto záměrně |
- Tier 2 obvykle potřebuje otevřené okno údržby (
fb_window_open, na stejnédb) a ověřenou zálohu mladší než 24 hodin. Odmítnutí řekne, co chybí. - Čekající požadavek vyprší po 15 minutách. Pokus ve špatném kanálu
ho nespotřebuje;
fb_cancelho odstraní. - Každý nástroj s potvrzením přijímá
mode: preview: ukáže dopad a nic neudělá. - Každé rozhodnutí (povolit, čeká, schváleno, zamítnuto) jde do
audit.jsonls řetězem hashů. - Schvalovací webová stránka neexistuje a nikdy existovat nesmí: stránka, na kterou by se model dostal, by návrh rozbila.
3. Volba nasazení
| Nasazení | Kde fbmcp běží | Kdy ho použít | Oddíl |
|---|---|---|---|
| A. Místní stdio | Váš počítač; spouští ho klient | Jeden správce, Firebird na tomto počítači nebo v LAN | §6 |
| B. Místní služba | Služba Windows na hostiteli DB (-serve) |
Rozvrhy musí běžet, i když není otevřený žádný klient | §7 |
| C. Vzdálené | Služba na databázovém serveru, HTTPS + API klíče | Několik správců, vzdálený server, autonomní agenti | §8 |
V nasazení A kernel žije jen po dobu, kdy běží klient, takže rozvrhy se spouštějí
jen tehdy. Pro rozvrhy bez obsluhy (nightly_verify) použijte B nebo C.
fbmcp v HQbird. Nasazení HQbird 2027 a fbagent instalují fbmcp
ve výchozím stavu: jedna služba na server pro všechny řady Firebird, nastavená
fbmcp ctl hqbird-install. Na takovém serveru nepostupujte podle §6–§8; přečtěte
hqbird.md (rozložení, vzdálený režim s --allow-from, API klíče).
4. Získání binárek
Požadavky: Go ≥ 1.26.11 (starší Go 1.21+ si při prvním sestavení samo stáhne go1.26.11; k tomu je potřeba internet), CGO není potřeba; Firebird 2.5–5.0; fbagent ≥ 2.67 s Local API pro nástroje agenta (volitelné); fbagent 3.1.0+ a RCM 2027.5.11+ pro nástroje clusteru (volitelné).
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-trayBinárky pro Linux (křížové sestavení z Windows, nebo sestavení na Linuxu bez
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/fbmcpctlKontrolní součty: Get-FileHash dist/* nebo sha256sum dist/*. Další cíle:
packaging/README.md. Binárky dejte do vlastní složky
(příklady používají C:\fbmcp\): mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\
(Linux: install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/).
fbmcp ctl a fbmcpctl jsou tentýž program. fbmcpctl help vypíše
příkazy. Příkazy, které čtou konfiguraci, berou --config <file>; bez něj
použijí FBMCP_CONFIG, pak fbmcp.yaml v aktuální složce, pak vedle
programu, pak výchozí cestu HQbird (C:\HQbirdData\fbmcp\fbmcp.yaml,
/etc/fbmcp/fbmcp.yaml) a vypíšou using config <path>.
5. Konfigurace fbmcp.yaml
Úplný příklad: packaging/fbmcp.yaml.example.
Minimální konfigurace pro 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 backupsTajné hodnoty. YAML drží jen názvy proměnných. fbmcp hledá každou
hodnotu v tomto pořadí: proměnná prostředí → soubor <secrets.dir>/<NAME> →
systémový keyring účtu, pod kterým fbmcp běží.
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)Hodnota se čte ze stdin (napište ji, pak Ctrl+Z, Enter; na Linuxu Ctrl+D).
Účet služby (LocalSystem, NT SERVICE\...) váš keyring nevidí:
pro služby použijte secrets.dir. Změněný soubor s tajnou hodnotou se uplatní za několik
sekund bez restartu.
Uživatel jen pro čtení. Pro ro_user vytvořte samostatného uživatele Firebird (SQL:
quickstart-en.md:
CREATE USER FBMCP_RO, GRANT SELECT na každou tabulku a na Firebird 4.0+
roli s MONITOR_ANY_ATTACHMENT, aby fb_sessions viděl všechna připojení).
SYSDBA jako uživatel RO je jen pro vývoj; doctor na to upozorní.
Živé opětovné načtení. fbmcp uplatní změny fbmcp.yaml sám (sledování
souboru), nebo na fb_config_reload. Bez restartu klienta ani procesu. Načtení
počká na úlohy na změněných databázích (30 s) a pak se uplatní. Odmítnuto:
změna state.dir, duplicitní cesty databází, nezabezpečená vzdálená konfigurace.
Kontrola: C:\fbmcp\fbmcpctl.exe doctor musí skončit doctor: green
(vzdálený režim: doctor --remote, žádné řádky FAIL). Vytvoří chybějící složku
stavu, přihlásí se do každé databáze oběma uživateli a každý řádek FAIL končí
Fix: a příkazem, který spustit.
6. Nasazení A — místní stdio
Používejte absolutní cesty. Nenastavujte listen. Po změně konfigurace klienta restartujte:
klienti načítají servery jen při startu.
| Klient | Kde | Záznam |
|---|---|---|
| Claude Desktop | Nastavení → Vývojář → Upravit konfiguraci (%APPDATA%\Claude\claude_desktop_config.json) |
"mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}} |
| Claude Code | příkazový řádek | claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml" |
| Cursor | %USERPROFILE%\.cursor\mcp.json nebo .cursor\mcp.json v projektu |
stejné JSON jako u Claude Desktop |
| Codex | codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml nebo %USERPROFILE%\.codex\config.toml |
[mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml'] |
| ZCode | .zcode\config.json v projektu |
"mcp": {"servers": {"fbmcp": { ...same command and args... }}} |
Hesla jsou v keyringu (§5), takže blok env není potřeba. Pokud heslo
do bloku env klienta přesto dáte, ten soubor držte mimo git.
Pak spusťte tray pro schvalování Tier 2:
C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml (při každém přihlášení:
.\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).
Rychlá zkouška v klientovi: “zavolejte fb_ping” (ukáže název serveru a vaši
identitu s jejím maximálním Tier), pak “fb_db_list”, pak “fb_db_health pro main”.
7. Nasazení B — místní služba Windows
PowerShell se zvýšenými oprávněními:
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp- Služba spouští
fbmcp -servejako LocalSystem, po selhání se restartuje a při zastavení služby se čistě ukončí. - Pro hesla použijte
secrets.dir(§5). - Zamkněte složku: do
C:\fbmcpsmí zapisovat jen SYSTEM a Administrators (skript vypíše příkazicacls). Složka vytvořená podC:\dovolí každému uživateli soubory měnit a služba je spouští jako SYSTEM. - Uživatel tray a místní stdio klienti potřebují čtení a zápis na adresář stavu:
icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M". Stdio klient se stejnou konfigurací se pak připojí ke kernelu služby. - Připravenost:
C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml. - Protokol:
<state_dir>\fbmcp.log(5 × 10 MiB; pády vfbmcp-crash.log).
Pro službu, ke které se správci dostávají po síti, použijte nasazení C.
8. Nasazení C — vzdálené (HTTPS + API klíče)
Úplný postup: remote.md. Stručná podoba:
Server Windows (se zvýšenými oprávněními):
- Binárky a
fbmcp.yamlvC:\fbmcp\(šablona: 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"— poznamenejte si pinsha256:....- Jeden klíč na osobu nebo agenta:
C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets(vypsán jednou). S--config C:\fbmcp\fbmcp.yamltaké přidá záznamidentities:a použijesecrets.dir. - Hesla a tokeny agenta:
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, pak bez-WhatIf. Vytvoří službu, pravidlo firewallu, ACL složek a práva služby Firebird.C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml→ žádné FAIL;curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz→ok.- Tray pro schvalovatele:
.\packaging\windows\install-tray.ps1.
Server Linux (root): zkopírujte fbmcp, fbmcpctl a packaging/linux/, pak
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/24Skript vytvoří složky, certifikát, první konfiguraci s klíčem
admin (vypsán jednou), jednotku systemd, pravidlo sudo pro
jednotku Firebird a pravidlo ufw, pak spustí doctor --remote. Přidejte
databases: a agents: do /etc/fbmcp/fbmcp.yaml. Schvalování na Linuxu
(bez tray): sudo -u firebird fbmcpctl approve [id]. Soubor
/etc/fbmcp/fbmcp.yaml najde sám, ptá se y/N (--yes se neptá) a
--deny <id> --reason "..." odmítne.
Počítač správce:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(klíč, který jste dostali).- Libovolný stdio klient (Claude Desktop, Cursor, Codex, ZCode): záznam z §6
s těmito
args:["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. Pin kontroluje klíč serveru, takže certifikát podepsaný sám sebou nepotřebuje nastavení CA. - Claude Code se může připojit i přímo přes HTTP (
.mcp.json"type": "http", hlavičkaAuthorization: Bearer ${FBMCP_KEY_SRV1},NODE_EXTRA_CA_CERTSpro certifikát podepsaný sám sebou). Klíč nepředávejte přesclaude mcp add --header: uloží se jako prostý text. - Zkouška:
fb_pingukáže název serveru a vaši identitu.
Autonomní agenti (OpenClaw a podobní): samostatný klíč pomocí
apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32.
Ve výchozím stavu jen pro čtení; každý požadavek Tier 1 čeká na operátora a
fb_confirm od agenta je odmítnuto. Limity: remote.md §6–7.
9. Most fbagent a cluster HQbird (volitelné)
Nástroje agenta (fb_agent_status, fb_agent_job_run, …) používají Local API
fbagent HQbird na stejném hostiteli.
Jsou vypnuté, dokud agents: nemá záznam.
- V klientovi: “
fb_agent_discover”. Vypíše místní agenty sbase_url,instance_ida navrženým názvem tokenu. Tokeny nikdy nečte. - Operátor uloží
local_api.tokenagenta (neagent.auth_token):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Token nikdy nepište do chatu. - V klientovi: “
fb_agent_registerpro toho agenta” → schvalte v tray. fbmcp přidá záznamagents:, znovu načte a ověří identitu. - Zkouška:
fb_agent_status,fb_agent_instances.
fb_agent_config_set (změna nastavení úloh: záloha, sweep, …) také potřebuje
config_path u záznamu a přístup ke čtení živého agent_config.json
plus právo vytvářet v jeho složce. Ten soubor drží token a přihlašovací údaje Firebird,
takže toto oprávnění je rozhodnutí operátora
(agent-bridge.md). Když kontrola agenta selže, nástroj
nic nezapíše.
Cluster HQbird (RCM). Nástroje clusteru volají správce clusteru HQbird
(hqbirdrcm) na stejném hostiteli. Zobrazí se jen tehdy, když
fbmcp.yaml má sekci rcm: (url, ca_file, user,
password_env). Na linuxovém serveru HQbird ji fbmcp ctl hqbird-install zapíše
z /opt/hqbirdrcm/rcm.json a první heslo RCM uloží do
tajné hodnoty FBMCP_RCM_PASSWORD; jinde sekci přidejte ručně
(tool-reference.md). Pak:
fb_cluster_rcm_password: nahraďte první heslo RCM (Tier 1).- Nový cluster: na každém hostiteli otevřete okno párování
(
fb_agent_cluster_pairing), spusťte RCM na masteru (fb_agent_cluster_rcm), propojte hostitele (fb_cluster_link), vytvořte repliky (fb_cluster_reinit, Tier 2) a porovnejte data (fb_cluster_verify). Kroky:prompts/cluster-setup.md. - Služby clusteru (switchover, failover, rejoin):
fb_cluster_serviceje ukáže i s kontrolami; přesuny jsou Tier 2. Kroky:prompts/cluster-services.md.
10. Každodenní použití
Ptejte se klienta běžnými slovy; nástroje vybere sám. Příklady:
| Úkol | Nástroje |
|---|---|
| Běží všechno? | fb_ping, fb_db_list, fb_db_health, fb_service_status |
| Čtení dat | fb_query (jen pro čtení, řádky + plán + statistiky po tabulkách; mřížka v klientech MCP-Apps); návrh zkontrolujte pomocí fb_query_check |
| Relace, dlouhé transakce | fb_sessions, fb_transactions, fb_session_kill (Tier 1) |
| Pomalý dotaz | fb_analyze_query, fb_index_advice → uplatněte pomocí fb_write; fb_agent_perf_report |
| Záloha | fb_backup_start → id úlohy → fb_job_status |
| Ověření zálohy | fb_restore_test (obnoví do work_dir, označí zálohu jako ověřenou) |
| Noční záloha + ověření | fb_schedule_create s target=nightly_verify (potvrzeno jednou; nasazení B nebo C) |
| Schéma / DDL | fb_schema_list, fb_describe, fb_write (každý příkaz se zařadí a dostane Tier), fb_diff_schema |
| Migrace | fb_migration_status, fb_migration_plan, fb_migration_apply |
| Konfigurace serveru | fb_config_get, fb_config_diff, fb_config_set (Tier 2) |
| Protokoly | fb_firebird_log |
| Kapacita | fb_trends, fb_gstat, fb_index_stats |
| Stav clusteru | fb_cluster_status, fb_cluster_service |
| Přesun masteru | fb_cluster_switchover (bez ztráty dat) nebo fb_cluster_failover (master ztracen), pak fb_cluster_rejoin (Tier 2) |
Úlohy jsou asynchronní: odešlete → fb_job_status. Úlohy na jedné databázi běží po
jedné. Úloha přežije restart fbmcp jen jako interrupted: odešlete ji
znovu, pokud je stále potřeba.
fb_config_set mění v firebird.conf jen vlastní řádek (komentáře,
odsazení a konce řádků zůstanou), starý soubor ponechá jako firebird.conf.prev
a Firebird nikdy nerestartuje. Restart pomocí fb_service_restart (Tier 2): počká,
až je služba zastavená a znovu běží.
11. Úkoly operátora
| Úkol | Příkaz |
|---|---|
| Vypsat / schválit / zamítnout požadavky | fbmcpctl approve; fbmcpctl approve <id>; fbmcpctl approve --deny <id> --reason "..." (nebo tray) |
| Rotovat klíč | fbmcpctl apikey rotate alice --config <fbmcp.yaml> (starý klíč přestane platit během sekund) |
| Vypsat klíče | fbmcpctl apikey list (názvy, zdroje, Tier; nikdy hodnoty) |
| Odebrat osobu | smažte záznam identities:, pak fbmcpctl secret drop --dir <dir> NAME |
| Obnovit certifikát | fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ... (pin beze změny, bez restartu) |
| Zkontrolovat řetěz auditu | fbmcpctl verify |
| Žije kernel? | fbmcpctl ping; fbmcpctl status (čtení stavu offline) |
| Povolit řízení služby | packaging/posture/verify.ps1 nebo verify.sh, pak fbmcpctl setup --write-posture |
| Upgrade | zastavte službu (nebo klienty), nahraďte binárky, spusťte, doctor |
| Odebrání | Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux: remote.md §10. Adresář stavu (audit) ponechte, pokud vlastník neřekne jinak |
Jen vývojový počítač: .\packaging\rebuild-install.ps1 -Force znovu sestaví dist\,
zastaví a nahradí běžící binárky (staré ponechá jako *.exe~),
sloučí konfigurace klientů a spustí doctor.
12. Obnova po pádu a restartu
Ověřeno zkušebním svazkem chaos (internal/killharness).
| Po pádu nebo zabití | Při restartu | Akce operátora |
|---|---|---|
| Úloha běžela nebo čekala ve frontě | Označena interrupted; nikdy se neobnoví |
Odešlete znovu, je-li třeba |
| Čekající požadavek, nepotvrzený | Obnoven z state.json (TTL stále platí) |
Potvrďte, nebo ho nechte vypršet |
fb_restore_replace probíhá |
Dokončí se: obnova, validace, databáze online; <db>.pre-restore zůstane |
Zkontrolujte fb_db_health; .pre-restore smažte později |
fb_shutdown_window probíhá |
Dokončí krok gfix -online |
Zkontrolujte, že je online |
Zastaralý instance.lock |
Převzat automaticky | Žádná |
state.json poškozený |
Kernel odmítne start; kopie zůstane jako state.json.corrupt-<ts> |
Prohlédněte; state.json opravte nebo záměrně odstraňte (fbmcpctl repair znovu sestaví oprávnění rozvrhů z auditu) |
audit.jsonl poškozený nebo useknutý |
Kernel odmítne start | §13.2: berte to jako signál manipulace |
| Hodiny posunuty zpět | Plánovač přeskočí; žádný dvojí běh | Žádná |
| Proces služby Windows zabit | SCM ho restartuje asi za 5 s | Žádná |
Kernel u všeho, co nedokáže prokázat jako neporušené, selže zavřeně. Smyčka restartů je nález: přečtěte protokol.
13. Postupy při incidentech
13.1 S databází je něco v nepořádku
fbmcpctl doctor --config <file>: konfigurace, tajné hodnoty, přihlášení Firebird, složky, postoj, rozvrhy. Každý řádek FAIL máFix:.fb_db_list→fb_db_health <db>;fb_service_statuspro instanci.fb_sessions,fb_transactionspro problémy s připojením nebo mezerou OAT;fb_firebird_logpro chyby enginu.
13.2 Podezření na manipulaci nebo poškození: nejdřív audit
fbmcpctl verify --config <file>→audit chain OK: N entriesneboBROKENs důvodem.- Pokud selže: ponechte celý adresář stavu (je to důkaz) a pak
vyšetřujte. Nemazte
audit.jsonl, abyste kernel nastartovali.
13.3 Nácvik obnovy (každé čtvrtletí)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ záloha je ověřená.fb_window_openpro databázi.fb_restore_replace→ schvalte mimo kanál. Výpadek, dokud není online.- Kontrola:
fb_db_health, pak skutečné čtení (fb_schema_list,fb_info). - Starý soubor zůstane jako
<db>.pre-restore, dokud ho nesmažete.
13.4 Klient se nemůže připojit
fbmcpctl ping --config <file>,fbmcpctl status --config <file>.- Přečtěte MCP protokol klienta (stdio) nebo
<state_dir>\fbmcp.log/journalctl -u fbmcp(služba). - “another fbmcp instance is active”: jeden kernel na adresář stavu. Klienti na rouře se připojí sami; druhý kernel podle návrhu rychle selže.
V příkazech výše můžete --config vynechat, když vyhledání v §4 soubor
najde.
14. Řešení problémů
| Příznak | Význam / náprava |
|---|---|
| Nástroje se neobjeví | Skladba JSON, absolutní cesty, úplný restart klienta; MCP protokol klienta |
| V seznamu chybí jeden nástroj | Schovaný záměrně (§1): nad vaším maximálním Tier, žádný záznam agents:, žádné migrations_dir, nebo žádná sekce rcm: |
| Server hned skončí | fbmcpctl doctor; chybějící tajná hodnota; služba nemůže číst váš keyring (použijte secrets.dir) |
| Tier 2 “confirmation rejected: channel policy” | V chatu se to očekává. Schvalte v tray nebo pomocí fbmcpctl approve |
| Tier 2 “no open maintenance window” | fb_window_open pro stejné db, které nástroji předáte |
fb_restore_replace zamítnuto: předpoklady |
Potřebuje ověřenou zálohu < 24 h: fb_backup_start + fb_restore_test, a okno |
| Řízení služby zamítnuto | Chybí posture.verified (fbmcpctl setup --write-posture), nebo účet nemá práva ke službě Firebird |
fb_config_set: nelze zapsat |
Účet ten soubor nesmí měnit (linuxová jednotka ProtectSystem=strict; ACL Windows). Upravte ručně, nebo viz remote.md §8 |
| Tray nic neukazuje | Ukazuje jen požadavky, které potřebují operátora; zkontrolujte práva uživatele tray na adresář stavu a tray.log v něm |
| 401 (vzdálené) | Špatný klíč, nebo ho server nenačetl: apikey list, doctor --remote |
| 403 (vzdálené) | Zdrojová IP není v allow_from / firewallu, nebo hlavička Origin není v allowed_origins |
| 429 (vzdálené) | Limity; počkejte na Retry-After |
| Pin nesouhlasí | Klíč serveru se změnil; nový pin si vyžádejte u správce serveru |
agent-unreachable |
Služba agenta neběží, local_api.enabled: false, nebo špatné base_url (výchozí 127.0.0.1:(10000 + firebird port)) |
agent-auth |
Uložený token není local_api.token agenta; nastavte ho znovu |
agent-timeout při restartech |
agents[].timeout_seconds (130) musí být větší než restart_timeout_seconds agenta (120) |
Error loading plugin MySQLEngine … při attach |
Na HQbird to obvykle znamená, že databázový soubor neexistuje; zkontrolujte cestu |
Holé DROP INDEX v fb_write potřebuje okno |
Tam je to Tier 2; použijte fb_index_drop (Tier 1; odmítne indexy omezení) |
| Nový index se nepoužívá | Spočítejte statistiky (fb_index_rebuild action=statistics); ORDER BY … DESC potřebuje index DESCENDING |
| Nástroje selžou jen u jedné databáze | Je offline (fb_db_health); nástroje se zhoršují po jednotlivých databázích |
15. Přehled adresáře stavu
| Cesta | Význam |
|---|---|
state.json (+ .tmp, .corrupt-*) |
Čekající požadavky, úlohy, katalog záloh, workflow, rozvrhy. Poškození ⇒ odmítne start |
audit.jsonl (+ .head) |
Auditní protokol s řetězem hashů; .head pozná useknutí |
events.jsonl |
Události úloh (job.succeeded, job.failed se zprávou) |
approvals\, denials\ |
Rozhodnutí mimo kanál (tray / fbmcpctl approve), použitá do ~2 s |
instance.lock |
Zámek jednoho kernelu |
attach.addr, attach.token |
Koncový bod attach pro další stdio klienty |
fbmcp.log, fbmcp-crash.log |
Protokol služby (rotovaný) a výstup pádu |
query-log.jsonl |
Každé volání fb_query |
trends\ |
Historie vzorkovače pro fb_trends |
config-journal\ |
Historie fb_config_set (stará a nová hodnota) |
posture.verified |
Značka, která povoluje řízení služby |
tray.log |
Chyby tray |
16. Stav průchodu
Čeká (M1): průchod na čistém hostiteli Windows jen podle tohoto průvodce.
Nálezy se zapisují zpět do tohoto souboru. Laboratorní výsledky pro vzdálený režim (hostitel Linux,
čerstvé VM, služba Windows): findings/phase12-lab-2026-11-03.md.