対象は、fbmcp をインストールして運用する人です。自分ではビルドしていません。 Go や Firebird 内部の知識は不要です。時点は 2026-11-16、 バージョン 2027.2.24(ローカルモードとリモートモード、HQbird へのインストール、fbagent ブリッジ、 HQbird クラスター、結果グリッド)です。

このサイトには載っていない短い版: quickstart-en.md、quickstart-ru.md、 quickstart-pt.md。詳細は英語です: remote.md(リモートモード)、 agent-bridge.md(fbagent)、 tool-reference.md(すべてのツール、その Tier と引数)、 claude-desktop.md(開発ホストでのクライアントの接続)、 ADR は decisions/ にあります。


1. fbmcp とは

fbmcp は、Windows と Linux 上の Firebird 2.5–5.0 向け MCP サーバーです。MCP クライアント(Claude Desktop、Claude Code、Cursor、Codex、ZCode、その他)はこれを使い、 DBA として作業します。監視、バックアップと検証済みリストア、SQL/DDL/DCL、 インデックス、ユーザーと権限、firebird.conf、スケジューラ、マイグレーション、 HQbird の fbagent、HQbird クラスターです。122 個のツールがあります。読み取り専用 56(Tier 0)、Tier 1 が 44、 Tier 2 が 21、Tier 3 が 1(無効)です。fb_demo_write があるのは、 サーバーが FBMCP_DEMO_TOOLS=1 で動いているときだけです。

クライアントに見えるのは、使えるツールだけです。ツール一覧が隠すもの: Tier 3、 アイデンティティの最大 Tier を超えるツール、読み取り専用アイデンティティに対する fb_confirm と fb_cancel、 agents: が空のあいだの fbagent ツール (fb_agent_discover と fb_agent_register は残る)、どのデータベースにも migrations_dir がないあいだのマイグレーションツール、 fbmcp.yaml に rcm: セクションがないあいだのクラスターツール。設定の再読み込みでこの 集合が変わると、クライアントは新しい一覧を受け取ります。隠したツールを直接呼ぶと、 明確な拒否が返ります。

バイナリ 役割
fbmcp サーバーです。既定: stdio 経由の MCP(クライアントが起動します)。-serve: stdio はなく、サービスとして動きます(スケジューラ、アタッチソケット、設定されていれば HTTPS リスナー)。fbmcp bridge: リモートの fbmcp に対する stdio クライアント
fbmcpctl 運用者向け CLI: doctor、approve、secret、apikey、tls、verify、status、ping、setup、repair、hqbird-install、gate。fbmcp ctl と同じプログラムです
fbmcp-tray Windows のトレイ: 運用者が必要な要求のための、承認/拒否のポップアップ

状態ディレクトリごとに カーネル は 1 つです。同じ設定の 2 番目のクライアントは 2 つ目のカーネルを起動しません。動いているカーネルにアタッチします。

2. 安全モデル

すべての呼び出しは、ポリシー → 人による確認 → 監査される実行、の順に通ります。

Tier 内容 確認の仕方
0 読み取り(エンジンが強制する読み取り専用トランザクション) 不要
1 日常の変更: DML/DDL、バックアップ、ユーザー、権限 帯域内: クライアントが要求 ID とトークンを示し、人が同意し、クライアントが fb_confirm を呼びます
2 影響が大きい操作: サービス制御、リストア置換、firebird.conf、排他ウィンドウ、登録、エージェントの再起動 帯域外のみ:トレイまたは fbmcpctl approve。クライアントが承認することは決してできません
3 致命的(fb_db_drop) 設計上、無効
  • Tier 2 は通常、開いているメンテナンスウィンドウ(同じ db に対する fb_window_open)と、 24 時間より新しい検証済みバックアップを必要とします。 拒否の文言に、何が足りないか示されます。
  • 保留中の要求は 15 分で期限切れになります。違う経路からの試行は その要求を消費しません。fb_cancel がそれを取り除きます。
  • ゲートされたツールはすべて mode: preview を受け付けます。影響を示し、 何もしません。
  • すべての判断(許可、保留、承認、拒否)は、 ハッシュ連鎖の audit.jsonl に入ります。
  • 承認用の Web ページはありません。あってはなりません。モデルが到達できるページは、 この設計を壊します。

