MCP Toolbox 的 dataplex-get-data-asset 工具：用 Knowledge Catalog 检索 Data Asset 详细元数据

MCP Toolbox 的 dataplex-get-data-asset 工具：用 Knowledge Catalog 检索 Data Asset 详细元数据

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

dataplex-get-data-asset是 MCP Toolbox（开源 MCP 数据库服务器）中面向 Google Cloud Knowledge Catalog（前身为 Dataplex）的元数据读取工具，用于按locationId + dataProductId + dataAssetId精确定位并返回某个 Data Asset 的完整元数据。本文以仓库内该工具的官方文档为骨架，结合internal/tools/dataplex/dataplexgetdataasset/与internal/sources/dataplex/的源码实现和集成测试，完整讲解该工具的参数、YAML 配置、IAM 前置条件、底层 API 调用链与返回结构，帮助你直接落地到自己的 Agent 配置中。

工具概览：它能做什么

Knowledge Catalog 是 Google Cloud 的统一数据治理方案，为组织内的数据资产维护一份集中式清单，承载业务、技术与运行时三类元数据。dataplex-get-data-asset就是针对其中Data Asset（数据资产）的读取工具：在给定 Data Product（数据产品）下，根据唯一标识取回某个 Data Asset 的详细元数据。

从官方描述看（见 关联文档），该工具适用于如下场景：

• Agent 已经通过list_data_products/list_data_assets拿到 Data Product 与 Data Asset 的 ID，需要进一步查看某个资产的详细属性；
• 需要确认 Data Asset 的资源 URI（resourceUri）、标签（labels）以及访问组配置（accessGroupConfigs），用于审计、权限核对或下游编排。

由于它是一个只读工具，工具注册时使用了只读注解（源码见 dataplexgetdataasset.go 中tools.NewReadOnlyAnnotations），不会对 Knowledge Catalog 产生任何写操作，适合安全地暴露给 LLM 使用。

兼容的 Source

该工具必须挂载在类型为dataplex的 Source 上执行。在 Knowledge Catalog Source 文档 中，Source 的最小配置如下：

kind: source name: my-dataplex-source type: "dataplex" project: "my-project-id"

其中type必须为"dataplex"，project是用于配额与计费的 GCP 项目 ID（例如"my-project-id"）。工具通过source字段引用该名称完成绑定。

这种绑定关系在源码层有强校验：dataplex-get-data-asset的ValidateSource方法要求所引用的 Source 必须实现compatibleSource接口（即具备GetDataAsset(ctx, locationId, dataProductId, dataAssetId)方法），否则会返回"invalid source for ... tool"错误（见 dataplexgetdataasset.go 与 L98-L104）。从源码结构看，当前仓库中dataplex类型 Source 是实现该接口的唯一来源。

前置条件：IAM 权限与 ADC

Knowledge Catalog 使用 Identity and Access Management（IAM）控制用户和组对 Catalog 资源的访问。MCP Toolbox 会使用你的Application Default Credentials（ADC）在与 Knowledge Catalog 交互时完成授权与认证。

除为服务器配置 ADC 外，还必须确保该 IAM 身份具备执行相应任务所需的 IAM 权限。在官方文档（关联文档 的 Requirements 一节）基础上，仓库的预构建配置文档给出了更明确的角色指引：

• Dataplex Reader（roles/dataplex.viewer）：用于搜索和查看条目；
• Dataplex Editor（roles/dataplex.editor）：用于修改条目。

对于只读的get_data_asset操作，最小化原则下使用roles/dataplex.viewer即可满足需求；只有当你同时启用create_data_product、update_data_asset等写工具时才需要 Editor 及以上角色。请结合 Knowledge Catalog 的 IAM 权限与角色说明，将对应角色授予运行 Toolbox 的 IAM 身份（服务账号或用户账号）。

参数详解

dataplex-get-data-asset共接收三个必填参数，完整参数表继承自关联文档：

在源码层，三个参数被逐一注册为字符串参数（见 dataplexgetdataasset.go）：

locationId := parameters.NewStringParameter("locationId", "The location ID (e.g., 'us', 'us-central1') where the Data Product is located.") dataProductId := parameters.NewStringParameter("dataProductId", "The unique ID of the parent Data Product.") dataAssetId := parameters.NewStringParameter("dataAssetId", "The unique ID of the Data Asset.")

调用时（Invoke方法，L106-L129）会做严格的非空校验：三个参数任何一个缺失或为空字符串，都会返回 Agent 错误"locationId is required and must be a non-empty string"（其余两个参数同理）。因此调用方必须同时提供三个完整 ID，缺一不可。

配置示例

在 Toolbox 的 YAML 配置中声明该工具（示例直接取自关联文档）：

kind: tool name: get_data_asset type: dataplex-get-data-asset source: my-dataplex-source description: Use this tool to retrieve a Data Asset.

对应 Reference 字段说明：

