MCP Toolbox Dataproc 数据源接入指南:配置、鉴权与集群/作业管理工具详解

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

MCP Toolbox Dataproc 数据源接入指南:配置、鉴权与集群/作业管理工具详解

MCP Toolbox for Databases 通过 dataproc 数据源(source)将 Google Cloud Dataproc Clusters 的能力暴露为标准的 MCP 工具,使 Agent 可以直接列出/查询 Spark 与 Hadoop 集群及作业。本文以 source.md 为主体,结合仓库源码与工具文档,完整讲解数据源配置、IAM/ADC 鉴权前提、四个内置工具的参数语义与输出结构,并深入到客户端初始化与 Console/Logs 链接生成的实现原理。

Dataproc Source 是什么

Dataproc Clusters 是 Google Cloud 上用于按需调配和管理 Apache Spark、Apache Hadoop 集群的托管服务。Dataproc Source 允许 Toolbox 与托管在 Google Cloud 上的 Dataproc Clusters 交互:通过一份 YAML 配置声明 project 与 region,Toolbox 即可创建底层 gRPC 客户端,并把 Dataproc 的集群与作业查询能力封装成可供 LLM 调用的工具。

从源码看,该数据源在仓库中以 internal/sources/dataproc/dataproc.go 实现,注册类型名为 dataproc,并通过 sources.Register(SourceType, newConfig) 完成自注册,配置结构非常简单:

type Config struct {
	Name    string `yaml:"name" validate:"required"`
	Type    string `yaml:"type" validate:"required"`
	Project string `yaml:"project" validate:"required"`
	Region  string `yaml:"region" validate:"required"`
}

即一个数据源只需要“名称 + 类型 + 项目 ID + 区域”四个字段即可工作,这也是后续所有 Dataproc 工具共享项目与区域上下文的依据(工具文档中反复出现的 "The tool gets the project and region from the source configuration" 即源于此)。

数据源配置:字段与完整示例

在 Toolbox 的配置文件中,用如下 YAML 声明一个 Dataproc 数据源:

kind: source
name: my-dataproc-source
type: dataproc
project: my-project
region: us-central1

字段参考表如下(完整继承自 source.md 的 Reference 节):

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。

需要特别说明的是 region 的作用范围。从 dataproc.go 的 Initialize 实现可以看到,region 不仅作为请求参数使用,还直接决定了客户端连接的服务端点:

endpoint := fmt.Sprintf("%s-dataproc.googleapis.com:443", r.Region)
client, err := dataproc.NewClusterControllerClient(ctx, option.WithEndpoint(endpoint), option.WithUserAgent(ua))

也就是说 Toolbox 会构造 {region}-dataproc.googleapis.com:443 这样的区域级端点,并分别创建三个底层客户端:

  • ClusterControllerClient:负责集群的列表与详情查询;
  • JobControllerClient:负责作业的列表与详情查询;
  • longrunning.OperationsClient:负责长时间运行操作的跟踪(为后续可能的异步操作预留)。

三个客户端会在 Close() 时被统一关闭(errors.Join),实现见 dataproc.go。

鉴权前提:ADC 与 IAM 权限

Dataproc 使用 Identity and Access Management (IAM) 控制用户和组对 Dataproc 资源的访问。Toolbox 在访问 Dataproc 时使用你的应用默认凭据(Application Default Credentials,ADC) 进行授权与认证。

使用这种方式时,需要确保与你的 ADC 关联的 IAM 身份具备你打算执行的操作所需的权限。常用角色包括:

  • roles/dataproc.editor:编辑级别权限,可执行创建、修改等操作;
  • roles/dataproc.viewer:只读查看权限,可列出与查看集群、作业。

如果只想让 Agent 执行查询类操作(本数据源当前暴露的四个工具均为读取类),roles/dataproc.viewer 通常已足够;具体可按官方 ADC 设置指引配置本地凭据。此外,预置配置(prebuilt config)也印证了这一最小权限要求:Dataproc 预置配置仅声明 Dataproc Viewer(roles/dataproc.viewer)用于检查集群与作业,详见 docs/en/integrations/dataproc/prebuilt-configs/dataproc.md。

