MCP Toolbox 中 bigtable-delete-cluster 工具详解通过 MCP 删除 Bigtable 集群【免费下载链接】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下文简称 Toolbox的bigtable-delete-cluster工具展开说明该工具的用途、配置参数、YAML 配置方式与 IAM 前置条件并结合仓库源码剖析其从工具调用到 Google Cloud Bigtable Admin API 的完整执行链路。读完本文你将能够正确配置该工具、理解其运行时参数instance_id/cluster_id的含义并掌握其作为破坏性工具destructive tool的默认行为与错误处理机制。工具定位与功能概述bigtable-delete-cluster是 Toolbox 提供的 Bigtable 管理类工具用于删除一个 Bigtable 集群cluster。Bigtable 集群是实例instance下按 zone 部署的计算与存储单元一个实例可以包含一个或多个集群例如跨区域复制场景。该工具属于 Toolbox 的 Bigtable 工具族与bigtable-create-cluster、bigtable-get-cluster、bigtable-list-clusters、bigtable-update-cluster等工具共同构成对 Bigtable 集群的完整生命周期管理能力。工具的实现位于 internal/tools/bigtable/bigtabledeletecluster/bigtabledeletecluster.go其类型常量定义如下const resourceType string bigtable-delete-cluster工具在包初始化阶段通过tools.Register注册到全局工具注册表若类型名重复注册会直接panic保证每个工具类型在进程内唯一。适用前提Source 与 IAM 权限工具文档标注该工具的适用源Compatible Sources为Bigtable source。一个合法的 Bigtable source 配置如下摘自 source 文档kind: source name: my-bigtable-source type: bigtable project: my-project-id instance: test-instance字段类型必填说明typestringtrue必须为bigtable。projectstringtrue集群所在 GCP 项目的 ID例如my-project-id。instancestringtrueBigtable 实例的名称。在权限方面Bigtable 使用 IAM 在 project、instance、table、backup 层级控制资源访问。Toolbox 会使用Application Default CredentialsADC进行身份认证与鉴权因此在使用该删除工具前需确保两点为 Toolbox 服务正确设置 ADCADC 对应的 IAM 主体被授予了删除 Bigtable 集群所需的权限可通过为身份应用相应的 IAM 角色来授予。由于删除集群是高危操作建议在配置该工具时将其限定在可信的 LLM 会话与权限边界内必要时结合authRequired字段强制关联特定的 auth 服务见下文配置参考。配置 bigtable-delete-cluster 工具工具文档给出的标准配置示例如下kind: tool name: bigtable_delete_cluster type: bigtable-delete-cluster source: my-bigtable-source description: Delete a Bigtable cluster.完整配置参考表与 工具文档 的 Reference 一致字段类型必填说明typestringtrue必须为bigtable-delete-cluster。sourcestringtrue指定在该 source 上执行工具。descriptionstringfalse传给 LLM 的工具描述。其中source必须指向一个已定义的bigtable类型 source 名称示例中的my-bigtable-source。若未提供description工具初始化时会回退为默认描述Delete a Bigtable cluster.这一点可以从源码Initialize方法中得到印证func (cfg Config) Initialize(context.Context) (tools.Tool, error) { if cfg.Description { cfg.Description Delete a Bigtable cluster. } // ... }来源bigtabledeletecluster.go。运行时参数bigtable-delete-cluster接受两个字符串类型的运行时参数由 LLM 在调用工具时提供参数类型说明instance_idstring目标 Bigtable 实例的 ID。cluster_idstring目标集群的 ID。源码中通过parameters.NewStringParameter声明这两个参数allParameters : parameters.Parameters{ parameters.NewStringParameter(instance_id, The ID of the instance), parameters.NewStringParameter(cluster_id, The ID of the cluster), }来源bigtabledeletecluster.go。这两个参数的说明文案会随工具清单Manifest暴露给 LLM指导模型正确填参。破坏性标注默认 Destructive 注解bigtable-delete-cluster在初始化时使用的默认注解是tools.NewDestructiveAnnotationsreturn Tool{ BaseTool: tools.NewBaseTool( cfg, tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewDestructiveAnnotations), tools.Manifest{Description: cfg.Description, Parameters: allParameters.Manifest(), AuthRequired: cfg.AuthRequired}, allParameters, ), }, nilNewDestructiveAnnotations的实现位于 internal/tools/tools.go// NewDestructiveAnnotations creates default annotations for a destructive tool. // Use this for tools that create, update, or delete data. func NewDestructiveAnnotations() *ToolAnnotations { readOnly : false destructive : true return ToolAnnotations{ ReadOnlyHint: readOnly, DestructiveHint: destructive, } }也就是说工具在 MCP 协议层默认携带readOnlyHint: false与destructiveHint: true两个注解注解结构遵循 MCP 规范中的 ToolAnnotations 定义明确告诉客户端与 LLM这是一个会不可逆地删除数据资源的工具。如果配置中显式提供了annotations字段则通过GetAnnotationsOrDefault优先采用自定义值。执行链路从 Invoke 到 Bigtable Admin API工具被调用时的执行流程可以从Tool.Invoke方法完整追溯bigtabledeletecluster.gofunc (t Tool) Invoke(ctx context.Context, src sources.Source, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) { source, ok : src.(compatibleSource) if !ok { return nil, util.NewClientServerError(source used is not compatible with the tool, http.StatusInternalServerError, nil) } paramsMap : params.AsMap() res, err : source.DeleteCluster(ctx, paramsMap[instance_id].(string), paramsMap[cluster_id].(string)) if err ! nil { return nil, util.ProcessGcpError(err) } return res, nil }可以将其拆解为三步源兼容性检查工具通过接口断言校验 source 是否实现了compatibleSource即是否具备DeleteCluster(context.Context, string, string) (any, error)方法。ValidateSource在服务启动阶段做同样的检查不兼容的 source 会被提前拦截返回source is not compatible with the tool错误。参数提取与调用将instance_id与cluster_id两个字符串参数取出调用 source 的DeleteCluster方法。错误归一化source 返回的错误会经过util.ProcessGcpError处理把 GCP API 错误转成 Toolbox 统一的ToolboxError结构返回给调用方。Bigtable source 侧的DeleteCluster实现位于 internal/sources/bigtable/admin_wrappers.gofunc (s *Source) DeleteCluster(ctx context.Context, instanceId, clusterId string) (any, error) { err : s.InstanceAdmin.DeleteCluster(ctx, instanceId, clusterId) if err ! nil { return nil, fmt.Errorf(failed to delete cluster: %w, err) } return map[string]string{status: cluster deleted successfully}, nil }从源码结构看它直接封装了 Google Bigtable Go 客户端库cloud.google.com/go/bigtable的InstanceAdmin.DeleteCluster即底层走的是 Bigtable Admin API。删除成功后工具向 LLM 返回统一的状态响应{status: cluster deleted successfully}失败时则包装为failed to delete cluster: 原始错误。配置解析与调用行为的测试验证工具的单元测试位于 bigtabledeletecluster_test.go覆盖了两类关键行为YAML 配置解析TestParseFromYamlBigtable验证标准配置kind/name/type/source/description能正确解析为Config结构包括带authRequired列表的场景kind: tool name: example_tool type: bigtable-delete-cluster source: my-bq-instance description: some description authRequired: - my-google-auth-service - other-auth-service调用行为TestInvoke使用实现了DeleteCluster的 mock source 验证两种路径——成功路径返回{status: cluster deleted successfully}错误路径在 mock 返回错误时确保Invoke也返回非 nil 错误。这印证了上文所述的错误处理链路。在集群管理工具族中的位置bigtable-delete-cluster通常与以下工具组合使用形成「查询确认 → 变更操作」的安全工作流相关工具文档均位于 Bigtable 工具目录工具说明文档bigtable-list-clusters列出实例下的集群删除前确认cluster_idbigtable-list-clustersbigtable-get-cluster查看单个集群详情bigtable-get-clusterbigtable-update-cluster调整集群节点数缩容后再删除的常见路径bigtable-update-clusterbigtable-delete-instance删除整个实例会连同其集群一起移除bigtable-delete-instance需要特别注意instance_id指向的是逻辑实例 ID而非 source 配置中静态声明的instance字段——source 的instance主要用于建立连接上下文而删除操作的真正目标由运行时参数决定。此外删除集群是不可逆的破坏性操作集群承载的数据将无法恢复实际使用前应先通过bigtable-list-clusters/bigtable-get-cluster确认目标并确保该集群已不再承担读写流量例如已完成节点缩容或流量切换。小结bigtable-delete-cluster工具以最小的配置面typesource与两个运行时参数instance_id、cluster_id完成了对 Bigtable 集群的删除能力封装配置层由bigtabledeletecluster包负责解析与注册执行层通过 source 的DeleteCluster方法落到 Bigtable Admin API 的InstanceAdmin.DeleteCluster调用错误统一经ProcessGcpError归一化返回。默认携带的 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），仅供参考