MCP Toolbox 的 alloydb-list-instances 工具通过 MCP 高效枚举 AlloyDB 实例【免费下载链接】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 中的alloydb-list-instances工具。该工具面向 Google Cloud AlloyDB 管理员用于按项目、集群与区域枚举 AlloyDB 实例的详细信息实例名称、类型、IP 地址、状态、配置等并通过 MCP 协议暴露给 Agent。读完本文你将掌握该工具的全部输入参数、YAML 配置方式、底层源码调用链、认证方式与所需 IAM 权限能够直接在自己的 MCP 配置中启用并调用它。工具定位AlloyDB Admin 集成中的实例枚举能力alloydb-list-instances是alloydb-admin集成下的管理类工具之一属于只读操作。它的核心能力是从 AlloyDB API 检索一个项目下、某个或全部集群与区域中的全部实例信息。与 alloydb-get-instance 的精确获取单个实例不同本工具用于批量盘点典型场景包括运维巡检时快速列出某项目全部区域的实例及其运行状态在创建实例、扩容等变更操作前确认目标集群已有的实例拓扑例如判断是否已存在主实例或只读池作为 Agent 驱动的自动化运维流程中的第一步为后续get_instance、create_instance等操作提供上下文。从源码看该工具的资源类型常量定义为alloydb-list-instances并在包初始化阶段通过tools.Register注册属于 internal/tools/alloydb/alloydblistinstances/alloydblistinstances.go 中可被配置系统识别的标准工具类型。输入参数详解工具接收三个参数其中仅project为必填。官方文档参数表如下参数类型描述必填projectstring要列出实例的 GCP 项目 ID。是clusterstring要列出实例的集群 ID。使用-获取所有集群的结果。默认-。否locationstring集群所在区域例如us-central1。使用-获取所有区域的结果。默认-。否源码中的参数定义与默认值在 alloydblistinstances.go 的 buildParams 函数 中参数的构造逻辑与文档表格完全对应project必填字符串参数。若 source 中配置了defaultProject则该参数会被预填默认值并向 Agent 提示该值已预配置除非用户显式提供不同值否则不要询问见 resolveParamslocation可选默认值为-表示查询所有区域cluster可选默认值为-表示查询所有集群。这里-是一个约定的通配值并非真实的集群或区域名。当调用者同时使用location: -与cluster: -时等价于列出整个项目下所有实例。参数校验与错误处理在 Tool.Invoke 方法 中工具对参数做了严格的类型与空值校验project缺失或为空字符串时返回 Agent 错误invalid or missing project parameter; expected a stringlocation、cluster非 string 类型时同样返回明确的 Agent 错误参数合法后调用 source 的ListInstance(ctx, project, location, cluster, accessToken)执行查询若底层 API 调用失败则通过util.ProcessGcpError将 GCP 错误规范化后返回。兼容的 Sourcealloydb-adminalloydb-list-instances必须与alloydb-admin类型的 source 配合使用。alloydb-adminsource 在 internal/sources/alloydbadmin/alloydbadmin.go 中定义本质上是 Google AlloyDB REST API 的客户端封装负责处理认证、HTTP 客户端构建与对projects.locations.clusters.instances资源的管理操作。两种认证方式该 source 支持两种认证详见 source.mdApplication Default CredentialsADC默认方式。source 初始化时通过google.FindDefaultCredentials(ctx, alloydbrestapi.CloudPlatformScope)获取默认凭据并使用 OAuth2 token source 构建 HTTP 客户端见 alloydbadmin.go客户端侧 OAuth当useClientOAuth: true时source 不再预先加载凭据而是在每次请求时使用客户端如浏览器提供的 OAuth 2.0 access token见 getService。工具层通过RequiresClientAuthorization返回 source 的UseClientAuthorization()结果即是否启用了useClientOAuth从而决定 MCP 会话是否需要携带访问令牌。Source 配置示例kind: source name: my-alloydb-admin type: alloydb-admin若需要客户端 OAuth 认证kind: source name: my-oauth-alloydb-admin type: alloydb-admin useClientOAuth: trueSource 支持的完整字段如下字段类型必填描述typestring是必须为alloydb-admin。defaultProjectstring否供 AlloyDB 基础设施工具使用的默认 GCP 项目 ID。useClientOAuthboolean否为true时使用客户端侧 OAuth否则使用 ADC。默认false。readOnlyboolean否为true时抑制具备写能力的 admin 工具。默认false。在 MCP 配置中声明工具在 MCP Toolbox 中工具通过 YAML 配置文件声明。官方文档给出的最小配置如下kind: tool name: list_instances type: alloydb-list-instances source: alloydb-admin-source description: Use this tool to list all AlloyDB instances for a given project, cluster and location.配置字段说明字段类型必填描述typestring是必须为alloydb-list-instances。sourcestring是一个alloydb-admin类型 source 的名称。descriptionstring否传给 Agent 的工具描述。此外从源码的Config结构体见 alloydblistinstances.go可以看出工具还支持以下可选字段baseURL自定义 API 端点地址默认使用https://alloydb.googleapis.comannotations工具注解用于声明读写属性等元信息authRequired继承自ConfigBase声明该工具需要哪些认证服务的授权。若不显式提供description初始化逻辑会自动使用默认描述Lists all AlloyDB instances in a given project, location and cluster.见 Initialize。使用预置配置快速启用仓库提供了名为alloydb-postgres-admin的预置配置一键即可获得包含list_instances在内的整套 AlloyDB 管理工具集见 alloydb-postgres-admin.yaml。启动时通过--prebuilt alloydb-postgres-admin引用即可。该配置支持两个环境变量ALLOYDB_POSTGRES_PROJECT可选作为 AlloyDB 基础设施工具的默认 GCP 项目 ID映射到 source 的defaultProjectALLOYDB_POSTGRES_READONLY可选设为true时抑制create_cluster、create_instance、create_user等写工具映射到 source 的readOnly。预置配置内list_instances的完整声明为kind: tool name: list_instances type: alloydb-list-instances source: alloydb-admin-source底层调用链从 MCP 请求到 AlloyDB REST API理解工具的内部实现有助于排查问题与预估其行为。整个调用链如下MCP 请求到达Agent 调用list_instances工具MCP 服务器根据配置类型找到已注册的alloydb-list-instances处理器参数解析与校验Tool.Invoke从parameters.ParamValues中提取project、location、cluster三个字符串并做校验见 InvokeSource 分发工具将参数连同 access token 传给 source 的ListInstance方法REST API 调用ListInstance构造资源路径projects/{project}/locations/{location}/clusters/{cluster}并调用 AlloyDB REST 客户端service.Projects.Locations.Clusters.Instances.List(urlString).Do()见 alloydbadmin.go。当location或cluster为-时该路径中的占位符即变为-对应 AlloyDB REST API 的列出所有语义结果返回API 返回的实例列表含名称、类型、IP、状态、配置等字段以结构化数据形式直接返回给 Agent。需要注意的是由于工具通过通配符-实现全项目/全区域枚举若项目规模较大返回的实例列表可能较长Agent 端应做好分页或筛选处理。测试验证与配置正确性保障仓库为alloydb-list-instances提供了完整的单元测试见 alloydblistinstances_test.go重点验证 YAML 配置解析基础配置解析验证kind: tool、name、type: alloydb-list-instances、source、description的完整解析结果与预期一致authRequired 解析验证authRequired列表可同时声明多个认证服务能正确解析并绑定到工具配置。这些测试通过server.UnmarshalPrimitiveConfig走真实配置解析链路确保文档中的 YAML 示例可以直接复制使用。此外tests/alloydb/alloydb_mcp_test.go 与 tests/alloydb/alloydb_integration_test.go 中还包含针对 MCP 会话与真实 AlloyDB 环境的集成测试。权限要求alloydb-list-instances属于只读list操作。根据 alloydb-postgres-admin 预置配置文档 的说明AlloyDB Viewerroles/alloydb.viewerlist与get类工具含list_instances所需的最低权限AlloyDB Adminroles/alloydb.admincreate类写工具create_cluster、create_instance、create_user所需权限。因此仅使用只读工具时为服务账号或用户授予roles/alloydb.viewer即可若配置中同时启用了写工具则需要roles/alloydb.admin。当使用客户端侧 OAuthuseClientOAuth: true时访问令牌对应的用户/主体同样需要满足上述角色要求。小结alloydb-list-instances是 MCP Toolbox 中面向 AlloyDB 的轻量只读管理工具三个参数、一个alloydb-adminsource、一段 YAML 配置即可接入 MCP 生态。它通过 AlloyDB REST API 的Instances.List接口实现枚举支持-通配符实现全项目、全区域、全集群的批量盘点并具备完整的参数校验、错误规范化与测试保障。配合 alloydb-create-instance、alloydb-get-instance 等其他工具可以构建出先盘点、再决策、后变更的完整 AlloyDB 运维闭环。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考