可用工具总览

dataproc 数据源当前暴露四个工具,均属于读取(只读)型工具,工具目录见 internal/tools/dataproc/:

工具类型 作用 文档
dataproc-list-clusters 列出并过滤 Dataproc 集群 tools/dataproc-list-clusters.md
dataproc-get-cluster 获取单个集群详情 tools/dataproc-get-cluster.md
dataproc-list-jobs 列出并过滤 Dataproc 作业 tools/dataproc-list-jobs.md
dataproc-get-job 获取单个作业详情 tools/dataproc-get-job.md

同时仓库提供 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-list-clusters

参数说明

  • 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(可选):上一次调用返回的页令牌,用于获取下一页结果。

该工具的项目与区域取自数据源配置。工具参数声明与默认值在源码中可查,例如 dataproclistclusters.go 中 pageSize 默认值即为 20,并且 pageSize <= 0 时工具会返回 Agent 错误 pageSize must be positive。

配置示例

kind: tool
name: list_clusters
type: dataproc-list-clusters
source: my-dataproc-source
description: Use this tool to list and filter Dataproc clusters.

输出格式

{
  "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=..."
    }
  ],
  "nextPageToken": "abcd1234"
}

每个集群字段(name、uuid、state、createTime、consoleUrl、logsUrl)与 dataproc.go 中 Cluster 结构体一一对应;name 为完整资源名(projects/{project}/regions/{region}/clusters/{clusterName}),state 取自 Status.State 的枚举字符串,createTime 取状态开始时间并格式化为 RFC3339。

实现要点

源码通过 iterator.NewPager 分页遍历 client.ListClusters 的结果(见 dataproc.go),将 protobuf 消息转换为 Cluster 结构后,连同 nextPageToken 一起封装为 ListClustersResponse 返回,因此支持分页游标式的连续拉取。

工具详解二:dataproc-get-cluster

参数说明

  • clusterName:要获取的集群的短名称。例如对于完整资源名 projects/my-project/regions/us-central1/clusters/my-cluster,只需传 my-cluster。

工具的项目与区域同样取自数据源配置。

配置示例

kind: tool
name: get_cluster
type: dataproc-get-cluster
source: my-dataproc-source
description: Use this tool to get details of a Dataproc cluster.

输出格式

{
  "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=..."
}

实现要点

与列表工具不同,GetCluster 返回的是完整的 protobuf 集群消息:源码先将 GetCluster 响应用 protojson.Marshal 序列化为 JSON 再反序列化为 map<a href="https://link.gitcode.com/i/697daa3309aa65947affef11e2600b8d" target="_blank">string]any,最后在外层包裹 consoleUrl、logsUrl 与 cluster 三个字段(见 [dataproc.go)。因此 cluster 对象内会包含 Dataproc API 返回的完整集群详情(如配置、软件、网络等),信息量远大于列表接口的摘要字段。

工具详解三:dataproc-list-jobs

参数说明

  • 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。若传入非法值,源码会返回明确错误 invalid jobStateMatcher: ... Supported values: ALL, ACTIVE, NON_ACTIVE(见 dataproc.go)。
  • pageSize(可选):单页返回的最大作业数。
  • pageToken(可选):上一次调用返回的页令牌,用于获取下一页结果。

配置示例

kind: tool
name: list_jobs
type: dataproc-list-jobs
source: my-dataproc-source
description: Use this tool to list and filter Dataproc jobs.

输出格式

{
  "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=..."
    }
  ],
  "nextPageToken": "abcd1234"
}

实现要点

作业字段映射见 dataproc.go 的 Job 结构体。其中 startTime 取 StatusHistory 与当前状态中最早的 StateStartTime,而 endTime 仅在作业进入终态(DONE、CANCELLED、ERROR)时填充;clusterName 取自 Placement.ClusterName。注意 subStatus 与 endTime 带有 omitempty 标签,未赋值时不会出现在 JSON 输出中。

