MCP Toolbox 数据库管理：alloydb-list-clusters 工具详解——列出 AlloyDB 集群的配置与实战
MCP Toolbox 数据库管理alloydb-list-clusters 工具详解——列出 AlloyDB 集群的配置与实战【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox导读alloydb-list-clusters是 MCP Toolbox for Databases 中 AlloyDB Admin 集成族提供的核心只读管理工具用于在指定 GCP 项目与区域location下列出 AlloyDB 集群的详细信息集群名称、状态、配置等。本文以 官方工具文档 为骨架结合仓库内的 Go 源码实现、预置配置与测试用例完整讲解该工具的输入参数、YAML 配置方法、底层 API 调用链与权限要求帮助你快速在自己的 MCP 服务配置中启用并正确使用它。工具概述它能做什么alloydb-list-clusters属于alloydb-admin集成族中的管理类工具它调用 Google AlloyDB REST API 的集群列表接口返回给定项目下全部或指定区域内的 AlloyDB 集群信息包括集群名称cluster name集群状态state集群配置configuration以及其他 AlloyDB API 返回的集群属性从源码实现看该工具被设计为只读操作在 alloydblistclusters.go 中Initialize默认使用tools.NewReadOnlyAnnotations作为工具注解并且对应 IAM 权限只需要roles/alloydb.viewerAlloyDB Viewer 角色即可调用这一点在 alloydb-postgres-admin.md 中有明确说明。输入参数详解该工具接受两个输入参数其中project必填、location可选具体如下参数类型说明是否必填projectstring要列出集群的 GCP 项目 ID是locationstring要列出集群的区域如us-central1使用-表示所有区域默认值为-否关于 location 的-通配语义location参数默认值是-代表跨所有区域列出集群。这意味着即使不显式传入该参数工具也会拉取项目下全部区域的集群清单。若只需查看特定区域例如us-central1、us-east1的集群则显式传入对应的区域名即可缩小查询范围。源码中的参数校验逻辑从源码看工具在Invoke阶段会对参数做严格校验alloydblistclusters.goproject必须存在且为非空字符串否则返回 Agent 级错误invalid or missing project parameter; expected a stringlocation必须是字符串类型缺失或类型错误同样会返回明确的错误提示。校验通过后工具将project、location与 access token 一并传给 source 的ListCluster方法由 source 层完成真正的 API 请求。默认项目的烘焙机制defaultProject值得注意的是工具的project参数并非一成不变。在 buildParams 中有一个细节如果alloydb-adminsource 配置了defaultProject工具会把它烘焙进project参数的默认值并自动改写参数描述为The GCP project ID. This is pre-configured; do not ask for it unless the user explicitly provides a different one.该 GCP 项目 ID 已预配置除非用户显式提供不同值否则不要询问。这意味着在实际的 Agent 工作流中若在 source 中配置了defaultProjectAgent 不会反复向用户索要项目 ID直接使用预配置值用户体验更顺畅若未配置默认项目Agent 才会把project作为必填参数向用户询问。工具配置在 MCP 服务中声明 alloydb-list-clusters官方文档示例原文档给出的最小配置如下alloydb-list-clusters.mdkind: tool name: list_clusters type: alloydb-list-clusters source: alloydb-admin-source description: Use this tool to list all AlloyDB clusters in a given project and location.配置字段参考字段类型必填说明typestringtrue必须为alloydb-list-clusterssourcestringtrue一个alloydb-admin类型 source 的名称descriptionstringfalse传给 Agent 的工具描述namestringtrue工具在当前配置中的唯一名称由配置框架要求见 alloydblistclusters_test.go 中的解析断言源码中Config结构还支持可选的baseURL与annotations字段alloydblistclusters.go其中annotations可用来显式指定工具注解未配置时默认采用只读注解。配套的 source 声明alloydb-list-clusters必须挂载到一个类型为alloydb-admin的 source 上。source 的最小声明方式参考 source.mdkind: source name: my-alloydb-admin type: alloydb-adminsource 支持的可选字段包括字段类型必填说明typestringtrue必须为alloydb-admindefaultProjectstringfalseAlloyDB 基础设施工具默认使用的 GCP 项目 IDuseClientOAuthbooleanfalse为true时使用客户端侧 OAuth由客户端如浏览器为每次请求提供 OAuth 2.0 access token否则使用 Application Default CredentialsADC。默认falsereadOnlybooleanfalse设为true时抑制具备写能力的 Admin 工具。默认false结合工具与 source 的完整配置示例kind: source name: alloydb-admin-source type: alloydb-admin defaultProject: my-gcp-project --- kind: tool name: list_clusters type: alloydb-list-clusters source: alloydb-admin-source description: Use this tool to list all AlloyDB clusters in a given project and location.底层调用链与实现原理工具层从参数到 REST 调用的完整链路alloydb-list-clusters的完整调用链如下依据 alloydblistclusters.go 与 alloydbadmin.goMCP 请求到达工具后Invoke从参数 Map 中取出project与location并校验校验通过后调用 source 的ListCluster(ctx, project, location, accessToken)source 层依据认证方式ADC 或客户端 OAuth获取alloydbrestapi.Service拼接资源路径projects/{project}/locations/{location}调用service.Projects.Locations.Clusters.List(urlString).Do()发起 REST 请求见 alloydbadmin.go返回的即是 AlloyDB API 的集群列表响应。认证方式ADC 与客户端 OAuth 二选一source 的初始化逻辑alloydbadmin.go决定了认证路径默认Application Default Credentials通过google.FindDefaultCredentials获取默认凭证使用oauth2.NewClient构造带凭证的 HTTP 客户端并注入 User-Agent客户端 OAuth当useClientOAuth: true时每次请求由客户端传入 access tokensource 通过oauth2.StaticTokenSource为当次请求构造服务客户端见getService方法。从源码结构可以推断两种认证模式最终都汇入同一个alloydbrestapi.Service调用只是客户端构造方式不同对工具使用方透明。兼容性校验工具与 source 的强绑定工具声明了compatibleSource接口alloydblistclusters.go要求挂载的 source 必须实现GetDefaultProject()、UseClientAuthorization()与ListCluster(...)三个方法。ValidateSource会在启动阶段校验若 source 类型不兼容会直接报错invalid source for alloydb-list-clusters tool。这保证了该工具只能与alloydb-adminsource 搭配使用。使用预置配置快速启用仓库提供了开箱即用的预置配置alloydb-postgres-admin一条命令即可获得包含list_clusters在内的整套 AlloyDB Postgres 管理工具集。在 alloydb-postgres-admin.yaml 中可以看到预置配置定义了alloydb-admin-source并将list_clusters注册进alloydb_postgres_admin_tools工具集与create_cluster、get_cluster、list_instances、create_user等 10 个工具组成完整的管理闭环。使用方式详见 alloydb-postgres-admin.md--prebuilt值alloydb-postgres-admin环境变量ALLOYDB_POSTGRES_PROJECT可选作为 AlloyDB 基础设施工具默认使用的 GCP 项目 IDALLOYDB_POSTGRES_READONLY可选设为true时抑制写工具如create_cluster、create_instance、create_user默认false。权限要求AlloyDB Viewerroles/alloydb.viewerlist/get类工具所需AlloyDB Adminroles/alloydb.admincreate类工具所需。对alloydb-list-clusters而言只需为运行 MCP 服务的账号授予roles/alloydb.viewer即可正常列出集群。常见使用场景与注意事项全量盘点不传location或显式传-一次性列出项目下所有区域的集群适合做集群资产盘点与审计区域聚焦传入具体区域名如us-central1缩小范围减少响应体量适合排查特定区域的集群状态配合只读模式在 source 或预置配置中开启readOnly/ALLOYDB_POSTGRES_READONLY可确保服务仅保留只读能力list_clusters这类只读工具不受影响而写类工具会被抑制参数错误处理project缺失或为空时会直接返回 Agent 错误提示配置阶段务必确认项目 ID 已通过参数或 source 的defaultProject提供。参考文档alloydb-list-clusters 工具文档alloydb-admin source 文档AlloyDB Postgres Admin 预置配置文档工具源码工具配置解析测试alloydb-admin source 实现预置配置 YAML【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考