3. 構成を選ぶ

構成 fbmcp が動く場所 使うとき 節
A. ローカル stdio 自分の PC。クライアントが起動する 管理者は 1 人。Firebird はこの PC 上、または LAN 内 §6
B. ローカルサービス DB ホスト上の Windows サービス(-serve) クライアントを開いていなくても、スケジュールを動かす必要がある §7
C. リモート DB サーバー上のサービス。HTTPS と API キー 管理者は複数、サーバーは遠い、自律エージェント §8

構成 A では、カーネルが存在するのはクライアントが動いているあいだだけなので、スケジュールが実行されるのもそのときだけです。無人のスケジュール(nightly_verify)には B または C を使います。

HQbird 内の fbmcp。 HQbird 2027 のセットアップと fbagent は、既定で fbmcp を インストールします。すべての Firebird ラインに対して、サーバーごとにサービスが 1 つで、 fbmcp ctl hqbird-install がセットアップします。そのようなサーバーでは §6–§8 に従わず、 hqbird.md(レイアウト、--allow-from 付きのリモートモード、API キー)を読んでください。

4. バイナリを入手する

要件: Go ≥ 1.26.11(より古い Go 1.21 以降は、最初のビルドで go1.26.11 を自力でダウンロードします。これにはインターネットが必要です)、 CGO は不要、Firebird 2.5–5.0、エージェントツールには Local API 付きの fbagent ≥ 2.67 (任意)、クラスターツールには fbagent 3.1.0 以降と RCM 2027.5.11 以降 (任意)。

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 バイナリ(Windows からのクロスビルド、または GOOS を付けずに Linux 上でビルド):

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

