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_cancel ho 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.jsonl s ř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é).

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

Binárky pro Linux (křížové sestavení z Windows, nebo sestavení na Linuxu bez 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

Kontrolní 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:

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

Tajné 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ěží.

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)

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:

Command
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp
  • Služba spouští fbmcp -serve jako 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:\fbmcp smí zapisovat jen SYSTEM a Administrators (skript vypíše příkaz icacls). Složka vytvořená pod C:\ 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 v fbmcp-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):

  1. Binárky a fbmcp.yaml v C:\fbmcp\ (šablona: 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" — poznamenejte si pin sha256:....
  3. 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.yaml také přidá záznam identities: a použije secrets.dir.
  4. Hesla a tokeny agenta: 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, pak bez -WhatIf. Vytvoří službu, pravidlo firewallu, ACL složek a práva služby Firebird.
  6. 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.
  7. Tray pro schvalovatele: .\packaging\windows\install-tray.ps1.

Server Linux (root): zkopírujte fbmcp, fbmcpctl a packaging/linux/, pak

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

Skript 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:

  1. C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1 (klíč, který jste dostali).
  2. 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.
  3. Claude Code se může připojit i přímo přes HTTP (.mcp.json "type": "http", hlavička Authorization: Bearer ${FBMCP_KEY_SRV1}, NODE_EXTRA_CA_CERTS pro certifikát podepsaný sám sebou). Klíč nepředávejte přes claude mcp add --header: uloží se jako prostý text.
  4. Zkouška: fb_ping ukáž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.

  1. V klientovi: “fb_agent_discover”. Vypíše místní agenty s base_url, instance_id a navrženým názvem tokenu. Tokeny nikdy nečte.
  2. Operátor uloží local_api.token agenta (ne agent.auth_token): fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Token nikdy nepište do chatu.
  3. V klientovi: “fb_agent_register pro toho agenta” → schvalte v tray. fbmcp přidá záznam agents:, znovu načte a ověří identitu.
  4. 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:

  1. fb_cluster_rcm_password: nahraďte první heslo RCM (Tier 1).
  2. 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.
  3. Služby clusteru (switchover, failover, rejoin): fb_cluster_service je 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

  1. fbmcpctl doctor --config <file>: konfigurace, tajné hodnoty, přihlášení Firebird, složky, postoj, rozvrhy. Každý řádek FAIL má Fix:.
  2. fb_db_list → fb_db_health <db>; fb_service_status pro instanci.
  3. fb_sessions, fb_transactions pro problémy s připojením nebo mezerou OAT; fb_firebird_log pro chyby enginu.

13.2 Podezření na manipulaci nebo poškození: nejdřív audit

  1. fbmcpctl verify --config <file> → audit chain OK: N entries nebo BROKEN s důvodem.
  2. 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í)

  1. fb_backup_start → fb_job_status = succeeded.
  2. fb_restore_test → záloha je ověřená.
  3. fb_window_open pro databázi.
  4. fb_restore_replace → schvalte mimo kanál. Výpadek, dokud není online.
  5. Kontrola: fb_db_health, pak skutečné čtení (fb_schema_list, fb_info).
  6. Starý soubor zůstane jako <db>.pre-restore, dokud ho nesmažete.

13.4 Klient se nemůže připojit

  1. fbmcpctl ping --config <file>, fbmcpctl status --config <file>.
  2. Přečtěte MCP protokol klienta (stdio) nebo <state_dir>\fbmcp.log / journalctl -u fbmcp (služba).
  3. “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.