MCP Toolbox 中的 bigtable-delete-materialized-view 工具：从配置到源码的完整解析

MCP Toolbox 中的 bigtable-delete-materialized-view 工具从配置到源码的完整解析【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxbigtable-delete-materialized-view是 MCP Toolbox 为 Google Cloud Bigtable 提供的管理类工具用于从 Bigtable 实例中删除一个已存在的物化视图materialized view。本文基于仓库中的官方文档与实现源码展开覆盖该工具的参数定义、YAML 配置方式、Reference 字段说明并深入 工具实现源码 与 Bigtable source 封装帮助读者理解从 LLM 调用到 Google Bigtable SDK 的完整执行链路。工具概览在 Bigtable 中物化视图允许用户将 GoogleSQL 查询结果物化为可加速查询的数据结构。与之对应MCP Toolbox 提供了完整的物化视图生命周期管理工具集创建、查询、更新、删除、列表分别位于 internal/tools/bigtable 下bigtable-delete-materialized-view负责其中的删除环节它根据实例 ID 和物化视图 ID调用底层 Bigtable InstanceAdmin 接口移除指定物化视图。由于删除是不可逆操作工具源码在初始化时会为其打上 destructive 注解这一点后文结合 bigtabledeletematerializedview.go#L62-L80 具体说明。兼容的 Source 类型该工具仅兼容bigtable类型的 source。在 工具源码 中兼容性通过一个接口断言来定义type compatibleSource interface { DeleteMaterializedView(context.Context, string, string) (any, error) }也就是说只有实现了DeleteMaterializedView(ctx, instanceID, materializedViewID)方法的 source 才能与该工具配合使用。Bigtable source 的封装在 internal/sources/bigtable/admin_wrappers.go#L269-L275 中提供了该方法因此type: 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 实例名称。从 source 实现 看name、type、project、instance四个字段均标记为validate:required缺少任一字段都会导致 source 配置解析失败。source 初始化时bigtable.go#L60-L86会同时创建三个客户端用于数据读写的bigtable.Client、用于实例级管理的InstanceAdminClient以及用于表级管理的AdminClient——物化视图的删除操作走的是InstanceAdminClient这条路径。此外根据 source 文档Bigtable 通过 IAM 控制对项目、实例、表和备份级资源访问Toolbox 使用你的 Application Default CredentialsADC完成授权需确保对应的 IAM 身份具备物化视图管理所需的权限。调用参数Parameters调用该工具时LLM 需要传入以下参数参数类型必填说明instance_idstring是Bigtable 实例的 ID。materialized_view_idstring是要删除的物化视图的 ID。这两个参数并非写死在文档中而是由源码统一注册。在 Initialize 方法 中allParameters : parameters.Parameters{ parameters.NewStringParameter(instance_id, The ID of the instance), parameters.NewStringParameter(materialized_view_id, The ID of the materialized view), }这两个字符串参数会进入工具的 Manifest随 MCP 协议一起暴露给客户端与 LLM参数描述文本即直接取自NewStringParameter的第二个参数。因此文档中的参数表与源码定义逐字对应。工具配置示例在 Toolbox 的 YAML 配置中声明该工具kind: tool name: delete_materialized_view type: bigtable-delete-materialized-view source: my-bigtable-source description: Use this tool to delete a materialized view.单元测试 中的解析用例验证了这段配置会被正确解析为bigtabledeletematerializedview.Config结构体同时也验证了可选的authRequired字段kind: tool name: example_tool type: bigtable-delete-materialized-view source: my-bt-instance description: some description authRequired: - my-google-auth-service - other-auth-service即工具可以声明依赖哪些认证服务调用时才能通过 Toolbox 的认证流程。Reference完整配置字段完整的工具级配置字段如下与 工具实现 中的Config结构体一致字段类型必填说明typestring是必须为bigtable-delete-materialized-view。sourcestring是要执行操作的目标 source 名称。descriptionstring否传给 LLM 的工具描述缺省时源码会使用默认文案 Delete an existing Bigtable materialized view.。annotationsobject否工具注解可覆盖默认的 destructive 标记。其中type和source在结构体中带有validate:required标签配置缺项会在启动阶段直接报错。源码级执行链路理解该工具行为的关键在于三段代码1. 注册阶段。工具类型字符串bigtable-delete-materialized-view在 init 函数 中通过tools.Register注册到全局工具表const resourceType string bigtable-delete-materialized-view func init() { if !tools.Register(resourceType, newConfig) { panic(fmt.Sprintf(tool type %q already registered, resourceType)) } }配置解析函数newConfig使用goccy/go-yaml将 YAML 片段解码为Config。2. 初始化阶段。Initialize除了注册两个字符串参数外还做了两件与删除操作特性相关的事bigtabledeletematerializedview.go#L62-L80若未提供description回退为默认描述 Delete an existing Bigtable materialized view.通过tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewDestructiveAnnotations)在用户未显式指定注解时自动附加 destructive破坏性操作注解。这会在 MCP 工具清单中标记该工具具有破坏性客户端如支持该特性的 MCP 宿主可以据此向用户发起确认。3. 调用阶段。Invoke方法完成运行时校验与执行bigtabledeletematerializedview.go#L104-L117func (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.DeleteMaterializedView(ctx, paramsMap[instance_id].(string), paramsMap[materialized_view_id].(string)) if err ! nil { return nil, util.ProcessGcpError(err) } return res, nil }执行逻辑可以概括为将传入的 source 断言为compatibleSource不兼容则返回 5xx 客户端服务端错误将参数值转为 map取出instance_id与materialized_view_id两个字符串调用 source 的DeleteMaterializedView出错时经util.ProcessGcpError归一化为 GCP 错误保留 HTTP 状态语义成功则透传结果。4. Source 侧的落地实现。在 admin_wrappers.go#L269-L275 中func (s *Source) DeleteMaterializedView(ctx context.Context, instanceId, materializedViewId string) (any, error) { err : s.InstanceAdmin.DeleteMaterializedView(ctx, instanceId, materializedViewId) if err ! nil { return nil, fmt.Errorf(failed to delete materialized view: %w, err) } return map[string]string{status: materialized view deleted successfully}, nil }可见最终执行的是cloud.google.com/go/bigtableSDK 的InstanceAdminClient.DeleteMaterializedView调用。成功后工具返回一个固定结构的结果{status: materialized view deleted successfully}——这个返回值正是 测试用例 中断言的期望输出。测试用例验证的行为bigtabledeletematerializedview_test.go 覆盖了三类场景可作为集成时的行为预期参考成功路径mock source 收到instance_idinst-1、materialized_view_idmview-1时返回{status: materialized view deleted successfully}与真实 source 的成功返回值一致GCP 错误路径source 返回错误时Invoke向调用方传播非 nil 的ToolboxError错误信息会经过util.ProcessGcpError处理不兼容 source 路径传入未实现DeleteMaterializedView的 source 时Invoke直接报错验证了接口断言的防护逻辑。另外mock 实现会对参数值做严格断言inst-1/mview-1说明参数是按名称逐一点名传给 source 方法的参数名拼写或配置错误无法静默通过。使用注意事项与局限结合文档与源码使用该工具时需注意以下前提前置条件需要一个已正确配置且通过认证校验的bigtablesourcesource 文档且 IAM 身份具备对目标实例物化视图的删除权限参数语义instance_id是运行时传入的实例 ID与 source 配置中的instance字段相互独立——从源码看工具将instance_id参数原样透传给 InstanceAdmin API因此调用时应保证它与目标实例一致不可逆性物化视图删除后不会保留数据工具通过默认的 destructive 注解向 MCP 客户端显式标记了这一点适用范围该工具面向 Bigtable 的 GoogleSQL 物化视图能力参数仅两个字符串没有级联、dry-run 等额外选项。相关工具与延伸阅读物化视图的完整生命周期由同目录下的兄弟工具覆盖可与本工具配合形成先建后删或删后重建的工作流bigtable-create-materialized-view.mdbigtable-get-materialized-view.mdbigtable-update-materialized-view.mdbigtable-list-materialized-views.mdbigtable-delete-logical-view.md逻辑视图的同类删除工具实现同样位于 admin_wrappers.go实现与测试代码索引工具实现工具测试Bigtable source 实现Bigtable source 管理方法封装Bigtable 集成文档索引【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考