MCP Toolbox for Databases 的 singlestore-execute-sql 工具：动态执行 SQL 的完整配置与实现原理

MCP Toolbox for Databases 的 singlestore-execute-sql 工具：动态执行 SQL 的完整配置与实现原理

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

singlestore-execute-sql是 MCP Toolbox for Databases（本仓库）为 SingleStore 数据源提供的一种 tool 类型，它接收一个sql参数，将 LLM/Agent 生成的任意 SQL 语句直接投递到指定的 SingleStore 实例上执行。本文以官方文档 singlestore-execute-sql.md 为骨架，结合仓库内的源码实现（singlestoreexecutesql.go、singlestore.go）与预置配置（singlestore.yaml），完整讲解它的适用场景、YAML 配置方法、底层调用链与安全边界。读完本文，你将能独立为 SingleStore 数据源声明并运行一个可被 Agent 动态调用的 SQL 执行工具，并理解它与固定语句工具singlestore-sql的取舍。

工具定位：一条由 Agent 动态拼装的 SQL

在 MCP Toolbox for Databases 的工具体系中，singlestore-execute-sql是一个动态 SQL 执行工具：它不像singlestore-sql那样在配置期用statement固定一条查询模板，而是只暴露一个名为sql的字符串入参，运行时把 Agent（LLM）给出的整条 SQL 原样交给底层连接池执行。

官方文档明确给出了它的使用边界：

Note:This tool is intended for developer assistant workflows with human-in-the-loop and shouldn't be used for production agents.

也就是说，它面向有人工参与的开发助手场景（如开发调试、临时查询、Schema 探索），并不适合作为生产环境中的无人值守 Agent 工具。原因很直观：动态 SQL 把语句生成权完全交给了模型，权限与审计控制相对薄弱，必须有开发者在环路中把关。

从源码看，这一设计在实现层面同样被刻意强调了破坏性：在 singlestoreexecutesql.go 中，工具初始化时显式使用tools.NewDestructiveAnnotations作为默认注解，向 MCP 客户端标注这是一类具有破坏能力的工具（可执行任意 DDL/DML），引导客户端做额外的确认与防护。

与 singlestore-sql 的分工

仓库在同一目录下还提供了固定语句工具 singlestore-sql。两者构成互补：

预置配置 singlestore.yaml 正是这一分工的体现：execute_sql使用singlestore-execute-sql类型负责自由执行，而list_tables使用singlestore-sql类型内置一段查询INFORMATION_SCHEMA的固定语句。

配置一个 singlestore-execute-sql 工具

工具在tools.yaml（或任意被加载的配置文件中）以kind: tool声明，官方文档给出的最小示例：

kind: tool name: execute_sql_tool type: singlestore-execute-sql source: my-s2-instance description: Use this tool to execute sql statement

其中source必须指向一个已声明的 SingleStore 数据源（type: singlestore），description会作为该工具对 LLM 的说明文本，直接决定 Agent 何时选择调用它，因此应写得足够具体。

字段参考表

对照实现 singlestoreexecutesql.go，Config还支持一个可选字段annotations（类型为tools.ToolAnnotations，对应 YAML 中的annotations），可用于覆盖默认的破坏性注解；description在Initialize阶段被强制校验——为空会直接报错description is required for tool %q（见 L70-L72），这与参考表中的 required 语义一致。

更完整的配置示例

kind: tool name: execute_sql_tool type: singlestore-execute-sql source: my-s2-instance description: | Use this tool to execute SQL statements on the SingleStore instance. Only use this when the user explicitly asks to run or inspect SQL. Never guess table or column names. annotations: title: Execute SQL readOnlyHint: false destructiveHint: true

前置条件：声明 SingleStore 数据源

source指向的数据源在 source.md 中有完整说明。SingleStore 数据源仅使用标准用户名密码认证（需先在数据库中创建用户并授权）。基础配置：

kind: source name: my-singlestore-source type: singlestore host: 127.0.0.1 port: 3306 database: my_db user: ${USER_NAME} password: ${PASSWORD} queryTimeout: 30s # Optional: query timeout duration

字段参考表（数据源）

TLS 连接配置

数据源默认tls=preferred（服务端支持则启用 SSL/TLS，否则回退明文）。需要强制时通过connectionParams覆盖：

