MCP Toolbox 预置配置详解：用 cloud-sql-postgres-admin 一键搭建 Cloud SQL for PostgreSQL 管理工具

MCP Toolbox 预置配置详解：用 cloud-sql-postgres-admin 一键搭建 Cloud SQL for PostgreSQL 管理工具

【免费下载链接】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 通过--prebuilt标志提供开箱即用的工具集合，其中cloud-sql-postgres-admin是面向 Cloud SQL for PostgreSQL 基础设施管理的预置配置，基于cloud-sql-adminsource 暴露了实例创建、克隆、备份恢复、用户与数据库管理等 11 个 MCP 工具。读完本文，你将了解该预置配置的完整工具清单、环境变量与 IAM 权限模型，并能在源码层面理解每个工具的实现细节与默认参数，从而正确地把 LLM Agent 接入自己的 Cloud SQL 管理工作流。

预置配置概览

cloud-sql-postgres-admin是 mcp-toolbox 内置的预置配置之一，其--prebuilt取值就是cloud-sql-postgres-admin。它对应的完整配置定义在仓库的 cloud-sql-postgres-admin.yaml 中，该文件声明了一个名为cloud-sql-admin-source的 source，以及挂载在它上面的全部工具，最终打包为一个名为cloud_sql_postgres_admin_tools的 toolset：

kind: source name: cloud-sql-admin-source type: cloud-sql-admin defaultProject: ${CLOUD_SQL_POSTGRES_PROJECT:} readOnly: ${CLOUD_SQL_POSTGRES_READONLY:false} --- kind: tool name: create_instance type: cloud-sql-postgres-create-instance source: cloud-sql-admin-source # ... 其余工具定义（get_instance、list_instances 等） --- kind: toolset name: cloud_sql_postgres_admin_tools tools: - create_instance - get_instance - list_instances - create_database - list_databases - create_user - wait_for_operation - postgres_upgrade_precheck - clone_instance - create_backup - restore_backup

官方文档对该配置的说明见 cloud-sql-for-postgresql-admin.md。

环境变量与 Source 配置

该预置配置只依赖两个可选环境变量，均通过 YAML 模板语法${VAR:default}注入到 source 的字段中：

环境变量	默认值	作用
CLOUD_SQL_POSTGRES_PROJECT	空	为 Cloud SQL 基础设施类工具提供默认 GCP 项目 ID，对应 source 的defaultProject字段
CLOUD_SQL_POSTGRES_READONLY	false	设为true时抑制所有具备写能力的管理工具，对应 source 的readOnly字段

这两个字段的实际解析逻辑在 cloud_sql_admin.go 的Config结构体中（L62-L68）：

type Config struct { Name string `yaml:"name" validate:"required"` Type string `yaml:"type" validate:"required"` DefaultProject string `yaml:"defaultProject"` UseClientOAuth bool `yaml:"useClientOAuth"` ReadOnly bool `yaml:"readOnly"` }

从源码结构看，defaultProject会直接影响工具参数：以create_instance为例，cloudsqlpgcreateinstances.go 的buildParams（L175-L187）检测到 source 配置了默认项目后，会把project参数改造为带默认值的参数，并在描述中写明 “This is pre-configured; do not ask for it unless the user explicitly provides a different one”，从而避免 Agent 反复向用户追问项目 ID。

cloud-sql-adminsource 的完整字段参考（含useClientOAuth客户端 OAuth 模式）见 source.md。source 初始化时默认使用 Application Default Credentials 认证并创建sqladmin服务客户端（Initialize，cloud_sql_admin.go L75-L108）；当ReadOnly为true时，Source.IsReadOnly()返回true，用于在工具暴露阶段过滤掉破坏性/写入类工具。

工具清单与参数详解

该预置配置共暴露 11 个工具。下表给出文档声明的功能与对应的工具实现类型，便于与源码对照：

