跳转到主要内容
hs-sql-agent
2.0.2
文档 2.0.2
文档 管理

自定义工具

在不绕过 hs-sql-agent 策略的前提下,构建并发布用途明确的 Query 或 DML MCP 工具。

Custom Tools 允许管理员把一段受控 SQL 封装为具名、用途明确的 MCP 操作,而不需要每个客户端每次都从头生成完整 SQL。

运行时会根据当前已认证 MCP 密钥绑定的数据库解析已发布工具。服务端加载发布定义,根据声明的参数渲染 SQL 模板,再按工具类型交给 typed Query runtime 或 typed DML runtime 执行。

工具类型

当前 Custom Tool 有两种执行类型:

  • Query — 走查询编译器/运行时路径,返回序列化后的结果行。
  • DML — 把渲染出的数据修改语句交给 typed DML runtime 解析,并进入与内置 DML 相同的审批流程。

未知工具类型会被拒绝。

是否发布决定工具是否可用

运行时只会解析当前 MCP 密钥所绑定数据库中的已发布工具。工具即使已经存在于管理界面,只要尚未发布,就不能通过 MCP 名称调用。

这样可以把编辑、审核中的内容与当前真正暴露给 MCP 的工具集合分开。

自定义不等于不受治理

执行前,代理层会验证工具访问权限和数据库绑定。Query 工具受到当前安全策略、表白名单和 SQL 并发限制约束。DML 工具则使用 typed DML parser 和 TypedDmlApprovalFlow,同样执行表白名单解析和人工审批。

执行过程也会写入审计事件。也就是说,Custom Tool 是同一安全边界内部的可复用接口,不是绕过安全边界的捷径。

暴露给 MCP 密钥

Custom Tool 名称可以像内置工具一样加入 MCP 密钥的允许工具列表。生产环境应优先只开放客户端真正需要的具名工具,而不是让整个工具面保持无限制。