HQbird MCP AI 助手
AI 助手 处于人工控制之下
HQbird MCP 将 Firebird 连接到 AI 助手。你用自然语言输入,助手会自行选择工具。读取操作自由执行。每次变更都要等待你回答“是”,而危险操作则要在服务器本身上等待批准。
- 122 个工具
- 56 个只读
- Firebird 2.5–5 Windows 和 Linux
- 2 个通道用于批准
- 审计日志带哈希链
示例
与助手的对话
用户抱怨数据库很慢。助手读取数据,找到原因,建议一项操作,然后等待你的决定。示例中的名称和数字均为虚构。
任何 MCP 客户端都可以使用:Claude Desktop、Claude Code、Cursor、Codex、ZCode 等。
策略 · 批准
四个危险级别
每个工具都有一个级别。MCP 服务器在调用执行前会自行检查级别和条件。会改变内容的调用返回的是批准请求,而不是结果。助手无法绕过这项检查。
选择一个工具,看看它的调用会走哪条路径。
| 级别 | 工具 | 示例 | 如何批准 |
|---|---|---|---|
| 0 · 读取 | 51 | 会话、事务、查询计划、gstat、firebird.log、agent 报告 | 不需要。只读事务。 |
| 1 · 变更 | 31 | DML 和 DDL、备份、测试恢复、sweep、用户和授权、结束会话 | 在聊天中:请求编号和令牌,然后 fb_confirm。 |
| 2 · 危险操作 | 14 | 从备份替换数据库、编辑 firebird.conf、停止并重启 Firebird | 仅在服务器上:fbmcp ctl approve 命令。在 Windows 上还可以安装托盘窗口。 |
| 3 · 已禁用 | 1 | 删除数据库 | 永不执行。 |
- 预览每个需要批准的工具都接受
mode: preview。它会显示将要执行的操作,但不做任何事。 - 级别 2 的条件每个级别 2 操作都需要在该数据库上打开维护窗口。从备份替换数据库、独占窗口和危险 SQL 还需要一份不超过 24 小时的已验证备份。拒绝时会说明缺少什么。
- 仅允许的工具客户端在列表中只能看到它被允许使用的内容:没有级别 3,也没有高于其密钥上限的级别。直接调用隐藏工具会被拒绝。
- 请求有效期为 15 分钟通过错误通道尝试批准不会消耗它。
fb_cancel会删除该请求。 - 没有批准页面而且也不会有:模型能够访问的页面会破坏保护。只有服务器上的人才能批准:使用
fbmcp ctl approve命令,或在托盘窗口中批准(如果已安装)。
读取在只读事务中运行:Firebird 本身会阻止写入。作为第二层保护,请设置一个没有写入权限的独立只读用户。
监控 · 备份 · 授权
面向 DBA
助手执行 DBA 手动完成的工作:检查会话和事务、读取日志、制作备份并通过恢复进行验证、管理用户。它通过 id 而不是文件路径来指定数据库。
| 任务 | 工具 | 级别 |
|---|---|---|
| 一切是否正常 | fb_ping, fb_db_list, fb_db_health, fb_service_status | 0 |
| 会话和长事务 | fb_sessions, fb_transactions;结束会话 — fb_session_kill | 0 · 1 |
| 日志和统计 | fb_firebird_log, fb_gstat, fb_lwmonitoring, fb_trends | 0 |
| 备份和验证 | fb_backup_start (gbak), fb_backup_nbackup, fb_restore_test | 1 |
| 旧备份 | fb_retention_run:先试运行;只删除其自身目录中已验证的备份 | 1 |
| Sweep 和数据库验证 | fb_sweep, fb_validate(仅报告发现,不修复) | 1 |
| 用户和授权 | fb_user_create, fb_grant, fb_revoke;SYSDBA 及其自身账户无法删除 | 1 |
| 跟踪 | fb_trace_start 仅使用模板:audit-lite、performance、errors | 1 |
| firebird.conf | fb_config_get, fb_config_diff;编辑 — fb_config_set,Firebird 不会重启 | 0 · 2 |
| 服务和数据库替换 | fb_service_restart;fb_restore_replace,旧文件保留为 .pre-restore | 2 |
夜间备份检查
计划在创建时审批一次。之后它无需人工干预即可运行。每晚你都会获得一份经过验证的备份。例如,当你需要从备份替换数据库时,就需要这样一份备份。
- 1计划
fb_schedule_create,目标nightly_verify;审批一次 - 2备份使用 gbak 备份到备份文件夹
- 3测试还原还原到工作文件夹;源数据库不受影响
- 4✓ 备份已验证在备份目录中留下标记
从备份替换数据库以及级别 3 的操作无法安排计划。
现成场景
场景向助手建议步骤顺序。它本身不会应用更改。
查询 · 索引 · 迁移
面向开发者
Cursor 或 Claude Code 中的助手了解你的架构,在查询运行前进行检查,并直接在聊天中以表格形式显示结果。
- 1任务用一句话说明你的需求
- 2事实
fb_schema_list、fb_describe:仅限现有的表和列 - 3草稿一个带 ORDER BY 的 SELECT
- 4检查
fb_query_check:仅编译,不运行 - 5✓ 聊天中的表格
fb_query:行、计划和统计信息
以表格形式呈现结果
在支持 MCP Apps 的客户端中,fb_query 的结果会显示为可排序的表格。其他客户端会以文本形式获得相同的数据。
默认 100 行,最多 1000 行。表格在内存中保留 30 分钟,且只有请求它的人才能看到。点击列标题即可排序。
SELECT full_name, dept_no, salary FROM employee WHERE salary > 60000 ORDER BY salary DESC
索引建议
发现全表扫描,并建议使用 CREATE INDEX,同时估算收益。它本身不会创建索引:由 fb_write 在获得批准后创建。索引创建后,它会再次检查计划。
数据库比较
比较两个数据库的架构,或数据库与其快照的架构:需要创建、更改、删除什么。数据按主键比较;该工具不比较大表(默认超过 100,000 行)。
迁移
计划会显示每条语句的级别。所有迁移在一次批准后应用;如果文件发生变化,则需要新的请求。回滚计划根据应用迁移时记录的内容构建。
fb_write 会找出脚本中每条语句的级别。混合了不同级别语句的脚本会被拒绝。
fbagent · 本地 API · 127.0.0.1
fbagent 数据
fbagent 代理已在 HQbird 服务器上运行。通过 MCP,助手可以获取代理收集的所有内容:健康报告、LWM(轻量级监控)、gstat、跟踪、死锁、备份状态。它还可以运行代理作业并更改其设置,同样遵循相同的级别和审批。
| 内容 | 工具 | 级别 |
|---|---|---|
| 服务器健康报告 | fb_agent_status | 0 |
| LWM、gstat、数据库指标、跟踪、死锁 | fb_agent_artifact_get、fb_agent_perf_report | 0 |
| 备份、sweep 和还原设置 | fb_agent_backup_config;密码和令牌会被隐藏 | 0 |
| 运行代理作业 | fb_agent_job_run;备份、还原和 SQL 脚本为级别 2 | 1 · 2 |
| 更改作业设置 | fb_agent_config_set;凭据、ID 和命令无法更改 | 2 |
| 通过代理重启 Firebird | fb_agent_restart、fb_agent_stop、fb_agent_start | 2 |
| 许可证和更新 | fb_agent_license、fb_agent_license_set、fb_agent_update_apply、fb_agent_product_update_apply | 0 · 1 · 2 |
- 仅限本地代理仅接受 127.0.0.1 上的请求。代理地址来自 MCP 服务器配置,而不是来自聊天。
- 令牌保持隐藏代理令牌不会出现在工具输出或审计日志中。
- 代理发现
fb_agent_discover通过 Windows 服务或 systemd 单元在服务器上查找代理。它不会读取令牌。 - 集群如果服务器上安装了集群节点,
fb_agent_restart、fb_agent_stop和fb_agent_start默认会拒绝:由节点控制重启。fb_service_restart不检查这一点,因此不要在集群节点上使用它。
双重控制。MCP 服务器批准请求,而代理本身按照自己的规则执行任务。MCP 日志显示是谁发起的请求;代理日志显示任务是如何完成的。
HQbird Cluster · RCM
通过助手构建复制集群
助手逐步构建复制集群:开启 RCM、打开配对窗口、连接主机、将数据库纳入管理,并为副本制作一份拷贝。它通过代理和 RCM 完成工作。你无需通过 SSH 登录服务器。
规则与其他地方相同。读取操作无需确认。变更在聊天中确认。Firebird 重启、将数据库复制到副本、从集群中移除服务器、switchover、failover 以及旧主节点的回归,均在服务器上确认。
| 操作 | 工具 | 级别 |
|---|---|---|
| 服务器上的集群状态 | fb_agent_cluster:空闲、在集群中或 RCM 所有者;槽位和端口 | 0 |
| RCM 中的集群概览 | fb_cluster_status:节点、数据库、命令、警报 | 0 |
| 连接前检查主机 | fb_cluster_probe:每个代理一行,证书指纹 | 0 |
| 比较主节点和副本 | fb_cluster_verify:每张表的行数 | 0 |
| 在服务器上开启 RCM | fb_agent_cluster_rcm | 1 |
| 配对窗口 | fb_agent_cluster_pairing:状态、开放 1–24 小时、关闭 | 0 · 1 |
| 连接主机 | fb_cluster_link;请求中显示用于比较的指纹 | 1 |
| 数据库与发布 | fb_cluster_replica_folder、fb_cluster_enroll、fb_cluster_publication | 1 |
| RCM 密码 | fb_cluster_rcm_password:新的随机密码,不在聊天中显示 | 1 |
| 将数据库复制到副本 | fb_cluster_reinit | 2 |
| 重启节点的 Firebird | fb_cluster_firebird_restart | 2 |
| 从集群中移除服务器 | fb_cluster_unlink | 2 |
| 服务:主节点所在位置 | fb_cluster_service:主节点、副本、路由器、问题、正在运行的操作 | 0 |
| 描述服务及其规则 | fb_cluster_service_put、fb_cluster_service_policy:服务描述、自动 failover 规则 | 1 |
| 恢复和取消操作 | fb_cluster_resume、fb_cluster_operation_cancel;只能在不可返回点之前取消 | 1 |
| Switchover | fb_cluster_switchover:计划内的主节点迁移,等待操作结束 | 2 |
| Failover | fb_cluster_failover:仅在明确同意数据丢失的情况下 | 2 |
| 恢复旧主节点 | fb_cluster_rejoin | 2 |
| 删除服务 | fb_cluster_service_delete:仅删除 RCM 中的记录 | 2 |
- 现成场景“构建集群”:助手逐步进行,并在每一步展示将要执行的操作。
- 指纹连接前,助手显示每台服务器的证书指纹。请将其与安装摘要中的行进行比较。
- 试运行在将包含数据库的文件夹纳入管理之前,助手会显示 RCM 将找到哪些数据库。
- Switchover 和 failover助手启动主节点迁移并跟踪操作的各个步骤。服务器上的人员确认启动。Failover 还需要明确同意数据丢失。集群页面上的更多内容。
HTTPS · API 密钥 · 审计
远程模式、安装和审计日志
助手运行在管理员的 PC 上,MCP 服务器运行在数据库服务器上。两者之间通过 HTTPS 和 API 密钥连接。每个人都有自己的密钥和自己的最高级别。
- 每人一个密钥
fbmcp ctl apikey new <name> --max-tier 2。该值仅显示一次。密钥更改后,旧密钥将在几秒内停止工作。 - 限制每个密钥:并发调用数、每分钟调用数、打开的会话数。超过限制时,响应为 429。
- 葡萄牙语指南完整的安装和使用指南也提供巴西葡萄牙语版本。
- 自主代理
autonomous配置文件:默认只读。变更等待服务器上的操作员;来自代理的fb_confirm会被拒绝。每分钟 10 次调用。请在公司网络内运行此类代理。 - 地址密钥可以绑定到地址(
allow_from)。其他地址会收到 403 并在日志中记录一条。
在 HQbird 中安装
HQbird 安装程序默认安装 MCP 服务器。一个服务器为机器上的所有 Firebird 线路提供服务。一条命令即可完成所有设置,并且可以再次运行。
- 1HQbird 安装程序Windows 或 Linux
- 2fbmcp ctl hqbird-install一条命令,无需手动编辑 YAML
- 3Firebird 线路找到每条线路及其代理
- 4数据库databases.conf 别名和最近连接的数据库
- 5✓ 服务启动、检查、为客户端生成 connect.txt 文件
当满足三个条件时,远程模式会开启:已设置管理员地址列表(--allow-from)、防火墙正在运行,并且至少存在一个 API 密钥。您需要单独创建密钥。之后,再次运行 fbmcp ctl hqbird-install。默认端口为 8650。
哈希链
每个决策(允许、待定、批准、拒绝)都会写入日志。每个条目都与前一个条目相链接。链校验可显示某个条目是否被更改或删除。
日志被截断 — 服务器保持停止
如果日志被截断,或其末尾与控制条目不匹配,MCP 服务器将不会启动。这是篡改的迹象,您必须进行调查。fbmcp ctl verify 命令会校验整条链。
通过代理
fbagent 更新 MCP 服务器:停止、替换、启动、检查、失败时回滚。在 Linux 上不会安装未签名的构建。配置和密钥不会改变。