MCP Toolbox for Databasescloud-storage-list-buckets 工具详解——枚举 GCS 存储桶的前缀过滤与分页机制【免费下载链接】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 官方文档 cloud-storage-list-buckets 工具说明讲解该工具如何列举指定 GCP 项目下的 Cloud Storage 存储桶bucket包括运行时参数project、prefix、max_results、page_token、在工具配置中固化project/prefix以隐藏运行时参数的机制、输出格式以及底层 Go 实现中的分页器、参数校验与错误分类逻辑。读完本文后你可以编写出可复制、可运行的cloud-storage-list-buckets工具配置并理解其行为在源码层面的完整调用链与验证方式。工具概述它解决什么问题cloud-storage-list-buckets是 MCP Toolbox 面向 Cloud Storage 集成提供的工具类型用于返回某个 GCP 项目中的存储桶列表。按文档定义它默认使用 source 上配置的项目调用时可以传入可选的project参数枚举同一个凭据ADC 或其他认证来源有权访问的其他项目的存储桶。该工具在 MCP 场景下的典型应用是让 LLM Agent 在执行任何读对象、建桶、改 IAM操作之前先完成发现步骤例如列出日志桶这类请求需要先知道项目里有哪些桶名才能进一步调用 cloud-storage-list-objects、cloud-storage-get-bucket-metadata 等工具。从源码结构看工具类型与数据源通过接口解耦工具层定义了一个compatibleSource接口要求数据源实现ListBuckets(ctx, project, prefix, maxResults, pageToken)方法见 cloudstoragelistbuckets.gotype compatibleSource interface { ListBuckets(ctx context.Context, project, prefix string, maxResults int, pageToken string) (map[string]any, error) }ValidateSource会在服务启动时做一次类型断言不匹配即报错见 cloudstoragelistbuckets.go。当前仓库中实现该接口的数据源是cloud-storage类型即下文说明的兼容 Source。兼容的 Sourcecloud-storage 数据源文档中的Compatible Sources一节指向 Cloud Storage 数据源其完整配置说明见 Cloud Storage source 文档。从实现看该 source 的配置结构定义在 cloudstorage.gotype Config struct { Name string yaml:name validate:required Type string yaml:type validate:required Project string yaml:project validate:required AllowedBuckets []string yaml:allowedBuckets,omitempty AllowedLocalRoots []string yaml:allowedLocalRoots,omitempty }其中project字段在 source 层面是必填的validate:required它正是cloud-storage-list-buckets在project参数留空时的回退值。工具与 source 之间通过GetProjectID()暴露该值见 cloudstorage.go。仓库自带的预置配置 cloud-storage.yaml 给出了一个完整可用的示例source 通过环境变量注入项目 ID工具直接引用该 sourcekind: source name: cloud-storage-source type: cloud-storage project: ${CLOUD_STORAGE_PROJECT} --- kind: tool name: list_buckets type: cloud-storage-list-buckets source: cloud-storage-source description: Lists Cloud Storage buckets in the configured project.该预置配置还把list_buckets归入cloud-storage-buckets工具组与create_bucket、get_bucket_metadata、get_bucket_iam_policy、delete_bucket一起构成桶管理工具集见 cloud-storage.yaml。工具配置参考Reference文档给出的完整配置字段如下其中project和prefix是配置级而非仅运行时的可选字段字段类型必填说明typestringtrue必须为cloud-storage-list-buckets。sourcestringtrue用于列举存储桶的 Cloud Storage source 名称。descriptionstringtrue传递给 LLM 的工具描述。projectstringfalse始终使用的项目 ID。设置后运行时project参数被隐藏空字符串则使用 source 配置的项目。prefixstringfalse始终使用的桶名前缀。设置后运行时prefix参数被隐藏。对应到 Go 配置结构project与prefix在源码中使用指针类型来区分未设置和设置了哪怕为空串两种状态见 cloudstoragelistbuckets.gotype Config struct { tools.ConfigBase yaml:,inline Type string yaml:type validate:required Source string yaml:source validate:required Annotations *tools.ToolAnnotations yaml:annotations,omitempty Project *string yaml:project,omitempty Prefix *string yaml:prefix,omitempty }这个指针语义是理解整个工具配置行为的关键nil表示未配置运行时参数可见非nil表示已固化运行时参数从 schema 中移除。Initialize中的参数构建逻辑直接基于这个判断见 cloudstoragelistbuckets.goallParameters : parameters.Parameters{} if cfg.Project nil { allParameters append(allParameters, parameters.NewStringParameter(projectKey, Project ID to list buckets in. When empty, the sources configured project is used., parameters.WithStringDefault())) } if cfg.Prefix nil { allParameters append(allParameters, parameters.NewStringParameter(prefixKey, Filter results to buckets whose names begin with this prefix., parameters.WithStringDefault())) } allParameters append(allParameters, maxResultsParam, pageTokenParam)此外Initialize还要求description非空缺失时直接返回错误并默认套用只读工具注解tools.NewReadOnlyAnnotations与列举这一纯读操作的语义一致。运行时参数Parameters文档定义的运行时参数表如下四个参数全部可选参数类型必填说明projectstringfalse要列举存储桶的项目 ID。留空时使用 source 配置的项目。prefixstringfalse仅返回名称以该前缀开头的桶。max_resultsintegerfalse每页最多返回的桶数。取 0 使用 API 默认值1000负值和超过 1000 的值会被拒绝。page_tokenstringfalse上一次返回的分页 token用于获取下一页结果。这些参数的默认值与说明文字在工具初始化时写入参数清单manifest见 cloudstoragelistbuckets.gomax_results默认为0表示使用 API 默认页大小page_token默认为空串。max_results 的校验规则max_results的取值约束在Invoke中显式校验超过每页上限 1000常量maxResultsLimit或为负值时返回AgentError而不是静默截断见 cloudstoragelistbuckets.go 与 cloudstoragelistbuckets.goconst maxResultsLimit 1000 // ... if maxResults 0 { return nil, util.NewAgentError(fmt.Sprintf(invalid %s parameter: %d must be 0 (use 0 for the API default), maxResultsKey, maxResults), nil) } if maxResults maxResultsLimit { return nil, util.NewAgentError(fmt.Sprintf(invalid %s parameter: %d exceeds the maximum of %d, maxResultsKey, maxResults, maxResultsLimit), nil) }选择AgentError而非ServerError的用意在于这类错误是LLM 可以通过改参数自我纠正的减小页大小或修正符号而基础设施问题认证、配额、5xx则应归为 ServerError。完整的错误分类逻辑见 errors.go 的ProcessGCSError上下文取消/超时映射为网关超时400 映射为 Agent 错误401/403/429/5xx 映射为 Server 错误等。单元测试TestInvokeMaxResultsValidation验证了这一点对max_results 1001和max_results -1工具必须返回*util.AgentError且错误信息包含相应关键词同时 mock source 的ListBuckets不得被调用校验先于任何 API 请求见 cloudstoragelistbuckets_test.go。配置示例可直接复制文档给出了两种典型写法。写法一完整开放——所有参数由调用方决定kind: tool name: list_buckets type: cloud-storage-list-buckets source: my-gcs-source description: Use this tool to list Cloud Storage buckets in the project.此时工具清单中暴露全部 4 个运行时参数project、prefix、max_results、page_token。写法二固化 project 与 prefix——收窄 Agent 的操作面kind: tool name: list_log_buckets type: cloud-storage-list-buckets source: my-gcs-source description: Use this tool to list log buckets in the configured project. project: prefix: logs-这个配置里有两个值得注意的细节project: 显式空串由于是非 nil 的指针值project参数从运行时 schema 中隐藏调用永远回落到 source 配置的项目。这正是想隐藏参数但仍用 source 项目的官方做法——注意它和完全不写project字段参数可见、可被调用方覆盖是两种不同行为。prefix: logs-桶名过滤被固化为logs-prefix参数同样从 schema 中消失Agent 只能列出以logs-开头的桶。测试用例TestConfiguredParametersHiddenAndForwarded精确验证了这个行为配置了Project: baked-project、Prefix: logs-后manifest 中只剩max_results和page_token两个参数而调用时 source 实际收到的是固化的baked-project/logs-见 cloudstoragelistbuckets_test.go。TestEmptyConfiguredProjectHiddenAndForwarded则覆盖Project: 的空串场景验证参数被隐藏且转发空串触发 source 项目回退见 cloudstoragelistbuckets_test.go。输出格式Output Format文档说明工具返回一个 JSON 对象包含两个字段字段类型说明bucketsarrayCloud Storage API 返回的桶元数据bucket metadata。nextPageTokenstring作为下一次调用的page_token传入用于获取下一页无更多页时为空。对应源码中ListBuckets的返回构造见 cloudstorage.govar buckets []*storage.BucketAttrs nextPageToken, err : pager.NextPage(buckets) if err ! nil { return nil, fmt.Errorf(failed to list buckets in project %q: %w, project, err) } return map[string]any{ buckets: buckets, nextPageToken: nextPageToken, }, nil其中buckets是[]*storage.BucketAttrs即 GCS Go 客户端返回的原始桶属性名称、位置、存储类、版本控制状态等 API 提供的字段nextPageToken在最后一页时为空字符串。分页使用的page_token就是上一次响应中的nextPageToken两者一一衔接。源码级实现剖析项目回退与前缀过滤数据源层的ListBuckets是整个工具的核心实现位于 cloudstorage.gofunc (s *Source) ListBuckets(ctx context.Context, project, prefix string, maxResults int, pageToken string) (map[string]any, error) { if project { project s.Project } it : s.client.Buckets(ctx, project) if prefix ! { it.Prefix prefix } ps : maxResults if ps 0 { ps 1000 } pager : iterator.NewPager(it, ps, pageToken) var buckets []*storage.BucketAttrs nextPageToken, err : pager.NextPage(buckets) if err ! nil { return nil, fmt.Errorf(failed to list buckets in project %q: %w, project, err) } return map[string]any{ buckets: buckets, nextPageToken: nextPageToken, }, nil }逐行对应文档语义project 回退if project { project s.Project }直接实现了project 参数留空时使用 source 配置项目的规则。测试TestInvokeProjectPassthrough用 mock source 分别验证了空串与显式覆盖两种传入路径见 cloudstoragelistbuckets_test.go。prefix 过滤只有非空前缀才设置到迭代器的Prefix字段上由 GCS 服务端完成桶名前缀匹配。max_results 归一maxResults 0一律归一为 1000与取 0 使用 API 默认值的文档描述一致。分页器google.golang.org/api/iterator的NewPager负责页大小与续传 tokenNextPage返回的nextPageToken为空即代表已无后续页。配置值与运行时值的合并顺序工具层在Invoke中通过ResolveString合并配置固化值与运行时参数值规则是配置值优先见 params.gofunc ResolveString(cfgVal *string, params map[string]any, key string) string { if cfgVal ! nil { return *cfgVal } val, _ : params[key].(string) return val }这与参数隐藏机制互相印证既然配置值存在时运行时参数已不可见合并逻辑天然以配置为准project: 时配置值为非 nil 空串ResolveString返回空串随后在 source 层触发项目回退——整条链路与文档描述完全吻合。鉴权与错误语义cloud-storagesource 初始化时通过initGCSClient创建 GCS 客户端并附带 Toolbox 的 User-Agent见 cloudstorage.go。凭据遵循 GCP 应用默认凭据ADC解析规则因此能否列举某项目取决于运行凭据对该项目的实际权限列举需要桶级别以上的storage.buckets.list权限权限不足时ProcessGCSError将 403 归类为 Server 错误cloud storage permission denied提示这是环境/权限问题而非调用参数问题。测试矩阵与行为验证该工具的单元测试覆盖了文档中承诺的每一个行为点位于 cloudstoragelistbuckets_test.go可以作为文档—实现一致性的直接证据测试验证点TestParseFromYamlCloudStorageListBucketsYAML 配置含project/prefix固化字段、authRequired能被正确解析为Config结构TestInvokeMaxResultsValidationmax_results越界1001、-1返回AgentError且不调用 sourceTestInvokeProjectPassthrough空串走 source 回退、显式值原样转发TestConfiguredParametersHiddenAndForwarded固化project/prefix后 manifest 仅含max_results、page_token且固化值被转发TestUnsetParametersRemainVisible未固化时 manifest 含全部 4 个参数TestEmptyConfiguredProjectHiddenAndForwardedproject: 隐藏参数并转发空串触发回退集成测试方面仓库在 tests/cloudstorage/cloud_storage_integration_test.go 中提供了针对真实 Cloud Storage 的端到端验证入口需要有效的 GCP 项目与凭据环境可用于在 CI 或本地确认工具的实际返回结构。小结cloud-storage-list-buckets虽然接口简单但它在 MCP Toolbox 中体现了配置即策略的设计同一个工具类型既可以完全开放4 个运行时参数全暴露给 LLM也可以把project/prefix固化为配置指针字段的 nil/非 nil 语义从而收窄 Agent 的操作面甚至用project: 这种空串配置实现隐藏参数 回退 source 项目的精确控制。分页语义max_results的 0 值归一、1000 上限、page_token/nextPageToken衔接与错误分类参数错误归 Agent、权限/基础设施错误归 Server都在 cloudstoragelistbuckets.go 与 cloudstorage.go 中有明确实现并有完整的单元测试佐证。对于需要在 Agent 工作流中做存储桶发现、日志桶盘点或多项目桶巡检的场景这是 Cloud Storage 集成中值得优先配置的工具之一。延伸阅读Cloud Storage 集成索引Cloud Storage source 配置文档Cloud Storage 预置工具组配置GCS 错误分类实现【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考