工具名	工具类型（type）	功能
create_instance	cloud-sql-postgres-create-instance	创建新的 Cloud SQL for PostgreSQL 实例
get_instance	cloud-sql-get-instance	查询单个实例信息
list_instances	cloud-sql-list-instances	列出项目中的实例
create_database	cloud-sql-create-database	在实例中创建数据库
list_databases	cloud-sql-list-databases	列出实例中的所有数据库
create_user	cloud-sql-create-users	在实例中创建用户
wait_for_operation	cloud-sql-wait-for-operation	轮询等待异步操作完成
clone_instance	cloud-sql-clone-instance	克隆已有实例
postgres_upgrade_precheck	postgres-upgrade-precheck	主版本升级前检查
create_backup	cloud-sql-create-backup	创建备份
restore_backup	cloud-sql-restore-backup	恢复备份

create_instance：内置 Production / Development 预设

该工具是 PostgreSQL 专属的实例创建工具，实现位于 cloudsqlpgcreateinstances.go。它接受 5 个参数：project、name、databaseVersion（默认POSTGRES_17）、rootPassword、editionPreset（默认Development）。

预设直接映射为 Cloud SQL 的Settings配置（L136-L152）：

预设	可用性	版本系列	机型	数据盘
Development	ZONAL（非 HA）	ENTERPRISE_PLUS	db-perf-optimized-N-2（2 vCPU / 16 GiB）	100 GiBPD_SSD
Production	REGIONAL（HA）	ENTERPRISE_PLUS	db-perf-optimized-N-8（8 vCPU / 64 GiB）	250 GiBPD_SSD

工具默认描述中还会提示 Agent：如果用户想使用其他数据库版本，应主动询问。该工具标注为破坏性操作（tools.NewDestructiveAnnotations），在CLOUD_SQL_POSTGRES_READONLY=true时会被抑制。

get_instance / list_instances / list_databases / create_database

这些工具最终都落到cloud-sql-adminsource 上对sqladminAPI 的封装：

• GetInstance调用service.Instances.Get(project, instance).Do()（cloud_sql_admin.go L228-L239）；
• ListInstance返回精简后的name与instanceType列表（L273-L301）；
• ListDatabase返回每个数据库的name、charset、collation（L241-L271）；
• CreateDatabase调用service.Databases.Insert(...)（L181-L198），属于写操作，受readOnly控制。

create_user：支持 IAM 用户与内置用户

source 的CreateUsers方法（cloud_sql_admin.go L200-L226）根据是否指定 IAM 用户切换user.Type：IAM 用户为CLOUD_IAM_USER，内置用户为BUILT_IN且强制要求password参数，否则返回missing 'password' parameter for non-IAM user错误。

wait_for_operation：指数退避轮询 + 连接指引

wait_for_operation用于等待create_instance等工具返回的长时操作（LRO）完成，实现位于 cloudsqlwaitforoperation.go。它的默认轮询参数值得注意：

• 初始delay3 秒，maxDelay4 分钟，maxRetries10 次，整体超时 30 分钟；
• 预置配置中额外把multiplier设为4（cloud-sql-postgres-admin.yaml L52-L55），意味着轮询间隔按 4 倍指数增长：3s → 12s → 48s → 3.2min → 4min（封顶）……

当被等待的操作是CREATE_DATABASE时，source 还会解析操作结果中的targetLink，取出项目/区域/实例/库名，并结合实例的databaseVersion判定引擎类型，最后渲染一份内置连接指引模板（generateCloudSQLConnectionMessage，cloud_sql_admin.go L447-L520），直接告诉用户如何用CLOUD_SQL_POSTGRES_*环境变量把数据面 MCP server 拉起来。

clone_instance：支持时间点克隆与可用区偏好

CloneInstance（cloud_sql_admin.go L152-L179）构造CloneContext，支持四个可选维度：目标实例名（必填）、PointInTime（时间点克隆）、PreferredZone、PreferredSecondaryZone，最终调用service.Instances.Clone(project, sourceInstanceName, rb).Do()发起克隆。

postgres_upgrade_precheck：主版本升级前检查

