fbmcp: kurulum ve kullanım
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_cancelonu kaldırır. - Kapıdan geçen her araç
mode: previewkabul eder: etkiyi gösterir ve hiçbir şey yapmaz. - Her karar (izin, bekliyor, onaylandı, reddedildi)
karmaya zincirlenmiş
audit.jsonldosyası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ı).
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 ikilileri (Windows’tan çapraz derleme veya GOOS olmadan Linux üzerinde derleme):
$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/fbmcpctlSağ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ı:
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 backupsSı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ığı.
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:
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp- Hizmet,
fbmcp -servekomutunu LocalSystem olarak çalıştırır, arızada yeniden başlar ve hizmet durunca temiz kapanır. - Parolalar için
secrets.dirkullanın (§5). - Klasörü kilitleyin:
C:\fbmcpiçine yalnızca SYSTEM ve Administrators yazabilir (betikicaclskomutunu 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; çökmelerfbmcp-crash.logiç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ş):
- İkililer ve
fbmcp.yaml,C:\fbmcp\içinde (şablon: 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"— pin’i not edinsha256:....- 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.yamlileidentities:girdisini de ekler vesecrets.dirkullanır. - Parolalar ve ajan belirteçleri:
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, sonra-WhatIfolmadan. Hizmeti, güvenlik duvarı kuralını, klasör ACL’lerini ve Firebird hizmet haklarını oluşturur.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.- Onaylayan için tepsi:
.\packaging\windows\install-tray.ps1.
Linux sunucusu (root): fbmcp, fbmcpctl ve packaging/linux/ kopyalayın, sonra
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/24Betik 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ı:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(aldığınız anahtar).- Herhangi bir stdio istemcisi (Claude Desktop, Cursor, Codex, ZCode): §6 girdisi,
şu
argsile:["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. - Claude Code doğrudan HTTP üzerinden de bağlanabilir (
.mcp.json"type": "http", başlıkAuthorization: Bearer ${FBMCP_KEY_SRV1}, kendinden imzalı bir sertifika içinNODE_EXTRA_CA_CERTS). Anahtarıclaude mcp add --headerile geçirmeyin: düz metin olarak saklanır. - Deneme:
fb_pingsunucu 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.
- İstemcide: “
fb_agent_discover”. Yerel ajanlarıbase_url,instance_idve önerilen belirteç adıyla listeler. Belirteçleri hiç okumaz. - Operatör, ajanın
local_api.tokendeğerini saklar (agent.auth_tokendeğil):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Bir belirteci asla sohbete yazmayın. - İstemcide: “
fb_agent_registero ajan için” → tepside onaylayın. fbmcpagents:girdisini ekler, yeniden yükler ve kimliği denetler. - 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:
fb_cluster_rcm_password: ilk RCM parolasını değiştirin (Tier 1).- 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. - Küme hizmetleri (switchover, failover, rejoin):
fb_cluster_serviceonları 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ış
fbmcpctl doctor --config <file>: yapılandırma, sırlar, Firebird oturum açmaları, klasörler, posture, zamanlamalar. Her FAIL satırında birFix:vardır.fb_db_list→fb_db_health <db>; instance içinfb_service_status.- Bağlantı veya OAT aralığı sorunları için
fb_sessions,fb_transactions; motor hataları içinfb_firebird_log.
13.2 Kurcalama veya bozulma kuşkusu: önce denetim
fbmcpctl verify --config <file>→audit chain OK: N entriesveya gerekçeliBROKEN.- 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.jsonldosyasını silmeyin.
13.3 Geri yükleme tatbikatı (her çeyrek)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ yedek doğrulanmıştır.- Veritabanı için
fb_window_open. fb_restore_replace→ bant dışında onaylayın. Çevrimiçi olana kadar kesinti.- Denetim:
fb_db_health, sonra gerçek bir okuma (fb_schema_list,fb_info). - Eski dosya, siz silene kadar
<db>.pre-restoreolarak kalır.
13.4 İstemci bağlanamıyor
fbmcpctl ping --config <file>,fbmcpctl status --config <file>.- İstemcinin MCP günlüğünü (stdio) veya
<state_dir>\fbmcp.log/journalctl -u fbmcp(hizmet) okuyun. - “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.