MCP Toolbox MySQL 执行 SQL 工具mysql-execute-sql完整指南配置、原理与实战【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本篇技术指南围绕 MCP Toolbox for Databases 开源项目中的mysql-execute-sql工具展开详细讲解它如何通过 MCP Server 让 LLM/Agent 对 MySQL 数据库执行 SQL 语句覆盖工具配置、数据源对接、参数说明、底层调用链与安全注解机制。读完本文你将掌握如何在自己的 MySQL 实例上配置并使用该工具理解它与mysql数据源之间的协作方式并能基于源码与测试用例深入排查问题。工具概述mysql-execute-sql 是什么mysql-execute-sql是 MCP Toolbox for Databases项目根目录为 MySQL 集成提供的一个工具tool。根据官方文档mysql-execute-sql.md的定义它负责对 MySQL 数据库执行一条 SQL 语句。该工具的行为非常简单直接接收一个输入参数sql要执行的 SQL 语句字符串将该语句在工具配置中指定的source数据源上执行并返回执行结果。注意源自官方文档此工具面向开发者辅助工作流developer assistant workflows强调 human-in-the-loop人在回路不应用于生产环境中的自动化 Agent。这是因为它可以执行任意 SQL包括 DDL/DML 写操作在生产场景下风险过高。从源码看该工具在 mysqlexecutesql.go 中以mysql-execute-sql为注册名通过包内init()函数调用tools.Register注册到全局工具注册表与 MySQL 集成下其他工具如mysql-list-tables、mysql-get-query-plan等见 tools 目录并列。兼容的数据源mysql-execute-sql需要挂在某个数据源source之上。官方文档通过{{ compatible-sources othersintegrations/cloud-sql-mysql}}声明其兼容来源即原生 MySQL 数据源type: mysql详见 source.mdGoogle Cloud SQL for MySQL 数据源integrations/cloud-sql-mysql见 cloud-sql-mysql 集成文档。这一约束在源码中有严格校验。工具定义了compatibleSource接口mysqlexecutesql.go要求数据源必须实现type compatibleSource interface { MySQLPool() *sql.DB RunSQL(context.Context, string, []any) (any, error) }当调用方传入不兼容的数据源时Invoke会返回客户端错误 source used is not compatible with the toolmysqlexecutesql.goValidateSource也会在初始化阶段拒绝类型不匹配的数据源。原生mysql数据源mysql.go同时实现了MySQLPool()与RunSQL()因此天然兼容。配置 mysql-execute-sql 工具最小 YAML 配置示例官方文档给出的工具配置示例如下kind: tool name: execute_sql_tool type: mysql-execute-sql source: my-mysql-instance description: Use this tool to execute sql statement.四个字段均为必填含义如下依据 Reference 表格 与 Config 结构体fieldtyperequireddescriptionkindstringtrue声明资源类型为工具固定为toolnamestringtrue工具实例名称在配置文件中唯一例如execute_sql_tooltypestringtrue工具类型必须为mysql-execute-sqlsourcestringtrue执行 SQL 的数据源名称必须指向配置文件中已定义的type: mysql数据源descriptionstringtrue传递给 LLM 的工具描述LLM 会据此决定何时调用该工具建议写清楚适用场景name、description、authRequired等通用字段来自tools.ConfigBase内联到 Config 中。其中description在Initialize阶段被强制校验——为空会直接报错description is required for tool %qmysqlexecutesql.go。可选配置authRequired 与 annotations虽然官方文档的 Reference 只列了三个核心字段但源码表明工具还支持两个可选配置项kind: tool name: execute_sql_tool type: mysql-execute-sql source: my-mysql-instance description: Use this tool to execute sql statement. authRequired: - my-google-auth-service annotations: destructiveHint: trueauthRequired声明调用该工具所需的认证服务列表解析行为已被单元测试覆盖见 mysqlexecutesql_test.go 中的TestParseFromYamlExecuteSqlannotations覆盖默认的 MCP Tool AnnotationsdestructiveHint/readOnlyHint/idempotentHint/openWorldHint与 MCP 规范中的 tool annotations 对应见 tools.go。配置 MySQL 数据源source工具本身不携带连接信息真正的数据库连接由mysql数据源负责。参考 source.md一个完整的 source 配置如下kind: source name: my-mysql-instance type: mysql host: 127.0.0.1 port: 3306 database: my_db user: ${USER_NAME} password: ${PASSWORD} # Optional TLS and other driver parameters. For example, enable preferred TLS: # queryParams: # tls: preferred queryTimeout: 30s # Optional: query timeout durationfieldtyperequireddescriptiontypestringtrue必须为mysqlhoststringtrue连接地址如127.0.0.1portstringtrue连接端口如3306userstringfalseMySQL 用户名passwordstringfalse用户密码databasestringfalse要连接的数据库名queryTimeoutstringfalse查询执行超时时间如30s、2m默认不设超时queryParamsmapstring,stringfalse传递给驱动的任意 DSN 参数如tls: preferred、charset: utf8mb4可用于启用 TLS 或其他连接选项sqlCommenterbooleanfalse覆盖全局--sql-commenter开关设置时优先于全局标志省略时遵循全局设置在源码层面数据源初始化逻辑位于 mysql.go 的initMySQLConnectionPool基于go-sql-driver/mysql构建 DSNuser与password成对生效无 user 时忽略 password默认注入parseTimetrue参数用户自定义的queryParams会合并进参数表空值被跳过queryTimeout通过time.ParseDuration解析后映射为驱动层的ReadTimeout解析失败会返回 invalid queryTimeout 错误将当前进程的 UserAgent 写入 DSN 的ConnectionAttributesprogram_name便于在 MySQL 侧追踪流量来源连接池建立后会执行PingContext验证连通性失败则关闭连接池并报错mysql.go。安全建议源自官方文档 tip使用${ENV_NAME}形式的环境变量替换例如${MYSQL_USER}、${MYSQL_PASSWORD}不要把明文密钥硬编码进配置文件。仓库预置配置 mysql.yaml 正是这样做的。底层执行原理一条 SQL 的完整旅程当 LLM 调用该工具时MCP Server 会路由到Tool.Invoke其执行链路mysqlexecutesql.go大致如下类型断言将sources.Source断言为compatibleSource失败则返回错误参数提取从paramsMap中取出sql字符串非字符串类型返回 Agent 错误日志记录以 Debug 级别记录将要执行的 SQLexecuting mysql-execute-sql tool query: ...便于排障执行调用source.RunSQL(ctx, sqlStr, nil)执行参数列表为空切片错误归一化执行失败时通过util.ProcessGeneralError转换为统一格式的 ToolboxError 返回。数据源侧 RunSQL 的实现原生mysql数据源的RunSQLmysql.go完成真正的数据库交互先用sqlcommenter.PrependComment为语句附加 SQLCommenter 注释受全局--sql-commenter或 source 级sqlCommenter控制该参数定义于 mysql.go通过连接池QueryContext执行语句并取出列名与列类型逐行Scan数据使用mysqlcommon.ConvertToType做类型归一化结果按orderedmap.Row保持列顺序组装为 JSON 友好的结构返回。类型转换细节JSON 列的防双重序列化ConvertToTypemysqlcommon.go有一个值得注意的细节当列类型为字符串/字节/sql.NullString且数据库类型名为JSON时会先对原始字节做json.Unmarshal再返回对象避免后续再次序列化造成双重编码其余数值类型保持原样返回。这意味着查询JSON类型的列时返回给 LLM 的是可直接使用的结构化对象而非转义后的字符串。安全注解只读数据源下的动态降级mysql-execute-sql默认被标记为**破坏性destructive**注解——Initialize中调用tools.NewDestructiveAnnotations作为默认值mysqlexecutesql.go因为任意 SQL 可能包含INSERT/UPDATE/DELETE/DDL。但源码实现了动态注解翻转mysqlexecutesql.go当所连接的数据源处于只读模式src.IsReadOnly()返回 true时工具会自动把destructiveHint翻转为 false、readOnlyHint翻转为 true同时保留用户自定义的idempotentHint、openWorldHint。这一行为在 TestGetAnnotations 中有完整覆盖nil source → 保持默认破坏性注解读写 source → 保持默认破坏性注解只读 source → 动态翻转为只读注解只读 source 显式只读 base → 仍为只读只读 source 自定义 hints → 仅翻转 readOnly/destructive 两项保留其余自定义 hint。这意味着在只读副本上配置该工具时MCP 客户端与 LLM 会自动感知到它只读的属性从而减少误写风险。开箱即用预置配置与工具集仓库为 MySQL 提供了开箱即用的预置配置 mysql.yaml其中定义了一个名为mysql-source的 source主机/端口/账号/密码全部通过环境变量注入MYSQL_HOST、MYSQL_PORT、MYSQL_DATABASE、MYSQL_USER、MYSQL_PASSWORDqueryTimeout预设为30s定义了名为execute_sql的mysql-execute-sql工具实例直接指向mysql-source同时定义了两个工具集toolsetdata由execute_sql、list_tables、get_query_plan组成面向数据读写与查询场景monitor由get_query_plan、list_active_queries、list_all_locks、list_table_fragmentation、list_table_stats、list_tables_missing_unique_indexes、show_query_stats组成面向实例监控与诊断。你可以直接复用这份预置配置只需把工具名改成符合自己语义的名字并确保source字段与实际的 source 名称一致。测试与验证如何确认配置正确仓库为mysql-execute-sql提供了单元测试 mysqlexecutesql_test.go可用于验证YAML 解析正确性TestParseFromYamlExecuteSql模拟一个包含authRequired的完整配置断言解析出的ConfigName/Description/AuthRequired/Type/Source与期望完全一致注解动态翻转逻辑TestGetAnnotations覆盖只读/读写数据源与自定义注解的各种组合。在本地执行go test ./internal/tools/mysql/...即可运行上述测试快速确认工具注册、配置解析链路没有问题真实数据库联调则需要可访问的 MySQL 实例或 Cloud SQL for MySQL 环境。最佳实践小结限定使用场景仅在开发者辅助、human-in-the-loop 的工作流中使用生产 Agent 不应直接暴露任意 SQL 执行能力严格的最小权限为工具配置独立、最小权限的 MySQL 用户该数据源仅使用标准认证需先创建可登录的 MySQL 用户参考 source.md使用环境变量注入密钥${ENV_NAME}占位符替代硬编码密码善用只读数据源查询类场景可指向只读副本工具注解会自动降级为只读降低误写风险写好 description该字段直接决定 LLM 何时选择调用此工具描述应覆盖典型用途如执行 SQL 查询/写入语句与限制合理设置 queryTimeout避免长时间运行的查询拖垮连接池30s是仓库预置配置的默认值。更完整的 MySQL 工具集清单查询计划、表统计、锁分析、碎片整理等可在 tools 文档目录 中继续探索。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