其中description会被写入工具 Manifest 并作为模型提示的一部分，建议用一句话说明工具的用途与适用时机（如“当用户询问某个 Data Asset 的详细元数据时使用”），以提升 LLM 的工具选择准确率。

仓库的单元测试TestParseFromYamlDataplexGetDataAsset验证了上述 YAML 的解析行为：kind: tool配置会被解析为dataplexgetdataasset.Config，其中name、description、type、source字段逐一映射，默认AuthRequired为空数组。这说明你可以在配置层面按需补充annotations或认证相关的字段。

底层实现：从 Invoke 到 GetDataAsset 的调用链

理解调用链有助于排查问题。当 LLM 触发该工具时，执行路径如下（见 dataplexgetdataasset.go）：

1. Invoke从参数映射中取出locationId、dataProductId、dataAssetId，并做非空校验；
2. 将调用转发给所绑定 Source 的GetDataAsset(ctx, locationId, dataProductId, dataAssetId)方法；
3. 出错时通过util.ProcessGcpError(err)将 GCP 错误统一转换为 Toolbox 错误格式返回。

Source 侧的实现位于 internal/sources/dataplex/dataplex.go。它首先构造 Data Asset 的完整资源名：

projects/{projectId}/locations/{locationId}/dataProducts/{dataProductId}/dataAssets/{dataAssetId}

其中{projectId}来自 Source 配置中的project字段。随后构造dataplexpb.GetDataAssetRequest{Name: name}，通过GetDataProductClient().GetDataAsset(ctx, req)调用 Dataplex DataProduct API。响应返回后，工具会从资源的规范名称中解析出locationId、dataProductId、dataAssetId三个片段（按projects/locations/dataProducts/dataAssets的路径结构切分），并组装为DataAsset对象返回。

返回的DataAsset结构定义在 dataplex.go：

在 Knowledge Catalog Source 文档 的get_data_asset工具指令中也印证了返回内容：应展示 Data Asset 的 ID、resource、labels 以及 access group configurations。

使用预构建配置快速启用

仓库已为 Knowledge Catalog 提供了开箱即用的预构建配置 dataplex.yaml，其中已包含get_data_asset工具的完整声明（L68-L72）：

kind: tool name: get_data_asset type: dataplex-get-data-asset source: dataplex-source description: Retrieves specific metadata regarding a Data Asset.

使用预构建配置时（详情见预构建配置文档）：

• 以--prebuilt参数指定dataplex；
• 通过环境变量DATAPLEX_PROJECT指定 GCP 项目 ID；
• 按需启用data-productstoolset（该 toolset 聚合了list_data_products、get_data_product、list_data_assets、get_data_asset等 Data Product/Data Asset 全生命周期读写工具以及get_operation），或discoverytoolset 以满足纯查询场景。

典型的端到端 Agent 工作流为：search_entries（或list_data_products）→list_data_assets→get_data_asset，先缩小范围拿到 ID，再精准取回单个资产的详细元数据。

测试验证与预期行为

仓库对dataplex-get-data-asset提供了双层测试保障：

• 单元测试dataplexgetdataasset_test.go：验证 YAML 配置能正确解析为工具 Config，覆盖type、source、description等字段的映射关系；
• 集成测试dataplex_integration_test.go：通过 HTTP 接口POST /api/tool/.../invoke发送{"locationId":"us","dataProductId":"...","dataAssetId":"..."}请求体，验证：
  • 授权与未授权两种场景下均能成功返回 200 且结果中包含预期的locationId/dataProductId/dataAssetId；
  • 使用无效 token 或不带 token 时返回 401，验证了认证失败时的行为（适用于启用了 Google 认证的配置）。

这提示你在本地联调时，可以先用list_data_assets确认目标 Data Asset 真实存在且三个 ID 准确无误，再调用get_data_asset，避免因 ID 拼写错误导致 "NotFound" 类错误。

总结与注意事项

dataplex-get-data-asset是 Knowledge Catalog 元数据消费链路中"精确取数"的一环，核心要点归纳如下：

1. 三个必填参数（locationId、dataProductId、dataAssetId）缺一不可，源码层有非空强校验；
2. 必须绑定dataplex类型 Source，且 Source 配置中的project决定了实际查询的 GCP 项目；
3. 前置 IAM：至少需要roles/dataplex.viewer，并通过 ADC 完成认证；
4. 只读工具：使用只读注解，不产生任何写操作，可放心交给 LLM 使用；
5. 返回结构：包含资源 URI、标签、访问组配置等元数据，可用于权限审计与资产核对；
6. 使用预构建配置（--prebuilt dataplex+DATAPLEX_PROJECT环境变量）可一键获得包含该工具在内的完整工具集。

如需进一步了解配套的list_data_products、list_data_assets、create_data_product等工具，可查阅 Knowledge Catalog Source 文档 与 预构建配置文档。

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox