Hedef kitle: fbmcp’yi kuran ve çalıştıran, onu derlememiş kişi. Go veya Firebird iç yapısı bilgisi gerekmez. Durum tarihi 2026-11-16, sürüm 2027.2.24 (yerel ve uzak kip, HQbird kurulumu, fbagent köprüsü, HQbird kümesi, sonuç ızgarası).

Kısa sürümler, bu sitede yok: quickstart-en.md, quickstart-ru.md, quickstart-pt.md. Ayrıntılar, İngilizce: remote.md (uzak kip), agent-bridge.md (fbagent), tool-reference.md (her araç, tier değeri ve argümanları), claude-desktop.md (geliştirme ana makinesinde istemci bağlantısı), ADR’ler decisions/ içinde.


1. fbmcp nedir

fbmcp, Windows ve Linux üzerinde Firebird 2.5–5.0 için bir MCP sunucusudur. Bir MCP istemcisi (Claude Desktop, Claude Code, Cursor, Codex, ZCode, diğerleri) onu bir DBA gibi çalışmak için kullanır: izleme, yedekler ve doğrulanmış geri yüklemeler, SQL/DDL/DCL, indeksler, kullanıcılar ve yetkiler, firebird.conf, bir zamanlayıcı, migrasyonlar, HQbird fbagent ve HQbird kümesi. 122 aracı vardır: 56 salt okunur (Tier 0), 44 Tier 1, 21 Tier 2, 1 Tier 3 (kapalı). fb_demo_write yalnızca sunucu FBMCP_DEMO_TOOLS=1 ile çalışırken vardır.

Bir istemci yalnızca kullanabildiği araçları görür. Araç listesi şunları gizler: Tier 3, kimliğin en yüksek tier değerinin üstündeki araçlar, salt okunur bir kimlik için fb_confirm ve fb_cancel, agents: boşken fbagent araçları (fb_agent_discover ve fb_agent_register kalır), hiçbir veritabanında migrations_dir yokken migrasyon araçları ve fbmcp.yaml bir rcm: bölümü içermezken küme araçları. Bir yapılandırma yeniden yüklemesi bu kümeyi değiştirince istemci yeni bir liste alır. Gizli bir araca doğrudan çağrı açık bir ret alır.

İkili Rol
fbmcp Sunucu. Varsayılan: stdio üzerinden MCP (bir istemci başlatır). -serve: stdio yok, hizmet olarak çalışır (zamanlayıcı, bağlanma soketi, yapılandırılmışsa HTTPS dinleyicisi). fbmcp bridge: uzak bir fbmcp için stdio istemcisi
fbmcpctl Operatör CLI: doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. fbmcp ctl ile aynı program
fbmcp-tray Windows tepsisi: operatör isteyen istekler için Onayla/Reddet açılır penceresi

Durum dizini başına bir çekirdek. Aynı yapılandırmaya sahip ikinci bir istemci ikinci bir çekirdek başlatmaz: çalışan çekirdeğe bağlanır.

2. Güvenlik modeli

Her çağrı ilkeden → insan onayından → denetimli yürütmeden geçer.

Tier Ne Nasıl onaylanır
0 Okumalar (motorun zorunlu kıldığı salt okunur işlemler) Gerekmez
1 Rutin değişiklikler: DML/DDL, yedek, kullanıcılar, yetkiler Bant içi: istemci bir istek kimliği ve bir belirteç gösterir; kişi kabul eder; istemci fb_confirm çağırır
2 Yüksek etki: hizmet denetimi, geri yükleyip değiştirme, firebird.conf, ayrıcalıklı pencere, kayıt, ajanın yeniden başlatılması Yalnızca bant dışı: tepsi veya fbmcpctl approve. İstemci bunu asla onaylayamaz
3 Kritik (fb_db_drop) Tasarım gereği kapalı
  • Tier 2 genellikle açık bir bakım penceresi (fb_window_open, aynı db üzerinde) ve 24 saatten yeni doğrulanmış bir yedek ister. Ret, neyin eksik olduğunu söyler.
  • Bekleyen bir istek 15 dakika sonra zaman aşımına uğrar. Yanlış kanaldan bir deneme onu tüketmez; fb_cancel onu kaldırır.
  • Kapıdan geçen her araç mode: preview kabul eder: etkiyi gösterir ve hiçbir şey yapmaz.
  • Her karar (izin, bekliyor, onaylandı, reddedildi) karmaya zincirlenmiş audit.jsonl dosyasına gider.
  • Onay web sayfası yoktur ve hiç olmamalıdır: modelin ulaşabildiği bir sayfa tasarımı bozar.

