MCP Toolbox Dataproc 工具集实战:用 MCP 工具查询与管理 Google Cloud Dataproc 集群和作业
MCP Toolbox Dataproc 工具集实战:用 MCP 工具查询与管理 Google Cloud Dataproc 集群和作业
导读
本文聚焦 MCP Toolbox for Databases 中 Google Cloud Dataproc 集成提供的四个核心 MCP 工具:dataproc-list-clusters、dataproc-get-cluster、dataproc-list-jobs 与 dataproc-get-job。你将掌握这四个工具的全部参数、YAML 配置方式、输出结构与底层实现原理,并学会通过 MCP 协议让 LLM(如 Gemini、Claude)直接查询 Dataproc 集群状态、筛选作业并获取控制台/日志跳转链接,从而在对话式数据分析场景中实现 Dataproc 资源观测的自动化。
1. Dataproc 工具集概览
在 MCP Toolbox 中,Dataproc 集成位于 docs/en/integrations/dataproc 目录下,其中 tools 索引页 统一收录了四个只读型查询工具:
| 工具类型 | 作用 |
|---|---|
dataproc-list-clusters |
返回 Dataproc 集群列表,支持过滤、分页 |
dataproc-get-cluster |
获取单个集群的完整详情 |
dataproc-list-jobs |
返回 Dataproc 作业列表,支持过滤、状态匹配与分页 |
dataproc-get-job |
获取单个作业的完整详情 |
这四个工具均从 Google Cloud Dataproc 数据源读取数据,且只做查询、不做变更——从源码看,它们都使用 tools.NewReadOnlyAnnotations 标记为只读工具(见 dataproclistclusters.go)。这意味着 Agent 可以安全地调用它们进行观测,不会对生产集群产生副作用。
工具的 project 与 region 不通过工具参数传入,而是统一从 source 配置中读取,因此一个 source 下的多个工具天然共享相同的项目与区域上下文,配置非常简洁。
2. 前置条件:Source 配置与 IAM 权限
2.1 定义 Dataproc Source
工具本身不含项目与区域信息,它们依赖 dataproc 类型的 source。一个最小可用的 source 配置如下(参见 source 文档):
kind: source
name: my-dataproc-source
type: dataproc
project: my-project
region: us-central1
source 字段说明:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | true | 必须为 "dataproc" |
| project | string | true | 包含 Dataproc 资源的 GCP 项目 ID |
| region | string | true | 包含 Dataproc 资源的区域 |
从源码实现看(dataproc.go),Config 结构体的 Project 与 Region 均带 validate:"required" 校验,缺失任一字段都会导致配置初始化失败。
2.2 IAM 权限要求
Toolbox 使用 Application Default Credentials (ADC) 对 Dataproc 进行认证授权。你需要确保 ADC 关联的 IAM 身份具备目标操作所需的权限,常用角色包括:
roles/dataproc.viewer:查看集群与作业(与四个查询工具的只读能力匹配);roles/dataproc.editor:更宽泛的管理权限。
2.3 区域端点解析
值得注意的一个实现细节:source 的 region 不仅用于 API 请求参数,还决定了客户端连接的端点。在 Initialize 中,Toolbox 会拼接形如 <region>-dataproc.googleapis.com:443 的区域化端点,并分别创建三个客户端:
ClusterControllerClient:负责集群的 List/Get;JobControllerClient:负责作业的 List/Get;OperationsClient:用于长时运行操作(供扩展场景使用)。
3. dataproc-list-clusters:列出并筛选集群
3.1 参数说明
dataproc-list-clusters 返回 Dataproc 集群列表(参见 工具文档),支持以下参数:
filter(可选):限制返回集群的过滤表达式。过滤器区分大小写,多个子句仅支持AND逻辑运算符组合。可过滤字段为status.state、clusterName与labels。示例:status.state = ACTIVE AND clusterName = mycluster。 支持的status.state值:ACTIVE、INACTIVE、CREATING、RUNNING、ERROR、DELETING、UPDATING、STOPPING、STOPPED。pageSize(可选):单页返回的最大集群数,默认20。pageToken(可选):上一次调用返回的分页令牌,用于获取下一页结果。
工具文档中 pageToken 的默认值标注为 20,结合源码可见该默认值实际归属于 pageSize(见下节 3.3),使用时建议按 pageSize=20 理解分页行为。
3.2 配置示例
kind: tool
name: list_clusters
type: dataproc-list-clusters
source: my-dataproc-source
description: Use this tool to list and filter Dataproc clusters.
3.3 源码级实现细节
工具实现位于 dataproclistclusters.go:
- 默认描述:若 YAML 中未提供
description,工具会自动使用"Lists and filters Dataproc clusters"作为 LLM 可见的描述。 - pageSize 校验:
pageSize必须是正整数,若传入<= 0的值,会返回 Agent 可读的错误提示pageSize must be positive: <n>(L119-L124)。 - 过滤语法细节:参数
filter的完整语法描述为field = value [AND [field = value]] ...,其中value可以是*以匹配所有值;ACTIVE聚合了CREATING、UPDATING、RUNNING状态,INACTIVE聚合了DELETING、ERROR、STOPPING、STOPPED状态;空格分隔的多个条件会被视为隐式AND。
底层数据流在 ListClusters 中完成:构建 ListClustersRequest(携带 project、region、pageSize、pageToken、filter),通过 iterator.NewPager 实现分页拉取,再经 ToClusters 将 protobuf 消息转换为精简的 JSON 结构。
3.4 输出格式
{
"clusters": [
{
"name": "projects/my-project/regions/us-central1/clusters/cluster-1",
"uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"state": "RUNNING",
"createTime": "2023-10-27T10:00:00Z",
"consoleUrl": "https://console.cloud.google.com/dataproc/clusters/cluster-1/monitoring?region=us-central1&project=my-project",
"logsUrl": "https://console.cloud.google.com/logs/viewer?advancedFilter=resource.type%3D%22cloud_dataproc_cluster%22..."
},
{
"name": "projects/my-project/regions/us-central1/clusters/cluster-2",
"uuid": "b2c3d4e5-f6a7-8901-2345-678901bcdefa",
"state": "ERROR",
"createTime": "2023-10-27T11:30:00Z",
"consoleUrl": "https://console.cloud.google.com/dataproc/clusters/cluster-2/monitoring?region=us-central1&project=my-project",
"logsUrl": "https://console.cloud.google.com/logs/viewer?advancedFilter=resource.type%3D%22cloud_dataproc_cluster%22..."
}
],
"nextPageToken": "abcd1234"
}
每个集群条目包含 6 个字段(对应 Cluster 结构体):
| 字段 | 说明 |
|---|---|
| name | 完整资源名,格式 projects/<project>/regions/<region>/clusters/<clusterName> |
| uuid | 集群 UUID |
| state | 集群状态(如 RUNNING、ERROR) |
| createTime | 状态开始时间,以 RFC3339 格式输出 |
| consoleUrl | Cloud Console 集群监控页直达链接 |
| logsUrl | Cloud Logging 过滤后的日志查看链接 |
从源码可以推断,state 来自 Status.State、createTime 取自 Status.StateStartTime,而 consoleUrl/logsUrl 分别由 ClusterConsoleURLFromProto 与 ClusterLogsURLFromProto 生成,后者会在 URL 中注入 project_id、region、cluster_name、cluster_uuid 等标签,方便一键跳转排查。
4. dataproc-get-cluster:获取单个集群详情
4.1 参数说明
dataproc-get-cluster 获取指定集群的完整信息(参见 工具文档),仅有一个参数:
clusterName:要获取的集群短名称。例如完整资源名为projects/my-project/regions/us-central1/clusters/my-cluster时,传入my-cluster即可。
project 与 region 同样取自 source 配置,无需在调用时指定。
4.2 配置示例
kind: tool
name: get_cluster
type: dataproc-get-cluster
source: my-dataproc-source
description: Use this tool to get details of a Dataproc cluster.
4.3 输出格式
{
"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..."
}
与列表接口不同,get-cluster 返回的 cluster 字段是 Dataproc API 的完整 protobuf 响应:源码 GetCluster 使用 protojson.Marshal 将整个 Cluster 消息序列化为 JSON,因此除了示例中展示的 name、uuid、state、createTime 外,还会包含配置、实例组、软件配置等全部字段(文档中以 ... 省略)。consoleUrl 与 logsUrl 仍然作为顶层字段附加,便于快速跳转。
5. dataproc-list-jobs:列出并筛选作业
5.1 参数说明
dataproc-list-jobs 返回 Dataproc 作业列表(参见 工具文档),支持以下参数:
filter(可选):限制返回作业的过滤表达式。区分大小写,多子句仅支持AND。可过滤字段为status.state与labels。示例:status.state = RUNNING AND labels.env = production。 支持的status.state值:PENDING、RUNNING、CANCEL_PENDING、JOB_STATE_CANCELLED、DONE、ERROR、ATTEMPT_FAILURE。jobStateMatcher(可选):指定状态匹配范围,默认ALL。支持值:ALL(所有作业)、ACTIVE(仅活跃作业)、NON_ACTIVE(仅非活跃作业)。pageSize(可选):单页返回的最大作业数。pageToken(可选):上一次调用返回的分页令牌,用于获取下一页结果。
5.2 配置示例
kind: tool
name: list_jobs
type: dataproc-list-jobs
source: my-dataproc-source
description: Use this tool to list and filter Dataproc jobs.
5.3 源码级实现细节
工具实现在 dataproclistjobs.go,底层逻辑位于 ListJobs:
- jobStateMatcher 合法性校验:若传入的值不在
ALL/ACTIVE/NON_ACTIVE之列,会直接返回错误invalid jobStateMatcher: <v>. Supported values: ALL, ACTIVE, NON_ACTIVE(L295-L300),映射到 Dataproc API 的ListJobsRequest_JobStateMatcher枚举。 - 时间字段推导:
startTime取StatusHistory与当前Status.StateStartTime中最早的时间;当作业处于DONE、CANCELLED、ERROR终态时,endTime取该终态的开始时间(ToJobs)。 - subStatus 字段:
subStatus仅在存在子状态时输出(Go 结构体带omitempty),对应Status.Substate枚举。
5.4 输出格式
{
"jobs": [
{
"id": "job-1",
"status": "DONE",
"subStatus": "HOURS",
"startTime": "2023-10-27T10:00:00Z",
"endTime": "2023-10-27T10:05:00Z",
"clusterName": "cluster-1",
"consoleUrl": "https://console.cloud.google.com/dataproc/jobs/job-1?region=us-central1&project=my-project",
"logsUrl": "https://console.cloud.google.com/logs/viewer?advancedFilter=resource.type%3D%22cloud_dataproc_cluster%22..."
},
{
"id": "job-2",
"status": "RUNNING",
"startTime": "2023-10-27T10:10:00Z",
"clusterName": "cluster-1",
"consoleUrl": "https://console.cloud.google.com/dataproc/jobs/job-2?region=us-central1&project=my-project",
"logsUrl": "https://console.cloud.google.com/logs/viewer?advancedFilter=resource.type%3D%22cloud_dataproc_cluster%22..."
}
],
"nextPageToken": "abcd1234"
}
每个作业条目(对应 Job 结构体)包含 id、status、可选 subStatus、startTime、可选 endTime、clusterName(取自 Placement.ClusterName)、consoleUrl 与 logsUrl。注意 RUNNING 中的 job-2 没有 endTime,符合其尚未结束的语义。
6. dataproc-get-job:获取单个作业详情
6.1 参数说明
dataproc-get-job 获取指定作业的完整信息(参见 工具文档),仅有一个参数:
jobId:作业 ID。例如完整资源名为projects/my-project/regions/us-central1/jobs/my-job时,传入my-job。
6.2 配置示例
kind: tool
name: get_job
type: dataproc-get-job
source: my-dataproc-source
description: Use this tool to get details of a Dataproc job.
6.3 输出格式
{
"job": {
"reference": {
"projectId": "my-project",
"jobId": "my-job"
},
"placement": {
"clusterName": "my-cluster",
"clusterUuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
},
"...": "..."
},
"consoleUrl": "https://console.cloud.google.com/dataproc/jobs/my-job?region=us-central1&project=my-project",
"logsUrl": "https://console.cloud.google.com/logs/viewer?advancedFilter=resource.type%3D%22cloud_dataproc_cluster%22..."
}
与 get-cluster 一致,get-job 的 job 字段也是完整 protobuf 响应(源码 GetJob 使用 protojson.Marshal 序列化),除 reference、placement 外还包含 Spark/Hadoop 作业的完整状态、状态历史、驱动程序信息、指标等全部字段;consoleUrl 与 logsUrl 附加在顶层。
7. 预构建配置:一条命令启用全部工具
MCP Toolbox 为 Dataproc 提供了开箱即用的预构建配置(详见 prebuilt-configs/dataproc.md):
--prebuilt取值:dataproc- 环境变量:
DATAPROC_PROJECT:GCP 项目 ID;DATAPROC_REGION:Dataproc 区域。
- 所需权限:
roles/dataproc.viewer(查看集群与作业) - 预置工具:
list_clusters、get_cluster、list_jobs、get_job
对应的完整配置模板位于 dataproc.yaml,它在一个文件中依次定义了 source、四个工具以及一个名为 dataproc_tools 的 group:
kind: source
name: dataproc-source
type: dataproc
project: ${DATAPROC_PROJECT}
region: ${DATAPROC_REGION}
---
kind: tool
name: list_clusters
type: dataproc-list-clusters
source: dataproc-source
---
kind: tool
name: get_cluster
type: dataproc-get-cluster
source: dataproc-source
---
kind: tool
name: list_jobs
type: dataproc-list-jobs
source: dataproc-source
---
kind: tool
name: get_job
type: dataproc-get-job
source: dataproc-source
---
kind: group
name: dataproc_tools
description: Skills to interact with your Dataproc clusters and jobs.
tools:
- list_clusters
- get_cluster
- list_jobs
- get_job
从该模板可以归纳出 Dataproc 工具的通用 YAML 字段(四个工具一致):
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | true | 对应工具类型,如 dataproc-list-clusters |
| source | string | true | 工具使用的 source 名称 |
| description | string | true | 传给 LLM 的工具描述(缺省时有内置默认描述) |
| authRequired | string[] | false | 调用该工具所需的服务认证列表 |
集成测试可参考 dataproc_integration_test.go,它验证了 source 初始化与工具注册的完整链路。
8. 典型应用场景与调用链路
结合上述四个工具,可以构建出完整的 Dataproc 观测工作流:
- 集群健康巡检:用
list-clusters配合filter=status.state = ERROR(或INACTIVE)快速定位异常集群,再对命中的集群调用get-cluster深入排查; - 作业状态监控:用
list-jobs配合jobStateMatcher=ACTIVE查看正在运行的作业,或用filter=status.state = ERROR找出失败作业,再调用get-job获取完整错误信息; - 日志与追踪:任意列表/详情返回中的
consoleUrl与logsUrl可直接交给 Agent 生成排查引导,或由用户一键跳转到 Cloud Console / Cloud Logging。
调用链路整体为:MCP 客户端(LLM)→ 工具 Invoke(参数校验)→ source 的 List/Get 方法(构造请求、分页、错误处理)→ 官方 Go 客户端 → Dataproc API,全程只读。
9. 小结
- 四个 Dataproc 工具均为只读查询工具,
project/region统一来自 source 配置,使用前需配置好 ADC 与roles/dataproc.viewer(或 editor)权限; - 列表类工具支持
filter(AND-only、区分大小写)、pageSize、pageToken,作业列表额外支持jobStateMatcher(ALL/ACTIVE/NON_ACTIVE); - 详情类工具返回完整 protobuf JSON,并附加
consoleUrl/logsUrl便于跳转; - 使用
--prebuilt dataproc即可通过两个环境变量快速启用全部工具,无需手工编写配置。