PostgreSQL 专属工具，实现位于 cloudsqlpgupgradeprecheck.go。参数为project、instance、targetDatabaseVersion（默认POSTGRES_18）。它调用Instances.PreCheckMajorVersionUpgrade发起 LRO，随后以 5 秒间隔、最长 20 秒窗口轮询操作状态（L180-L211），完成后返回preCheckResponse数组。每条结果包含三级信息：

• ERROR：Action Required，阻断升级，必须先按actionsRequired处理；
• WARNING：Review Recommended，不阻断但建议复核；
• INFO：No Action Needed，仅提示。

该工具使用只读注解（tools.NewReadOnlyAnnotations），即使在readOnly模式下也会保留。

create_backup / restore_backup：三种备份标识的兼容处理

create_backup通过 source 的InsertBackupRun（cloud_sql_admin.go L383-L403）调用service.BackupRuns.Insert，支持指定location与backupDescription。

restore_backup的参数设计比较讲究（cloudsqlrestorebackup.go L86-L98）：target_project、target_instance、backup_id必填，source_project与source_instance仅当backup_id是 BackupRun ID 时才需要。source 端RestoreBackup（cloud_sql_admin.go L405-L445）对backup_id做了三种形态的自动判别：

1. 能解析为 int64 的 BackupRun ID → 填充RestoreBackupContext（此时必须提供 source 项目与实例）；
2. 匹配projects/{p}/locations/{l}/backupVaults/{v}/dataSources/{ds}/backups/{uid}的 BackupDR 备份名 → 填充BackupdrBackup字段；
3. 其余按projects/{p}/backups/{uid}形式填充Backup字段。

这两个工具均标注为破坏性操作，受readOnly模式约束。

IAM 权限与工具可见性的对应关系

官方文档按 Google 角色层级给出了各工具的权限要求，可直接用于设计最小权限策略：

IAM 角色	可用的工具
Cloud SQL Viewer（roles/cloudsql.viewer）	get_instance、list_instances、list_databases、wait_for_operation
Cloud SQL Editor（roles/cloudsql.editor）	全部 viewer 工具 +create_database、create_backup
Cloud SQL Admin（roles/cloudsql.admin）	全部 editor/viewer 工具 +create_instance、create_user、clone_instance、restore_backup

从源码结构看，工具侧通过注解（只读/破坏性）+ source 的readOnly标志实现“抑制写工具”，而具体能否调用成功仍由 GCP IAM 最终裁决，因此建议按上表为服务账号分配角色，与预置配置的工具集对齐。

运行方式与预置配置加载机制

使用预置配置启动 server 只需一条命令，无需手写 YAML：

./toolbox serve --prebuilt cloud-sql-postgres-admin --stdio

--prebuilt值的解析机制在 prebuiltconfigs.go 中：包级变量通过//go:embed tools/*.yaml在编译期把 internal/prebuiltconfigs/tools/ 目录下所有 YAML 嵌入二进制（L24-L32），init时按“去掉.yaml后缀的文件名”作为 key 建立映射（loadPrebuiltToolYAMLs，L62-L92）。因此cloud-sql-postgres-admin.yaml就对应--prebuilt cloud-sql-postgres-admin；若传入不存在的名称，Get会返回not found错误并列出所有可用预置名称（L48-L59）。启动后可通过 Toolbox 内置 Web UI 或 MCP 客户端列举cloud_sql_postgres_admin_toolstoolset 中的工具。

小结

cloud-sql-postgres-admin预置配置把 Cloud SQL for PostgreSQL 的日常基础设施运维浓缩为 11 个语义清晰的 MCP 工具：用两个环境变量即可完成默认项目与只读模式配置，用 IAM 三级角色即可做权限对齐，用--prebuilt cloud-sql-postgres-admin一条命令即可启动。实例创建自带 Production/Development 两套 Enterprise Plus 预设，备份恢复兼容 BackupRun ID 与 BackupDR 命名，长时操作有指数退避轮询兜底——再结合源码中各工具的参数默认值与错误分支（如 cloudsqlpgcreateinstances.go、cloud_sql_admin.go），可以在部署前准确预判 Agent 的实际行为边界。

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