3. Bir düzen seçin

Düzen fbmcp nerede çalışır Ne zaman kullanılır Bölüm
A. Yerel stdio Sizin bilgisayarınız; istemci başlatır Bir yönetici, Firebird bu bilgisayarda veya LAN içinde §6
B. Yerel hizmet Veritabanı ana makinesinde Windows hizmeti (-serve) Zamanlamalar hiçbir istemci açık değilken de çalışmalı §7
C. Uzak Veritabanı sunucusunda hizmet, HTTPS + API anahtarları Birkaç yönetici, uzak bir sunucu, özerk ajanlar §8

Düzen A’da çekirdek yalnızca bir istemci çalışırken yaşar, bu yüzden zamanlamalar yalnızca o zaman tetiklenir. Gözetimsiz zamanlamalar (nightly_verify) için B veya C kullanın.

HQbird içinde fbmcp. HQbird 2027 kurulumları ve fbagent, fbmcp’yi varsayılan olarak kurar: tüm Firebird hatları için sunucu başına bir hizmet, kuran fbmcp ctl hqbird-install. Böyle bir sunucuda §6–§8 izlemeyin; hqbird.md okuyun (yerleşim, --allow-from ile uzak kip, API anahtarları).

4. İkilileri edinin

Gereksinimler: Go ≥ 1.26.11 (daha eski bir Go 1.21+ ilk derlemede go1.26.11’i kendisi indirir; bunun için internet gerekir), CGO gerekmez; Firebird 2.5–5.0; ajan araçları için Local API ile fbagent ≥ 2.67 (isteğe bağlı); küme araçları için fbagent 3.1.0+ ve RCM 2027.5.11+ (isteğe bağlı).

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 ikilileri (Windows’tan çapraz derleme veya GOOS olmadan Linux üzerinde derleme):

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