チェックサム: Get-FileHash dist/* または sha256sum dist/*。他の対象: packaging/README.md。バイナリは専用のフォルダーに置きます (例では C:\fbmcp\): mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\ (Linux: install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/)。

fbmcp ctl と fbmcpctl は同じプログラムです。fbmcpctl help がコマンドを一覧します。 設定を読むコマンドは --config <file> を取ります。付けないときは FBMCP_CONFIG、次にカレントフォルダーの fbmcp.yaml、次にプログラムの隣、次に HQbird の既定(C:\HQbirdData\fbmcp\fbmcp.yaml、 /etc/fbmcp/fbmcp.yaml)を使い、using config <path> を表示します。

5. fbmcp.yaml を設定する

完全な例: packaging/fbmcp.yaml.example。 最小の Windows 設定:

yaml
state:
  dir: C:\ProgramData\fbmcp\state
# secrets:
#   dir: C:\ProgramData\fbmcp\secrets   # setups B and C
instances:
  - id: fb5
    addr: localhost:3050
    bin_dir: C:\Program Files\Firebird\Firebird_5_0   # folder with gbak, gfix, gstat
    version: "5.0"
    service: FirebirdServerDefaultInstance            # Linux: firebird.opt_fb50
    service_user: SYSDBA                              # instance tools (fb_firebird_log, ...)
    service_secret_env: FBMCP_FB5_SERVICE_PW
databases:
  - id: main                 # tools and chats use the id, never the path
    instance: fb5
    path: D:\Data\main.fdb
    backup_dir: D:\fbmcp\backups
    work_dir: D:\fbmcp\work  # restore tests; Linux: not under /tmp
    ro_user: FBMCP_RO        # a read-only Firebird user
    ro_secret_env: FBMCP_MAIN_RO_PW
    admin_user: SYSDBA
    admin_secret_env: FBMCP_MAIN_ADMIN_PW
notify:
  webhook_url: ""            # optional: a chat webhook for pending requests
retention:
  keep_days: 0               # 0 = never delete backups

シークレット。 YAML が保持するのは変数の名前だけです。fbmcp は各 値を次の順で探します。環境変数 → ファイル <secrets.dir>/<NAME> → fbmcp を実行するアカウントの OS キーリング。

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)

値は stdin から読みます(入力してから Ctrl+Z、Enter。Linux では Ctrl+D)。 サービスアカウント(LocalSystem、NT SERVICE\...)は、あなたのキーリングを見えません。 サービスには secrets.dir を使ってください。変更したシークレットファイルは、再起動なしで 数秒のうちに適用されます。

読み取り専用ユーザー。 ro_user 用に、別の Firebird ユーザーを作ります(SQL は quickstart-en.md: CREATE USER FBMCP_RO、すべてのテーブルへの GRANT SELECT、そして Firebird 4.0 以降では fb_sessions がすべての接続を見るための、MONITOR_ANY_ATTACHMENT を持つロール)。 RO ユーザーとしての SYSDBA は開発専用です。doctor がそれについて警告します。

ライブ再読み込み。 fbmcp は fbmcp.yaml への変更を自分で適用します(ファイル ウォッチャー)。fb_config_reload でも適用します。クライアントもプロセスも再起動しません。再読み込みは 変更されたデータベース上のジョブを待ち(30 秒)、そのあと適用します。拒否されるもの: state.dir の変更、重複するデータベースパス、安全でないリモート設定。

確認: C:\fbmcp\fbmcpctl.exe doctor は doctor: green で終わらなければなりません (リモートモード: doctor --remote、FAIL 行なし)。足りない状態 フォルダーを作り、両方のユーザーで各データベースにログインし、各 FAIL 行は Fix: と、実行するコマンドで終わります。

6. 構成 A — ローカル stdio

絶対パスを使ってください。listen は設定しないでください。設定を変えたあとはクライアントを再起動します。 クライアントがサーバーを読み込むのは、起動時だけです。

クライアント 場所 エントリ
Claude Desktop Settings → Developer → Edit Config(%APPDATA%\Claude\claude_desktop_config.json) "mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}}
Claude Code コマンドライン claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml"
Cursor %USERPROFILE%\.cursor\mcp.json、またはプロジェクト内の .cursor\mcp.json Claude Desktop と同じ JSON
Codex codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml、または %USERPROFILE%\.codex\config.toml [mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml']
ZCode プロジェクト内の .zcode\config.json "mcp": {"servers": {"fbmcp": { ...same command and args... }}}

パスワードはキーリングにあります(§5)。そのため env ブロックは不要です。それでも クライアントの env ブロックにパスワードを入れる場合は、そのファイルを git に入れないでください。

そのあと、Tier 2 の承認のためにトレイを起動します。 C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml(ログオンのたび: .\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml)。

クライアントでの動作確認: 「fb_ping を呼ぶ」(サーバー名と、最大 Tier 付きの自分の アイデンティティを表示する)、次に「fb_db_list」、次に「main に対する fb_db_health」。

7. 構成 B — ローカル Windows サービス

管理者権限の PowerShell:

Command
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp
  • サービスは fbmcp -serve を LocalSystem として実行し、失敗すると再起動し、 サービスの停止ではきれいに停止します。
  • パスワードには secrets.dir を使います(§5)。
  • フォルダーをロックします。C:\fbmcp に書き込めるのは SYSTEM と Administrators だけです (スクリプトが icacls コマンドを表示します)。C:\ の直下に作ったフォルダーでは、 すべてのユーザーがファイルを変更でき、サービスはそれらを SYSTEM として実行します。
  • トレイのユーザーと、ローカルの stdio クライアントには、状態ディレクトリへの読み書きが必要です。 icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M"。同じ設定の stdio クライアントは、そのあとサービスのカーネルにアタッチします。
  • 準備完了の確認: C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml。
  • ログ: <state_dir>\fbmcp.log(5 × 10 MiB。クラッシュは fbmcp-crash.log)。

管理者がネットワーク越しに到達するサービスには、構成 C を使います。

8. 構成 C — リモート(HTTPS + API キー)

手順の全体: remote.md。短い形:

Windows サーバー(管理者権限):

  1. バイナリと fbmcp.yaml を C:\fbmcp\ に置く(テンプレートは 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" — ピン sha256:... を控える。
  3. 人またはエージェントごとにキーを 1 つ: C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets(表示は 1 回だけ)。--config C:\fbmcp\fbmcp.yaml を付けると、identities: のエントリも追加し、secrets.dir を使う。
  4. パスワードとエージェントのトークン: 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、そのあと -WhatIf なし。サービス、ファイアウォール規則、フォルダーの ACL、Firebird サービスの権限を作る。
  6. C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml → FAIL なし。curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz → ok。
  7. 承認者のトレイ: .\packaging\windows\install-tray.ps1。

Linux サーバー(root): fbmcp、fbmcpctl、packaging/linux/ をコピーしてから、

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

スクリプトは、フォルダー、証明書、admin キー付きの最初の設定 (表示は 1 回だけ)、systemd ユニット、Firebird ユニット用の sudo 規則、 ufw 規則を作り、そのあと doctor --remote を実行します。 /etc/fbmcp/fbmcp.yaml に databases: と agents: を追加します。Linux での承認 (トレイなし): sudo -u firebird fbmcpctl approve [id]。これは /etc/fbmcp/fbmcp.yaml を自分で見つけ、y/N を尋ね(--yes は尋ねない)、 --deny <id> --reason "..." は拒否します。

管理者の PC:

  1. C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(受け取ったキー)。
  2. 任意の stdio クライアント(Claude Desktop、Cursor、Codex、ZCode): §6 のエントリで、 次の args を使います。 ["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]。 ピンはサーバーの鍵を確認するので、自己署名証明書に CA の 設定は不要です。
  3. Claude Code は HTTP で直接接続することもできます(.mcp.json の "type": "http"、ヘッダー Authorization: Bearer ${FBMCP_KEY_SRV1}、 自己署名証明書のための NODE_EXTRA_CA_CERTS)。キーを claude mcp add --header で渡さないでください。平文で保存されます。
  4. テスト: fb_ping がサーバー名と自分のアイデンティティを表示します。

自律エージェント(OpenClaw など): 別のキーを apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32 で作ります。 既定は読み取り専用です。Tier 1 の要求はすべて運用者を待ち、 エージェントからの fb_confirm は拒否されます。制限: remote.md §6–7。

9. fbagent ブリッジと HQbird クラスター(任意)

エージェントツール(fb_agent_status、fb_agent_job_run、…)は、同じホスト上の HQbird fbagent の Local API を使います。 agents: にエントリがあるまで、これらはオフです。

  1. クライアントで「fb_agent_discover」。ローカルのエージェントを、 base_url、instance_id、提案されるトークン名とともに一覧します。トークンは 決して読みません。
  2. 運用者が、エージェントのlocal_api.tokenを保存します( agent.auth_token ではない): fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>。 トークンをチャットに入力しないでください。
  3. クライアントで「そのエージェントに対する fb_agent_register」→ トレイで承認します。 fbmcp が agents: エントリを追加し、再読み込みしてアイデンティティを確認します。
  4. テスト: fb_agent_status、fb_agent_instances。

fb_agent_config_set(ジョブ設定の変更: バックアップ、スイープ、…)には、エントリの config_path と、稼働中の agent_config.json への読み取りアクセス、 およびそのフォルダーへの作成権限も必要です。そのファイルにはトークンと Firebird の資格情報があるので、この許可を与えるかどうかは運用者の判断です (agent-bridge.md)。エージェントの確認に失敗すると、ツールは 何も書きません。

HQbird クラスター(RCM)。クラスターツールは、同じホスト上の HQbird クラスター マネージャー(hqbirdrcm)を呼びます。表示されるのは、 fbmcp.yaml に rcm: セクション(url、ca_file、user、 password_env)があるときだけです。Linux の HQbird サーバーでは、fbmcp ctl hqbird-install が /opt/hqbirdrcm/rcm.json からそれを書き、最初の RCM パスワードを シークレット FBMCP_RCM_PASSWORD に保存します。それ以外では、セクションを手で追加します (tool-reference.md)。そのあと:

  1. fb_cluster_rcm_password: 最初の RCM パスワードを置き換える(Tier 1)。
  2. 新しいクラスター: 各ホストでペアリングウィンドウを開き (fb_agent_cluster_pairing)、マスターで RCM を起動し (fb_agent_cluster_rcm)、ホストを結び(fb_cluster_link)、レプリカを作り (fb_cluster_reinit、Tier 2)、データを比較する (fb_cluster_verify)。手順: prompts/cluster-setup.md。
  3. クラスターサービス(スイッチオーバー、フェイルオーバー、再参加): fb_cluster_service がそれらと検査項目を表示します。移動は Tier 2 です。 手順: prompts/cluster-services.md。

10. 日常の使い方

クライアントには平易な言葉で頼んでください。ツールはクライアントが選びます。例:

作業 ツール
すべて稼働しているか fb_ping、fb_db_list、fb_db_health、fb_service_status
データを読む fb_query(読み取り専用。行 + プラン + テーブルごとの統計。MCP-Apps クライアントではグリッド)。下書きは fb_query_check で確認
セッション、長いトランザクション fb_sessions、fb_transactions、fb_session_kill(Tier 1)
遅いクエリ fb_analyze_query、fb_index_advice → fb_write で適用。fb_agent_perf_report
バックアップ fb_backup_start → ジョブ ID → fb_job_status
バックアップを検証する fb_restore_test(work_dir へリストアし、そのバックアップを検証済みにする)
夜間バックアップ + 検証 target=nightly_verify を付けた fb_schedule_create(確認は一度。構成 B または C)
スキーマ / DDL fb_schema_list、fb_describe、fb_write(各文は分類され Tier が付く)、fb_diff_schema
マイグレーション fb_migration_status、fb_migration_plan、fb_migration_apply
サーバー設定 fb_config_get、fb_config_diff、fb_config_set(Tier 2)
ログ fb_firebird_log
容量 fb_trends、fb_gstat、fb_index_stats
クラスターの状態 fb_cluster_status、fb_cluster_service
マスターを移す fb_cluster_switchover(データ損失なし)、または fb_cluster_failover(マスターを失ったとき)。そのあと fb_cluster_rejoin(Tier 2)

ジョブは非同期です。投入 → fb_job_status。1 つのデータベース上のジョブは、一度に 1 つだけ実行されます。ジョブが fbmcp の再起動後に残るのは interrupted としてだけです。まだ必要なら、 もう一度投入してください。

fb_config_set が変えるのは、firebird.conf の自分の行だけです(コメント、 インデント、行末はそのままです)。古いファイルは firebird.conf.prev として残し、 Firebird を再起動することはありません。再起動は fb_service_restart(Tier 2)で行います。 サービスが停止し、再び起動するまで待ちます。

11. 運用者の作業

作業 コマンド
要求を一覧する / 承認する / 拒否する fbmcpctl approve、fbmcpctl approve <id>、fbmcpctl approve --deny <id> --reason "..."(またはトレイ)
キーをローテーションする fbmcpctl apikey rotate alice --config <fbmcp.yaml>(古いキーは数秒で止まる)
キーを一覧する fbmcpctl apikey list(名前、出所、Tier。値は出さない)
人を外す identities: のエントリを削除し、そのあと fbmcpctl secret drop --dir <dir> NAME
証明書を更新する fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ...(ピンは変わらず、再起動なし)
監査チェーンを確認する fbmcpctl verify
カーネルは動いているか fbmcpctl ping、fbmcpctl status(状態のオフライン読み取り)
サービス制御を許可する packaging/posture/verify.ps1 または verify.sh、そのあと fbmcpctl setup --write-posture
アップグレード サービス(またはクライアント)を止め、バイナリを置き換え、起動し、doctor
削除する Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote。Linux: remote.md §10。所有者が別のことを言わない限り、状態ディレクトリ(監査)は残す

開発ホストだけ: .\packaging\rebuild-install.ps1 -Force は dist\ を再ビルドし、 動いているバイナリを止めて置き換え(古いものは *.exe~ として残る)、 クライアント設定をマージし、doctor を実行します。

12. クラッシュと再起動からの回復

カオスハーネス(internal/killharness)で検証済みです。

クラッシュまたは強制終了のあと 再起動時 運用者の操作
ジョブが実行中、またはキューにあった interrupted とマークされる。再開はしない 必要なら再投入する
保留中の要求で、未確認 state.json から復元される(TTL は引き続き適用される) 確認するか、期限切れに任せる
fb_restore_replace の実行中 完了する: リストア、検証、データベースはオンライン。<db>.pre-restore は残る fb_db_health を確認する。.pre-restore はあとで削除する
fb_shutdown_window の実行中 gfix -online のステップを完了する オンラインかを確認する
古い instance.lock 自動的に引き継がれる なし
state.json が壊れている カーネルは起動を拒否する。コピーは state.json.corrupt-<ts> として残る 調べる。意図して state.json を修復するか、削除する(fbmcpctl repair が監査からスケジュールの許可を再構築する)
audit.jsonl が壊れている、または途中で切れている カーネルは起動を拒否する §13.2: 改ざんの合図として扱う
時計が巻き戻された スケジューラはスキップする。二重実行はない なし
Windows サービスのプロセスが強制終了された SCM が約 5 秒で再起動する なし

カーネルは、無傷だと証明できないものについてはフェイルクローズします。再起動 ループは所見です。ログを読んでください。

13. インシデントの手順

13.1 データベースに異常がある

  1. fbmcpctl doctor --config <file>: 設定、シークレット、Firebird へのログイン、 フォルダー、ポスチャ、スケジュール。各 FAIL 行には Fix: があります。
  2. fb_db_list → fb_db_health <db>。インスタンスには fb_service_status。
  3. アタッチメントまたは OAT ギャップの問題には fb_sessions、fb_transactions。 エンジンのエラーには fb_firebird_log。

13.2 改ざんまたは破損の疑い: まず監査

  1. fbmcpctl verify --config <file> → audit chain OK: N entries、または理由付きの BROKEN。
  2. 失敗したとき: 状態ディレクトリ全体を残します(それが証拠です)。そのあと 調査します。カーネルを起動させるために audit.jsonl を削除しないでください。

13.3 リストア訓練(四半期ごと)

  1. fb_backup_start → fb_job_status = succeeded。
  2. fb_restore_test → バックアップは検証済みになる。
  3. そのデータベースに対して fb_window_open。
  4. fb_restore_replace → 帯域外で承認する。オンラインになるまで停止時間がある。
  5. 確認: fb_db_health、そのあと実際の読み取り(fb_schema_list、fb_info)。
  6. 古いファイルは、削除するまで <db>.pre-restore として残る。

13.4 クライアントが接続できない

  1. fbmcpctl ping --config <file>、fbmcpctl status --config <file>。
  2. クライアントの MCP ログ(stdio)、または <state_dir>\fbmcp.log / journalctl -u fbmcp(サービス)を読む。
  3. 「another fbmcp instance is active」: 状態ディレクトリごとにカーネルは 1 つです。パイプ経由の クライアントは自分でアタッチします。2 つ目のカーネルがすぐ失敗するのは、設計どおりです。

上のコマンドでは、§4 の検索がそのファイルを見つけるとき、 --config を省略できます。

14. トラブルシューティング

症状 意味 / 対処
ツールが表示されない JSON の構文、絶対パス、クライアントの完全な再起動。クライアントの MCP ログ
一覧からツールが 1 つ欠けている 意図的に隠しています(§1): 自分の最大 Tier を超える、agents: のエントリがない、migrations_dir がない、または rcm: セクションがない
サーバーがすぐに終了する fbmcpctl doctor。足りないシークレット。サービスはあなたのキーリングを読めない(secrets.dir を使う)
Tier 2 の「confirmation rejected: channel policy」 チャットでは想定どおりです。トレイ、または fbmcpctl approve で承認する
Tier 2 の「no open maintenance window」 ツールに渡すのと同じ db に対する fb_window_open
fb_restore_replace が拒否される: 前提条件 24 時間未満の検証済みバックアップが必要です: fb_backup_start + fb_restore_test、およびウィンドウ
サービス制御が拒否される posture.verified がない(fbmcpctl setup --write-posture)、またはそのアカウントに Firebird サービスへの権限がない
fb_config_set: 書き込めない そのアカウントはそのファイルを変更できないことがある(Linux ユニットの ProtectSystem=strict、Windows の ACL)。手で編集するか、remote.md §8 を参照する
トレイに何も出ない 表示するのは、運用者が必要な要求だけです。状態ディレクトリに対するトレイユーザーの権限と、そこにある tray.log を確認する
401(リモート) キーが違う、またはサーバーがそれを読み込んでいない: apikey list、doctor --remote
403(リモート) 送信元 IP が allow_from / ファイアウォールにない、または Origin ヘッダーが allowed_origins にない
429(リモート) 制限です。Retry-After を待つ
ピンの不一致 サーバーの鍵が変わった。新しいピンはサーバー管理者から受け取る
agent-unreachable エージェントサービスが停止している、local_api.enabled: false、または base_url が違う(既定は 127.0.0.1:(10000 + firebird port))
agent-auth 保存したトークンが、エージェントの local_api.token ではない。もう一度設定する
再起動時の agent-timeout agents[].timeout_seconds(130)は、エージェントの restart_timeout_seconds(120)より大きくなければならない
アタッチ時の Error loading plugin MySQLEngine … HQbird では、これは通常、データベースのファイルが存在しないことを意味します。パスを確認する
fb_write での裸の DROP INDEX にはウィンドウが必要 そこでは Tier 2 です。fb_index_drop を使う(Tier 1。制約インデックスは拒否する)
新しいインデックスが使われない 統計を実行する(fb_index_rebuild の action=statistics)。ORDER BY … DESC には DESCENDING インデックスが必要
1 つのデータベースだけでツールが失敗する オフラインです(fb_db_health)。ツールはデータベースごとに劣化する

15. 状態ディレクトリの参照

パス 意味
state.json(+ .tmp、.corrupt-*) 保留中の要求、ジョブ、バックアップカタログ、ワークフロー、スケジュール。壊れている ⇒ 起動を拒否する
audit.jsonl(+ .head) ハッシュ連鎖の監査ログ。.head は切り詰めを検出する
events.jsonl ジョブのイベント(メッセージ付きの job.succeeded、job.failed)
approvals\、denials\ 帯域外の判断(トレイ / fbmcpctl approve)。約 2 秒以内に使われる
instance.lock カーネルを 1 つに保つロック
attach.addr、attach.token 追加の stdio クライアント用アタッチエンドポイント
fbmcp.log、fbmcp-crash.log サービスログ(ローテーションあり)とクラッシュ出力
query-log.jsonl すべての fb_query 呼び出し
trends\ fb_trends 用のサンプラー履歴
config-journal\ fb_config_set の履歴(古い値と新しい値)
posture.verified サービス制御を許可するマーカー
tray.log トレイのエラー

16. ウォークスルーの状態

未了(M1): このガイドだけを使い、まっさらな Windows ホストで行うウォークスルー。 所見はこのファイルに戻します。リモートモードのラボ結果(Linux ホスト、 まっさらな VM、Windows サービス): findings/phase12-lab-2026-11-03.md。