MCP Toolbox Dataproc 工具集实战:用 MCP 工具查询与管理 Google Cloud Dataproc 集群和作业

原创2026-09-13 18:04:491,615 阅读
文章标签:人工智能AI 应用MCP 服务数据库后端数据存储可观测性

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 观测工作流:

  1. 集群健康巡检:用 list-clusters 配合 filter=status.state = ERROR(或 INACTIVE)快速定位异常集群,再对命中的集群调用 get-cluster 深入排查;
  2. 作业状态监控:用 list-jobs 配合 jobStateMatcher=ACTIVE 查看正在运行的作业,或用 filter=status.state = ERROR 找出失败作业,再调用 get-job 获取完整错误信息;
  3. 日志与追踪:任意列表/详情返回中的 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 即可通过两个环境变量快速启用全部工具,无需手工编写配置。

相关文档与源码索引:tools 目录、source 配置、预构建配置、source 实现、工具实现、配置模板。

登录后查看全文
mcp-toolbox