Sağlamalar: Get-FileHash dist/* veya sha256sum dist/*. Daha fazla derleme hedefi: packaging/README.md. İkilileri kendi klasörlerine koyun (örnekler C:\fbmcp\ kullanır): mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\ (Linux: install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/).

fbmcp ctl ve fbmcpctl aynı programdır. fbmcpctl help komutları listeler. Yapılandırmayı okuyan komutlar --config <file> alır; o olmadan FBMCP_CONFIG kullanır, sonra geçerli klasördeki fbmcp.yaml, sonra programın yanı, sonra HQbird varsayılanı (C:\HQbirdData\fbmcp\fbmcp.yaml, /etc/fbmcp/fbmcp.yaml) ve using config <path> yazar.

5. fbmcp.yaml dosyasını yapılandırın

Tam örnek: packaging/fbmcp.yaml.example. En küçük Windows yapılandırması:

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

Sırlar. YAML yalnızca değişken adlarını tutar. fbmcp her değeri şu sırayla arar: ortam değişkeni → <secrets.dir>/<NAME> dosyası → fbmcp’yi çalıştıran hesabın işletim sistemi anahtarlığı.

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)

Değer stdin’den okunur (yazın, sonra Ctrl+Z, Enter; Linux’ta Ctrl+D). Bir hizmet hesabı (LocalSystem, NT SERVICE\...) anahtarlığınızı göremez: hizmetler için secrets.dir kullanın. Değişen bir sır dosyası yeniden başlatmadan birkaç saniye içinde uygulanır.

Salt okunur kullanıcı. ro_user için ayrı bir Firebird kullanıcısı oluşturun (SQL: quickstart-en.md: CREATE USER FBMCP_RO, her tabloda GRANT SELECT ve Firebird 4.0+ üzerinde fb_sessions tüm bağlantıları görsün diye MONITOR_ANY_ATTACHMENT içeren bir rol). RO kullanıcı olarak SYSDBA yalnızca geliştirme içindir; doctor bu konuda uyarır.

Canlı yeniden yükleme. fbmcp, fbmcp.yaml değişikliklerini kendisi uygular (dosya izleyici) veya fb_config_reload ile. İstemci veya süreç yeniden başlatılmaz. Yeniden yükleme değişen veritabanlarındaki işleri bekler (30 s), sonra uygular. Reddedilir: bir state.dir değişikliği, yinelenen veritabanı yolları, güvensiz bir uzak yapılandırma.

Kontrol: C:\fbmcp\fbmcpctl.exe doctor doctor: green ile bitmeli (uzak kip: doctor --remote, FAIL satırı yok). Eksik durum klasörünü oluşturur, her veritabanına her iki kullanıcıyla giriş yapar ve her FAIL satırı Fix: ve çalıştırılacak komutla biter.

6. Düzen A — yerel stdio

Mutlak yollar kullanın. listen ayarlamayın. Yapılandırma değişince istemciyi yeniden başlatın: istemciler sunucuları yalnızca başlangıçta yükler.

İstemci Nerede Girdi
Claude Desktop Ayarlar → Geliştirici → Yapılandırmayı düzenle (%APPDATA%\Claude\claude_desktop_config.json) "mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}}
Claude Code komut satırı claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml"
Cursor %USERPROFILE%\.cursor\mcp.json veya projedeki .cursor\mcp.json Claude Desktop ile aynı JSON
Codex codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml veya %USERPROFILE%\.codex\config.toml [mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml']
ZCode projedeki .zcode\config.json "mcp": {"servers": {"fbmcp": { ...same command and args... }}}

Parolalar anahtarlıktadır (§5), bu yüzden env bloğu gerekmez. Yine de bir parolayı istemcinin env bloğuna koyarsanız, o dosyayı git dışında tutun.

Ardından Tier 2 onayları için tepsiyi başlatın: C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml (her oturum açılışında: .\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).

İstemcide duman testi: “çağır fb_ping” (sunucu adını ve kimliğinizi en yüksek Tier değeriyle gösterir), sonra “fb_db_list”, sonra “fb_db_health main için”.

7. Düzen B — yerel Windows hizmeti

Yükseltilmiş PowerShell:

Command
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp
  • Hizmet, fbmcp -serve komutunu LocalSystem olarak çalıştırır, arızada yeniden başlar ve hizmet durunca temiz kapanır.
  • Parolalar için secrets.dir kullanın (§5).
  • Klasörü kilitleyin: C:\fbmcp içine yalnızca SYSTEM ve Administrators yazabilir (betik icacls komutunu yazar). C:\ altında açılan bir klasör her kullanıcının dosyaları değiştirmesine izin verir ve hizmet onları SYSTEM olarak çalıştırır.
  • Tepsi kullanıcısı ve yerel stdio istemcileri durum dizininde okuma/yazma ister: icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M". Aynı yapılandırmaya sahip bir stdio istemcisi o zaman hizmet çekirdeğine bağlanır.
  • Hazırlık: C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml.
  • Günlük: <state_dir>\fbmcp.log (5 × 10 MiB; çökmeler fbmcp-crash.log içinde).

Yöneticilerin ağ üzerinden eriştiği bir hizmet için düzen C’yi kullanın.

8. Düzen C — uzak (HTTPS + API anahtarları)

Tam yordam: remote.md. Kısa biçim:

Windows sunucusu (yükseltilmiş):

  1. İkililer ve fbmcp.yaml, C:\fbmcp\ içinde (şablon: remote.md §3: listen, tls, identities, allowed_origins, secrets.dir).
  2. C:\fbmcp\fbmcpctl.exe tls selfsign --out C:\fbmcp\tls --dns srv1 --ip 10.0.0.5 --grant "NT SERVICE\fbmcp" — pin’i not edin sha256:....
  3. Kişi veya ajan başına bir anahtar: C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets (bir kez yazdırılır). --config C:\fbmcp\fbmcp.yaml ile identities: girdisini de ekler ve secrets.dir kullanır.
  4. Parolalar ve ajan belirteçleri: 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, sonra -WhatIf olmadan. Hizmeti, güvenlik duvarı kuralını, klasör ACL’lerini ve Firebird hizmet haklarını oluşturur.
  6. C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml → FAIL yok; curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz → ok.
  7. Onaylayan için tepsi: .\packaging\windows\install-tray.ps1.

Linux sunucusu (root): fbmcp, fbmcpctl ve packaging/linux/ kopyalayın, sonra

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

Betik klasörleri, sertifikayı, bir admin anahtarı olan ilk yapılandırmayı (bir kez yazdırılır), systemd birimini, Firebird birimi için sudo kuralını ve ufw kuralını oluşturur, sonra doctor --remote çalıştırır. /etc/fbmcp/fbmcp.yaml dosyasına databases: ve agents: ekleyin. Linux’ta onaylar (tepsi yok): sudo -u firebird fbmcpctl approve [id]. /etc/fbmcp/fbmcp.yaml dosyasını kendisi bulur, y/N sorar (--yes sormaz) ve --deny <id> --reason "..." reddeder.

Yönetici bilgisayarı:

  1. C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1 (aldığınız anahtar).
  2. Herhangi bir stdio istemcisi (Claude Desktop, Cursor, Codex, ZCode): §6 girdisi, şu args ile: ["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. Pin sunucu anahtarını denetler, bu yüzden kendinden imzalı bir sertifika CA kurulumu istemez.
  3. Claude Code doğrudan HTTP üzerinden de bağlanabilir (.mcp.json "type": "http", başlık Authorization: Bearer ${FBMCP_KEY_SRV1}, kendinden imzalı bir sertifika için NODE_EXTRA_CA_CERTS). Anahtarı claude mcp add --header ile geçirmeyin: düz metin olarak saklanır.
  4. Deneme: fb_ping sunucu adını ve kimliğinizi gösterir.

Özerk ajanlar (OpenClaw ve benzerleri): ayrı bir anahtar, apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32. Varsayılan olarak salt okunur; her Tier 1 isteği bir operatörü bekler ve ajandan gelen fb_confirm reddedilir. Sınırlar: remote.md §6–7.

9. fbagent köprüsü ve HQbird kümesi (isteğe bağlı)

Ajan araçları (fb_agent_status, fb_agent_job_run, …) aynı ana makinedeki HQbird fbagent Local API kullanır. agents: bir girdi içerene kadar kapalıdır.

  1. İstemcide: “fb_agent_discover”. Yerel ajanları base_url, instance_id ve önerilen belirteç adıyla listeler. Belirteçleri hiç okumaz.
  2. Operatör, ajanın local_api.token değerini saklar (agent.auth_token değil): fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Bir belirteci asla sohbete yazmayın.
  3. İstemcide: “fb_agent_register o ajan için” → tepside onaylayın. fbmcp agents: girdisini ekler, yeniden yükler ve kimliği denetler.
  4. Deneme: fb_agent_status, fb_agent_instances.

fb_agent_config_set (iş ayarlarını değiştirme: yedek, sweep, …) girdide config_path ve canlı agent_config.json için okuma erişimi, artı klasöründe oluşturma hakkı da ister. Bu dosya belirteci ve Firebird kimlik bilgilerini tutar, bu yüzden bu yetki operatörün kararıdır (agent-bridge.md). Ajan denetimi başarısız olursa araç hiçbir şey yazmaz.

HQbird kümesi (RCM). Küme araçları aynı ana makinedeki HQbird küme yöneticisini (hqbirdrcm) çağırır. Yalnızca fbmcp.yaml bir rcm: bölümü içerdiğinde gösterilir (url, ca_file, user, password_env). Bir Linux HQbird sunucusunda fbmcp ctl hqbird-install bölümü /opt/hqbirdrcm/rcm.json dosyasından yazar ve ilk RCM parolasını FBMCP_RCM_PASSWORD sırrında saklar; başka yerde bölümü elle ekleyin (tool-reference.md). Sonra:

  1. fb_cluster_rcm_password: ilk RCM parolasını değiştirin (Tier 1).
  2. Yeni bir küme: her ana makinede eşleştirme penceresini açın (fb_agent_cluster_pairing), master üzerinde RCM’yi başlatın (fb_agent_cluster_rcm), ana makineleri bağlayın (fb_cluster_link), replikaları oluşturun (fb_cluster_reinit, Tier 2) ve veriyi karşılaştırın (fb_cluster_verify). Adımlar: prompts/cluster-setup.md.
  3. Küme hizmetleri (switchover, failover, rejoin): fb_cluster_service onları ve denetimleri gösterir; taşımalar Tier 2’dir. Adımlar: prompts/cluster-services.md.

10. Günlük kullanım

İstemciye düz sözcüklerle sorun; araçları o seçer. Örnekler:

Görev Araçlar
Her şey ayakta mı? fb_ping, fb_db_list, fb_db_health, fb_service_status
Veri okuma fb_query (salt okunur, satırlar + plan + tablo başına istatistik; MCP-Apps istemcilerinde bir ızgara); taslağı fb_query_check ile denetleyin
Oturumlar, uzun işlemler fb_sessions, fb_transactions, fb_session_kill (Tier 1)
Yavaş sorgu fb_analyze_query, fb_index_advice → fb_write ile uygulayın; fb_agent_perf_report
Yedek fb_backup_start → iş kimliği → fb_job_status
Bir yedeği doğrulama fb_restore_test (work_dir içine geri yükler, yedeği doğrulanmış işaretler)
Gece yedeği + doğrulama fb_schedule_create ile target=nightly_verify (bir kez onaylanır; düzen B veya C)
Şema / DDL fb_schema_list, fb_describe, fb_write (her deyim sınıflanır ve tier alır), fb_diff_schema
Migrasyonlar fb_migration_status, fb_migration_plan, fb_migration_apply
Sunucu yapılandırması fb_config_get, fb_config_diff, fb_config_set (Tier 2)
Günlükler fb_firebird_log
Kapasite fb_trends, fb_gstat, fb_index_stats
Küme durumu fb_cluster_status, fb_cluster_service
Master’ı taşıma fb_cluster_switchover (veri kaybı yok) veya fb_cluster_failover (master kayıp), sonra fb_cluster_rejoin (Tier 2)

İşler asenkrondur: gönderin → fb_job_status. Bir veritabanındaki işler teker teker çalışır. Bir iş, fbmcp yeniden başlasa yalnızca interrupted olarak kalır: hâlâ gerekiyorsa yeniden gönderin.

fb_config_set yalnızca firebird.conf içindeki kendi satırını değiştirir (yorumlar, girinti ve satır sonları kalır), eski dosyayı firebird.conf.prev olarak saklar ve Firebird’ü hiç yeniden başlatmaz. fb_service_restart ile yeniden başlatın (Tier 2): hizmet durup yeniden çalışana kadar bekler.

11. Operatör görevleri

Görev Komut
İstekleri listele / onayla / reddet fbmcpctl approve; fbmcpctl approve <id>; fbmcpctl approve --deny <id> --reason "..." (veya tepsi)
Bir anahtarı döndürme fbmcpctl apikey rotate alice --config <fbmcp.yaml> (eski anahtar saniyeler içinde durur)
Anahtarları listele fbmcpctl apikey list (adlar, kaynaklar, tier değerleri; asla değerler)
Bir kişiyi kaldırma identities: girdisini silin, sonra fbmcpctl secret drop --dir <dir> NAME
Sertifikayı yenileme fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ... (pin değişmez, yeniden başlatma yok)
Denetim zincirini denetle fbmcpctl verify
Çekirdek canlı mı? fbmcpctl ping; fbmcpctl status (durumun çevrimdışı okuması)
Hizmet denetimine izin ver packaging/posture/verify.ps1 veya verify.sh, sonra fbmcpctl setup --write-posture
Yükseltme hizmeti (veya istemcileri) durdurun, ikilileri değiştirin, başlatın, doctor
Kaldırma Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux: remote.md §10. Sahibi başka demedikçe durum dizinini (denetim) saklayın

Yalnızca geliştirme ana makinesi: .\packaging\rebuild-install.ps1 -Force dist\ klasörünü yeniden derler, çalışan ikilileri durdurup değiştirir (eskiler *.exe~ olarak kalır), istemci yapılandırmalarını birleştirir ve doctor çalıştırır.

12. Çökme ve yeniden başlatmadan kurtarma

Kaos koşumu tarafından doğrulanmıştır (internal/killharness).

Çökme veya sonlandırma sonrası Yeniden başlamada Operatör eylemi
İş çalışıyordu veya kuyruktaydı interrupted işaretlenir; hiç sürdürülmez Gerekirse yeniden gönderin
Bekleyen istek, onaylanmamış state.json dosyasından geri yüklenir (TTL hâlâ geçerlidir) Onaylayın veya süresinin dolmasına bırakın
fb_restore_replace sürüyor Bitirir: geri yükleme, doğrulama, veritabanı çevrimiçi; <db>.pre-restore saklanır fb_db_health denetleyin; .pre-restore dosyasını sonra silin
fb_shutdown_window sürüyor gfix -online adımını bitirir Çevrimiçi olduğunu denetleyin
Bayat instance.lock Otomatik devralınır Yok
state.json bozuk Çekirdek başlamayı reddeder; kopya state.json.corrupt-<ts> olarak saklanır İnceleyin; onarın veya state.json dosyasını bilerek kaldırın (fbmcpctl repair zamanlama yetkilerini denetimden yeniden kurar)
audit.jsonl bozuk veya kesik Çekirdek başlamayı reddeder §13.2: bunu bir kurcalama işareti sayın
Saat geri alındı Zamanlayıcı atlar; çift çalıştırma olmaz Yok
Windows hizmet süreci sonlandırıldı SCM onu yaklaşık 5 s içinde yeniden başlatır Yok

Çekirdek, sağlam olduğunu kanıtlayamadığı her şeyde kapalı kalır. Yeniden başlatma döngüsü bir bulgudur: günlüğü okuyun.

13. Olay prosedürleri

13.1 Bir veritabanında bir şey yanlış

  1. fbmcpctl doctor --config <file>: yapılandırma, sırlar, Firebird oturum açmaları, klasörler, posture, zamanlamalar. Her FAIL satırında bir Fix: vardır.
  2. fb_db_list → fb_db_health <db>; instance için fb_service_status.
  3. Bağlantı veya OAT aralığı sorunları için fb_sessions, fb_transactions; motor hataları için fb_firebird_log.

13.2 Kurcalama veya bozulma kuşkusu: önce denetim

  1. fbmcpctl verify --config <file> → audit chain OK: N entries veya gerekçeli BROKEN.
  2. Başarısız olursa: bütün durum dizinini saklayın (kanıttır), sonra araştırın. Çekirdeğin başlaması için audit.jsonl dosyasını silmeyin.

13.3 Geri yükleme tatbikatı (her çeyrek)

  1. fb_backup_start → fb_job_status = succeeded.
  2. fb_restore_test → yedek doğrulanmıştır.
  3. Veritabanı için fb_window_open.
  4. fb_restore_replace → bant dışında onaylayın. Çevrimiçi olana kadar kesinti.
  5. Denetim: fb_db_health, sonra gerçek bir okuma (fb_schema_list, fb_info).
  6. Eski dosya, siz silene kadar <db>.pre-restore olarak kalır.

13.4 İstemci bağlanamıyor

  1. fbmcpctl ping --config <file>, fbmcpctl status --config <file>.
  2. İstemcinin MCP günlüğünü (stdio) veya <state_dir>\fbmcp.log / journalctl -u fbmcp (hizmet) okuyun.
  3. “another fbmcp instance is active”: durum dizini başına bir çekirdek. Borulu istemciler kendiliğinden bağlanır; ikinci bir çekirdek tasarım gereği hemen başarısız olur.

Yukarıdaki komutlarda, §4 araması dosyayı bulduğunda --config atlanabilir.

14. Sorun giderme

Belirti Anlam / düzeltme
Araçlar görünmüyor JSON sözdizimi, mutlak yollar, istemcinin tam yeniden başlatılması; istemcinin MCP günlüğü
Listede bir araç yok Bilerek gizli (§1): en yüksek tier değerinizin üstünde, agents: girdisi yok, migrations_dir yok veya rcm: bölümü yok
Sunucu hemen çıkar fbmcpctl doctor; eksik bir sır; bir hizmet anahtarlığınızı okuyamaz (secrets.dir kullanın)
Tier 2 “confirmation rejected: channel policy” Sohbette beklenen durum. Tepside veya fbmcpctl approve ile onaylayın
Tier 2 “no open maintenance window” Araca verdiğiniz aynı db için fb_window_open
fb_restore_replace reddedildi: ön koşullar 24 saatten yeni doğrulanmış bir yedek gerekir: fb_backup_start + fb_restore_test ve bir pencere
Hizmet denetimi reddedildi posture.verified eksik (fbmcpctl setup --write-posture) veya hesabın Firebird hizmetinde hakkı yok
fb_config_set: yazılamıyor Hesap o dosyayı değiştiremeyebilir (Linux birimi ProtectSystem=strict; Windows ACL). Elle düzenleyin veya remote.md §8 bakın
Tepsi hiçbir şey göstermiyor Yalnızca operatör isteyen istekleri gösterir; tepsi kullanıcısının durum dizinindeki haklarını ve oradaki tray.log dosyasını denetleyin
401 (uzak) Yanlış anahtar veya sunucu onu yüklemedi: apikey list, doctor --remote
403 (uzak) Kaynak IP allow_from / güvenlik duvarında değil veya bir Origin başlığı allowed_origins içinde değil
429 (uzak) Sınırlar; Retry-After için bekleyin
Pin uyuşmuyor Sunucu anahtarı değişti; yeni pin’i sunucu yöneticisinden alın
agent-unreachable Ajan hizmeti kapalı, local_api.enabled: false veya yanlış base_url (varsayılan 127.0.0.1:(10000 + firebird port))
agent-auth Saklanan belirteç ajanın local_api.token değeri değil; yeniden ayarlayın
Yeniden başlatmalarda agent-timeout agents[].timeout_seconds (130), ajanın restart_timeout_seconds değerinden (120) büyük olmalı
Bağlanırken Error loading plugin MySQLEngine … HQbird üzerinde bu genellikle veritabanı dosyasının var olmadığı anlamına gelir; yolu denetleyin
fb_write içinde çıplak DROP INDEX bir pencere ister Orada Tier 2’dir; fb_index_drop kullanın (Tier 1; kısıt indekslerini reddeder)
Yeni indeks kullanılmıyor İstatistikleri çalıştırın (fb_index_rebuild action=statistics); ORDER BY … DESC bir DESCENDING indeks ister
Araçlar yalnızca bir veritabanı için başarısız Çevrimdışıdır (fb_db_health); araçlar veritabanı başına geriler

15. Durum dizini başvurusu

Yol Anlam
state.json (+ .tmp, .corrupt-*) Bekleyen istekler, işler, yedek kataloğu, iş akışları, zamanlamalar. Bozuk ⇒ başlamayı reddeder
audit.jsonl (+ .head) Karmaya zincirlenmiş denetim günlüğü; .head kesilmeyi saptar
events.jsonl İş olayları (job.succeeded, job.failed iletiyle)
approvals\, denials\ Bant dışı kararlar (tepsi / fbmcpctl approve), ~2 s içinde kullanılır
instance.lock Tek çekirdek kilidi
attach.addr, attach.token Ek stdio istemcileri için bağlanma uç noktası
fbmcp.log, fbmcp-crash.log Hizmet günlüğü (döndürülür) ve çökme çıktısı
query-log.jsonl Her fb_query çağrısı
trends\ fb_trends için örnekleyici geçmişi
config-journal\ fb_config_set geçmişi (eski ve yeni değer)
posture.verified Hizmet denetimine izin veren işaret
tray.log Tepsi hataları

16. Adım adım deneme durumu

Beklemede (M1): yalnızca bu kılavuzla temiz bir Windows ana makinesinde adım adım geçiş. Bulgular bu dosyaya geri yazılır. Uzak kip için laboratuvar sonuçları (Linux ana makinesi, temiz VM, Windows hizmeti): findings/phase12-lab-2026-11-03.md.