MCP Toolbox for Databases 中 cloud-storage-delete-bucket 工具详解空桶安全删除、参数校验与错误分类机制【免费下载链接】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-delete-bucket工具展开系统讲解该工具的 YAML 配置方式、调用参数、输出格式与 IAM 权限要求并结合仓库源码剖析其底层的桶校验、破坏性操作标注以及 GCS 错误分类逻辑帮助你在生产环境中安全地将删除 Cloud Storage 空桶能力暴露给 LLM 客户端使用。工具定位与功能边界cloud-storage-delete-bucket是 Cloud Storage 集成下的一组桶管理工具之一其唯一职责是删除一个空的 Cloud Storage 桶。需要特别注意它的功能边界该工具不会先清空桶内对象——它不调用任何对象删除逻辑如果目标桶不为空Cloud Storage 服务会直接拒绝删除操作工具将返回错误调用前必须确保桶内没有任何对象含归档版本由 GCS 服务端判断。从源码看工具与数据源之间通过一个极简的接口契约通信cloudstoragedeletebucket.gotype compatibleSource interface { DeleteBucket(ctx context.Context, bucket string) (map[string]any, error) }任何实现了DeleteBucket方法的 Source 都被视为该工具的兼容数据源这也是官方文档中 Compatible Sources 一节的代码级定义。工具配置在 Toolbox 配置文件中以kind: tool声明该工具。官方文档给出的最小配置示例如下kind: tool name: delete_bucket type: cloud-storage-delete-bucket source: my-gcs-source description: Use this tool to delete empty Cloud Storage buckets.其中source指向一个已配置的 Cloud Storage 数据源。对应的数据源配置示例摘自 Cloud Storage Source 文档kind: source name: my-gcs-source type: cloud-storage project: my-project-id allowedBuckets: - my-app-bucket - my-backup-bucket allowedLocalRoots: - /workspace配置字段参考对照源码中Config结构体的定义cloudstoragedeletebucket.go字段类型必填说明typestring是必须为cloud-storage-delete-bucketsourcestring是要从中删除桶的 Cloud Storage 数据源名称descriptionstring是传递给 LLM 的工具描述Initialize时若为空会直接报错authRequired[]string否需要的前置认证服务列表测试用例覆盖了authRequired: [google-auth-service]的解析annotationsobject否MCP 工具注解缺省时自动套用破坏性操作默认注解见下文破坏性操作标注一个容易忽略但很关键的设计该工具在初始化时会为 MCP 客户端附加注解cloudstoragedeletebucket.gotools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewDestructiveAnnotations),也就是说若配置中未显式提供annotations工具会自动使用NewDestructiveAnnotations生成的注解向 MCP 客户端声明这是一个破坏性操作destructive。客户端可据此决定是否对调用施加确认流程。若业务上希望自定义这一语义可在 YAML 中显式给出annotations覆盖默认值。调用参数工具只接受一个参数参数类型必填说明bucketstring是要删除的空 Cloud Storage 桶名称从参数构造代码可以看到Initialize阶段用parameters.NewStringParameter(bucketKey, Name of the empty Cloud Storage bucket to delete.)注册了该参数因此 LLM 客户端在tools/list中拿到的就是这条参数 schema 与描述。Invoke阶段还会做防御性校验cloudstoragedeletebucket.gomapParams : params.AsMap() bucket, ok : mapParams[bucketKey].(string) if !ok || bucket { return nil, util.NewAgentError( fmt.Sprintf(invalid or missing %s parameter; expected a non-empty string, bucketKey), nil) }即bucket缺失、为空字符串或类型不是 string 时返回AgentErrorinvalid or missing bucket parameter; expected a non-empty string且不会真正调用数据源。这一行为在单元测试TestInvokeValidation中有明确断言参数校验失败时mockSource.called必须为falsecloudstoragedeletebucket_test.go。输出格式删除成功后工具返回如下 JSON 对象字段类型说明bucketstring被删除的 Cloud Storage 桶名deletedboolean是否已删除成功时恒为true这个返回结构由数据源层的DeleteBucket方法直接构造cloudstorage.go// DeleteBucket deletes an empty Cloud Storage bucket. func (s *Source) DeleteBucket(ctx context.Context, bucket string) (map[string]any, error) { if err : s.validateBucket(bucket); err ! nil { return nil, err } if err : s.client.Bucket(bucket).Delete(ctx); err ! nil { return nil, fmt.Errorf(failed to delete bucket %q: %w, bucket, err) } return map[string]any{ bucket: bucket, deleted: true, }, nil }单元测试中的 mock 数据源也以相同结构返回map[string]any{bucket: bucket, deleted: true}印证了契约的一致性cloudstoragedeletebucket_test.go。数据源侧实现细节桶白名单校验cloud-storage数据源在配置层是项目级的单个数据源即可操作凭证有权限访问的任意桶而每个桶级操作包括本工具都会先经过白名单校验func (s *Source) validateBucket(bucket string) error { if len(s.AllowedBuckets) 0 { return nil } for _, b : range s.AllowedBuckets { if b bucket { return nil } } return fmt.Errorf(bucket %q is not allowed by source %q configuration, bucket, s.Name) }cloudstorage.go关键结论省略allowedBuckets时项目内所有桶都允许操作——对于删除这种破坏性操作生产配置建议显式列出白名单把删除范围收敛到确需管理的桶数据源配置中project为必填字段cloudstorage.go用于初始化 GCS 客户端与确定桶归属项目白名单之外的桶错误消息形如bucket xxx is not allowed by source my-gcs-source configuration便于在日志中定位越界调用。错误分类AgentError 与 ServerError工具调用出错时所有来自 GCS 客户端的错误都会经过统一的分类函数ProcessGCSErrorerrors.go。该函数把错误分成两类AgentErrorLLM 可以通过修正输入自行纠正的问题ServerError基础设施/权限层面的失败改输入也没用。与delete-bucket场景直接相关的映射规则如下底层情况分类返回语义storage.ErrBucketNotExistGCS 哨兵错误AgentErrorcloud storage bucket does not existHTTP 404 Not FoundAgentErrorcloud storage resource not foundHTTP 401 UnauthorizedServerErrorcloud storage authentication failedHTTP 403 ForbiddenServerErrorcloud storage permission denied上下文取消/超时ServerErrorcloud storage request cancelled or timed out504 语义HTTP ≥500ServerErrorcloud storage server error502 语义其他未识别错误ServerErrorcloud storage request failed500 语义对删除桶这一动作的实际含义桶不存在被归类为 AgentError提示 Agent 停止用同样的桶名重试改为核对list_buckets的结果权限不足凭证没有删除桶的 IAM 权限会被归类为 ServerError401/403明确告知这是凭证问题而非参数问题桶非空导致的删除失败由 GCS 服务端返回相应错误码后经上述管道透传Agent 可据此先调用list_objects检查桶内容再决定后续动作。工具层对源兼容性的兜底检查同样位于Invoke入口若运行时传入的数据源未实现DeleteBucket配置期ValidateSource应已拦截则返回 500 ServerErrorsource used is not compatible with the toolcloudstoragedeletebucket.go。IAM 权限要求要使该工具可用需要满足两个前提凭证权限Toolbox 使用 Application Default CredentialsADC与 Cloud Storage 交互删除桶属于桶管理操作按照 Cloud Storage 集成文档 与 预构建配置说明桶生命周期操作list_buckets、create_bucket、delete_bucket等需要Storage Adminroles/storage.admin级别的角色。只读角色roles/storage.bucketViewer、roles/storage.objectViewer不足以执行删除。桶必须为空即使拥有足够权限非空桶的删除请求也会被 Cloud Storage 拒绝。预构建配置与工具集若不想手写上述 source tool 配置可以直接使用cloud-storage预构建配置启动 Toolbox--prebuilt取值cloud-storage环境变量CLOUD_STORAGE_PROJECT桶所属的 GCP 项目 ID预构建配置内置了delete_bucket工具其描述为 Deletes an empty bucket.并归入cloud-storage-buckets工具集桶管理list、create、inspect metadata/IAM、delete详见 cloud-storage.md。预构建配置下删除桶所需权限同样是roles/storage.admin如需最小权限部署可按预构建文档中的角色矩阵裁剪暴露的工具集。测试覆盖情况仓库中为该工具提供了两层测试cloudstoragedeletebucket_test.go配置解析测试TestParseFromYamlCloudStorageDeleteBucket验证基本 YAMLname/type/source/description以及带authRequired的 YAML 都能被正确反序列化为cloudstoragedeletebucket.Config调用行为测试TestInvokeValidation用实现DeleteBucket的mockSource验证——bucket为空时返回AgentError且数据源未被调用正常路径下数据源收到正确的桶名并返回{bucket: ..., deleted: true}。这些测试与本文描述的配置字段、参数校验和输出结构一一对应可作为行为验证依据。实操注意事项小结删除前先用list_objects或list_buckets工具确认桶存在且为空避免把 404/非空错误浪费在一次真实调用上生产环境务必在 source 上配置allowedBuckets白名单将delete-bucket的影响面限定在指定桶不要依赖该工具做级联删除——清空桶内对象应通过cloud-storage-delete-object等对象工具完成桶不存在会返回 AgentError而非静默成功因此对 Agent 而言该工具天然不具备幂等成功语义由于工具默认携带 destructive 注解对接的 MCP 客户端可能会要求人工确认这是预期行为而非配置缺陷。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考