MCP Toolbox 中的 dataproc-get-cluster 工具:查询 Google Cloud Dataproc 集群详情
MCP Toolbox 中的 dataproc-get-cluster 工具:查询 Google Cloud Dataproc 集群详情
dataproc-get-cluster 是 MCP Toolbox(Google Cloud 开源的数据库 MCP Server)为 Dataproc 集成提供的只读工具,用于按短名称精确获取某个 Google Cloud Dataproc 集群的完整详情,并自动附上 Google Cloud Console 监控页与 Cloud Logging 日志页的直达链接。通过本文,你将掌握如何在 Toolbox 配置中声明该工具、理解其 clusterName 参数的用法与限制、看懂其返回 JSON 的每个字段,并从源码层面了解 Toolbox 是如何调用 Dataproc Cluster Controller API 完成查询与结果包装的。
工具概览
dataproc-get-cluster 从配置的 Dataproc source 中检索一个指定的 Dataproc 集群。与 dataproc-list-clusters(批量列举集群)不同,该工具面向“已知集群短名称、需要获取单个集群完整状态”的场景,适合 Agent 在需要确认集群是否运行、查看 UUID、获取排障入口时使用。
该工具定义在 dataprocgetcluster.go 中,其注册的类型标识为 dataproc-get-cluster:
const kind = "dataproc-get-cluster"
工具本身是只读的:初始化时使用 tools.NewReadOnlyAnnotations 作为默认注解(见 dataprocgetcluster.go),不会对集群产生任何写操作。
前置条件:配置 Dataproc Source
dataproc-get-cluster 本身不携带项目与区域信息,它从 source 配置中获取 project 与 region。因此使用前需要先声明一个类型为 dataproc 的 source,其完整字段说明见 source.md:
kind: source
name: my-dataproc-source
type: dataproc
project: my-project
region: us-central1
| field | type | required | description |
|---|---|---|---|
| type | string | true | Must be "dataproc". |
| project | string | true | ID of the GCP project with Dataproc resources. |
| region | string | true | Region containing Dataproc resources. |
从源码看,dataproc source 的配置结构在 dataproc.go 中定义,project 与 region 均标注为 validate:"required"。初始化时,Toolbox 会根据 region 拼接区域化端点并创建三个 gRPC 客户端(ClusterController、Longrunning Operations、JobController):
endpoint := fmt.Sprintf("%s-dataproc.googleapis.com:443", r.Region)
client, err := dataproc.NewClusterControllerClient(ctx, option.WithEndpoint(endpoint), option.WithUserAgent(ua))
IAM 权限要求
Dataproc 通过 Identity and Access Management (IAM) 控制对资源的访问。Toolbox 使用 Application Default Credentials (ADC) 完成认证与授权,因此需要确保 ADC 关联的 IAM 身份具备执行相应操作所需的权限。查询集群详情属于只读操作,常见的最小权限角色为 roles/dataproc.viewer;若后续还会对集群/作业执行管理操作,则需要 roles/dataproc.editor。预构建配置(见下文)默认声明了 Dataproc Viewer 权限。
配置工具:YAML 声明与参数说明
在 Toolbox 的配置文件中通过 kind: tool 块声明该工具(示例来自原文档 dataproc-get-cluster.md):
kind: tool
name: get_cluster
type: dataproc-get-cluster
source: my-dataproc-source
description: Use this tool to get details of a Dataproc cluster.
该工具接受如下参数:
clusterName:要检索的集群短名称。例如对于资源全名projects/my-project/regions/us-central1/clusters/my-cluster,只需传入my-cluster,无需传入 project 与 region——它们由 source 配置提供。
需要特别注意的是,源码在 Invoke 方法 中对 clusterName 做了显式校验:若传入的值包含 /,会直接返回 Agent 错误,提示必须使用不带斜杠的短名称:
if strings.Contains(name, "/") {
return nil, util.NewAgentError(fmt.Sprintf("clusterName must be a short name without '/': %s", name), nil)
}
clusterName 在参数清单中被声明为 WithStringRequired(false)(见 dataprocgetcluster.go),但若调用时未提供该参数,Invoke 中类型断言失败会返回 "missing required parameter: clusterName" 错误,因此实际调用时必须携带。
工具配置的参考字段如下(完整字段表来自原文档):
| field | type | required | description |
|---|---|---|---|
| type | string | true | Must be "dataproc-get-cluster". |
| source | string | true | Name of the source the tool should use. |
| description | string | true | Description of the tool that is passed to the LLM. |
| authRequired | string[] | false | List of auth services required to invoke this tool |
其中 description 会作为 Manifest 描述传给 LLM,用于让 Agent 理解该工具的用途(见 dataprocgetcluster.go);若未提供,默认值为 "Gets a Dataproc cluster"。type 与 source 在配置解析阶段即被校验为必填。
输出格式与字段含义
调用成功后返回的 JSON 结构如下(示例来自原文档):
{
"cluster": {
"name": "projects/my-project/regions/us-central1/clusters/my-cluster",
"uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"state": "RUNNING",
"createTime": "2023-10-27T10:00:00Z"
},
"consoleUrl": "https://console.cloud.google.com/dataproc/clusters/my-cluster/monitoring?region=us-central1&project=my-project",
"logsUrl": "https://console.cloud.google.com/logs/viewer?advancedFilter=resource.type%3D%22cloud_dataproc_cluster%22%0Aresource.labels.project_id%3D%22my-project%22%0Aresource.labels.region%3D%22us-central1%22%0Aresource.labels.cluster_name%3D%22my-cluster%22%0Aresource.labels.cluster_uuid%3D%22a1b2c3d4-e5f6-7890-1234-567890abcdef%22&project=my-project&resource=cloud_dataproc_cluster%2Fcluster_name%2Fmy-cluster"
}
返回结果包含三个顶层字段:
cluster:Dataproc Cluster 资源的完整 JSON 表示。源码在 GetCluster 方法 中先通过client.GetCluster拿到 protobuf 消息,再用protojson.Marshal序列化后反序列化为map[string]any嵌套在cluster键下,因此该对象会包含 Dataproc API 返回的完整集群信息(包括但不限于上例中的name、uuid、state、createTime),而不仅仅是摘要字段。consoleUrl:指向 Google Cloud Console 中该集群监控页的链接,由 ClusterConsoleURLFromProto 生成,格式为https://console.cloud.google.com/dataproc/clusters/{clusterName}/monitoring?region={region}&project={projectId}。logsUrl:指向 Cloud Logging 查看器的预过滤链接,由 ClusterLogsURLFromProto 生成。它会把resource.type="cloud_dataproc_cluster"与 project、region、cluster_name、cluster_uuid 等标签编码进 advancedFilter;当集群处于ERROR、DELETING、STOPPED、STOPPING等终止或停止状态时,还会自动把日志时间范围收窄到状态变更前 1 小时(startTime = stateStartTime.Add(-1 * time.Hour)),方便 Agent 直接定位故障窗口。对于运行中的集群,则不带时间过滤,查询全部日志。
底层实现:从工具调用到 GCP API
一次 dataproc-get-cluster 调用的完整调用链如下:
- 工具注册与配置解析:
init()中将dataproc-get-cluster注册到 Toolbox 工具注册表(见 dataprocgetcluster.go);配置块通过newConfig解码为Config结构体。 - Source 兼容性校验:
ValidateSource要求 source 实现了GetCluster(context.Context, string) (any, error)接口(dataprocgetcluster.go),dataprocsource 恰好满足该契约。 - 参数提取与校验:
Invoke从参数表中取出clusterName,并拒绝包含/的完整资源名。 - 调用 Dataproc Cluster Controller API:
Source.GetCluster构造GetClusterRequest{ProjectId, Region, ClusterName}(project/region 来自 source 配置),调用client.GetCluster获取 protobuf 集群对象。 - 结果包装:将集群 JSON 放入
cluster键,并附加consoleUrl与logsUrl两个排障入口,整体返回给 LLM。
这一链路同样被单元测试与集成测试覆盖:单元测试 dataprocgetcluster_test.go 验证了 YAML 配置能被正确解析为 dataprocgetcluster.Config(含 Type、Source、Description 等字段);集成测试 dataproc_integration_test.go 则直接调用 client.GetCluster 请求真实集群并比对返回差异,确保与 Dataproc API 的行为一致。
预构建配置与快速启用
若不想手写 source 与 tool 两份配置,可以使用 Toolbox 的预构建配置 dataproc(详见 prebuilt-configs/dataproc.md):
--prebuilt值:dataproc- 环境变量:
DATAPROC_PROJECT(GCP 项目 ID)、DATAPROC_REGION(Dataproc 区域) - 权限:
roles/dataproc.viewer(Dataproc Viewer,用于查看集群与作业) - 包含工具:
list_clusters(列出集群)、get_cluster(获取集群,即本文主题)、list_jobs(列出作业)、get_job(获取作业)
启动 Toolbox 服务时通过 --prebuilt dataproc 并设置上述两个环境变量,即可一次性获得包括 get_cluster 在内的四个 Dataproc 工具,配合 ADC 认证即可让 Agent 直接查询集群详情。该工具适合作为 Dataproc 集群排障、容量确认、状态审计等 Agent 工作流中的基础只读能力。