MCP 工具參考 | hs-sql-agent

low risk

資料庫結構探索 先用 get_schemas、get_tables、get_columns 探索金鑰綁定的資料庫，再產生 SQL。

read

查詢 SQL execute_query_sql 接受單一受治理的 SELECT，並回傳序列化後的結果資料列。

approval

Safe DML execute_dml_sql 只會在預覽、Elicitation 與提交前重新驗證都通過後執行支援的資料修改。

hs-sql-agent 由 MCP 金鑰正式管理的內建工具只有五個名稱：

工具	公開輸入	回傳格式	風險
`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 可以依資料庫擴充工具集合，但不算額外的內建工具。

建議的探索流程

01 get_schemas

02 get_tables

03 get_columns

04 execute_query_sql

先探索實體結構，再讓模型產生 SQL。DML 刻意不放進預設讀取流程。

當用戶端不知道可靠的 schema 時，先使用中繼資料工具。這些工具都在已驗證金鑰所綁定的資料庫上下文中執行，不接受模型自行傳入 connection string。

`get_schemas`

回傳 MCP 金鑰綁定資料庫的 provider metadata runtime 所提供的 schemas。

參數： 無。

成功結果： 以逗號串接的 schema 名稱。

授權與限制：

若有明確工具允許清單，金鑰必須允許 get_schemas；
資料庫 provider 與連線會從已驗證的金鑰上下文解析；
執行時會取得共用 SQL 並行限制器的 lease；
成功或失敗都會寫入稽核 action 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 陣列。

hs-sql-agent 每個 ColumnInfo 物件會暴露：

屬性	意義
`Name`	實體欄位名稱
`Column`	同一欄位名稱值的 alias
`Type`	provider 回報的欄位型別
`Description`	有語意中繼資料時的說明
`IsPrimaryKey`	provider metadata 是否標示為主鍵的一部分
`PrimaryKeyOrdinal`	複合主鍵中可為空的排序位置

語意中繼資料可以把顯示名稱、說明、同義詞與關聯說明加入 Description。只有在金鑰的資料表白名單同時允許關聯兩端資料表時，才會提供關聯資訊。

稽核 action： mcp.get_columns。

`execute_query_sql`

execute_query_sql(sql: string)

接受單一 SELECT SQL statement。hs-sql-agent 公開工具契約明確列出常見查詢形式：JOIN、WHERE、GROUP BY、HAVING、ORDER BY、LIMIT/OFFSET、DISTINCT、CTE、subquery，以及 UNION/INTERSECT/EXCEPT。

01 Parse

02 Bind

03 Authorize tables

04 Validate policy

05 Compile immutable command

06 Execute

原始 SQL 不會直接送給 provider 執行。

請求會進入 F# 型別化查詢執行階段。執行流程會取得被參照的資料表、CTE、subquery 等編譯器事實，並把這些資訊用於稽核證據。

成功結果： 回傳資料列集合的 JSON 序列化結果。

失敗結果： 一般失敗會回傳以 Execution failed: 開頭的文字；如果是呼叫端取消，則會直接向外傳遞，不會包成一般結果字串。

執行階段邊界：

MCP 工具允許清單；
MCP 金鑰的資料庫綁定；
資料表白名單；
目前的安全與查詢政策；
SQL 並行限制器；
來源與目標 SQL capability 檢查；
稽核事件 mcp.query.executed，記錄 operation、duration、returned rows 與編譯器推導出的 definition facts。

可搭配 SQL 支援參考。

`execute_dml_sql`

execute_dml_sql(sql: string)

MCP 對外可見的輸入只有 SQL。.NET 方法中的 McpServer 與 cancellation token 是執行階段注入的基礎設施，不是 Agent 需要傳入的欄位。

hs-sql-agent MCP DML 路徑支援：

Statement	狀態
`UPDATE`	解析、capability、政策與核准全部通過時支援
`DELETE`	解析、capability、政策與核准全部通過時支援
`INSERT ... VALUES`	支援不可變 payload 的核准語意
`INSERT ... SELECT`	hs-sql-agent 以 fail-closed 方式拒絕

01 Parse + verify profile

02 Compile mutation

03 Preview exact impact

04 Human Elicitation

05 Transaction revalidation

06 Commit

核准綁定的是已驗證的資料修改上下文，不只是原始 SQL 文字。

UPDATE / DELETE 的核准會綁定精確的主鍵資料列集合，提交時會在交易內再次驗證資料列身分。INSERT VALUES 則把核准綁定到不可變的 literal payload 與精確編譯命令，提交時再驗證已核准 payload 的資料列數。

如果真人拒絕，或驗證無法完成，資料修改就不會提交。稽核使用 mcp.dml.executed，並記錄 operation、processing duration、affected rows、approval status 與必要的 error category。

完整協定請見 Safe DML。

內建工具的常見錯誤

常見失敗包括：

缺少 MCP 授權上下文；
明確工具允許清單不包含該工具；
資料庫 provider 或連線設定無效；
SQL 並行限制器無法取得 lease（Server busy）；
要求的資料表不在金鑰白名單；
SQL 為空、語法不支援、政策拒絕或 capability 拒絕；
provider 執行失敗。

工具只會回傳受限制的錯誤資訊，不會退回成不受限制的 provider 執行模式。

Custom Tools

已發布的 Custom Tools 會依 MCP 金鑰綁定的 Database Management 項目載入，也可以依名稱加入同一個 AllowedTools。執行時仍會經過資料庫綁定、資料表白名單、安全政策、並行控制與稽核流程；DML Custom Tool 同樣必須走核准管線。

請見 Custom Tools。

語意中繼資料不算第六個內建工具

hs-sql-agent 程式庫確實存在語意管理相關實作，但正式 MCP 金鑰內建工具註冊表，以及管理介面的金鑰管理功能，仍只管理本頁列出的五個工具。因此 hs-sql-agent 文件把語意中繼資料視為由管理介面維護、再由 schema discovery 使用的能力，不把它宣稱成額外的內建 MCP 契約。

請見語意中繼資料。