MCP Toolbox 实战使用 dataplex-create-data-product 工具在 Knowledge Catalog 中创建 Data Product【免费下载链接】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 开源仓库中的 dataplex-create-data-product 工具文档 为核心系统讲解如何通过 MCP Toolbox 提供的dataplex-create-data-product工具在 Google Cloud Knowledge Catalog前称 Dataplex中创建 Data Product。你将掌握该工具的完整参数语义、YAML 配置写法、IAM 权限前提、异步 Long-Running OperationLRO的运行机制以及基于源码层面的参数校验与调用链原理从而能够独立编排创建 Data Product → 轮询操作状态 → 管理 Data Asset的元数据治理工作流。一、背景Data Product 与 Knowledge Catalog 的定位在深入工具用法之前需要先理解 Data Product 在整个 Knowledge Catalog 元数据体系中的位置。Knowledge Catalog 是 Google Cloud 面向数据与 AI 资产的统一智能治理方案其核心是一个集中式的目录catalog保存组织中所有数据资产的业务、技术与运行时元数据并通过 AI/ML 帮助用户发现元数据之间的关系与语义。Knowledge Catalog 集成文档 将其描述为为 AI、分析和商业智能提供规模化支撑的治理底座。在 Knowledge Catalog 的模型中几个核心概念层层嵌套Entry条目某个具体数据资产的元数据记录例如一张 BigQuery 表、一个 Cloud Storage 桶或一个本地 SQL 表。Aspect方面挂在 Entry 上、承载丰富描述信息的组件如 schema、数据类型、业务描述、分类等由 Aspect Type 模板定义。Aspect Type / Entry Type定义元数据字段结构的可复用模板例如dataplex-types.global.bigquery-table、data-product等。Entry Group / Entry LinkEntry 的逻辑命名空间以及用于表达数据资产间关系如外键的链接。Data Product数据产品则是该目录中用于治理和组织的一组数据资产的逻辑容器你可以为它指定展示名称、描述、所有者邮箱并通过 access groups 控制访问主体。创建 Data Product 是后续在其下创建 Data Asset数据资产的前提步骤两者共同构成数据产品的产品化治理单元。二、工具概述一次调用立即返回异步落盘dataplex-create-data-product工具用于在 Knowledge Catalog 中创建新的 Data Product。其核心行为特点是这是一个长时间运行的操作Long-Running Operation, LRO。根据工具文档的说明工具调用后会立即返回响应中包含操作的位置 IDlocation ID与操作 IDoperation ID而 Data Product 的实际创建由 Google Cloud 后台异步完成。因此调用方通常是大模型 Agent需要随后使用dataplex-get-operation工具轮询该操作直至done字段为true才能确认 Data Product 创建成功并拿到最终资源详情。这一异步语义在源码层面得到了印证在 dataplex.go 的 CreateDataProduct 实现 中函数调用GetDataProductClient().CreateDataProduct(ctx, req)返回的是一个 operation 对象随后代码解析操作资源名projects/{project}/locations/{location}/operations/{operation_id}并只返回return map[string]string{ locationId: parts[3], operationId: parts[5], }, nil即工具响应只包含locationId与operationId两个字段与文档描述完全一致。三、兼容源dataplex Source 是唯一的执行载体工具的source字段必须指向一个类型为dataplex的源。该源在 source.md 集成文档 中有完整定义其基础配置如下kind: source name: my-dataplex-source type: dataplex project: my-project-id参考字段说明字段类型是否必填描述typestringtrue必须为dataplexprojectstringtrue用于配额与计费的 GCP 项目 ID例如my-project-id从源码看dataplex类型的 Source 配置还支持两个可选字段impersonateServiceAccount服务账号提权需为合法邮箱格式与scopes自定义 OAuth 范围缺省时使用https://www.googleapis.com/auth/cloud-platform。初始化时Toolbox 会依次创建 CatalogClient、DataScanClient、DataProductClient 与 ResourceManager ProjectsClient并通过 ResourceManager 解析出项目编号project number供后续 API 调用使用。四、前置要求ADC 认证与 IAM 权限工具文档的 Requirements 章节明确了两类前置条件认证AuthenticationToolbox 会使用你的Application Default CredentialsADC与 Knowledge Catalog 交互完成授权与鉴权。因此需要在运行 Toolbox Server 的环境中正确配置 ADC。授权Authorization除了配置 ADC还必须确保该 IAM 身份具备执行目标任务所需的 IAM 权限与角色。Knowledge Catalog 的权限体系与 Dataplex 一致具体可查阅 Google Cloud 官方的 IAM permissions 与 IAM roles 文档。在预置配置文档中对权限给出了可直接套用的落地建议Dataplex Readerroles/dataplex.viewer用于搜索和查找条目entriesDataplex Editorroles/dataplex.editor用于修改条目创建 Data Product 属于写操作需要此级别的权限。五、参数详解六个字段的完整语义工具文档给出的参数表如下这是使用该工具时必须严格遵循的契约fieldtyperequireddescriptionlocationIdstringtrue创建 Data Product 的位置 ID例如us、us-central1。dataProductIdstringfalse要创建的 Data Product 的唯一 ID。若未指定后端会自动生成唯一 ID。displayNamestringtrueData Product 的展示名称。descriptionstringfalseData Product 的描述。ownerEmailsarray of stringstrueData Product 的所有者邮箱列表。accessGroupsarray of objectsfalse与 Data Product 关联的访问组列表。每个组对象可包含id必填、displayName必填、description以及googleGroup与serviceAccount中至少一个。源码级参数校验细节参数并非简单透传工具实现 在注册阶段为每个字段构造了参数定义其中dataProductId、description、accessGroups被标记为可选WithStringRequired(false)/WithArrayRequired(false)与文档一致。而在Invoke阶段同一文件 L135-L205代码对参数做了严格的运行时校验这些约束是对文档参数表的有效补充locationId必填且必须是非空字符串否则返回 Agent 错误locationId is required and must be a non-empty stringdisplayName必填且必须是非空字符串否则返回displayName is required and must be a non-empty stringownerEmails数组中的每个元素必须是字符串且过滤空值后至少保留一个邮箱否则返回ownerEmails is required and must contain at least one non-empty stringaccessGroups数组中的每个元素必须是对象每个对象的id与displayName均必填且非空googleGroup与serviceAccount必须至少提供其一否则报错at least one of access group googleGroup or serviceAccount must be a non-empty string。AccessGroup 的数据结构在 dataplex.go 中定义了 AccessGroup 结构与工具参数一一对应type AccessGroup struct { ID string json:id DisplayName string json:displayName Description string json:description GoogleGroup string json:googleGroup ServiceAccount string json:serviceAccount }在构造底层请求时dataplex.go L640-L657每个 AccessGroup 会被转换为DataProduct_AccessGroupgoogleGroup映射为 Principal 的GoogleGroup类型serviceAccount映射为 Principal 的ServiceAccount字段并最终以map[ID]AccessGroup的形式写入CreateDataProductRequest。这说明accessGroups 以 ID 作为唯一键组织同一 Data Product 内不应出现重复的组 ID。六、YAML 配置示例如何声明该工具工具文档给出的最小声明示例kind: tool name: create_data_product type: dataplex-create-data-product source: my-dataplex-source description: Use this tool to create a Data Product.其中name工具在 Toolbox 中注册的名称供 Agent 引用type必须为dataplex-create-data-product这是工具注册时使用的资源类型常量见 dataplexcreatedataproduct.go 中的 resourceTypesource必须指向已声明的dataplex类型源名称description传入 LLM 的工具描述用于帮助 Agent 判断何时调用该工具。这一配置的合法性由单元测试直接验证测试TestParseFromYamlDataplexCreateDataProduct解析上述 YAML 片段并断言解析结果中Type为dataplex-create-data-product、Source为my-instance确保配置解析链路正确。如果不想从零编写配置也可以直接使用仓库提供的预置配置在预置工具配置 dataplex.yaml 中create_data_product已被声明为kind: tool name: create_data_product type: dataplex-create-data-product source: dataplex-source description: Creates a new Data Product.并通过--prebuilt dataplex与环境变量DATAPLEX_PROJECT组合启用详见预置配置文档。同时create_data_product还被编排进data-products工具集toolset与list_data_products、get_data_product、create_data_asset、update_data_product、get_operation等工具协同构成完整的数据产品治理闭环。七、异步工作流创建后如何确认成功由于创建操作是异步的Agent 必须遵循以下编排步骤这与source.md 中的 create_data_product 工具指令要求一致发起创建调用create_data_product传入locationId、displayName、ownerEmails必填可选传入dataProductId、description、accessGroups立即展示响应向用户展示返回的locationId与operationId轮询操作使用dataplex-get-operation工具传入完整操作资源名projects/{projectId}/locations/{locationId}/operations/{operationId}以约 5 秒的间隔轮询直至响应中的done字段为true读取结果操作完成后response字段将包含创建成功的DataProduct资源详情如展示名称、描述、所有者邮箱、资产数量、标签、访问组等。dataplex-get-operation工具的声明与用法详见其独立文档其 YAML 配置同样简单kind: tool name: get_operation type: dataplex-get-operation source: my-dataplex-source description: Check the status of a long-running scan template creation.从源码角度看get_operation的底层实现dataplex.go L907-L931会先用正则^projects/[^/]/locations/[^/]/operations/[^/]$校验操作资源名格式再通过 LROClient 查询操作并序列化为 JSON 返回。八、参考字段速查Reference工具文档末尾的 Reference 表是配置该工具时的权威字段清单fieldtyperequireddescriptiontypestringtrue必须为dataplex-create-data-product。sourcestringtrue工具执行的源名称。descriptionstringtrue传给 LLM 的工具描述。注意区分两个层面的描述Reference 表中的description是配置层面的工具元数据喂给 LLM 用而第五节参数表中的description是调用层面的 Data Product 业务描述写入 Knowledge Catalog 的元数据二者不要混淆。九、典型实战路径小结把上述内容串成一条可落地的完整路径在 Toolbox 配置中声明dataplex源并指定project按需为 IAM 身份授予roles/dataplex.editor创建/修改类操作与roles/dataplex.viewer查询类操作并确保 ADC 就绪声明create_data_product工具手动编写或启用--prebuilt dataplex由 Agent 调用工具创建 Data Product并用get_operation轮询直至完成后续可继续使用create_data_asset在该 Data Product 下挂载数据资产使用update_data_product修改元数据使用update_data_product_aspects补充 overview、contacts 等业务方面最终在 Knowledge Catalog 中沉淀结构化的数据产品治理元数据。通过本文档与仓库源码的对照你可以确信工具的参数契约、异步返回语义、访问组结构乃至底层 gRPC 请求构造均已由工具实现、源实现与解析测试三重印证可直接作为集成与排障的依据。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考