MCP Toolbox Cloud Storage 工具详解用 cloud-storage-get-bucket-metadata 读取存储桶元数据【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxcloud-storage-get-bucket-metadata是 MCP Toolbox 为 Google Cloud Storage 提供的只读工具用于获取单个存储桶bucket的完整元数据。当 LLM 需要回答这个桶建在哪个区域、存储类别是什么、打了哪些标签、生命周期规则如何、是否启用了统一桶级访问控制这类问题时这个工具就是答案来源。读完本文你将掌握该工具的配置方式、参数语义、底层调用链与权限要求并能直接在 MCP Toolbox 中落地使用。工具概述一次调用拿到存储桶全量元数据该工具面向的典型场景是存储桶的体检与决策前侦察Agent 在规划数据迁移、评估存储成本、核对标签规范、检查合规配置之前先调用本工具拉取存储桶的元数据快照。工具返回的结构正是 Cloud Storage API 的存储桶元数据结构storage.BucketAttrs字段覆盖Name、Location、StorageClass、Created、Labels、VersioningEnabled、Lifecycle、UniformBucketLevelAccess等核心信息LLM 可以直接基于这些字段做出判断无需再访问 Google Cloud Console。源码实现从 YAML 配置到 API 调用的完整链路该工具在仓库中对应两个核心实现文件工具注册与执行逻辑位于 internal/tools/cloudstorage/cloudstoragegetbucketmetadata/cloudstoragegetbucketmetadata.go底层 GCS 客户端封装位于 internal/sources/cloudstorage/cloudstorage.go。整个调用链可以拆解为四步注册init()中通过tools.Register(cloud-storage-get-bucket-metadata, newConfig)注册工具类型resourceType常量即cloud-storage-get-bucket-metadata。配置解析newConfig用 YAML 解码器将工具配置填充进Config结构体字段包括Type、Source、Annotations和可选的Bucket指针类型用于区分未配置与配置了空串两种状态。初始化校验Initialize阶段强制校验两点——description不能为空若配置了bucket其值必须是非空字符串否则直接报错bucket cannot be empty。执行Invoke中先通过cloudstoragecommon.ResolveString解析 bucket配置值优先其次才是运行时参数空值则返回AgentError随后调用 source 的GetBucketMetadata(ctx, bucket)。底层实现非常直白在 internal/sources/cloudstorage/cloudstorage.go#L342-L352 中可以看到// GetBucketMetadata returns raw bucket metadata from the Cloud Storage client. func (s *Source) GetBucketMetadata(ctx context.Context, bucket string) (*storage.BucketAttrs, error) { if err : s.validateBucket(bucket); err ! nil { return nil, err } attrs, err : s.client.Bucket(bucket).Attrs(ctx) if err ! nil { return nil, fmt.Errorf(failed to get metadata for bucket %q: %w, bucket, err) } return attrs, nil }它先通过validateBucket做桶名校验与allowedBuckets白名单联动然后调用 Google Cloud 官方 Go 客户端storage的Bucket(bucket).Attrs(ctx)拉取原始元数据。执行过程中的错误统一交给cloudstoragecommon.ProcessGCSError转换为对 Agent 友好的错误格式便于 LLM 理解失败原因。值得注意的一点是该工具在初始化时使用tools.NewReadOnlyAnnotations作为默认注解——从源码结构看它是一个纯只读工具不会对存储桶产生任何副作用可以放心暴露给 Agent 使用。前置要求IAM 权限与 Source 配置最小权限根据 docs/en/integrations/cloud-storage/source.md 中的说明Cloud Storage 使用 IAM 控制访问MCP Toolbox 通过 Application Default CredentialsADC完成鉴权。要让cloud-storage-get-bucket-metadata正常工作运行 MCP Toolbox 的 IAM 身份至少需要roles/storage.bucketViewer——对桶元数据的只读访问同时覆盖cloud-storage-list-buckets与本文介绍的cloud-storage-get-bucket-metadata。也就是说所需权限就是能读取目标桶的元数据这一个条件。如果只读工具链list buckets、get object metadata、read object 等已配置了storage.objectViewer仍需要为桶元数据额外授予bucketViewer。Source 配置示例工具本身不持有 GCP 凭据而是通过source字段引用一个已配置的cloud-storage类型 Source。典型的 Source 配置如下kind: source name: my-gcs-source type: cloud-storage project: my-project-id allowedBuckets: - my-app-bucket - my-backup-bucket allowedLocalRoots: - /workspace其中allowedBuckets是可选的桶白名单若省略则凭据有权访问的所有桶都允许操作。该工具运行时对 bucket 的校验validateBucket正是与这份白名单交互的。参数说明该工具只有一个运行时参数parametertyperequireddescriptionbucketstringtrueName of the Cloud Storage bucket to inspect.从源码看这个参数的注册逻辑是有条件的只有在配置中没有预设bucket时Initialize才会把bucket字符串参数追加进工具的参数清单并暴露给 LLM一旦配置中预设了bucket该参数就不会出现在运行时参数 schema 中测试TestUnsetBucketRemainsVisible与TestConfiguredBucketHiddenAndForwarded分别验证了这两种行为。参数解析的优先级定义在 internal/tools/cloudstorage/cloudstoragecommon/params.go 的ResolveString中配置值cfgVal优先只有配置值为 nil 时才回退到运行时参数。调用时 bucket 为空串会被判定为非法返回AgentError。配置示例通用版与固定桶版工具文档给出了两种典型配置均以 MCP Toolbox 的kind: tool资源形式声明。示例一bucket 由 LLM 运行时指定kind: tool name: get_bucket_metadata type: cloud-storage-get-bucket-metadata source: my-gcs-source description: Use this tool to inspect metadata for a Cloud Storage bucket.这种配置下bucket会作为必填运行时参数暴露给 LLMAgent 可以在每次调用时自由选择要检查的桶适合需要探测多个桶的通用场景。示例二bucket 固定写死在配置里kind: tool name: get_app_bucket_metadata type: cloud-storage-get-bucket-metadata source: my-gcs-source description: Use this tool to inspect metadata for the application bucket. bucket: my-app-bucket这种配置下bucket被烘焙进工具定义运行时参数 schema 中不再出现bucket字段工具永远只检查my-app-bucket。它的价值在于安全性与简洁性LLM 无法也无需传入其他桶名从根本上杜绝了误查或越权探测同时减少了每次调用需要传递的参数。对应的解析行为在单元测试 internal/tools/cloudstorage/cloudstoragegetbucketmetadata/cloudstoragegetbucketmetadata_test.go 中有完整覆盖TestParseFromYamlCloudStorageGetBucketMetadata验证基础配置、authRequired配置、bucket预设配置三种 YAML 的解析结果TestConfiguredBucketHiddenAndForwarded预设bucket后manifest 中参数数量为 0且调用时桶名被正确转发到 sourceTestUnsetBucketRemainsVisible未预设时manifest 中保留bucket参数TestEmptyConfiguredBucketRejected预设空串时初始化报错TestInvokeValidation运行时缺失 bucket 返回包含bucket字样的AgentError且不会触发对 source 的调用。输出格式返回的元数据结构工具返回的是 Cloud Storage API 的存储桶元数据Go 侧对应*storage.BucketAttrs字段包括Name——存储桶名称Location——存储桶所在的区域或多区域StorageClass——存储类别如 STANDARD、NEARLINE、COLDLINE 等直接影响成本评估Created——创建时间Labels——键值对标签可用于成本分摊与资源组织VersioningEnabled——是否开启对象版本控制Lifecycle——生命周期管理规则如自动降冷、自动删除UniformBucketLevelAccess——是否启用统一桶级访问控制UBLA这决定了桶内对象是否还能配置独立的 ACL。这些字段共同构成了一次完整的存储桶体检报告Agent 可据此判断存储成本、合规状态与访问控制模型为后续的迁移、清理或优化决策提供依据。配置字段参考fieldtyperequireddescriptiontypestringtrueMust be cloud-storage-get-bucket-metadata.sourcestringtrueName of the Cloud Storage source to get bucket metadata from.descriptionstringtrueDescription of the tool that is passed to the LLM.bucketstringfalseBucket to always inspect. When set, the runtimebucketparameter is hidden. Must not be empty.其中type必须是固定的cloud-storage-get-bucket-metadatasource指向已配置的cloud-storageSource 名称description会原样传递给 LLM用于帮助模型判断何时调用该工具因此建议写成何时使用导向的自然语言描述bucket为可选字段语义如上文所述。实战在预置配置中启用该工具仓库自带的预置工具集 internal/prebuiltconfigs/tools/cloud-storage.yaml 已经包含get_bucket_metadata工具对应type: cloud-storage-get-bucket-metadata并且它被归入cloud-storage-buckets工具组kind: group name: cloud-storage-buckets description: Use these tools when you need to administer cloud storage buckets, including listing and creating buckets, inspecting bucket metadata and access control policies, and deleting buckets. tools: - list_buckets - create_bucket - get_bucket_metadata - get_bucket_iam_policy - delete_bucket也就是说在使用预置配置时只要 Source 指向的项目凭据具备roles/storage.bucketViewerLLM 就能在管理存储桶类任务中自动选用get_bucket_metadata来完成元数据检查。若你希望将检查范围收敛到单一桶只需仿照示例二为工具补充bucket字段即可。常见错误与排查建议现象可能原因处理方式初始化报错description is required工具配置缺少description字段补充面向 LLM 的用途描述初始化报错bucket cannot be empty配置了bucket: 移除该字段或填写真实桶名调用时报invalid or missing bucket parameter运行时未传 bucket 且配置未预设传入非空桶名或在配置中预设bucket调用时报权限类错误IAM 身份缺少roles/storage.bucketViewer为服务身份授予桶元数据读取权限桶不在白名单allowedBuckets未包含目标桶在 Source 配置的白名单中加入目标桶结合上述源码与测试证据cloud-storage-get-bucket-metadata是一个结构简单、行为明确、可读可审计的只读工具配置上注意description必填、bucket预设即隐藏运行时参数这两条规则权限上保证bucketViewer即可让 LLM 稳定、安全地获取存储桶元数据为成本分析、合规巡检与迁移规划类任务提供可靠输入。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/15 3:06:42 · 阅读 1.2k MCP Toolbox Cloud Storage 工具详解：用 cloud-storage-get-bucket-metadata 读取存储桶元数据
MCP Toolbox Cloud Storage 工具详解用 cloud-storage-get-bucket-metadata 读取存储桶元数据【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxcloud-storage-get-bucket-metadata是 MCP Toolbox 为 Google Cloud Storage 提供的只读工具用于获取单个存储桶bucket的完整元数据。当 LLM 需要回答这个桶建在哪个区域、存储类别是什么、打了哪些标签、生命周期规则如何、是否启用了统一桶级访问控制这类问题时这个工具就是答案来源。读完本文你将掌握该工具的配置方式、参数语义、底层调用链与权限要求并能直接在 MCP Toolbox 中落地使用。工具概述一次调用拿到存储桶全量元数据该工具面向的典型场景是存储桶的体检与决策前侦察Agent 在规划数据迁移、评估存储成本、核对标签规范、检查合规配置之前先调用本工具拉取存储桶的元数据快照。工具返回的结构正是 Cloud Storage API 的存储桶元数据结构storage.BucketAttrs字段覆盖Name、Location、StorageClass、Created、Labels、VersioningEnabled、Lifecycle、UniformBucketLevelAccess等核心信息LLM 可以直接基于这些字段做出判断无需再访问 Google Cloud Console。源码实现从 YAML 配置到 API 调用的完整链路该工具在仓库中对应两个核心实现文件工具注册与执行逻辑位于 internal/tools/cloudstorage/cloudstoragegetbucketmetadata/cloudstoragegetbucketmetadata.go底层 GCS 客户端封装位于 internal/sources/cloudstorage/cloudstorage.go。整个调用链可以拆解为四步注册init()中通过tools.Register(cloud-storage-get-bucket-metadata, newConfig)注册工具类型resourceType常量即cloud-storage-get-bucket-metadata。配置解析newConfig用 YAML 解码器将工具配置填充进Config结构体字段包括Type、Source、Annotations和可选的Bucket指针类型用于区分未配置与配置了空串两种状态。初始化校验Initialize阶段强制校验两点——description不能为空若配置了bucket其值必须是非空字符串否则直接报错bucket cannot be empty。执行Invoke中先通过cloudstoragecommon.ResolveString解析 bucket配置值优先其次才是运行时参数空值则返回AgentError随后调用 source 的GetBucketMetadata(ctx, bucket)。底层实现非常直白在 internal/sources/cloudstorage/cloudstorage.go#L342-L352 中可以看到// GetBucketMetadata returns raw bucket metadata from the Cloud Storage client. func (s *Source) GetBucketMetadata(ctx context.Context, bucket string) (*storage.BucketAttrs, error) { if err : s.validateBucket(bucket); err ! nil { return nil, err } attrs, err : s.client.Bucket(bucket).Attrs(ctx) if err ! nil { return nil, fmt.Errorf(failed to get metadata for bucket %q: %w, bucket, err) } return attrs, nil }它先通过validateBucket做桶名校验与allowedBuckets白名单联动然后调用 Google Cloud 官方 Go 客户端storage的Bucket(bucket).Attrs(ctx)拉取原始元数据。执行过程中的错误统一交给cloudstoragecommon.ProcessGCSError转换为对 Agent 友好的错误格式便于 LLM 理解失败原因。值得注意的一点是该工具在初始化时使用tools.NewReadOnlyAnnotations作为默认注解——从源码结构看它是一个纯只读工具不会对存储桶产生任何副作用可以放心暴露给 Agent 使用。前置要求IAM 权限与 Source 配置最小权限根据 docs/en/integrations/cloud-storage/source.md 中的说明Cloud Storage 使用 IAM 控制访问MCP Toolbox 通过 Application Default CredentialsADC完成鉴权。要让cloud-storage-get-bucket-metadata正常工作运行 MCP Toolbox 的 IAM 身份至少需要roles/storage.bucketViewer——对桶元数据的只读访问同时覆盖cloud-storage-list-buckets与本文介绍的cloud-storage-get-bucket-metadata。也就是说所需权限就是能读取目标桶的元数据这一个条件。如果只读工具链list buckets、get object metadata、read object 等已配置了storage.objectViewer仍需要为桶元数据额外授予bucketViewer。Source 配置示例工具本身不持有 GCP 凭据而是通过source字段引用一个已配置的cloud-storage类型 Source。典型的 Source 配置如下kind: source name: my-gcs-source type: cloud-storage project: my-project-id allowedBuckets: - my-app-bucket - my-backup-bucket allowedLocalRoots: - /workspace其中allowedBuckets是可选的桶白名单若省略则凭据有权访问的所有桶都允许操作。该工具运行时对 bucket 的校验validateBucket正是与这份白名单交互的。参数说明该工具只有一个运行时参数parametertyperequireddescriptionbucketstringtrueName of the Cloud Storage bucket to inspect.从源码看这个参数的注册逻辑是有条件的只有在配置中没有预设bucket时Initialize才会把bucket字符串参数追加进工具的参数清单并暴露给 LLM一旦配置中预设了bucket该参数就不会出现在运行时参数 schema 中测试TestUnsetBucketRemainsVisible与TestConfiguredBucketHiddenAndForwarded分别验证了这两种行为。参数解析的优先级定义在 internal/tools/cloudstorage/cloudstoragecommon/params.go 的ResolveString中配置值cfgVal优先只有配置值为 nil 时才回退到运行时参数。调用时 bucket 为空串会被判定为非法返回AgentError。配置示例通用版与固定桶版工具文档给出了两种典型配置均以 MCP Toolbox 的kind: tool资源形式声明。示例一bucket 由 LLM 运行时指定kind: tool name: get_bucket_metadata type: cloud-storage-get-bucket-metadata source: my-gcs-source description: Use this tool to inspect metadata for a Cloud Storage bucket.这种配置下bucket会作为必填运行时参数暴露给 LLMAgent 可以在每次调用时自由选择要检查的桶适合需要探测多个桶的通用场景。示例二bucket 固定写死在配置里kind: tool name: get_app_bucket_metadata type: cloud-storage-get-bucket-metadata source: my-gcs-source description: Use this tool to inspect metadata for the application bucket. bucket: my-app-bucket这种配置下bucket被烘焙进工具定义运行时参数 schema 中不再出现bucket字段工具永远只检查my-app-bucket。它的价值在于安全性与简洁性LLM 无法也无需传入其他桶名从根本上杜绝了误查或越权探测同时减少了每次调用需要传递的参数。对应的解析行为在单元测试 internal/tools/cloudstorage/cloudstoragegetbucketmetadata/cloudstoragegetbucketmetadata_test.go 中有完整覆盖TestParseFromYamlCloudStorageGetBucketMetadata验证基础配置、authRequired配置、bucket预设配置三种 YAML 的解析结果TestConfiguredBucketHiddenAndForwarded预设bucket后manifest 中参数数量为 0且调用时桶名被正确转发到 sourceTestUnsetBucketRemainsVisible未预设时manifest 中保留bucket参数TestEmptyConfiguredBucketRejected预设空串时初始化报错TestInvokeValidation运行时缺失 bucket 返回包含bucket字样的AgentError且不会触发对 source 的调用。输出格式返回的元数据结构工具返回的是 Cloud Storage API 的存储桶元数据Go 侧对应*storage.BucketAttrs字段包括Name——存储桶名称Location——存储桶所在的区域或多区域StorageClass——存储类别如 STANDARD、NEARLINE、COLDLINE 等直接影响成本评估Created——创建时间Labels——键值对标签可用于成本分摊与资源组织VersioningEnabled——是否开启对象版本控制Lifecycle——生命周期管理规则如自动降冷、自动删除UniformBucketLevelAccess——是否启用统一桶级访问控制UBLA这决定了桶内对象是否还能配置独立的 ACL。这些字段共同构成了一次完整的存储桶体检报告Agent 可据此判断存储成本、合规状态与访问控制模型为后续的迁移、清理或优化决策提供依据。配置字段参考fieldtyperequireddescriptiontypestringtrueMust be cloud-storage-get-bucket-metadata.sourcestringtrueName of the Cloud Storage source to get bucket metadata from.descriptionstringtrueDescription of the tool that is passed to the LLM.bucketstringfalseBucket to always inspect. When set, the runtimebucketparameter is hidden. Must not be empty.其中type必须是固定的cloud-storage-get-bucket-metadatasource指向已配置的cloud-storageSource 名称description会原样传递给 LLM用于帮助模型判断何时调用该工具因此建议写成何时使用导向的自然语言描述bucket为可选字段语义如上文所述。实战在预置配置中启用该工具仓库自带的预置工具集 internal/prebuiltconfigs/tools/cloud-storage.yaml 已经包含get_bucket_metadata工具对应type: cloud-storage-get-bucket-metadata并且它被归入cloud-storage-buckets工具组kind: group name: cloud-storage-buckets description: Use these tools when you need to administer cloud storage buckets, including listing and creating buckets, inspecting bucket metadata and access control policies, and deleting buckets. tools: - list_buckets - create_bucket - get_bucket_metadata - get_bucket_iam_policy - delete_bucket也就是说在使用预置配置时只要 Source 指向的项目凭据具备roles/storage.bucketViewerLLM 就能在管理存储桶类任务中自动选用get_bucket_metadata来完成元数据检查。若你希望将检查范围收敛到单一桶只需仿照示例二为工具补充bucket字段即可。常见错误与排查建议现象可能原因处理方式初始化报错description is required工具配置缺少description字段补充面向 LLM 的用途描述初始化报错bucket cannot be empty配置了bucket: 移除该字段或填写真实桶名调用时报invalid or missing bucket parameter运行时未传 bucket 且配置未预设传入非空桶名或在配置中预设bucket调用时报权限类错误IAM 身份缺少roles/storage.bucketViewer为服务身份授予桶元数据读取权限桶不在白名单allowedBuckets未包含目标桶在 Source 配置的白名单中加入目标桶结合上述源码与测试证据cloud-storage-get-bucket-metadata是一个结构简单、行为明确、可读可审计的只读工具配置上注意description必填、bucket预设即隐藏运行时参数这两条规则权限上保证bucketViewer即可让 LLM 稳定、安全地获取存储桶元数据为成本分析、合规巡检与迁移规划类任务提供可靠输入。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考