MCP Toolbox for Databases 的 cloud-storage-copy-object 工具在 LLM Agent 中安全复制 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 集成文档 cloud-storage-copy-object 为主线讲解该工具如何把一个 Cloud Storage 对象复制到同一桶或跨桶的目标位置并结合 工具实现源码 与 source 层实现 剖析参数隐藏机制、桶白名单校验和错误分类的底层逻辑。读完后你可以直接在自己的 toolbox.yaml 中配置该工具并理解 LLM 每次调用时参数如何流转、哪些错误 Agent 可自行纠正、哪些属于基础设施故障。工具定位与核心语义cloud-storage-copy-object工具将一个对象从一个 Cloud Storage 位置复制到另一个位置。它有三个关键语义源桶与目标桶相互独立source_bucket与destination_bucket是两个分离的参数因此目标位置可以是同一桶内的另一个对象名也可以是完全不同的桶覆盖式写入目标位置已存在对象时会被直接替换这与 Cloud Storage 原生 copy 语义一致源码注释中明确说明Existing destination objects are replaced服务端复制复制由 Cloud Storage 服务完成对象数据不经过 MCP server 本地内存因此对大对象的复制不会受到本地带宽或内存限制。源码中的CopyObject实现印证了最后一点cloudstorage.go#L544-L567// CopyObject copies an object to a destination object. The destination may be // in the same bucket or a different bucket. Existing destination objects are // replaced, matching Cloud Storages copy semantics without preconditions. func (s *Source) CopyObject(ctx context.Context, sourceBucket, sourceObject, destinationBucket, destinationObject string) (map[string]any, error) { ... attrs, err : dst.CopierFrom(src).Run(ctx) ... }可以看到它直接调用 GCS Go 客户端的dst.CopierFrom(src).Run(ctx)复制完成后从返回的对象属性中提取Size与ContentType作为结果。参考字段Reference配置一个cloud-storage-copy-object工具时各字段的完整定义如下对应文档的 Reference 一节fieldtyperequireddescriptiontypestring必填必须为cloud-storage-copy-objectsourcestring必填用于执行复制的 Cloud Storage source 名称descriptionstring必填工具描述会传递给 LLM 辅助其决定是否调用source_bucketstring可选每次调用固定使用的源桶。设置后source_bucket会从工具参数列表中隐藏destination_bucketstring可选每次调用固定使用的目标桶。设置后destination_bucket会从工具参数列表中隐藏该工具兼容cloud-storage类型的 sourcesource 需在 toolbox 配置中单独声明并指定project等字段参见 cloud-storage source 配置 中的Config结构name、type、project均为必填可选allowedBuckets桶白名单与allowedLocalRoots本地路径白名单。YAML 配置示例文档给出两种典型配置形态这里完整继承并补充注释。形态一完全参数化。四个参数全部暴露给 LLM适合通用复制场景kind: tool name: copy_object type: cloud-storage-copy-object source: my-gcs-source # 引用已定义的 cloud-storage 类型 source description: Use this tool to copy Cloud Storage objects.形态二固定桶、只暴露对象路径。源桶与目标桶写死在工具配置里LLM 只需决定复制哪个对象到哪个对象名。这是归档、日志轮转等固定流向场景的推荐做法kind: tool name: copy_reports type: cloud-storage-copy-object source: my-gcs-source description: Use this tool to copy reports into the archive bucket. source_bucket: analytics-exports # 固定源桶从参数列表中移除 destination_bucket: analytics-archive # 固定目标桶从参数列表中移除仓库自带的预构建配置 cloud-storage.yaml 中同样定义了copy_object工具第 86-90 行并将其归入cloud-storage-objects工具组组描述为管理对象文件——列举、读取、写入、复制、移动、删除对象并获取元数据可作为生产配置的参照。调用参数Parameters工具暴露给 LLM 的参数如下表这是 Agent 每次调用时实际填写的输入parametertyperequireddescriptionsource_bucketstring是包含源对象的 Cloud Storage 桶名称source_objectstring是源桶内完整的对象名路径例如path/to/file.txtdestination_bucketstring是要复制进入的目标桶名称destination_objectstring是目标桶内完整的对象名路径桶参数的隐藏机制当source_bucket或destination_bucket在工具配置中设置后对应字段会从参数列表中移除每次调用都使用配置的固定值。这一机制在源码中体现得很清晰——Initialize方法按顺序构建参数列表cloudstoragecopyobject.go#L83-L93allParameters : parameters.Parameters{} if cfg.SourceBucket nil { // 仅当配置中未固定源桶时才把 source_bucket 暴露为参数 allParameters append(allParameters, parameters.NewStringParameter(sourceBucketKey, Name of the Cloud Storage bucket containing the source object.)) } allParameters append(allParameters, sourceObjectParam) if cfg.DestinationBucket nil { allParameters append(allParameters, parameters.NewStringParameter(destinationBucketKey, Name of the Cloud Storage bucket to copy into.)) } allParameters append(allParameters, destinationObjectParam)对应的单元测试 cloudstoragecopyobject_test.go#L138-L190 验证了两种形态固定桶配置下 manifest 只含source_object与destination_object两个参数且调用时配置的桶名仍被正确转发到 source未固定桶时四个参数全部可见。此外TestEmptyConfiguredBucketsRejected保证配置中显式写出空字符串桶名会在工具初始化阶段直接报错而不是静默放行。源码纵深从工具层到 Source 层的完整调用链理解这个工具最有价值的部分是参数从 LLM 到 GCS API 的完整流转以及每一步的防护。1. 工具层参数解析与校验Invoke方法cloudstoragecopyobject.go#L127-L155的执行流程断言 source 实现了compatibleSource接口即具备CopyObject方法否则返回 500 级错误——这保证只有 cloud-storage source 能挂到该工具上通过 ResolveString 解析桶名配置值优先未配置时回退到调用参数。这就是固定桶语义的实现核心——配置存在时无条件覆盖参数值对四个参数做非空与类型校验任一缺失或为空即返回 AgentErrorinvalid or missing key parameter; expected a non-empty string此时不会触碰底层 source调用source.CopyObject(...)并将返回错误交给ProcessGCSError分类。单元测试TestInvokeValidationcloudstoragecopyobject_test.go#L238-L304覆盖了四个参数逐一缺失的场景并断言校验失败时 mock source 的called标志为 false即参数校验先于一切 I/O。2. 工具标注默认按破坏性标注复制会覆盖已存在的目标对象因此该工具默认使用破坏性标注tools.NewDestructiveAnnotations()tools.go#L88-L97即readOnlyHint: false、destructiveHint: true。这意味着支持 MCP 标注的客户端可以把调用提示为具有破坏性的写操作供人在回路human-in-the-loop审批流程中参考。3. Source 层桶白名单与执行复制进入 Source.CopyObject 后第一道防护是双向桶校验if err : s.validateBucket(sourceBucket); err ! nil { return nil, err } if err : s.validateBucket(destinationBucket); err ! nil { return nil, err }validateBucket 的逻辑是若 source 配置了allowedBuckets列表则源桶和目标桶都必须在该列表中否则报bucket %q is not allowed by source %q configuration。这是最小权限设计的落点——即使 LLM 被诱导传入任意桶名白名单外的桶也会被 source 层拒绝。若未配置allowedBuckets则不做限制。校验通过后执行dst.CopierFrom(src).Run(ctx)完成复制最终返回的 map 即文档所述输出格式见下一节其中bytes取自attrs.SizecontentType取自attrs.ContentType。4. 错误分类Agent 可自愈 vs 基础设施故障工具层把CopyObject的返回错误统一交给 ProcessGCSError 分类这是 MCP Toolbox 工具层的通用错误处理策略与复制场景直接相关的映射包括底层错误分类语义storage.ErrObjectNotExist源对象不存在AgentErrorLLM 应自行纠正对象名后重试storage.ErrBucketNotExistAgentError桶名错误可纠正HTTP 400 / 409 / 412 / 416AgentError请求本身无效改参数可重试HTTP 401 / 403认证失败 / 权限不足ServerError基础设施或 IAM 问题Agent 无法自行修复HTTP 429 / 5xxServerError限流或服务端故障上下文取消 / 超时ServerError504传输层问题这一分类让 LLM 收到 AgentError 时知道是我的输入问题换个参数重试收到 ServerError 时知道这不是我改参数能解决的应停止重试并报告。输出格式调用成功后工具返回一个 JSON 对象字段定义如下fieldtypedescriptionsourceBucketstring源 Cloud Storage 桶sourceObjectstring源 Cloud Storage 对象名destinationBucketstring目标 Cloud Storage 桶destinationObjectstring目标 Cloud Storage 对象名bytesinteger被复制对象的大小contentTypestring记录在目标对象上的 Content-Type对照 Source.CopyObject 的返回构造bytes与contentType均取自复制完成后 GCS 返回的目标对象属性反映的是目标对象而非调用时的预期值。权限要求与实操注意事项凭据权限Cloud Storage 凭据必须能够读取源对象storage.objects.get并在目标桶上创建或更新对象storage.objects.create/storage.objects.update。跨桶复制时两边桶的权限缺一不可。覆盖语义目标对象已存在时会被静默替换没有前置条件保护。生产环境建议配合allowedBuckets把可复制范围收敛到归档桶等白名单桶并结合工具的destructiveHint标注启用人工审批。适用前提该工具只支持cloud-storage类型的 source跨桶移动对象应建模为复制 删除两步源码注释cloudstorage.go#L569-L571对MoveObject也有同样说明——原子移动 API 仅支持同桶内的重命名。与 move_object 的分工同桶内的对象改名建议优先用cloud-storage-move-object基于 GCS 原生 move API原子操作跨桶搬迁则用本工具复制后视需要删除源对象。小结cloud-storage-copy-object是一个参数面很窄、但安全面完整的写工具四个必填参数、可选的固定桶隐藏机制、source 层双向桶白名单校验、覆盖式复制语义以及把对象/桶不存在归为 Agent 可自愈错误、把权限/限流/超时归为服务端错误的两级错误分类。通过 工具实现、source 实现、错误分类器 与 单元测试 这四份仓库文件可以完整核对从 LLM 参数到 GCS API 调用的每一环节行为。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考