企业官网建设流程全解析

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.viewer（AlloyDB Viewer 角色）即可调用，这一点在 alloydb-postgres-admin.md 中有明确说明。

输入参数详解

该工具接受两个输入参数，其中project必填、location可选，具体如下：

关于 location 的-通配语义

location参数默认值是-，代表跨所有区域列出集群。这意味着即使不显式传入该参数，工具也会拉取项目下全部区域的集群清单。若只需查看特定区域（例如us-central1、us-east1）的集群，则显式传入对应的区域名即可缩小查询范围。

源码中的参数校验逻辑

从源码看，工具在Invoke阶段会对参数做严格校验（alloydblistclusters.go）：

• project必须存在且为非空字符串，否则返回 Agent 级错误invalid or missing 'project' parameter; expected a string；
• location必须是字符串类型，缺失或类型错误同样会返回明确的错误提示。

校验通过后，工具将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 中配置了defaultProject，Agent 不会反复向用户索要项目 ID，直接使用预配置值，用户体验更顺畅；
• 若未配置默认项目，Agent 才会把project作为必填参数向用户询问。

工具配置：在 MCP 服务中声明 alloydb-list-clusters

官方文档示例

原文档给出的最小配置如下（alloydb-list-clusters.md）：

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.

配置字段参考

源码中Config结构还支持可选的baseURL与annotations字段（alloydblistclusters.go），其中annotations可用来显式指定工具注解，未配置时默认采用只读注解。

配套的 source 声明

alloydb-list-clusters必须挂载到一个类型为alloydb-admin的 source 上。source 的最小声明方式参考 source.md：

kind: source name: my-alloydb-admin type: alloydb-admin

source 支持的可选字段包括：

结合工具与 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.go）：

1. MCP 请求到达工具后，Invoke从参数 Map 中取出project与location并校验；
2. 校验通过后调用 source 的ListCluster(ctx, project, location, accessToken)；
3. source 层依据认证方式（ADC 或客户端 OAuth）获取alloydbrestapi.Service，拼接资源路径projects/{project}/locations/{location}；
4. 调用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 token，source 通过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 项目 ID；
  • ALLOYDB_POSTGRES_READONLY（可选）：设为true时抑制写工具（如create_cluster、create_instance、create_user），默认false。
• 权限要求：
  • AlloyDB Viewer（roles/alloydb.viewer）：list/get类工具所需；
  • AlloyDB Admin（roles/alloydb.admin）：create类工具所需。

对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