fbmcp: インストールと使い方
対象は、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 以降 (任意)。
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 バイナリ(Windows からのクロスビルド、または GOOS を付けずに Linux 上でビルド):
$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 設定:
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 キーリング。
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:
.\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 サーバー(管理者権限):
- バイナリと
fbmcp.yamlをC:\fbmcp\に置く(テンプレートは 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"— ピンsha256:...を控える。- 人またはエージェントごとにキーを 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を使う。 - パスワードとエージェントのトークン:
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、そのあと-WhatIfなし。サービス、ファイアウォール規則、フォルダーの ACL、Firebird サービスの権限を作る。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。- 承認者のトレイ:
.\packaging\windows\install-tray.ps1。
Linux サーバー(root): fbmcp、fbmcpctl、packaging/linux/ をコピーしてから、
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:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(受け取ったキー)。- 任意の stdio クライアント(Claude Desktop、Cursor、Codex、ZCode): §6 のエントリで、
次の
argsを使います。["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]。 ピンはサーバーの鍵を確認するので、自己署名証明書に CA の 設定は不要です。 - Claude Code は HTTP で直接接続することもできます(
.mcp.jsonの"type": "http"、ヘッダーAuthorization: Bearer ${FBMCP_KEY_SRV1}、 自己署名証明書のためのNODE_EXTRA_CA_CERTS)。キーをclaude mcp add --headerで渡さないでください。平文で保存されます。 - テスト:
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: にエントリがあるまで、これらはオフです。
- クライアントで「
fb_agent_discover」。ローカルのエージェントを、base_url、instance_id、提案されるトークン名とともに一覧します。トークンは 決して読みません。 - 運用者が、エージェントの
local_api.tokenを保存します(agent.auth_tokenではない):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>。 トークンをチャットに入力しないでください。 - クライアントで「そのエージェントに対する
fb_agent_register」→ トレイで承認します。 fbmcp がagents:エントリを追加し、再読み込みしてアイデンティティを確認します。 - テスト:
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)。そのあと:
fb_cluster_rcm_password: 最初の RCM パスワードを置き換える(Tier 1)。- 新しいクラスター: 各ホストでペアリングウィンドウを開き
(
fb_agent_cluster_pairing)、マスターで RCM を起動し (fb_agent_cluster_rcm)、ホストを結び(fb_cluster_link)、レプリカを作り (fb_cluster_reinit、Tier 2)、データを比較する (fb_cluster_verify)。手順:prompts/cluster-setup.md。 - クラスターサービス(スイッチオーバー、フェイルオーバー、再参加):
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 データベースに異常がある
fbmcpctl doctor --config <file>: 設定、シークレット、Firebird へのログイン、 フォルダー、ポスチャ、スケジュール。各 FAIL 行にはFix:があります。fb_db_list→fb_db_health <db>。インスタンスにはfb_service_status。- アタッチメントまたは OAT ギャップの問題には
fb_sessions、fb_transactions。 エンジンのエラーにはfb_firebird_log。
13.2 改ざんまたは破損の疑い: まず監査
fbmcpctl verify --config <file>→audit chain OK: N entries、または理由付きのBROKEN。- 失敗したとき: 状態ディレクトリ全体を残します(それが証拠です)。そのあと
調査します。カーネルを起動させるために
audit.jsonlを削除しないでください。
13.3 リストア訓練(四半期ごと)
fb_backup_start→fb_job_status= succeeded。fb_restore_test→ バックアップは検証済みになる。- そのデータベースに対して
fb_window_open。 fb_restore_replace→ 帯域外で承認する。オンラインになるまで停止時間がある。- 確認:
fb_db_health、そのあと実際の読み取り(fb_schema_list、fb_info)。 - 古いファイルは、削除するまで
<db>.pre-restoreとして残る。
13.4 クライアントが接続できない
fbmcpctl ping --config <file>、fbmcpctl status --config <file>。- クライアントの MCP ログ(stdio)、または
<state_dir>\fbmcp.log/journalctl -u fbmcp(サービス)を読む。 - 「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。