MCP Toolbox 预置配置 cloud-sql-mssql-admin让 Agent 安全接管 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 Admin 预置配置prebuilt config说明展开完整解读--prebuilt cloud-sql-mssql-admin这一配置的来源、内置的 10 个管理工具、各工具参数与默认值以及 IAM 角色Viewer / Editor / Admin与工具权限的映射关系并结合仓库源码说明该配置是如何被加载和执行的。读完后你可以直接用一条命令把 Cloud SQL Admin API 的管理能力建实例、建库、建用户、备份与克隆等暴露给 MCP 客户端并理解每个工具背后的实际行为。1. 配置概览一个 prebuilt 值拉起整套管理工具链在 MCP Toolbox 中cloud-sql-mssql-admin是一个预置配置prebuilt configuration其对应的--prebuilt取值为cloud-sql-mssql-admin。该预置配置在 docs/en/integrations/cloud-sql-admin/prebuilt-configs/cloud-sql-for-sql-server-admin.md 中定义其本质是仓库内一份内嵌的 YAML 配置文件internal/prebuiltconfigs/tools/cloud-sql-mssql-admin.yaml。该文件声明了1 个cloud-sql-admin类型的 source名称为cloud-sql-admin-sourcedefaultProject取自环境变量CLOUD_SQL_MSSQL_PROJECT10 个 admin 工具全部挂载到该 source 上1 个名为cloud_sql_mssql_admin_tools的 toolset把上述 10 个工具聚合为一个工具集合。YAML 中的 source 段节选kind: source name: cloud-sql-admin-source type: cloud-sql-admin defaultProject: ${CLOUD_SQL_MSSQL_PROJECT:}以及工具与工具集节选完整 10 个工具见下kind: tool name: create_instance type: cloud-sql-mssql-create-instance source: cloud-sql-admin-source --- kind: tool name: wait_for_operation type: cloud-sql-wait-for-operation source: cloud-sql-admin-source multiplier: 4 --- kind: toolset name: cloud_sql_mssql_admin_tools tools: - create_instance - get_instance - list_instances - create_database - list_databases - create_user - wait_for_operation - clone_instance - create_backup - restore_backup值得注意的是wait_for_operation上的multiplier: 4该值覆盖了工具自身的轮询退避倍率工具默认值为 2.0使轮询间隔增长更快适合实例创建这类耗时较长的操作见 internal/tools/cloudsql/cloudsqlwaitforoperation/cloudsqlwaitforoperation.go。2. 预置配置是如何被加载的从--prebuilt到 YAML从源码结构看--prebuilt是一个由字符串列表构成的 CLI 参数帮助文本由可用预置配置名动态拼接而成见 cmd/internal/flags.go。这些配置文件在包初始化阶段通过 Go 的embed.FS机制从 internal/prebuiltconfigs/tools 目录内嵌进二进制并按文件名去掉.yaml后缀作为键建立映射internal/prebuiltconfigs/prebuiltconfigs.go。因此命令行传入的--prebuilt cloud-sql-mssql-admin会精确匹配到文件 internal/prebuiltconfigs/tools/cloud-sql-mssql-admin.yaml若名称不存在Get会返回错误并列出全部可用预置配置名internal/prebuiltconfigs/prebuiltconfigs.go。本地直接启动的命令行形式该形式与仓库中工具自带提示模板给出的启动参数一致见 internal/tools/cloudsql/cloudsqlwaitforoperation/cloudsqlwaitforoperation.go# 默认 serve 模式 toolbox --prebuilt cloud-sql-mssql-admin # stdio 模式供 MCP 客户端以子进程方式接入 toolbox --prebuilt cloud-sql-mssql-admin --stdio对应的 MCP 客户端配置示例{ mcpServers: { cloud-sql-mssql-admin: { command: ./PATH/TO/toolbox, args: [--prebuilt, cloud-sql-mssql-admin, --stdio], env: { CLOUD_SQL_MSSQL_PROJECT: your-project-id } } } }其中CLOUD_SQL_MSSQL_PROJECT会被注入为 source 的defaultProject后续各工具的project参数即以此作为默认值详见第 4 节。3. 底层 sourcecloud-sql-admin预置配置中的 source 类型为cloud-sql-admin它封装了对 Cloud SQL Admin API 的调用客户端。该 source 的完整字段参考见 docs/en/integrations/cloud-sql-admin/source.md字段类型必填说明typestring是固定为cloud-sql-admindefaultProjectstring否Cloud SQL 基础设施工具使用的 Google Cloud 项目 IDuseClientOAuthboolean否为true时使用客户端侧 OAuth 授权否则使用 ADC默认falsereadOnlyboolean否为true时抑制具备写能力的 admin 工具默认false从源码实现看internal/sources/cloudsqladmin/cloud_sql_admin.go初始化逻辑为默认走Application Default CredentialsADC通过google.FindDefaultCredentials获取sqlserviceadminscope 的凭据构造 HTTP 客户端若配置了useClientOAuth: true则不携带服务端凭据改为在每次请求时由 MCP 客户端提供 OAuth 2.0 access token这也是 internal/tools/cloudsql/cloudsqlwaitforoperation/cloudsqlwaitforoperation.go 等工具通过UseClientAuthorization()判断是否需要客户端授权的原因最终基于该 HTTP 客户端创建sqladmin.NewServiceAPI 基址https://sqladmin.googleapis.com供所有 admin 工具调用。也就是说预置配置里只需要defaultProject一个环境变量认证本身交给 ADC例如gcloud auth application-default login之后的默认凭据。4. 十个管理工具逐一解析文档列出的 10 个工具在 YAML 中映射到具体的工具类型如下工具名MCP 暴露名工具类型type实现位置create_instancecloud-sql-mssql-create-instanceinternal/tools/cloudsqlmssql/cloudsqlmssqlcreateinstance/cloudsqlmssqlcreateinstance.goget_instancecloud-sql-get-instanceinternal/tools/cloudsql/cloudsqlgetinstanceslist_instancescloud-sql-list-instancesinternal/tools/cloudsql/cloudsqllistinstancescreate_databasecloud-sql-create-databaseinternal/tools/cloudsql/cloudsqlcreatedatabaselist_databasescloud-sql-list-databasesinternal/tools/cloudsql/cloudsqllistdatabasescreate_usercloud-sql-create-usersinternal/tools/cloudsql/cloudsqlcreateuserswait_for_operationcloud-sql-wait-for-operationinternal/tools/cloudsql/cloudsqlwaitforoperation/cloudsqlwaitforoperation.goclone_instancecloud-sql-clone-instanceinternal/tools/cloudsql/cloudsqlcloneinstancecreate_backupcloud-sql-create-backupinternal/tools/cloudsql/cloudsqlcreatebackuprestore_backupcloud-sql-restore-backupinternal/tools/cloudsql/cloudsqlrestorebackup各工具的官方功能说明与参数文档位于 docs/en/integrations/cloud-sql-admin/tools 目录例如create_instance的参数文档见 docs/en/integrations/cloud-sql-admin/tools/cloudsqlmssqlcreateinstance.mdwait_for_operation见 docs/en/integrations/cloud-sql-admin/tools/cloudsqlwaitforoperation.md。4.1 create_instance面向 SQL Server 的实例创建核心工具create_instance是该预置配置中唯一的 MSSQL 专属工具类型为cloud-sql-mssql-create-instance由 internal/tools/cloudsqlmssql/cloudsqlmssqlcreateinstance/cloudsqlmssqlcreateinstance.go 实现其设计目标是让 Agent 用少数几个参数即可创建出配置合理的实例。参数定义internal/tools/cloudsqlmssql/cloudsqlmssqlcreateinstance/cloudsqlmssqlcreateinstance.go参数说明默认值projectGCP 项目 ID若 source 配置了defaultProject则作为默认值注入且参数描述会提示已预配置除非用户明确给出不同值否则不必再询问source 的 defaultProjectname实例名称无databaseVersionSQL Server 数据库版本SQLSERVER_2022_STANDARDrootPassword实例 root 密码无editionPreset实例预设Production或DevelopmentDevelopment两个预设对应的实际sqladmin.Settings源码中的 switch 分支internal/tools/cloudsqlmssql/cloudsqlmssqlcreateinstance/cloudsqlmssqlcreateinstance.go预设AvailabilityTypeEditionTier数据盘ProductionREGIONALHA/区域级ENTERPRISEdb-custom-4-266244 vCPU / 26 GiB250 GBPD_SSDDevelopmentZONAL非 HA/可用区级ENTERPRISEdb-custom-2-81922 vCPU / 8 GiB100 GBPD_SSD如果传入其他预设值工具会返回 Agent 可读的错误invalid editionPreset: … Must be either Production or Development。该工具在注册时使用 destructive 注解tools.NewDestructiveAnnotationsinternal/tools/cloudsqlmssql/cloudsqlmssqlcreateinstance/cloudsqlmssqlcreateinstance.go默认描述还特别提醒Agent 应询问用户是否需要使用不同的数据库版本。其创建行为的集成测试见 tests/cloudsqlmssql/cloud_sql_mssql_create_instance_integration_test.go。4.2 wait_for_operation轮询操作直至完成并给出后续指引Cloud SQL 的创建/克隆/备份恢复均为长时异步操作返回一个 operation 对象。wait_for_operation工具internal/tools/cloudsql/cloudsqlwaitforoperation/cloudsqlwaitforoperation.go负责阻塞式轮询参数为project与operationoperation ID。从源码可确认其轮询策略internal/tools/cloudsql/cloudsqlwaitforoperation/cloudsqlwaitforoperation.go初始轮询间隔delay默认 3 秒每次失败后间隔乘以multiplier指数退避上限maxDelay默认 4 分钟预置配置中通过multiplier: 4将倍率从默认 2.0 调整为 4最多重试maxRetries次默认 10整体上下文超时 30 分钟工具完成时会附带一段模板化提示告诉用户资源已就绪请配置环境变量启动数据面 MCP server并给出本地 stdio 与远程部署两种场景的CLOUD_SQL_MSSQL_PROJECT/REGION/INSTANCE/DATABASE/USER/PASSWORD环境变量示例internal/tools/cloudsql/cloudsqlwaitforoperation/cloudsqlwaitforoperation.go。这使 Agent 的工作流自然形成闭环create_instance→ 拿到 operation →wait_for_operation阻塞至实例就绪 → 输出连接配置。4.3 其余工具的默认参数行为get_instance、list_instances、create_database、list_databases、create_user、clone_instance、create_backup、restore_backup均为 Cloud SQL 通用 admin 工具位于 internal/tools/cloudsql 各子目录。它们的project参数同样支持source 默认项目机制当 source 配置了defaultProject时project参数会带上默认值并提示无需重复询问与create_instance中的buildParams(project)逻辑一致见 internal/tools/cloudsqlmssql/cloudsqlmssqlcreateinstance/cloudsqlmssqlcreateinstance.go 中对该模式的注释。这些工具对应的验收测试位于 tests/cloudsql 目录如cloud_sql_clone_instance_test.go、cloud_sql_create_backup_test.go、cloud_sql_restore_backup_test.go等。5. IAM 角色与工具权限的映射官方文档为该预置配置定义了三级 IAM 角色到工具的权限映射。由于该 source 默认使用 ADC角色实际上是授予运行 toolbox 的那个身份服务账号或用户的决定了其能安全执行哪些工具IAM 角色可用工具Cloud SQL Viewerroles/cloudsql.viewer只读get_instance、list_instances、list_databases、wait_for_operationCloud SQL Editorroles/cloudsql.editor管理已有资源全部 viewer 工具另加create_database、create_backupCloud SQL Adminroles/cloudsql.admin完全控制全部 editor/viewer 工具另加create_instance、create_user、clone_instance、restore_backup这一映射体现了最小权限原则只读巡检场景只需 Viewer需要建库与备份的运维场景给 Editor只有需要新建实例、创建用户、克隆或恢复备份的完整生命周期管理才需要 Admin。若你希望进一步收紧行为还可以在 source 上设置readOnly: true从服务端抑制写能力工具参考 docs/en/integrations/cloud-sql-admin/source.md 的readOnly字段说明。6. 典型使用场景从零到可连接的 SQL Server 实例将上述工具组合起来一条完整的 Agent 驱动流程如下创建实例调用create_instance指定project、name、rootPassword选择editionPreset开发环境用Development生产用Production版本默认SQLSERVER_2022_STANDARD等待就绪拿到返回的 operation 后调用wait_for_operation工具按3 秒起步、4 倍退避、最长 4 分钟间隔、最多 10 次轮询、30 分钟总超时的策略阻塞等待初始化资源就绪后依次调用create_database建库、create_user建用户、list_databases确认生命周期保护变更窗口前调用create_backup备份需要演练或迁移时调用clone_instance克隆必要时restore_backup恢复。运行前提与限制需要已配置 ADC 的 GCP 凭据或为该预置 source 开启useClientOAuth并由客户端逐请求提供 access token该身份需至少具备上表中的相应 IAM 角色否则对应工具调用会被 API 拒绝该配置只覆盖控制面Cloud SQL Admin API不含直接对 SQL Server 数据面执行 SQL 的工具实例就绪后需另行配置数据面连接工具返回的提示模板即给出所需环境变量。7. 延伸阅读该预置配置所属的 Cloud SQL Admin 集成总览docs/en/integrations/cloud-sql-admin同类预置配置Cloud SQL for MySQL Admin、Cloud SQL for PostgreSQL Admin各工具详细参数文档docs/en/integrations/cloud-sql-admin/tools相关集成测试tests/cloudsql、tests/cloudsqlmssql【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考