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ême db) 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_cancel la 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).

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

Binaires Linux (compilation croisée depuis Windows, ou compilation sur Linux sans 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

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

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

Secrets. 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.

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)

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

Command
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp
  • Le service exécute fbmcp -serve en tant que LocalSystem, redémarre en cas d’échec, et s’arrête proprement à l’arrêt du service.
  • Utilisez secrets.dir pour les mots de passe (§5).
  • Verrouillez le dossier : seuls SYSTEM et Administrators peuvent écrire dans C:\fbmcp (le script affiche la commande icacls). Un dossier créé sous C:\ 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 dans fbmcp-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é) :

  1. Binaires et fbmcp.yaml dans C:\fbmcp\ (modèle : 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" — notez le pin sha256:....
  3. 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ée identities: et utilise secrets.dir.
  4. Mots de passe et jetons d’agent : 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, puis sans -WhatIf. Il crée le service, la règle de pare-feu, les ACL des dossiers et les droits du service Firebird.
  6. 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.
  7. Zone de notification pour l’approbateur : .\packaging\windows\install-tray.ps1.

Serveur Linux (root) : copiez fbmcp, fbmcpctl et packaging/linux/, puis

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

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

  1. C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1 (la clé que vous avez reçue).
  2. 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.
  3. Claude Code peut aussi se connecter directement en HTTP (.mcp.json "type": "http", en-tête Authorization: Bearer ${FBMCP_KEY_SRV1}, NODE_EXTRA_CA_CERTS pour un certificat auto-signé). Ne passez pas la clé avec claude mcp add --header : elle est stockée en clair.
  4. Test : fb_ping affiche 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.

  1. Dans le client : “fb_agent_discover”. Il liste les agents locaux avec base_url, instance_id et le nom de jeton suggéré. Il ne lit jamais les jetons.
  2. L’opérateur enregistre le local_api.token de l’agent (pas agent.auth_token) : fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Ne tapez jamais un jeton dans le chat.
  3. Dans le client : “fb_agent_register pour cet agent” → approuvez dans la zone de notification. fbmcp ajoute l’entrée agents:, recharge et vérifie l’identité.
  4. 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 :

  1. fb_cluster_rcm_password : remplacer le premier mot de passe RCM (Tier 1).
  2. 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.
  3. Services du cluster (switchover, failover, rejoin) : fb_cluster_service les 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

  1. fbmcpctl doctor --config <file> : config, secrets, connexions Firebird, dossiers, posture, planifications. Chaque ligne FAIL a un Fix:.
  2. fb_db_list → fb_db_health <db> ; fb_service_status pour l’instance.
  3. fb_sessions, fb_transactions pour les problèmes d’attachement ou d’écart d’OAT ; fb_firebird_log pour les erreurs du moteur.

13.2 Altération ou corruption suspectée : l’audit d’abord

  1. fbmcpctl verify --config <file> → audit chain OK: N entries ou BROKEN avec la raison.
  2. S’il échoue : conservez tout le répertoire d’état (c’est la preuve), puis enquêtez. Ne supprimez pas audit.jsonl pour faire démarrer le noyau.

13.3 Exercice de restauration (chaque trimestre)

  1. fb_backup_start → fb_job_status = succeeded.
  2. fb_restore_test → la sauvegarde est vérifiée.
  3. fb_window_open pour la base.
  4. fb_restore_replace → approuvez hors canal. Indisponibilité jusqu’au retour en ligne.
  5. Contrôle : fb_db_health, puis une vraie lecture (fb_schema_list, fb_info).
  6. L’ancien fichier reste sous <db>.pre-restore jusqu’à ce que vous le supprimiez.

13.4 Le client ne peut pas se connecter

  1. fbmcpctl ping --config <file>, fbmcpctl status --config <file>.
  2. Lisez le journal MCP du client (stdio) ou <state_dir>\fbmcp.log / journalctl -u fbmcp (service).
  3. “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.