MCP Toolbox Dataproc 数据源接入指南:配置、鉴权与集群/作业管理工具详解
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 直接就是"有货可看"的排障链接。
常见使用场景
- 集群巡检:用
list_clusters加filter(如status.state = ERROR)快速发现异常集群,再配合get_cluster与logsUrl深入排查; - 作业状态追踪:用
list_jobs按status.state = RUNNING或jobStateMatcher = ACTIVE过滤进行中的作业,用get_job查看单个作业完整详情; - 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/ 下的工具文档。