对象是安装并运行 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 托盘:对需要操作员处理的请求弹出批准/拒绝

每个状态目录有一个 内核。使用同一配置的第二个客户端 不会再启动一个内核:它挂接到正在运行的那个内核。

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。
  • 没有审批网页,也绝不能有:模型能够打开的页面会 破坏这一设计。

3. 选择一种部署

部署 fbmcp 运行在哪里 何时使用 节
A. 本地 stdio 你的 PC;由客户端启动 一名管理员,Firebird 在这台 PC 上或在局域网内 §6
B. 本地服务 数据库主机上的 Windows 服务(-serve) 没有打开客户端时计划任务也必须运行 §7
C. 远程 数据库服务器上的服务,HTTPS + API 密钥 多名管理员、远程服务器、自主代理 §8

在部署 A 中,内核只在客户端运行时存在,因此计划任务也只在那时执行。无人值守的计划任务(nightly_verify)请用 B 或 C。

HQbird 中的 fbmcp。 HQbird 2027 的安装与 fbagent 默认会安装 fbmcp: 一台服务器上的所有 Firebird 产品线共用一个服务,由 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 的账户的操作系统密钥环。

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 及以上 创建一个带 MONITOR_ANY_ATTACHMENT 的角色,以便 fb_sessions 看到全部连接)。 把 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
  • 服务以 LocalSystem 运行 fbmcp -serve,失败后会重启, 并在服务停止时干净地停止。
  • 密码使用 secrets.dir(§5)。
  • 锁定文件夹:只有 SYSTEM 和 Administrators 可以写入 C:\fbmcp (脚本会打印 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" — 记下 pin sha256:...。
  3. 每个人员或代理一把密钥:C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets(只打印一次)。加上 --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 密钥的初始配置 (只打印一次)、systemd 单元、Firebird 单元的 sudo 规则 和 ufw 规则,然后运行 doctor --remote。把 databases: 和 agents: 加到 /etc/fbmcp/fbmcp.yaml。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>"]。 pin 用来核对服务器密钥,因此自签名证书不需要配置 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(更改作业设置:备份、sweep、……)还需要条目上的 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. 集群服务(switchover、failover、重新加入): 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(每条语句都会被分类并定级)、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。同一个数据库上的作业一次只 运行一个。作业在 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 ...(pin 不变,无需重启)
检查审计链 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”:每个状态目录一个内核。经管道启动的 客户端会自行挂接;第二个内核迅速失败是设计如此。

在上面的命令中,当 §4 的查找能找到该文件时, 可以省略 --config。

14. 故障排查

症状 含义 / 处理
工具不出现 JSON 语法、绝对路径、完全重启客户端;查看客户端的 MCP 日志
列表里缺一个工具 有意隐藏(§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
pin 不匹配 服务器密钥已变更;向服务器管理员索取新的 pin
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 索引
工具只在一个数据库上失败 它处于离线状态(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 单内核锁
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 主机、 全新虚拟机、Windows 服务):findings/phase12-lab-2026-11-03.md。