MCP Toolbox for Databases 的 Dataproc 预构建配置一条命令接入 GCP 集群与作业查询能力【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本指南以 MCP Toolbox for Databases 仓库中的 Dataproc 预构建配置文档docs/en/integrations/dataproc/prebuilt-configs/dataproc.md为核心详解如何通过--prebuilt dataproc一次性接入 GCP Dataproc 的集群与作业查询能力。你将掌握预构建配置声明的环境变量、IAM 权限要求、四个内置工具list_clusters、get_cluster、list_jobs、get_job的参数与返回格式以及这些能力在仓库源码中的实现原理可直接上手配置并接入你的 LLM Agent。预构建配置总览一个参数接入 DataprocDataproc 预构建配置是 MCP Toolbox for Databases 提供的开箱即用型配置之一其完整声明位于 dataproc.md要点如下配置项取值--prebuilt值dataproc环境变量DATAPROC_PROJECTGCP 项目 ID、DATAPROC_REGIONDataproc 区域所需 IAM 权限Dataproc Viewerroles/dataproc.viewer用于查看集群与作业内置工具list_clusters、get_cluster、list_jobs、get_job该配置的价值在于只需通过--prebuilt dataproc加载预构建配置并设置好上述两个环境变量MCP Toolbox 就会自动完成 Source 与四个工具的注册和绑定无需手工编写配置清单。四个工具全部是只读查询类能力适合 Agent 在执行任务时观测 Dataproc 集群状态、排查作业运行情况。预构建配置内部结构dataproc.yaml 源码剖析预构建配置的真实内容定义在仓库的 internal/prebuiltconfigs/tools/dataproc.yaml 中使用 Toolbox 的配置 DSLYAML 文档分隔符---串联多个资源定义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类型的 Source名为dataproc-source通过${DATAPROC_PROJECT}、${DATAPROC_REGION}两个占位符从环境变量注入project与region四个 Tool分别对应dataproc-list-clusters、dataproc-get-cluster、dataproc-list-jobs、dataproc-get-job四种工具类型全部显式绑定到dataproc-source一个 Group名为dataproc_tools把四个工具聚合为一个可供 LLM 引用的技能分组描述为与你的 Dataproc 集群和作业交互的技能。这也解释了为什么关联文档中工具列表恰好是这四个——它们是预构建配置中实际注册并被 LLM 可见的工具集合。环境变量与 Source 配置project 与 region 的传递链环境变量注入使用预构建配置时两个环境变量是必填的DATAPROC_PROJECTGCP 项目 ID决定查询哪个项目下的 Dataproc 资源DATAPROC_REGIONDataproc 资源所在的区域例如us-central1。它们通过配置占位符${VAR}注入到 Source 的project与region字段中见 dataproc.yaml。手工声明 Source不使用预构建配置时如果不使用预构建配置也可以手工声明等价 Source。仓库的 source.md 给出了标准写法kind: source name: my-dataproc-source type: dataproc project: my-project region: us-central1Source 的字段说明如下fieldtyperequireddescriptiontypestringtrue必须为dataprocprojectstringtrue拥有 Dataproc 资源的 GCP 项目 IDregionstringtrueDataproc 资源所在区域源码中的解析与客户端初始化在源码 internal/sources/dataproc/dataproc.go 中Config结构体与文档字段一一对应且name、type、project、region均带有validate:required校验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 }Initialize方法中一个值得注意的实现细节客户端 endpoint 由region拼接而成即fmt.Sprintf(%s-dataproc.googleapis.com:443, r.Region)随后创建三个客户端——ClusterControllerClient集群控制、OperationsClient长时操作、JobControllerClient作业控制。这意味着region不仅用于 API 请求参数还直接决定了 gRPC 连接的端点因此必须填写资源实际所在的区域。IAM 权限与 ADC 认证预构建配置文档要求的最小权限为Dataproc Viewerroles/dataproc.viewer足以支持查看集群与作业的四个只读工具。而 source.md 补充说明了更完整的授权路径Dataproc 通过 Identity and Access Management (IAM) 控制用户和组对 Dataproc 资源的访问Toolbox 使用Application Default Credentials (ADC)完成认证与授权与 ADC 关联的 IAM 身份需要具备执行相应操作的权限常见角色为roles/dataproc.editor或roles/dataproc.viewer若尚未配置 ADC需按 Google Cloud 官方指南设置gcloud auth application-default login等流程。一句话总结预构建配置要求roles/dataproc.viewer即可跑通四个查询工具如果你的 IAM 身份权限不足Agent 调用时会因 Dataproc API 拒绝授权而失败。四个内置工具详解四个工具均从 Source 配置中读取project和region无需在工具层重复指定。以下逐一说明参数、配置与输出。list_clusters列出并过滤集群工具文档见 dataproc-list-clusters.md参数如下参数必填说明filter否过滤表达式大小写敏感多个条件仅支持 AND 连接。可用字段status.state、clusterName、labels。示例status.state ACTIVE AND clusterName mycluster。status.state支持ACTIVE、INACTIVE、CREATING、RUNNING、ERROR、DELETING、UPDATING、STOPPING、STOPPEDpageSize否单页返回的最大集群数pageToken否上一页返回的分页令牌用于取下一页文档标注默认分页大小为20工具配置示例kind: tool name: list_clusters type: dataproc-list-clusters source: my-dataproc-source description: Use this tool to list and filter Dataproc clusters.输出格式字段说明见 dataproc.go 的ListClustersResponse与Cluster结构体{ 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?regionus-central1projectmy-project, logsUrl: https://console.cloud.google.com/logs/viewer?advancedFilterresource.type%3D%22cloud_dataproc_cluster%22...projectmy-project } ], nextPageToken: abcd1234 }get_cluster获取单个集群详情工具文档见 dataproc-get-cluster.md仅一个参数参数必填说明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: { ...完整集群对象... }, consoleUrl: ..., logsUrl: ... }的结构。与list_clusters返回精简字段不同get_cluster通过protojson.Marshal将 Dataproc API 返回的完整 protobuf Cluster 对象序列化为 JSON见 dataproc.go 的GetCluster方法因此字段更全适合排查集群配置细节。list_jobs列出并过滤作业工具文档见 dataproc-list-jobs.md参数如下参数必填说明filter否过滤表达式大小写敏感仅支持 AND 连接。可用字段status.state、labels。示例status.state RUNNING AND labels.env production。status.state支持PENDING、RUNNING、CANCEL_PENDING、JOB_STATE_CANCELLED、DONE、ERROR、ATTEMPT_FAILUREjobStateMatcher否作业状态匹配策略ALL全部作业默认、ACTIVE仅活跃作业、NON_ACTIVE仅非活跃作业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?regionus-central1projectmy-project, logsUrl: https://console.cloud.google.com/logs/viewer?advancedFilter...projectmy-project } ], nextPageToken: abcd1234 }源码层面dataproc.go 的ListJobs方法jobStateMatcher会被映射为 Dataproc API 的ListJobsRequest_JobStateMatcher枚举值非法取值会直接返回错误invalid jobStateMatcher: ... Supported values: ALL, ACTIVE, NON_ACTIVE。startTime/endTime则取自作业的StatusHistory与当前Status中的StateStartTime最小值开始时间与终止态时间结束时间。get_job获取单个作业详情工具文档见 dataproc-get-job.md仅一个参数参数必填说明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: { ...完整作业对象... }, consoleUrl: ..., logsUrl: ... }其中job对象同样来自protojson.Marshal的完整 protobuf 序列化GetJob方法包含reference、placement等原始字段可直接透传给 Agent 做进一步分析。输出格式背后的实现consoleUrl 与 logsUrl 的生成原理四个工具的响应中都包含consoleUrl与logsUrl其生成逻辑集中在 internal/sources/dataproc/url.goClusterConsoleURL/JobConsoleURL拼接 Google Cloud Console 的 Dataproc 集群监控页或作业页地址ClusterLogsURL/JobLogsURL构造 Cloud Logging 查看器的advancedFilter按cloud_dataproc_cluster资源类型、项目、区域、集群名可选cluster_uuid、作业 ID 过滤日志日志时间窗源码定义了logTimeBufferBefore 1 * time.Minute与logTimeBufferAfter 10 * time.Minute两个缓冲常量为起始/结束时间各外扩前后缓冲避免边缘日志遗漏终止态特殊处理当集群处于ERROR、DELETING、STOPPED、STOPPING等状态时ClusterLogsURLFromProto会把日志时间窗绑定到状态变更前 1 小时便于调试故障见 url.go。这意味着 Agent 拿到工具返回的logsUrl后可以直接把链接交给用户或打开日志查看器定位问题实现查询—诊断闭环。快速开始三步接入 Dataproc准备认证确保本机已配置 ADC且 IAM 身份拥有roles/dataproc.viewer或更高权限设置环境变量export DATAPROC_PROJECTmy-project export DATAPROC_REGIONus-central1启动服务并加载预构建配置mcp-toolbox serve --prebuilt dataproc启动后Sourcedataproc-source会按region拼接出{region}-dataproc.googleapis.com:443端点并初始化三个 Dataproc 客户端见 dataproc.go 的Initialize四个工具随即注册完成。之后你的 LLM Agent 便可通过list_clusters/get_cluster观测集群、通过list_jobs/get_job追踪作业全程只读、无需额外写权限。若需要更细粒度地自定义工具名称、描述或过滤默认值可放弃--prebuilt以 dataproc.yaml 为模板手工编写配置文件并参照 source.md 与四个工具文档调整参数通过mcp-toolbox serve --config file的方式加载。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MCP Toolbox for Databases 的 Dataproc 预构建配置：一条命令接入 GCP 集群与作业查询能力
MCP Toolbox for Databases 的 Dataproc 预构建配置一条命令接入 GCP 集群与作业查询能力【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本指南以 MCP Toolbox for Databases 仓库中的 Dataproc 预构建配置文档docs/en/integrations/dataproc/prebuilt-configs/dataproc.md为核心详解如何通过--prebuilt dataproc一次性接入 GCP Dataproc 的集群与作业查询能力。你将掌握预构建配置声明的环境变量、IAM 权限要求、四个内置工具list_clusters、get_cluster、list_jobs、get_job的参数与返回格式以及这些能力在仓库源码中的实现原理可直接上手配置并接入你的 LLM Agent。预构建配置总览一个参数接入 DataprocDataproc 预构建配置是 MCP Toolbox for Databases 提供的开箱即用型配置之一其完整声明位于 dataproc.md要点如下配置项取值--prebuilt值dataproc环境变量DATAPROC_PROJECTGCP 项目 ID、DATAPROC_REGIONDataproc 区域所需 IAM 权限Dataproc Viewerroles/dataproc.viewer用于查看集群与作业内置工具list_clusters、get_cluster、list_jobs、get_job该配置的价值在于只需通过--prebuilt dataproc加载预构建配置并设置好上述两个环境变量MCP Toolbox 就会自动完成 Source 与四个工具的注册和绑定无需手工编写配置清单。四个工具全部是只读查询类能力适合 Agent 在执行任务时观测 Dataproc 集群状态、排查作业运行情况。预构建配置内部结构dataproc.yaml 源码剖析预构建配置的真实内容定义在仓库的 internal/prebuiltconfigs/tools/dataproc.yaml 中使用 Toolbox 的配置 DSLYAML 文档分隔符---串联多个资源定义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类型的 Source名为dataproc-source通过${DATAPROC_PROJECT}、${DATAPROC_REGION}两个占位符从环境变量注入project与region四个 Tool分别对应dataproc-list-clusters、dataproc-get-cluster、dataproc-list-jobs、dataproc-get-job四种工具类型全部显式绑定到dataproc-source一个 Group名为dataproc_tools把四个工具聚合为一个可供 LLM 引用的技能分组描述为与你的 Dataproc 集群和作业交互的技能。这也解释了为什么关联文档中工具列表恰好是这四个——它们是预构建配置中实际注册并被 LLM 可见的工具集合。环境变量与 Source 配置project 与 region 的传递链环境变量注入使用预构建配置时两个环境变量是必填的DATAPROC_PROJECTGCP 项目 ID决定查询哪个项目下的 Dataproc 资源DATAPROC_REGIONDataproc 资源所在的区域例如us-central1。它们通过配置占位符${VAR}注入到 Source 的project与region字段中见 dataproc.yaml。手工声明 Source不使用预构建配置时如果不使用预构建配置也可以手工声明等价 Source。仓库的 source.md 给出了标准写法kind: source name: my-dataproc-source type: dataproc project: my-project region: us-central1Source 的字段说明如下fieldtyperequireddescriptiontypestringtrue必须为dataprocprojectstringtrue拥有 Dataproc 资源的 GCP 项目 IDregionstringtrueDataproc 资源所在区域源码中的解析与客户端初始化在源码 internal/sources/dataproc/dataproc.go 中Config结构体与文档字段一一对应且name、type、project、region均带有validate:required校验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 }Initialize方法中一个值得注意的实现细节客户端 endpoint 由region拼接而成即fmt.Sprintf(%s-dataproc.googleapis.com:443, r.Region)随后创建三个客户端——ClusterControllerClient集群控制、OperationsClient长时操作、JobControllerClient作业控制。这意味着region不仅用于 API 请求参数还直接决定了 gRPC 连接的端点因此必须填写资源实际所在的区域。IAM 权限与 ADC 认证预构建配置文档要求的最小权限为Dataproc Viewerroles/dataproc.viewer足以支持查看集群与作业的四个只读工具。而 source.md 补充说明了更完整的授权路径Dataproc 通过 Identity and Access Management (IAM) 控制用户和组对 Dataproc 资源的访问Toolbox 使用Application Default Credentials (ADC)完成认证与授权与 ADC 关联的 IAM 身份需要具备执行相应操作的权限常见角色为roles/dataproc.editor或roles/dataproc.viewer若尚未配置 ADC需按 Google Cloud 官方指南设置gcloud auth application-default login等流程。一句话总结预构建配置要求roles/dataproc.viewer即可跑通四个查询工具如果你的 IAM 身份权限不足Agent 调用时会因 Dataproc API 拒绝授权而失败。四个内置工具详解四个工具均从 Source 配置中读取project和region无需在工具层重复指定。以下逐一说明参数、配置与输出。list_clusters列出并过滤集群工具文档见 dataproc-list-clusters.md参数如下参数必填说明filter否过滤表达式大小写敏感多个条件仅支持 AND 连接。可用字段status.state、clusterName、labels。示例status.state ACTIVE AND clusterName mycluster。status.state支持ACTIVE、INACTIVE、CREATING、RUNNING、ERROR、DELETING、UPDATING、STOPPING、STOPPEDpageSize否单页返回的最大集群数pageToken否上一页返回的分页令牌用于取下一页文档标注默认分页大小为20工具配置示例kind: tool name: list_clusters type: dataproc-list-clusters source: my-dataproc-source description: Use this tool to list and filter Dataproc clusters.输出格式字段说明见 dataproc.go 的ListClustersResponse与Cluster结构体{ 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?regionus-central1projectmy-project, logsUrl: https://console.cloud.google.com/logs/viewer?advancedFilterresource.type%3D%22cloud_dataproc_cluster%22...projectmy-project } ], nextPageToken: abcd1234 }get_cluster获取单个集群详情工具文档见 dataproc-get-cluster.md仅一个参数参数必填说明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: { ...完整集群对象... }, consoleUrl: ..., logsUrl: ... }的结构。与list_clusters返回精简字段不同get_cluster通过protojson.Marshal将 Dataproc API 返回的完整 protobuf Cluster 对象序列化为 JSON见 dataproc.go 的GetCluster方法因此字段更全适合排查集群配置细节。list_jobs列出并过滤作业工具文档见 dataproc-list-jobs.md参数如下参数必填说明filter否过滤表达式大小写敏感仅支持 AND 连接。可用字段status.state、labels。示例status.state RUNNING AND labels.env production。status.state支持PENDING、RUNNING、CANCEL_PENDING、JOB_STATE_CANCELLED、DONE、ERROR、ATTEMPT_FAILUREjobStateMatcher否作业状态匹配策略ALL全部作业默认、ACTIVE仅活跃作业、NON_ACTIVE仅非活跃作业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?regionus-central1projectmy-project, logsUrl: https://console.cloud.google.com/logs/viewer?advancedFilter...projectmy-project } ], nextPageToken: abcd1234 }源码层面dataproc.go 的ListJobs方法jobStateMatcher会被映射为 Dataproc API 的ListJobsRequest_JobStateMatcher枚举值非法取值会直接返回错误invalid jobStateMatcher: ... Supported values: ALL, ACTIVE, NON_ACTIVE。startTime/endTime则取自作业的StatusHistory与当前Status中的StateStartTime最小值开始时间与终止态时间结束时间。get_job获取单个作业详情工具文档见 dataproc-get-job.md仅一个参数参数必填说明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: { ...完整作业对象... }, consoleUrl: ..., logsUrl: ... }其中job对象同样来自protojson.Marshal的完整 protobuf 序列化GetJob方法包含reference、placement等原始字段可直接透传给 Agent 做进一步分析。输出格式背后的实现consoleUrl 与 logsUrl 的生成原理四个工具的响应中都包含consoleUrl与logsUrl其生成逻辑集中在 internal/sources/dataproc/url.goClusterConsoleURL/JobConsoleURL拼接 Google Cloud Console 的 Dataproc 集群监控页或作业页地址ClusterLogsURL/JobLogsURL构造 Cloud Logging 查看器的advancedFilter按cloud_dataproc_cluster资源类型、项目、区域、集群名可选cluster_uuid、作业 ID 过滤日志日志时间窗源码定义了logTimeBufferBefore 1 * time.Minute与logTimeBufferAfter 10 * time.Minute两个缓冲常量为起始/结束时间各外扩前后缓冲避免边缘日志遗漏终止态特殊处理当集群处于ERROR、DELETING、STOPPED、STOPPING等状态时ClusterLogsURLFromProto会把日志时间窗绑定到状态变更前 1 小时便于调试故障见 url.go。这意味着 Agent 拿到工具返回的logsUrl后可以直接把链接交给用户或打开日志查看器定位问题实现查询—诊断闭环。快速开始三步接入 Dataproc准备认证确保本机已配置 ADC且 IAM 身份拥有roles/dataproc.viewer或更高权限设置环境变量export DATAPROC_PROJECTmy-project export DATAPROC_REGIONus-central1启动服务并加载预构建配置mcp-toolbox serve --prebuilt dataproc启动后Sourcedataproc-source会按region拼接出{region}-dataproc.googleapis.com:443端点并初始化三个 Dataproc 客户端见 dataproc.go 的Initialize四个工具随即注册完成。之后你的 LLM Agent 便可通过list_clusters/get_cluster观测集群、通过list_jobs/get_job追踪作业全程只读、无需额外写权限。若需要更细粒度地自定义工具名称、描述或过滤默认值可放弃--prebuilt以 dataproc.yaml 为模板手工编写配置文件并参照 source.md 与四个工具文档调整参数通过mcp-toolbox serve --config file的方式加载。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考