工具详解四:dataproc-get-job

参数说明

  • jobId:作业 ID。例如对于完整资源名 projects/my-project/regions/us-central1/jobs/my-job,只需传 my-job。

配置示例

kind: tool
name: get_job
type: dataproc-get-job
source: my-dataproc-source
description: Use this tool to get details of a Dataproc job.

输出格式

{
  "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=..."
}

与 get-cluster 一致,get-job 也返回完整的 protobuf 作业消息(通过 protojson 序列化),外层包裹 consoleUrl、logsUrl 与 job 三个字段(见 dataproc.go),因此 job 对象包含作业的引用、放置信息、状态历史、Spark/Hive 等作业详情配置。

通用参考字段与实现纵深

四个工具均继承自 tools.ConfigBase,其 YAML 配置字段完全一致(分别见各工具文档的 Reference 节):

field type required description
type string true 必须为该工具的唯一类型(如 "dataproc-list-clusters")。
source string true 该工具要使用的数据源名称。
description string true 传给 LLM 的工具描述。
authRequired string[] false 调用该工具所需的鉴权服务列表。

以 dataproclistclusters.go 为例,工具注册流程为:tools.Register(kind, newConfig) 注册类型 → Initialize 构建参数清单与 Manifest → Invoke 校验 source 兼容性(要求数据源实现 ListClusters(context.Context, *int, string, string) (any, error) 接口)后执行调用;GCP 侧错误统一通过 util.ProcessGcpError 转换为 Toolbox 错误结构返回给客户端。

Console 与 Logs 链接的生成

工具输出中的 consoleUrl 与 logsUrl 并非来自 Dataproc API,而是由 Toolbox 本地拼接生成,实现在 internal/sources/dataproc/url.go:

  • ClusterConsoleURL / JobConsoleURL:直接生成指向 Cloud Console 监控页 / 作业页的 URL;
  • ClusterLogsURL / JobLogsURL:使用 resource.type="cloud_dataproc_cluster" 与 resource.labels.*、labels.job_id 等条件构造 Cloud Logging 的 advancedFilter,并附上 URL 编码的时间范围。

值得注意的细节是日志时间窗的智能处理(见 url.go 与 url.go):常量 logTimeBufferBefore = 1 * time.Minute、logTimeBufferAfter = 10 * time.Minute,即日志查询的起始时间会提前 1 分钟、结束时间会延后 10 分钟,避免边界日志遗漏。此外,当集群处于 ERROR、DELETING、STOPPED、STOPPING 等状态时,日志窗口会被限制在状态变更前一小时以内,方便定位故障;作业处于 DONE、CANCELLED、ERROR 终态时同样会以状态开始时间为界截断日志窗口。这些设计让 Agent 拿到的 logsUrl 直接就是"有货可看"的排障链接。

常见使用场景

  1. 集群巡检:用 list_clusters 加 filter(如 status.state = ERROR)快速发现异常集群,再配合 get_cluster 与 logsUrl 深入排查;
  2. 作业状态追踪:用 list_jobs 按 status.state = RUNNING 或 jobStateMatcher = ACTIVE 过滤进行中的作业,用 get_job 查看单个作业完整详情;
  3. Agent 化运维问答:在 Toolbox 配置中声明数据源与工具后,LLM 即可基于工具描述自动发起集群/作业查询,并将 consoleUrl 直接呈现给用户跳转排查。

总结

dataproc 数据源是 Toolbox 接入 Google Cloud Dataproc 的最小且完整的示例:一份含 project/region 的 YAML 配置、ADC + IAM 角色鉴权、四个开箱即用的只读工具。理解其底层实现(区域级端点构造、protobuf 转换、分页游标、日志链接时间窗)有助于在配置工具链时准确预判参数行为与输出结构。完整源码与工具文档可继续参阅 internal/sources/dataproc/dataproc.go、internal/sources/dataproc/url.go 以及 docs/en/integrations/dataproc/ 下的工具文档。

登录后查看全文
mcp-toolbox