# 强制 TLS 并校验服务端证书 kind: source name: my-singlestore-source type: singlestore host: svc-abc123.svc.singlestore.com port: 3306 database: my_db user: ${USER_NAME} password: ${PASSWORD} connectionParams: tls: "true"

# 强制 TLS 但跳过证书校验 connectionParams: tls: "skip-verify"

# 完全关闭 TLS connectionParams: tls: "false"

提示：建议使用${ENV_NAME}形式的环境变量替换（如${SINGLESTORE_PASSWORD}），不要把密钥硬编码进配置文件。

从实现看，这些细节在 singlestore.go 的initSingleStoreConnectionPool中得到印证：连接池默认tls=preferred，queryTimeout会被解析为 DSN 的readTimeout；用户传入的connectionParams在最后统一覆写默认值，且空值会被跳过。同时该函数固定设置了vector_type_project_format=JSON等驱动参数，为 SingleStore 的向量能力（配合JSON_ARRAY_PACK()）预留了支持。

使用预置配置快速起步

如果不想手写数据源与工具，可以直接使用仓库提供的预置配置 singlestore.yaml，它通过--prebuilt singlestore加载（详见 prebuilt-configs/singlestore.md），依赖以下环境变量：

加载后会生成execute_sql（singlestore-execute-sql 类型，即本文主角）与list_tables两个工具，并打包进名为singlestore-database-tools的 toolset，方便在 MCP 客户端中整体暴露。

底层执行链路：从参数到结果

理解singlestore-execute-sql的运行时行为，只需抓住 Invoke 方法 这条链路：

1. 参数校验：工具在Initialize阶段注册唯一参数sql（string 类型）；调用时把sql从参数表中取出并断言为字符串，否则返回 Agent 错误。
2. 类型兼容检查：Invoke通过compatibleSource接口（要求实现SingleStorePool()与RunSQL(context.Context, string, []any)）校验source是否为兼容数据源，不匹配会返回source used is not compatible with the tool（500）。
3. 执行：调用source.RunSQL(ctx, sqlStr, nil)——注意第三参为nil，即不携带任何绑定参数，语句以原样字符串执行。
4. 结果物化：底层 RunSQL 通过QueryContext执行查询，逐行读取列元数据与类型，借助mysqlcommon.ConvertToType将数据库原始值转换为可序列化的 Go 值，最终以[]map[string]any（列名 → 值）的形式返回给 MCP 客户端。因此 Agent 拿到的是一个结构化 JSON 数组，而非原始文本流。

此外，工具覆盖了EmbedParams（见 L121-L124），在嵌入参数时会应用 pgvector 向量格式化；查询执行前还会通过 context 中的 logger 输出 debug 日志（executing ... tool query: <sql>），便于排查 Agent 实际提交的语句。

安全实践建议

结合文档声明与源码事实，使用singlestore-execute-sql时应遵循以下原则：

1. 只用于有人工在场的开发助手流程，生产 Agent 请改用参数化工具singlestore-sql（工具配置文档）并声明固定statement。
2. 为数据库用户做最小授权：工具能执行任意 SQL，尽量用只读或限定 Schema 的账号连接（可在数据源处配置），从源头收敛风险。
3. 依赖破坏性注解：默认的NewDestructiveAnnotations会向客户端传递破坏性语义，配合人工确认（human-in-the-loop）再放行 DDL/DML。
4. 善用queryTimeout：为数据源设置合理的查询超时（如30s），避免 Agent 拼出的失控长查询长期占用连接。
5. 描述信息要"教"模型：description会原样进入 LLM 上下文，建议像预置配置那样写明"仅当用户明确要求执行/检查 SQL 时使用"，减少误调用。

小结

singlestore-execute-sql是 MCP Toolbox for Databases 中面向 SingleStore 的动态 SQL 执行入口：配置仅需type、source、description三个字段，运行时通过compatibleSource接口将sql参数原样下发到连接池执行并返回结构化结果。它与singlestore-sql的"自由执行 vs 固定语句"分工、默认破坏性注解、tls/queryTimeout等数据源细节，共同构成了一个清晰、可审计、适合开发助手的 SQL 工具面。需要进一步扩展时，可继续阅读 SingleStore 集成总览 及其 工具清单。

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox