MCP Toolbox 数据库工具详解使用 alloydb-list-users 工具列出 AlloyDB 集群数据库用户【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox导读alloydb-list-users是 MCP Toolbox for Databases 中 AlloyDB Admin 集成模块提供的只读管理工具用于列出指定 AlloyDB 集群内的全部数据库用户。本文以官方文档为骨架结合仓库源码与预置配置系统讲解该工具的参数含义、YAML 配置方式、底层调用链与典型使用场景帮助你为 Agent 快速接入查询 AlloyDB 用户列表的能力。工具定位AlloyDB 用户管理的只读查询入口在 MCP Toolbox for Databases 中AlloyDB Admin 集成通过alloydb-admin类型的 source 提供面向 Google AlloyDB API 的管理客户端覆盖集群、实例与用户的增删查改等管理操作。alloydb-list-users就是其中负责列出用户的只读工具它只读取数据、不产生任何副作用因此在源码中被归类为只读注解ReadOnly工具。从源码结构看该工具的实现位于 internal/tools/alloydb/alloydblistusers/alloydblistusers.go通过init()中的tools.Register(alloydb-list-users, newConfig)完成类型注册工具在初始化时若未显式提供描述会使用默认描述 Lists all AlloyDB users in a given project, location and cluster.见 alloydblistusers.go#L69-L83并默认套用只读注解tools.NewReadOnlyAnnotations。输入参数说明工具接收三个必填参数均来自官方文档的参数表参数类型必填说明projectstring是要列出用户的 GCP 项目 IDclusterstring是要列出用户的集群 IDlocationstring是集群所在位置例如us-central1三个参数在运行时都会被严格校验在Invoke阶段源码会逐一从参数映射中取出project、location、cluster若缺失或为空会返回 agent 级错误 invalid or missing ... parameter; expected a string见 alloydblistusers.go#L114-L125因此 Agent 调用时必须完整提供三者。defaultProject 对参数展示的影响从源码可以推断project参数的形态与 source 上是否配置了defaultProject有关buildParams在传入非空默认项目时会把默认值烘焙进参数描述与默认值This is pre-configured; do not ask for it unless the user explicitly provides a different one.否则使用普通形式见 alloydblistusers.go#L149-L159。也就是说当 source 配了defaultProject后Agent 无需再向用户反复询问项目 ID只有在用户显式给出其他项目时才需要覆盖。YAML 配置示例官方文档给出了最精简的注册方式kind: tool name: list_users type: alloydb-list-users source: alloydb-admin-source description: Use this tool to list all database users within an AlloyDB cluster其中source必须指向一个已声明的alloydb-admin类型 source即文档中 Compatible Sources 所指的兼容来源。该解析行为有测试用例佐证在 alloydblistusers_test.go 的TestParseFromYaml中同样形式的 YAML 会被解析为alloydblistusers.Config{Type: alloydb-list-users, Source: my-alloydb-admin-source}还验证了authRequired字段的解析。字段参考字段类型必填说明typestring是必须为alloydb-list-userssourcestring是一个alloydb-admin类型 source 的名称descriptionstring否传给 Agent 的工具描述此外从 Config 结构体alloydblistusers.go#L52-L58可以看到还支持name由基类提供、baseURL与annotations等可选字段用于覆盖默认请求地址或自定义工具注解。底层调用链从 Invoke 到 AlloyDB REST APIalloydb-list-users是一次典型的工具 → 兼容 source → 官方 Go SDK调用链Invoke 校验Tool.Invoke先将运行时的 source 断言为compatibleSource接口该接口要求实现GetDefaultProject()、UseClientAuthorization()与ListUsers(...)见 alloydblistusers.go#L45-L49随后校验三个必填参数透传调用以source.ListUsers(ctx, project, location, cluster, accessToken)将参数透传给 sourceREST 请求在 source 实现 alloydbadmin.go#L312-L325 中调用 Google AlloyDB Go SDK 的Projects.Locations.Clusters.Users.List(urlString)其中urlString形如projects/{project}/locations/{location}/clusters/{cluster}实际请求的是https://alloydb.googleapis.com上的 AlloyDB REST API错误处理任何 API 错误都会经util.ProcessGcpError转换为统一的 Toolbox 错误返回给 Agent。当 source 配置了useClientOAuth: true时getService会使用客户端提供的 OAuth 2.0 access token 构造临时 service否则使用 Application Default CredentialsADC初始化全局 service见 alloydbadmin.go#L126-L137。因此该工具天然支持两种鉴权模式无需额外改动工具配置。预置配置alloydb-postgres-admin.yaml 中的开箱用法仓库的预置配置 internal/prebuiltconfigs/tools/alloydb-postgres-admin.yaml 已经把该工具编排进完整的 AlloyDB Admin 工具集source 通过环境变量注入defaultProject与readOnlylist_users与create_user、get_user、create_cluster等工具共同组成alloydb_postgres_admin_toolstoolset。其核心片段如下kind: source name: alloydb-admin-source type: alloydb-admin defaultProject: ${ALLOYDB_POSTGRES_PROJECT:} readOnly: ${ALLOYDB_POSTGRES_READONLY:false} --- kind: tool name: list_users type: alloydb-list-users source: alloydb-admin-source --- kind: toolset name: alloydb_postgres_admin_tools tools: - list_users - get_user - create_user注意readOnly仅在 source 层面抑制写类型工具alloydb-list-users本身始终是只读查询工具。若采用预置配置启动时需注入ALLOYDB_POSTGRES_PROJECT等环境变量具体接入方式可参考该集成入口文档 docs/en/integrations/alloydb-admin/_index.md。典型使用场景与注意事项用户盘点与审计在集群初始化或交接时通过 Agent 一句话列出 xxx 集群的所有用户快速获取用户清单配合创建/获取工具形成闭环先用list_users发现用户再对指定用户调用alloydb-get-user查看详情或调用alloydb-create-user新增用户配合只读运维结合 source 的readOnly: true可以构建纯只读的管理面 Agentlist_users是其中安全的组成部分。使用时要特别注意project、location、cluster三个参数缺一不可且location必须与集群创建时使用的区域一致例如us-central1否则 AlloyDB API 会返回资源未找到类错误。若在配置了defaultProject的 source 上运行Agent 通常会直接复用默认项目而不再询问。小结alloydb-list-users是一个小而实用的只读管理工具文档层面只需三行参数与一段 YAML 即可接入源码层面则完整展示了工具配置 → 兼容 source 接口 → 官方 Go SDK → AlloyDB REST API的标准调用链并天然兼容 ADC 与客户端 OAuth 两种鉴权方式。无论是手动编写配置还是直接复用alloydb-postgres-admin.yaml预置工具集都能快速让 Agent 具备 AlloyDB 用户列表查询能力。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考