mcp-toolbox Cloud SQL for SQL Server 数据源配置、连接链路与工具生态详解【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本文基于 mcp-toolbox 仓库中 Cloud SQL for SQL Server 数据源source的官方文档与配套源码完整讲解cloud-sql-mssql数据源的 YAML 配置字段、IAM 与网络要求、预构建prebuilt配置方式并结合 数据源实现代码 深入剖析其从 ADC 鉴权、mTLS 握手到 SQL 执行的完整连接链路帮助你将 SQL Server 数据库安全地暴露为 MCP 工具供 Agent 调用。关于 Cloud SQL for SQL Server 数据源Cloud SQL for SQL Server 是 Google Cloud 提供的全托管 SQL Server 数据库服务负责帮你完成 SQL Server 数据库的部署、维护、管理与运维。mcp-toolbox 通过cloud-sql-mssql类型的 source让 MCP 客户端如 IDE 中的 AI 助手、Gemini CLI 等能够以自然语言驱动的方式查询和操作你的 Cloud SQL for SQL Server 实例。如果你还没接触过 Cloud SQL for SQL Server可以先参考 Google Cloud 官方文档了解如何创建实例并建立连接再继续阅读本篇。在 mcp-toolbox 中该数据源通过 Go 语言的 source 注册机制接入数据源入口文件 中的init()函数调用sources.Register(cloud-sql-mssql, newConfig)把类型名cloud-sql-mssql绑定到配置解析函数因此 YAML 中type: cloud-sql-mssql是解析该 source 的钥匙。可用工具围绕该数据源mcp-toolbox 提供了一系列通用 SQL 工具定义在 internal/tools/mssql 目录下mssql-sqlexecute_sql执行一条 SQL 语句并返回结果集支持命名/位置参数mssql-list-tableslist_tables列出数据库中的表。以 mssql-sql 工具实现 为例其核心机制包括source 兼容性检查工具通过compatibleSource接口断言 source 必须同时提供MSSQLDB() *sql.DB与RunSQL(ctx, statement, params)两个方法这正是 Source 结构体 对外暴露的能力不兼容时在启动阶段直接报错模板参数与标准参数支持templateParameters对语句文本做占位符替换与parameters以name命名参数或位置参数绑定从源码可以看到它会检测语句中是否包含参数名来决定使用sql.Named还是位置绑定从而同时兼容两种传参风格默认危险操作标注未显式配置annotations时工具默认打上 destructive 注解提醒 Agent 与用户该工具可能修改数据。执行时工具调用source.RunSQL(...)将语句送入数据库这正是下一节要剖析的 source 侧入口。预构建配置Pre-built Configuration除了手写 YAMLmcp-toolbox 还支持一条命令拉起预构建配置--prebuilt取值为cloud-sql-mssql。该配置需要以下环境变量环境变量说明CLOUD_SQL_MSSQL_PROJECTGCP 项目 IDCLOUD_SQL_MSSQL_REGIONCloud SQL 实例所在区域CLOUD_SQL_MSSQL_INSTANCECloud SQL 实例 IDCLOUD_SQL_MSSQL_DATABASE要连接的数据库名CLOUD_SQL_MSSQL_USER数据库用户名CLOUD_SQL_MSSQL_PASSWORD数据库用户密码CLOUD_SQL_MSSQL_IP_TYPE可选IP 类型public或private默认public对应的预构建 YAML 模板见 cloud-sql-mssql.yaml配置细节文档见 Cloud SQL for SQL Server 预构建配置。该预构建配置暴露的工具为execute_sql执行 SQL 查询与list_tables列出数据库中的表。此外仓库还收录了通过 MCP 将 IDE 接入 Cloud SQL for SQL Server 的文档见docs/en/documentation/connect-to/ides/下的 SQL Server 接入指南目录可作为 IDE 侧的配套参考。配置示例与字段参考完整的手写 source 配置示例如下来自 source 文档kind: source name: my-cloud-sql-mssql-instance type: cloud-sql-mssql project: my-project region: my-region instance: my-instance database: my_db user: ${USER_NAME} password: ${PASSWORD} # ipType: private提示使用${ENV_NAME}格式的环境变量替换来管理用户名与密码等敏感信息不要把密钥硬编码进配置文件。字段参考表完整继承自原文档字段类型必填说明typestring是必须为cloud-sql-mssql。projectstring是集群实例所在 GCP 项目的 ID如my-project-id。regionstring是集群所在 GCP 区域名如us-central1。instancestring是集群内 Cloud SQL 实例的名称如my-instance。databasestring是要连接的 Cloud SQL 数据库名如my_db。userstring是连接所用的 SQL Server 用户名如my-mssql-user。passwordstring是SQL Server 用户的密码如my-password。ipTypestring否Cloud SQL 实例的 IP 类型必须是public、private或psc之一。默认public。从源码侧看Config 结构体 中每个必填字段都带有validate:required标签ipType的缺省值在配置解析函数newConfig中被显式初始化为public与文档中“Default: public”的说明完全一致。需求一IAM 权限该数据源默认使用 Cloud SQL Go Connectorcloudsqlconn来授权并建立到 Cloud SQL 实例的 mTLS 连接而 Connector 依赖Application Default CredentialsADC完成对 Cloud SQL 的鉴权。因此你需要为运行 mcp-toolbox 的服务器正确配置 ADC确保对应的 IAM 身份拥有以下角色或等价权限roles/cloudsql.client提示如果从 Compute Engine 上发起连接还要确保 VM 的服务账号具有使用 Cloud SQL Admin API 所需的服务范围scope否则实例发现/连接建立会失败。从源码可以印证这一链路Initialize方法调用initCloudSQLMssqlConnection时通过sources.GetCloudSQLOpts(ipType, userAgent, false)组装 connector 的 dial 选项随后注册名为cloudsql-sqlserver-driver的数据库驱动——这个驱动正是基于cloud.google.com/go/cloudsqlconn/sqlserver/mssql实现的mTLS 与 ADC 鉴权都在 connector 层自动完成。需求二网络ipTypeCloud SQL 同时支持通过公网public IP和内网private IP两种方式连接。你可以在 source 配置中设置ipType为public或private以匹配实例的实际网络配置。无论选择哪种所有连接都使用基于 IAM 的鉴权并以 mTLS 加密。该字段还有第三个别名pscPrivate Service Connect。其取值校验逻辑实现在 IPType 类型定义UnmarshalYAML会把配置值转为小写后与private/public/psc三者比对任何其它取值都会报ipType invalid错误String()方法在值为空时回退返回public这是“缺省即 public”的兜底实现同时它会从上下文读取 User-Agent 注入连接便于 Cloud SQL 侧识别调用来源。需求三数据库用户当前该数据源仅支持标准认证用户名/密码你需要先在 Cloud SQL 中创建 SQL Server 用户然后用该用户登录数据库。注意IAM 角色解决的是“能否建立到实例的连接通道”问题而能否对数据库做查询/写入还取决于该 SQL Server 用户在库内的权限例如SELECT、INSERT等数据库级权限。源码纵深连接建立与 SQL 执行链路数据源实现 只有 200 余行但把“配置 → 连接 → 执行”三步讲得很清楚值得逐段对照理解。1. 连接建立DSN 与驱动注册initCloudSQLMssqlConnection的组装顺序是用project:region:instance三元组构造cloudsql参数连同database与 User-Agentapp name拼成 URL 查询串以sqlserver://user:pass?cloudsql...形式的 DSN 调用sql.Open(cloudsql-sqlserver-driver, ...)驱动采用“按需注册”策略——先检查sql.Drivers()中是否已有cloudsql-sqlserver-driver没有才调用mssql.RegisterDriver(...)注册避免重复注册冲突。值得注意的是sql.Open只做惰性打开并不真正建连。真正的连通性验证发生在Initialize中紧随其后的db.PingContext(ctx)Ping 失败会立即关闭连接池并返回unable to connect successfully错误。也就是说mcp-toolbox 在服务器启动阶段就会 fail-fast配置错误错误的项目/区域/实例、缺 IAM 角色、密码错误会直接暴露在启动日志中而不是等到第一次工具调用时才报错。2. 连接池暴露验证通过后Source结构体持有*sql.DB连接池并通过MSSQLDB()方法暴露给工具层。IsReadOnly()固定返回false——这意味着该 source 不做只读限制配置mssql-sql等可写工具时需要注意数据库账号的授权范围。3. SQL 执行RunSQL 的结果处理RunSQL(ctx, statement, params)是 MCP 工具调用的最终落点其结果处理对理解返回格式很关键通过QueryContext执行逐行Scan到[]any切片再按列名组装成orderedmap.Row保序的 map保证 JSON 序列化后列名顺序稳定便于 LLM 阅读结果对不带结果集的语句DDL/DML 且无 OUTPUT 子句做了专门处理results.Columns()出错时不再中断而是继续走results.Err()检查真实的执行错误此时返回空结果集最后统一检查results.Err()把“行迭代期间的错误”与“查询执行错误”都归并进返回的错误中。这套逻辑使得同一个 source 既能支撑“查表列表”这类元数据查询也能支撑任意 DML/DDL 语句工具层只需关心如何解析返回值。验证与测试资源如果你在接入时遇到问题仓库中提供了多层测试可直接参照或运行数据源单元测试覆盖配置解析、字段校验与连接初始化集成测试针对真实 Cloud SQL for SQL Server 实例的端到端验证GCE 连接测试验证从 Compute Engine 出发的连接场景。小结cloud-sql-mssql数据源是 mcp-toolbox 接入 SQL Server 生态的标准化入口以 8 个配置字段描述“项目 区域 实例 库 账号”以 ADC roles/cloudsql.client mTLS 保证传输与鉴权安全以ipType适配公网/内网/psc 三种网络形态其底层通过 cloudsqlconn 的 SQL Server 驱动惰性建连、启动时 Ping 校验并通过RunSQL以保序行集把结果稳定地交付给 MCP 工具层。理解了这条链路后你可以从容选择手写 YAML 或--prebuilt cloud-sql-mssql两种方式把 SQL Server 数据库安全地交给 AI Agent 使用。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考