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-toolboxMCP 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的 toolsetkind: 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_READONLYfalse设为true时抑制所有具备写能力的管理工具对应 source 的readOnly字段这两个字段的实际解析逻辑在 cloud_sql_admin.go 的Config结构体中L62-L68type 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 的buildParamsL175-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服务客户端Initializecloud_sql_admin.go L75-L108当ReadOnly为true时Source.IsReadOnly()返回true用于在工具暴露阶段过滤掉破坏性/写入类工具。工具清单与参数详解该预置配置共暴露 11 个工具。下表给出文档声明的功能与对应的工具实现类型便于与源码对照工具名工具类型type功能create_instancecloud-sql-postgres-create-instance创建新的 Cloud SQL for PostgreSQL 实例get_instancecloud-sql-get-instance查询单个实例信息list_instancescloud-sql-list-instances列出项目中的实例create_databasecloud-sql-create-database在实例中创建数据库list_databasescloud-sql-list-databases列出实例中的所有数据库create_usercloud-sql-create-users在实例中创建用户wait_for_operationcloud-sql-wait-for-operation轮询等待异步操作完成clone_instancecloud-sql-clone-instance克隆已有实例postgres_upgrade_precheckpostgres-upgrade-precheck主版本升级前检查create_backupcloud-sql-create-backup创建备份restore_backupcloud-sql-restore-backup恢复备份create_instance内置 Production / Development 预设该工具是 PostgreSQL 专属的实例创建工具实现位于 cloudsqlpgcreateinstances.go。它接受 5 个参数project、name、databaseVersion默认POSTGRES_17、rootPassword、editionPreset默认Development。预设直接映射为 Cloud SQL 的Settings配置L136-L152预设可用性版本系列机型数据盘DevelopmentZONAL非 HAENTERPRISE_PLUSdb-perf-optimized-N-22 vCPU / 16 GiB100 GiBPD_SSDProductionREGIONALHAENTERPRISE_PLUSdb-perf-optimized-N-88 vCPU / 64 GiB250 GiBPD_SSD工具默认描述中还会提示 Agent如果用户想使用其他数据库版本应主动询问。该工具标注为破坏性操作tools.NewDestructiveAnnotations在CLOUD_SQL_POSTGRES_READONLYtrue时会被抑制。get_instance / list_instances / list_databases / create_database这些工具最终都落到cloud-sql-adminsource 上对sqladminAPI 的封装GetInstance调用service.Instances.Get(project, instance).Do()cloud_sql_admin.go L228-L239ListInstance返回精简后的name与instanceType列表L273-L301ListDatabase返回每个数据库的name、charset、collationL241-L271CreateDatabase调用service.Databases.Insert(...)L181-L198属于写操作受readOnly控制。create_user支持 IAM 用户与内置用户source 的CreateUsers方法cloud_sql_admin.go L200-L226根据是否指定 IAM 用户切换user.TypeIAM 用户为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设为4cloud-sql-postgres-admin.yaml L52-L55意味着轮询间隔按 4 倍指数增长3s → 12s → 48s → 3.2min → 4min封顶……当被等待的操作是CREATE_DATABASE时source 还会解析操作结果中的targetLink取出项目/区域/实例/库名并结合实例的databaseVersion判定引擎类型最后渲染一份内置连接指引模板generateCloudSQLConnectionMessagecloud_sql_admin.go L447-L520直接告诉用户如何用CLOUD_SQL_POSTGRES_*环境变量把数据面 MCP server 拉起来。clone_instance支持时间点克隆与可用区偏好CloneInstancecloud_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数组。每条结果包含三级信息ERRORAction Required阻断升级必须先按actionsRequired处理WARNINGReview Recommended不阻断但建议复核INFONo Action Needed仅提示。该工具使用只读注解tools.NewReadOnlyAnnotations即使在readOnly模式下也会保留。create_backup / restore_backup三种备份标识的兼容处理create_backup通过 source 的InsertBackupRuncloud_sql_admin.go L383-L403调用service.BackupRuns.Insert支持指定location与backupDescription。restore_backup的参数设计比较讲究cloudsqlrestorebackup.go L86-L98target_project、target_instance、backup_id必填source_project与source_instance仅当backup_id是 BackupRun ID 时才需要。source 端RestoreBackupcloud_sql_admin.go L405-L445对backup_id做了三种形态的自动判别能解析为 int64 的 BackupRun ID → 填充RestoreBackupContext此时必须提供 source 项目与实例匹配projects/{p}/locations/{l}/backupVaults/{v}/dataSources/{ds}/backups/{uid}的 BackupDR 备份名 → 填充BackupdrBackup字段其余按projects/{p}/backups/{uid}形式填充Backup字段。这两个工具均标注为破坏性操作受readOnly模式约束。IAM 权限与工具可见性的对应关系官方文档按 Google 角色层级给出了各工具的权限要求可直接用于设计最小权限策略IAM 角色可用的工具Cloud SQL Viewerroles/cloudsql.viewerget_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从源码结构看工具侧通过注解只读/破坏性 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-L32init时按“去掉.yaml后缀的文件名”作为 key 建立映射loadPrebuiltToolYAMLsL62-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/14 18:29:59 · 阅读 1.2k 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-toolboxMCP 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的 toolsetkind: 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_READONLYfalse设为true时抑制所有具备写能力的管理工具对应 source 的readOnly字段这两个字段的实际解析逻辑在 cloud_sql_admin.go 的Config结构体中L62-L68type 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 的buildParamsL175-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服务客户端Initializecloud_sql_admin.go L75-L108当ReadOnly为true时Source.IsReadOnly()返回true用于在工具暴露阶段过滤掉破坏性/写入类工具。工具清单与参数详解该预置配置共暴露 11 个工具。下表给出文档声明的功能与对应的工具实现类型便于与源码对照工具名工具类型type功能create_instancecloud-sql-postgres-create-instance创建新的 Cloud SQL for PostgreSQL 实例get_instancecloud-sql-get-instance查询单个实例信息list_instancescloud-sql-list-instances列出项目中的实例create_databasecloud-sql-create-database在实例中创建数据库list_databasescloud-sql-list-databases列出实例中的所有数据库create_usercloud-sql-create-users在实例中创建用户wait_for_operationcloud-sql-wait-for-operation轮询等待异步操作完成clone_instancecloud-sql-clone-instance克隆已有实例postgres_upgrade_precheckpostgres-upgrade-precheck主版本升级前检查create_backupcloud-sql-create-backup创建备份restore_backupcloud-sql-restore-backup恢复备份create_instance内置 Production / Development 预设该工具是 PostgreSQL 专属的实例创建工具实现位于 cloudsqlpgcreateinstances.go。它接受 5 个参数project、name、databaseVersion默认POSTGRES_17、rootPassword、editionPreset默认Development。预设直接映射为 Cloud SQL 的Settings配置L136-L152预设可用性版本系列机型数据盘DevelopmentZONAL非 HAENTERPRISE_PLUSdb-perf-optimized-N-22 vCPU / 16 GiB100 GiBPD_SSDProductionREGIONALHAENTERPRISE_PLUSdb-perf-optimized-N-88 vCPU / 64 GiB250 GiBPD_SSD工具默认描述中还会提示 Agent如果用户想使用其他数据库版本应主动询问。该工具标注为破坏性操作tools.NewDestructiveAnnotations在CLOUD_SQL_POSTGRES_READONLYtrue时会被抑制。get_instance / list_instances / list_databases / create_database这些工具最终都落到cloud-sql-adminsource 上对sqladminAPI 的封装GetInstance调用service.Instances.Get(project, instance).Do()cloud_sql_admin.go L228-L239ListInstance返回精简后的name与instanceType列表L273-L301ListDatabase返回每个数据库的name、charset、collationL241-L271CreateDatabase调用service.Databases.Insert(...)L181-L198属于写操作受readOnly控制。create_user支持 IAM 用户与内置用户source 的CreateUsers方法cloud_sql_admin.go L200-L226根据是否指定 IAM 用户切换user.TypeIAM 用户为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设为4cloud-sql-postgres-admin.yaml L52-L55意味着轮询间隔按 4 倍指数增长3s → 12s → 48s → 3.2min → 4min封顶……当被等待的操作是CREATE_DATABASE时source 还会解析操作结果中的targetLink取出项目/区域/实例/库名并结合实例的databaseVersion判定引擎类型最后渲染一份内置连接指引模板generateCloudSQLConnectionMessagecloud_sql_admin.go L447-L520直接告诉用户如何用CLOUD_SQL_POSTGRES_*环境变量把数据面 MCP server 拉起来。clone_instance支持时间点克隆与可用区偏好CloneInstancecloud_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数组。每条结果包含三级信息ERRORAction Required阻断升级必须先按actionsRequired处理WARNINGReview Recommended不阻断但建议复核INFONo Action Needed仅提示。该工具使用只读注解tools.NewReadOnlyAnnotations即使在readOnly模式下也会保留。create_backup / restore_backup三种备份标识的兼容处理create_backup通过 source 的InsertBackupRuncloud_sql_admin.go L383-L403调用service.BackupRuns.Insert支持指定location与backupDescription。restore_backup的参数设计比较讲究cloudsqlrestorebackup.go L86-L98target_project、target_instance、backup_id必填source_project与source_instance仅当backup_id是 BackupRun ID 时才需要。source 端RestoreBackupcloud_sql_admin.go L405-L445对backup_id做了三种形态的自动判别能解析为 int64 的 BackupRun ID → 填充RestoreBackupContext此时必须提供 source 项目与实例匹配projects/{p}/locations/{l}/backupVaults/{v}/dataSources/{ds}/backups/{uid}的 BackupDR 备份名 → 填充BackupdrBackup字段其余按projects/{p}/backups/{uid}形式填充Backup字段。这两个工具均标注为破坏性操作受readOnly模式约束。IAM 权限与工具可见性的对应关系官方文档按 Google 角色层级给出了各工具的权限要求可直接用于设计最小权限策略IAM 角色可用的工具Cloud SQL Viewerroles/cloudsql.viewerget_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从源码结构看工具侧通过注解只读/破坏性 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-L32init时按“去掉.yaml后缀的文件名”作为 key 建立映射loadPrebuiltToolYAMLsL62-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考