fbmcp : installation et utilisation
Public : la personne qui installe et fait tourner fbmcp, et qui ne l’a pas construit. Aucune connaissance des internes de Go ou de Firebird n’est nécessaire. État au 2026-11-16, version 2027.2.24 (mode local et distant, installation HQbird, pont fbagent, cluster HQbird, grille de résultats).
Versions courtes, absentes de ce site : quickstart-en.md, quickstart-ru.md,
quickstart-pt.md. Détails, en anglais : remote.md (mode
distant), agent-bridge.md (fbagent),
tool-reference.md (chaque outil, son Tier et ses arguments),
claude-desktop.md (branchement du client sur l’hôte de développement),
ADR dans decisions/.
1. Qu’est-ce que fbmcp
fbmcp est un serveur MCP pour Firebird 2.5–5.0 sous Windows et Linux. Un
client MCP (Claude Desktop, Claude Code, Cursor, Codex, ZCode, d’autres) s’en
sert pour travailler comme un DBA : surveillance, sauvegardes et restaurations
vérifiées, SQL/DDL/DCL, index, utilisateurs et droits, firebird.conf, un
planificateur, des migrations, le fbagent HQbird et le cluster HQbird. Il
compte 122 outils : 56 en lecture seule (Tier 0), 44 Tier 1, 21 Tier 2,
1 Tier 3 (désactivé). fb_demo_write n’est présent que lorsque le serveur
tourne avec FBMCP_DEMO_TOOLS=1.
Un client ne voit que les outils qu’il peut utiliser. La liste des outils
masque : le Tier 3, les outils au-dessus du Tier maximal de l’identité,
fb_confirm et fb_cancel pour une identité en lecture seule, les outils
fbagent tant que agents: est vide (fb_agent_discover et
fb_agent_register restent), les outils de migration tant qu’aucune base
n’a migrations_dir, et les outils de cluster tant que fbmcp.yaml n’a pas
de section rcm:. Quand un rechargement de la config change cet ensemble, le
client reçoit une nouvelle liste. Un appel direct à un outil masqué reçoit un
refus clair.
| Binaire | Rôle |
|---|---|
fbmcp |
Le serveur. Par défaut : MCP sur stdio (un client le démarre). -serve : pas de stdio, tourne comme un service (planificateur, socket d’attache, écouteur HTTPS s’il est configuré). fbmcp bridge : un client stdio pour un fbmcp distant |
fbmcpctl |
CLI de l’opérateur : doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. Même programme que fbmcp ctl |
fbmcp-tray |
Zone de notification Windows : fenêtre Approve/Deny pour les demandes qui exigent un opérateur |
Un noyau par répertoire d’état. Un second client avec la même config ne démarre pas un second noyau : il s’attache à celui qui tourne.
2. Modèle de sécurité
Chaque appel passe par politique → confirmation humaine → exécution auditée.
| Tier | Quoi | Comment c’est confirmé |
|---|---|---|
| 0 | Lectures (transactions en lecture seule imposées par le moteur) | Pas nécessaire |
| 1 | Changements courants : DML/DDL, sauvegarde, utilisateurs, droits | Dans le canal : le client montre un id de demande et un jeton ; la personne accepte ; le client appelle fb_confirm |
| 2 | Fort impact : contrôle du service, restauration-remplacement, firebird.conf, fenêtre exclusive, enregistrement, redémarrages d’agent |
Hors canal uniquement : la zone de notification ou fbmcpctl approve. Le client ne peut jamais l’approuver |
| 3 | Critique (fb_db_drop) |
Désactivé par conception |
- Le Tier 2 a en général besoin d’une fenêtre de maintenance ouverte (
fb_window_open, sur la mêmedb) et d’une sauvegarde vérifiée de moins de 24 heures. Le refus dit ce qui manque. - Une demande en attente expire au bout de 15 minutes. Une tentative sur le mauvais canal ne la consomme pas ;
fb_cancella retire. - Chaque outil gardé accepte
mode: preview: il montre l’impact et ne fait rien. - Chaque décision (autorisation, en attente, approuvée, refusée) va dans
audit.jsonl, chaîné par hachage. - Il n’y a pas de page web d’approbation, et il ne doit jamais y en avoir : une page que le modèle peut atteindre casserait la conception.
3. Choisir une installation
| Installation | Où fbmcp tourne | À utiliser quand | Section |
|---|---|---|---|
| A. Stdio local | Votre PC ; le client le démarre | Un administrateur, Firebird sur ce PC ou dans le LAN | §6 |
| B. Service local | Service Windows sur l’hôte de la base (-serve) |
Les planifications doivent tourner sans client ouvert | §7 |
| C. Distant | Service sur le serveur de bases, HTTPS + clés d’API | Plusieurs administrateurs, un serveur éloigné, des agents autonomes | §8 |
Dans l’installation A, le noyau ne vit que pendant qu’un client tourne, donc
les planifications ne se déclenchent qu’alors. Utilisez B ou C pour les
planifications sans surveillance (nightly_verify).
fbmcp dans HQbird. Les installations HQbird 2027 et fbagent installent
fbmcp par défaut : un service par serveur pour toutes les lignes Firebird,
mis en place par fbmcp ctl hqbird-install. Sur un tel serveur, ne suivez
pas §6–§8 ; lisez hqbird.md (disposition, mode distant avec --allow-from,
clés d’API).
4. Obtenir les binaires
Prérequis : Go ≥ 1.26.11 (un Go plus ancien, 1.21 ou ultérieur, télécharge go1.26.11 de lui-même à la première compilation ; cela exige Internet), CGO n’est pas nécessaire ; Firebird 2.5–5.0 ; fbagent ≥ 2.67 avec la Local API pour les outils d’agent (facultatif) ; fbagent 3.1.0+ et RCM 2027.5.11+ pour les outils de cluster (facultatif).
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-trayBinaires Linux (compilation croisée depuis Windows, ou compilation sur Linux
sans 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/fbmcpctlSommes de contrôle : Get-FileHash dist/* ou sha256sum dist/*. Autres
cibles : packaging/README.md. Placez les binaires dans un dossier à eux
(les exemples utilisent C:\fbmcp\) : mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\
(Linux : install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/).
fbmcp ctl et fbmcpctl sont le même programme. fbmcpctl help liste les
commandes. Les commandes qui lisent la config prennent --config <file> ;
sans cela, elles utilisent FBMCP_CONFIG, puis fbmcp.yaml dans le dossier
courant, puis à côté du programme, puis le défaut HQbird
(C:\HQbirdData\fbmcp\fbmcp.yaml, /etc/fbmcp/fbmcp.yaml), et affichent
using config <path>.
5. Configurer fbmcp.yaml
Exemple complet : packaging/fbmcp.yaml.example.
Configuration Windows minimale :
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 backupsSecrets. Le YAML ne contient que les noms de variables. fbmcp cherche
chaque valeur dans cet ordre : variable d’environnement → fichier
<secrets.dir>/<NAME> → trousseau de l’OS du compte qui fait tourner fbmcp.
C:\fbmcp\fbmcpctl.exe secret set FBMCP_MAIN_RO_PW # keyring of the current user (setup A)
C:\fbmcp\fbmcpctl.exe secret set --dir C:\ProgramData\fbmcp\secrets FBMCP_MAIN_RO_PW # secrets dir (setups B, C)La valeur est lue sur stdin (tapez-la, puis Ctrl+Z, Entrée ; Linux Ctrl+D).
Un compte de service (LocalSystem, NT SERVICE\...) ne voit pas votre
trousseau : utilisez secrets.dir pour les services. Un fichier de secret
modifié s’applique en quelques secondes, sans redémarrage.
Utilisateur en lecture seule. Créez un utilisateur Firebird distinct pour
ro_user (SQL : quickstart-en.md :
CREATE USER FBMCP_RO, GRANT SELECT sur chaque table, et sur Firebird 4.0+
un rôle avec MONITOR_ANY_ATTACHMENT pour que fb_sessions voie toutes les
connexions). SYSDBA comme utilisateur RO est réservé au développement ;
doctor avertit à ce sujet.
Rechargement à chaud. fbmcp applique seul les changements de fbmcp.yaml
(surveillance du fichier), ou sur fb_config_reload. Aucun redémarrage de
client ou de processus. Un rechargement attend les travaux sur les bases
modifiées (30 s), puis applique. Refusé : un changement de state.dir, des
chemins de base en double, une config distante non sûre.
Contrôle : C:\fbmcp\fbmcpctl.exe doctor doit se terminer par
doctor: green (mode distant : doctor --remote, aucune ligne FAIL). Il
crée le dossier d’état manquant, se connecte à chaque base avec les deux
utilisateurs, et chaque ligne FAIL se termine par Fix: et la commande à
lancer.
6. Installation A — stdio local
Utilisez des chemins absolus. Ne définissez pas listen. Redémarrez le
client après un changement de config : les clients ne chargent les serveurs
qu’au démarrage.
| Client | Où | Entrée |
|---|---|---|
| Claude Desktop | Paramètres → Développeur → Modifier la config (%APPDATA%\Claude\claude_desktop_config.json) |
"mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}} |
| Claude Code | ligne de commande | claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml" |
| Cursor | %USERPROFILE%\.cursor\mcp.json ou .cursor\mcp.json dans le projet |
le même JSON que Claude Desktop |
| Codex | codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml ou %USERPROFILE%\.codex\config.toml |
[mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml'] |
| ZCode | .zcode\config.json dans le projet |
"mcp": {"servers": {"fbmcp": { ...same command and args... }}} |
Les mots de passe sont dans le trousseau (§5), donc aucun bloc env n’est
nécessaire. Si vous mettez malgré tout un mot de passe dans un bloc env du
client, gardez ce fichier hors de git.
Puis démarrez la zone de notification pour les approbations Tier 2 :
C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml (à chaque ouverture de session :
.\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).
Essai rapide dans le client : “appelez fb_ping” (affiche le nom du serveur
et votre identité avec son Tier maximal), puis “fb_db_list”, puis
“fb_db_health pour main”.
7. Installation B — service Windows local
PowerShell élevé :
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp- Le service exécute
fbmcp -serveen tant que LocalSystem, redémarre en cas d’échec, et s’arrête proprement à l’arrêt du service. - Utilisez
secrets.dirpour les mots de passe (§5). - Verrouillez le dossier : seuls SYSTEM et Administrators peuvent écrire dans
C:\fbmcp(le script affiche la commandeicacls). Un dossier créé sousC:\laisse chaque utilisateur modifier les fichiers, et le service les exécute en tant que SYSTEM. - L’utilisateur de la zone de notification et les clients stdio locaux ont besoin de lecture/écriture sur le répertoire d’état :
icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M". Un client stdio avec la même config s’attache alors au noyau du service. - Disponibilité :
C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml. - Journal :
<state_dir>\fbmcp.log(5 × 10 MiB ; plantages dansfbmcp-crash.log).
Pour un service que les administrateurs joignent par le réseau, utilisez l’installation C.
8. Installation C — distant (HTTPS + clés d’API)
Procédure complète : remote.md. Forme courte :
Serveur Windows (élevé) :
- Binaires et
fbmcp.yamldansC:\fbmcp\(modèle : 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"— notez le pinsha256:....- Une clé par personne ou par agent :
C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets(affichée une seule fois). Avec--config C:\fbmcp\fbmcp.yaml, il ajoute aussi l’entréeidentities:et utilisesecrets.dir. - Mots de passe et jetons d’agent :
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, puis sans-WhatIf. Il crée le service, la règle de pare-feu, les ACL des dossiers et les droits du service Firebird.C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml→ pas de FAIL ;curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz→ok.- Zone de notification pour l’approbateur :
.\packaging\windows\install-tray.ps1.
Serveur Linux (root) : copiez fbmcp, fbmcpctl et packaging/linux/, puis
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/24Le script crée les dossiers, le certificat, une première config avec une clé
admin (affichée une seule fois), l’unité systemd, la règle sudo pour
l’unité Firebird et la règle ufw, puis lance doctor --remote. Ajoutez
databases: et agents: à /etc/fbmcp/fbmcp.yaml. Approbations sous Linux
(pas de zone de notification) : sudo -u firebird fbmcpctl approve [id]. Il
trouve /etc/fbmcp/fbmcp.yaml tout seul, demande y/N (--yes ne demande
pas), et --deny <id> --reason "..." refuse.
PC administrateur :
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(la clé que vous avez reçue).- N’importe quel client stdio (Claude Desktop, Cursor, Codex, ZCode) : l’entrée du §6 avec ces
args:["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. Le pin vérifie la clé du serveur, donc un certificat auto-signé n’a pas besoin d’une mise en place d’AC. - Claude Code peut aussi se connecter directement en HTTP (
.mcp.json"type": "http", en-têteAuthorization: Bearer ${FBMCP_KEY_SRV1},NODE_EXTRA_CA_CERTSpour un certificat auto-signé). Ne passez pas la clé avecclaude mcp add --header: elle est stockée en clair. - Test :
fb_pingaffiche le nom du serveur et votre identité.
Agents autonomes (OpenClaw et similaires) : une clé distincte avec
apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32.
Lecture seule par défaut ; chaque demande Tier 1 attend un opérateur, et
fb_confirm venant de l’agent est refusé. Limites : remote.md §6–7.
9. Pont fbagent et cluster HQbird (facultatif)
Les outils d’agent (fb_agent_status, fb_agent_job_run, …) utilisent la
Local API fbagent de HQbird sur le même hôte.
Ils restent coupés tant que agents: n’a pas d’entrée.
- Dans le client : “
fb_agent_discover”. Il liste les agents locaux avecbase_url,instance_idet le nom de jeton suggéré. Il ne lit jamais les jetons. - L’opérateur enregistre le
local_api.tokende l’agent (pasagent.auth_token) :fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Ne tapez jamais un jeton dans le chat. - Dans le client : “
fb_agent_registerpour cet agent” → approuvez dans la zone de notification. fbmcp ajoute l’entréeagents:, recharge et vérifie l’identité. - Test :
fb_agent_status,fb_agent_instances.
fb_agent_config_set (changer les réglages des travaux : sauvegarde, sweep, …) a aussi besoin de config_path sur l’entrée, d’un accès en lecture au agent_config.json actif, et du droit de créer dans son dossier. Ce fichier contient le jeton et les identifiants Firebird, donc cet octroi est la décision de l’opérateur (agent-bridge.md). Quand le contrôle de l’agent échoue, l’outil n’écrit rien.
Cluster HQbird (RCM). Les outils de cluster appellent le gestionnaire de cluster HQbird (hqbirdrcm) sur le même hôte. Ils ne s’affichent que lorsque fbmcp.yaml a une section rcm: (url, ca_file, user, password_env). Sur un serveur HQbird Linux, fbmcp ctl hqbird-install l’écrit à partir de /opt/hqbirdrcm/rcm.json et range le premier mot de passe RCM dans le secret FBMCP_RCM_PASSWORD ; ailleurs, ajoutez la section à la main (tool-reference.md). Puis :
fb_cluster_rcm_password: remplacer le premier mot de passe RCM (Tier 1).- Un nouveau cluster : ouvrez la fenêtre d’appairage sur chaque hôte (
fb_agent_cluster_pairing), démarrez le RCM sur le maître (fb_agent_cluster_rcm), reliez les hôtes (fb_cluster_link), créez les réplicas (fb_cluster_reinit, Tier 2) et comparez les données (fb_cluster_verify). Étapes :prompts/cluster-setup.md. - Services du cluster (switchover, failover, rejoin) :
fb_cluster_serviceles affiche ainsi que les contrôles ; les déplacements sont Tier 2. Étapes :prompts/cluster-services.md.
10. Usage quotidien
Demandez au client en langage courant ; il choisit les outils. Exemples :
| Tâche | Outils |
|---|---|
| Tout fonctionne-t-il ? | fb_ping, fb_db_list, fb_db_health, fb_service_status |
| Lire des données | fb_query (lecture seule, lignes + plan + statistiques par table ; une grille dans les clients MCP-Apps) ; vérifier un brouillon avec fb_query_check |
| Sessions, transactions longues | fb_sessions, fb_transactions, fb_session_kill (Tier 1) |
| Requête lente | fb_analyze_query, fb_index_advice → appliquer avec fb_write ; fb_agent_perf_report |
| Sauvegarde | fb_backup_start → id de travail → fb_job_status |
| Vérifier une sauvegarde | fb_restore_test (restaure dans work_dir, marque la sauvegarde comme vérifiée) |
| Sauvegarde de nuit + vérification | fb_schedule_create avec target=nightly_verify (confirmé une fois ; installation B ou C) |
| Schéma / DDL | fb_schema_list, fb_describe, fb_write (chaque instruction est classée et affectée à un Tier), fb_diff_schema |
| Migrations | fb_migration_status, fb_migration_plan, fb_migration_apply |
| Config du serveur | fb_config_get, fb_config_diff, fb_config_set (Tier 2) |
| Journaux | fb_firebird_log |
| Capacité | fb_trends, fb_gstat, fb_index_stats |
| État du cluster | fb_cluster_status, fb_cluster_service |
| Déplacer le maître | fb_cluster_switchover (sans perte de données) ou fb_cluster_failover (maître perdu), puis fb_cluster_rejoin (Tier 2) |
Les travaux sont asynchrones : soumettre → fb_job_status. Les travaux sur
une même base s’exécutent un par un. Un travail ne survit à un redémarrage
de fbmcp que comme interrupted : soumettez-le à nouveau s’il est encore
nécessaire.
fb_config_set ne change que sa propre ligne dans firebird.conf (les
commentaires, l’indentation et les fins de ligne restent), garde l’ancien
fichier sous firebird.conf.prev, et ne redémarre jamais Firebird.
Redémarrez avec fb_service_restart (Tier 2) : il attend que le service
soit arrêté, puis de nouveau en marche.
11. Tâches de l’opérateur
| Tâche | Commande |
|---|---|
| Lister / approuver / refuser les demandes | fbmcpctl approve ; fbmcpctl approve <id> ; fbmcpctl approve --deny <id> --reason "..." (ou la zone de notification) |
| Faire tourner une clé | fbmcpctl apikey rotate alice --config <fbmcp.yaml> (l’ancienne clé s’arrête en quelques secondes) |
| Lister les clés | fbmcpctl apikey list (noms, sources, Tier ; jamais les valeurs) |
| Retirer une personne | supprimez l’entrée identities:, puis fbmcpctl secret drop --dir <dir> NAME |
| Renouveler le certificat | fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ... (pin inchangé, pas de redémarrage) |
| Vérifier la chaîne d’audit | fbmcpctl verify |
| Le noyau est-il vivant ? | fbmcpctl ping ; fbmcpctl status (lecture hors ligne de l’état) |
| Autoriser le contrôle du service | packaging/posture/verify.ps1 ou verify.sh, puis fbmcpctl setup --write-posture |
| Mise à niveau | arrêtez le service (ou les clients), remplacez les binaires, démarrez, doctor |
| Retirer | Windows : sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux : remote.md §10. Conservez le répertoire d’état (audit) sauf indication contraire du propriétaire |
Hôte de développement seulement : .\packaging\rebuild-install.ps1 -Force
reconstruit dist\, arrête et remplace les binaires en cours (les anciens
sont gardés sous *.exe~), fusionne les configs des clients et lance
doctor.
12. Reprise après plantage et redémarrage
Vérifié par le harnais de chaos (internal/killharness).
| Après un plantage ou un arrêt forcé | Au redémarrage | Action de l’opérateur |
|---|---|---|
| Un travail tournait ou était en file d’attente | Marqué interrupted ; jamais repris |
Soumettre à nouveau si nécessaire |
| Demande en attente, non confirmée | Restaurée depuis state.json (le TTL s’applique encore) |
Confirmer ou laisser expirer |
fb_restore_replace en cours |
Se termine : restauration, validation, base en ligne ; <db>.pre-restore conservé |
Vérifier fb_db_health ; supprimer .pre-restore plus tard |
fb_shutdown_window en cours |
Termine l’étape gfix -online |
Vérifier que la base est en ligne |
instance.lock périmé |
Repris automatiquement | Aucune |
state.json corrompu |
Le noyau refuse de démarrer ; copie conservée sous state.json.corrupt-<ts> |
Inspecter ; réparer ou retirer state.json volontairement (fbmcpctl repair reconstruit les autorisations de planification à partir de l’audit) |
audit.jsonl corrompu ou tronqué |
Le noyau refuse de démarrer | §13.2 : traitez-le comme un signal d’altération |
| Horloge reculée | Le planificateur saute l’échéance ; pas de double exécution | Aucune |
| Processus du service Windows tué | Le SCM le relance en environ 5 s | Aucune |
Le noyau échoue en mode fermé sur tout ce qu’il ne peut pas prouver intact. Une boucle de redémarrages est un constat : lisez le journal.
13. Conduites d’incident
13.1 Quelque chose ne va pas avec une base
fbmcpctl doctor --config <file>: config, secrets, connexions Firebird, dossiers, posture, planifications. Chaque ligne FAIL a unFix:.fb_db_list→fb_db_health <db>;fb_service_statuspour l’instance.fb_sessions,fb_transactionspour les problèmes d’attachement ou d’écart d’OAT ;fb_firebird_logpour les erreurs du moteur.
13.2 Altération ou corruption suspectée : l’audit d’abord
fbmcpctl verify --config <file>→audit chain OK: N entriesouBROKENavec la raison.- S’il échoue : conservez tout le répertoire d’état (c’est la preuve), puis enquêtez. Ne supprimez pas
audit.jsonlpour faire démarrer le noyau.
13.3 Exercice de restauration (chaque trimestre)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ la sauvegarde est vérifiée.fb_window_openpour la base.fb_restore_replace→ approuvez hors canal. Indisponibilité jusqu’au retour en ligne.- Contrôle :
fb_db_health, puis une vraie lecture (fb_schema_list,fb_info). - L’ancien fichier reste sous
<db>.pre-restorejusqu’à ce que vous le supprimiez.
13.4 Le client ne peut pas se connecter
fbmcpctl ping --config <file>,fbmcpctl status --config <file>.- Lisez le journal MCP du client (stdio) ou
<state_dir>\fbmcp.log/journalctl -u fbmcp(service). - “another fbmcp instance is active” : un noyau par répertoire d’état. Les clients reliés par un tube s’attachent d’eux-mêmes ; un second noyau échoue tout de suite, par conception.
Dans les commandes ci-dessus, vous pouvez omettre --config lorsque la
recherche du §4 trouve le fichier.
14. Dépannage
| Symptôme | Signification / correctif |
|---|---|
| Les outils n’apparaissent pas | Syntaxe JSON, chemins absolus, redémarrage complet du client ; le journal MCP du client |
| Un outil manque dans la liste | Masqué volontairement (§1) : au-dessus de votre Tier maximal, pas d’entrée agents:, pas de migrations_dir, ou pas de section rcm: |
| Le serveur quitte tout de suite | fbmcpctl doctor ; un secret manquant ; un service ne peut pas lire votre trousseau (utilisez secrets.dir) |
| Tier 2 “confirmation rejected: channel policy” | Attendu dans le chat. Approuvez dans la zone de notification ou avec fbmcpctl approve |
| Tier 2 “no open maintenance window” | fb_window_open pour la même db que vous passez à l’outil |
fb_restore_replace refusé : préconditions |
Exige une sauvegarde vérifiée < 24 h : fb_backup_start + fb_restore_test, et une fenêtre |
| Contrôle du service refusé | posture.verified manquant (fbmcpctl setup --write-posture) ou le compte n’a pas de droits sur le service Firebird |
fb_config_set : écriture impossible |
Le compte n’a pas le droit de modifier ce fichier (unité Linux ProtectSystem=strict ; ACL Windows). Modifiez à la main, ou voyez remote.md §8 |
| La zone de notification n’affiche rien | Elle n’affiche que les demandes qui exigent un opérateur ; vérifiez les droits de cet utilisateur sur le répertoire d’état et tray.log qui s’y trouve |
| 401 (distant) | Mauvaise clé, ou le serveur ne l’a pas chargée : apikey list, doctor --remote |
| 403 (distant) | IP source absente de allow_from / du pare-feu, ou un en-tête Origin absent de allowed_origins |
| 429 (distant) | Limites ; attendez Retry-After |
| Pin non concordant | La clé du serveur a changé ; obtenez le nouveau pin auprès de l’administrateur du serveur |
agent-unreachable |
Service de l’agent arrêté, local_api.enabled: false, ou mauvais base_url (par défaut 127.0.0.1:(10000 + firebird port)) |
agent-auth |
Le jeton enregistré n’est pas le local_api.token de l’agent ; définissez-le à nouveau |
agent-timeout au redémarrage |
agents[].timeout_seconds (130) doit être plus grand que le restart_timeout_seconds de l’agent (120) |
Error loading plugin MySQLEngine … à l’attachement |
Sur HQbird, cela signifie en général que le fichier n’existe pas ; vérifiez le chemin |
DROP INDEX nu dans fb_write exige une fenêtre |
C’est Tier 2 à cet endroit ; utilisez fb_index_drop (Tier 1 ; refuse les index de contrainte) |
| Nouvel index non utilisé | Lancez les statistiques (fb_index_rebuild action=statistics) ; ORDER BY … DESC exige un index DESCENDING |
| Les outils échouent pour une seule base | Elle est hors ligne (fb_db_health) ; les outils se dégradent base par base |
15. Référence du répertoire d’état
| Chemin | Signification |
|---|---|
state.json (+ .tmp, .corrupt-*) |
Demandes en attente, travaux, catalogue de sauvegardes, workflows, planifications. Corrompu ⇒ refuse de démarrer |
audit.jsonl (+ .head) |
Journal d’audit chaîné par hachage ; .head détecte la troncature |
events.jsonl |
Événements de travaux (job.succeeded, job.failed avec le message) |
approvals\, denials\ |
Décisions hors canal (zone de notification / fbmcpctl approve), utilisées en ~2 s |
instance.lock |
Verrou d’un seul noyau |
attach.addr, attach.token |
Point d’attache pour des clients stdio supplémentaires |
fbmcp.log, fbmcp-crash.log |
Journal du service (en rotation) et sortie de plantage |
query-log.jsonl |
Chaque appel fb_query |
trends\ |
Historique de l’échantillonneur pour fb_trends |
config-journal\ |
Historique de fb_config_set (ancienne et nouvelle valeur) |
posture.verified |
Marqueur qui autorise le contrôle du service |
tray.log |
Erreurs de la zone de notification |
16. État du parcours
En attente (M1) : un parcours sur un hôte Windows neuf en n’utilisant que ce
guide. Les constats reviennent dans ce fichier. Résultats de labo pour le
mode distant (hôte Linux, VM neuve, service Windows) :
findings/phase12-lab-2026-11-03.md.