MCP Toolbox 中的 dataproc-get-cluster 工具查询 Google Cloud Dataproc 集群详情【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxdataproc-get-cluster是 MCP ToolboxGoogle Cloud 开源的数据库 MCP Server为 Dataproc 集成提供的只读工具用于按短名称精确获取某个 Google Cloud Dataproc 集群的完整详情并自动附上 Google Cloud Console 监控页与 Cloud Logging 日志页的直达链接。通过本文你将掌握如何在 Toolbox 配置中声明该工具、理解其clusterName参数的用法与限制、看懂其返回 JSON 的每个字段并从源码层面了解 Toolbox 是如何调用 Dataproc Cluster Controller API 完成查询与结果包装的。工具概览dataproc-get-cluster从配置的 Dataproc source 中检索一个指定的 Dataproc 集群。与dataproc-list-clusters批量列举集群不同该工具面向“已知集群短名称、需要获取单个集群完整状态”的场景适合 Agent 在需要确认集群是否运行、查看 UUID、获取排障入口时使用。该工具定义在 dataprocgetcluster.go 中其注册的类型标识为dataproc-get-clusterconst kind dataproc-get-cluster工具本身是只读的初始化时使用tools.NewReadOnlyAnnotations作为默认注解见 dataprocgetcluster.go不会对集群产生任何写操作。前置条件配置 Dataproc Sourcedataproc-get-cluster本身不携带项目与区域信息它从 source 配置中获取project与region。因此使用前需要先声明一个类型为dataproc的 source其完整字段说明见 source.mdkind: source name: my-dataproc-source type: dataproc project: my-project region: us-central1fieldtyperequireddescriptiontypestringtrueMust be dataproc.projectstringtrueID of the GCP project with Dataproc resources.regionstringtrueRegion containing Dataproc resources.从源码看dataprocsource 的配置结构在 dataproc.go 中定义project与region均标注为validate:required。初始化时Toolbox 会根据 region 拼接区域化端点并创建三个 gRPC 客户端ClusterController、Longrunning Operations、JobControllerendpoint : fmt.Sprintf(%s-dataproc.googleapis.com:443, r.Region) client, err : dataproc.NewClusterControllerClient(ctx, option.WithEndpoint(endpoint), option.WithUserAgent(ua))IAM 权限要求Dataproc 通过 Identity and Access Management (IAM) 控制对资源的访问。Toolbox 使用 Application Default Credentials (ADC) 完成认证与授权因此需要确保 ADC 关联的 IAM 身份具备执行相应操作所需的权限。查询集群详情属于只读操作常见的最小权限角色为roles/dataproc.viewer若后续还会对集群/作业执行管理操作则需要roles/dataproc.editor。预构建配置见下文默认声明了 Dataproc Viewer 权限。配置工具YAML 声明与参数说明在 Toolbox 的配置文件中通过kind: tool块声明该工具示例来自原文档 dataproc-get-cluster.mdkind: tool name: get_cluster type: dataproc-get-cluster source: my-dataproc-source description: Use this tool to get details of a Dataproc cluster.该工具接受如下参数clusterName要检索的集群短名称。例如对于资源全名projects/my-project/regions/us-central1/clusters/my-cluster只需传入my-cluster无需传入 project 与 region——它们由 source 配置提供。需要特别注意的是源码在 Invoke 方法 中对clusterName做了显式校验若传入的值包含/会直接返回 Agent 错误提示必须使用不带斜杠的短名称if strings.Contains(name, /) { return nil, util.NewAgentError(fmt.Sprintf(clusterName must be a short name without /: %s, name), nil) }clusterName在参数清单中被声明为WithStringRequired(false)见 dataprocgetcluster.go但若调用时未提供该参数Invoke中类型断言失败会返回 missing required parameter: clusterName 错误因此实际调用时必须携带。工具配置的参考字段如下完整字段表来自原文档fieldtyperequireddescriptiontypestringtrueMust be dataproc-get-cluster.sourcestringtrueName of the source the tool should use.descriptionstringtrueDescription of the tool that is passed to the LLM.authRequiredstring[]falseList of auth services required to invoke this tool其中description会作为 Manifest 描述传给 LLM用于让 Agent 理解该工具的用途见 dataprocgetcluster.go若未提供默认值为 Gets a Dataproc cluster。type与source在配置解析阶段即被校验为必填。输出格式与字段含义调用成功后返回的 JSON 结构如下示例来自原文档{ 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?regionus-central1projectmy-project, logsUrl: https://console.cloud.google.com/logs/viewer?advancedFilterresource.type%3D%22cloud_dataproc_cluster%22%0Aresource.labels.project_id%3D%22my-project%22%0Aresource.labels.region%3D%22us-central1%22%0Aresource.labels.cluster_name%3D%22my-cluster%22%0Aresource.labels.cluster_uuid%3D%22a1b2c3d4-e5f6-7890-1234-567890abcdef%22projectmy-projectresourcecloud_dataproc_cluster%2Fcluster_name%2Fmy-cluster }返回结果包含三个顶层字段clusterDataproc Cluster 资源的完整 JSON 表示。源码在 GetCluster 方法 中先通过client.GetCluster拿到 protobuf 消息再用protojson.Marshal序列化后反序列化为map[string]any嵌套在cluster键下因此该对象会包含 Dataproc API 返回的完整集群信息包括但不限于上例中的name、uuid、state、createTime而不仅仅是摘要字段。consoleUrl指向 Google Cloud Console 中该集群监控页的链接由 ClusterConsoleURLFromProto 生成格式为https://console.cloud.google.com/dataproc/clusters/{clusterName}/monitoring?region{region}project{projectId}。logsUrl指向 Cloud Logging 查看器的预过滤链接由 ClusterLogsURLFromProto 生成。它会把resource.typecloud_dataproc_cluster与 project、region、cluster_name、cluster_uuid 等标签编码进 advancedFilter当集群处于ERROR、DELETING、STOPPED、STOPPING等终止或停止状态时还会自动把日志时间范围收窄到状态变更前 1 小时startTime stateStartTime.Add(-1 * time.Hour)方便 Agent 直接定位故障窗口。对于运行中的集群则不带时间过滤查询全部日志。底层实现从工具调用到 GCP API一次dataproc-get-cluster调用的完整调用链如下工具注册与配置解析init()中将dataproc-get-cluster注册到 Toolbox 工具注册表见 dataprocgetcluster.go配置块通过newConfig解码为Config结构体。Source 兼容性校验ValidateSource要求 source 实现了GetCluster(context.Context, string) (any, error)接口dataprocgetcluster.godataprocsource 恰好满足该契约。参数提取与校验Invoke从参数表中取出clusterName并拒绝包含/的完整资源名。调用 Dataproc Cluster Controller APISource.GetCluster构造GetClusterRequest{ProjectId, Region, ClusterName}project/region 来自 source 配置调用client.GetCluster获取 protobuf 集群对象。结果包装将集群 JSON 放入cluster键并附加consoleUrl与logsUrl两个排障入口整体返回给 LLM。这一链路同样被单元测试与集成测试覆盖单元测试 dataprocgetcluster_test.go 验证了 YAML 配置能被正确解析为dataprocgetcluster.Config含Type、Source、Description等字段集成测试 dataproc_integration_test.go 则直接调用client.GetCluster请求真实集群并比对返回差异确保与 Dataproc API 的行为一致。预构建配置与快速启用若不想手写 source 与 tool 两份配置可以使用 Toolbox 的预构建配置dataproc详见 prebuilt-configs/dataproc.md--prebuilt值dataproc环境变量DATAPROC_PROJECTGCP 项目 ID、DATAPROC_REGIONDataproc 区域权限roles/dataproc.viewerDataproc Viewer用于查看集群与作业包含工具list_clusters列出集群、get_cluster获取集群即本文主题、list_jobs列出作业、get_job获取作业启动 Toolbox 服务时通过--prebuilt dataproc并设置上述两个环境变量即可一次性获得包括get_cluster在内的四个 Dataproc 工具配合 ADC 认证即可让 Agent 直接查询集群详情。该工具适合作为 Dataproc 集群排障、容量确认、状态审计等 Agent 工作流中的基础只读能力。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考