MCP 工具参考 | hs-sql-agent

低风险

Schema 发现 get_schemas、get_tables、get_columns 在生成 SQL 前发现当前密钥绑定的数据库结构。

读取

Query SQL execute_query_sql 接受一条受控 SELECT，并返回序列化结果行。

审批

Safe DML execute_dml_sql 只执行通过预览、Elicitation 和提交时重新验证的受支持数据修改。

由 MCP 密钥管理的 2.0.2 正式内置工具面恰好包含 5 个工具：

工具	公共输入	返回形式	风险
`get_schemas`	无	逗号分隔的 schema 名称	元数据读取
`get_tables`	`schemaName: string`	逗号分隔的表说明	元数据读取
`get_columns`	`schemaName: string`, `tableName: string`	列对象 JSON 数组	元数据读取
`execute_query_sql`	`sql: string`	结果行 JSON 数组，或执行错误字符串	数据读取
`execute_dml_sql`	`sql: string`	审批/执行结果文本	数据修改

已发布 Custom Tools 可以扩展绑定数据库的工具集合，但它们不是额外的内置工具。

`get_schemas`

返回 MCP 密钥绑定数据库中 provider metadata runtime 报告的 schema。

**参数：**无。

**成功结果：**以逗号分隔字符串返回 schema 名称。

授权和限制：

存在显式工具允许列表时，密钥必须允许 get_schemas；
database provider/connection 必须已经根据已认证密钥解析；
操作需要获得共享 SQL 并发 limiter；
成功/失败会以 mcp.get_schemas 写入审计路径。

该工具不会让模型提供 database ID 或 connection string。

`get_tables`

get_tables(schemaName: string)

返回指定 schema 中 provider 报告的表；如果 MCP 密钥配置了表白名单，还会据此过滤。

如果绑定的 Database Management 条目存在语义元数据，每张可见表还可以包含：

显示名称
说明
同义词
该表范围内的指标说明

**成功结果：**逗号分隔字符串，因此每一项可能比单纯物理表名包含更多语义信息。

审计 action：mcp.get_tables。

`get_columns`

get_columns(schemaName: string, tableName: string)

服务端先检查请求的全限定表是否被当前 MCP 密钥允许，再读取 provider 列元数据并序列化为 JSON 数组。

2.0.2 的 ColumnInfo 对象公开：

属性	含义
`Name`	物理列名
`Column`	同一列名值的 alias
`Type`	provider 报告的列类型
`Description`	可用时的语义增强
`IsPrimaryKey`	provider metadata 是否把该列标记为主键的一部分
`PrimaryKeyOrdinal`	复合主键中的 nullable 顺序

语义增强可以把显示名称、说明、同义词和关系说明补入 Description。只有关系两端表都在密钥表白名单内时，才会包含对应关系上下文。

审计 action：mcp.get_columns。

`execute_query_sql`

execute_query_sql(sql: string)

接受一条 SELECT SQL 语句。2.0.2 公共工具契约明确包含常见 Query 结构，例如 JOIN、WHERE、GROUP BY、HAVING、ORDER BY、LIMIT/OFFSET、DISTINCT、CTE、子查询以及 UNION/INTERSECT/EXCEPT。

01 Parse

02 Bind

03 授权表

04 验证策略

05 编译 immutable command

06 执行

Raw SQL 不会直接交给 provider。

请求通过 F# typed-query runtime 执行。根据运行时 capability，引用表、是否存在 CTE、是否存在子查询等 Query facts 会在同一受控路径中收集，并用于审计 evidence。

**成功结果：**返回行集合的 JSON 序列化结果。

**失败结果：**返回以 Execution failed: 开头的文本并附错误消息。调用方主动取消会直接传播，不会被转换成普通结果字符串。

运行时边界：

MCP tool allowlist
MCP 密钥数据库绑定
表白名单
当前 security/query policy
SQL concurrency limiter
source/target SQL capability check
mcp.query.executed 审计事件，记录 operation、duration、returned rows 和 compiler-derived definition facts

人类可读的能力总结见 SQL 支持参考。

`execute_dml_sql`

execute_dml_sql(sql: string)

MCP 对外输入只有 SQL。.NET 方法使用的 McpServer 和 cancellation token 是运行时注入的基础设施，不是 Agent 提供的字段。

2.0.2 MCP DML 路径支持：

语句	状态
`UPDATE`	parse、capability、policy、approval 全部满足时支持
`DELETE`	parse、capability、policy、approval 全部满足时支持
`INSERT ... VALUES`	使用 immutable payload 审批语义支持
`INSERT ... SELECT`	2.0.2 中失败即拒绝

01 Parse + 验证 profile

02 编译数据修改

03 精确预览影响

04 人工 Elicitation

05 事务内重新验证

06 提交

审批绑定到已验证的数据修改上下文，而不只是原始 SQL 文本。

UPDATE 和 DELETE 的审批会绑定到精确的 primary-key row set，提交时在事务内重新验证行身份。INSERT VALUES 的审批绑定到 immutable literal payload 和精确 compiled command，提交时验证已审批 payload 的行数。

人工拒绝或验证无法完成时，不会提交修改。审计使用 mcp.dml.executed，记录 operation、processing duration、affected rows、approval status，以及适用时的 error category。

完整协议见 Safe DML。

内置工具共有错误

常见失败包括：

缺少 MCP authorization context
密钥显式工具允许列表不包含该工具
database provider 或 connection 配置无效
SQL concurrency limit 无法授予 lease（Server busy）
请求的表不在密钥白名单中
SQL 为空、不受支持、被策略拒绝或被 capability boundary 拒绝
provider 执行失败

工具会返回受限错误信息，而不会降级为无限制 provider SQL 执行。

Custom Tools

已发布 Custom Tools 会根据 MCP 密钥绑定的 Database Management 条目加载，也可以按名称加入同一个 AllowedTools 集合。调用时仍受 runtime database binding、table whitelist、security policy、concurrency control 和 audit path 约束；DML Custom Tool 还必须经过 approval pipeline。

详见自定义工具。

语义元数据不是第六个内置工具

2.0.2 仓库包含语义管理实现，但正式 MCP key built-in registry 和 Admin key-management surface 只识别本页列出的 5 个工具。因此官方 2.0.2 文档把语义元数据视为由管理控制平面维护、由 schema discovery 消费的 capability，而不是额外的正式 MCP 内置契约。

详见语义元数据。

推荐发现流程

get_schemas

get_tables

get_columns

execute_query_sql

execute_dml_sql