MCP Toolbox cloud-healthcare-get-dataset 工具：一次调用获取 Cloud Healthcare 数据集元数据
【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox
cloud-healthcare-get-dataset是 MCP Toolbox（MCP Toolbox for Databases）中专用于 Cloud Healthcare API 集成的一只读 MCP 工具，它不接收任何额外参数，直接返回当前 source 所绑定数据集（dataset）的完整元数据。本文以 cloud-healthcare-get-dataset 官方文档 为主体，结合仓库中的工具实现、source 实现、预置配置与集成测试，完整讲清该工具的配置方式、鉴权模式、底层调用链以及如何在预置配置中启用它。读完本文，你可以独立编写并验证该工具的配置，并理解它从 MCP 请求到 GCP API 调用的全过程。
工具定位：为什么需要一个"获取数据集元数据"的工具
Cloud Healthcare API 中的 dataset 是 Google Cloud 项目内承载模态化医疗数据的容器，其内部可包含 FHIR store 与 DICOM store 等数据仓库（见 Cloud Healthcare Source 文档）。dataset 是其他医疗数据资源（FHIR store、DICOM store）的命名空间前缀，因此"先拿到 dataset 元数据，再决定访问哪些 store"是典型的 LLM 工作流第一步。
cloud-healthcare-get-dataset工具的定位非常聚焦：
- 无参调用：文档明确说明 "It takes no extra parameters"，工具不暴露任何参数，调用方只需发起调用即可获得结果；
- 只读语义：工具返回的是数据集的描述信息（metadata），不产生任何写操作；
- 绑定 source：返回哪一个数据集的元数据，完全由配置中
source字段指向的cloud-healthcaresource 决定。
在仓库的预置配置 cloud-healthcare.yaml 中，该工具被命名为get_dataset，并与list_dicom_stores、list_fhir_stores一起打包进cloud_healthcare_dataset_tools工具集，构成"发现资源"类工具组（见 cloud-healthcare.yaml#L113-L118），印证了它作为数据集探索入口的设计意图。
前置条件：配置 cloud-healthcare source
cloud-healthcare-get-dataset只能配合type: cloud-healthcare的 source 使用。以下示例完整继承自 Cloud Healthcare Source 文档：
使用 ADC（应用默认凭证）的 source
kind: source name: my-healthcare-source type: "cloud-healthcare" project: "my-project-id" region: "us-central1" dataset: "my-healthcare-dataset-id" # allowedFhirStores: # Optional: Restricts tool access to a specific list of FHIR store IDs. # - "my_fhir_store_1" # allowedDicomStores: # Optional: Restricts tool access to a specific list of DICOM store IDs. # - "my_dicom_store_1" # - "my_dicom_store_2"使用客户端 OAuth 访问令牌的 source
kind: source name: my-healthcare-client-auth-source type: "cloud-healthcare" project: "my-project-id" region: "us-central1" dataset: "my-healthcare-dataset-id" useClientOAuth: truesource 配置字段参考（来自 source.md）：
| field | type | required | description |
|---|---|---|---|
| type | string | true | Must be "cloud-healthcare"。 |
| project | string | true | dataset 所在的 GCP 项目 ID。 |
| region | string | true | 数据集所在区域（如us、asia-northeast1）。 |
| dataset | string | true | 医疗数据集 ID。 |
| allowedFhirStores | []string | false | 可选的 FHIR store ID 白名单。配置后，工具尝试访问名单外的 store 会被拒绝；若只配置一个 store，预置工具会将其视为默认值。 |
| allowedDicomStores | []string | false | 可选的 DICOM store ID 白名单，语义同上。 |
| useClientOAuth | bool | false | 为 true 时，将请求 "Authorization" 头中的客户端 OAuth 访问令牌转发给下游查询，代表最终用户执行操作。 |
两点实现细节值得注意（均可在源码中确认）：
- 启动时校验数据集存在性。在 cloud_healthcare.go 中，source 初始化时会用 ADC 凭证实际调用一次
svc.Projects.Locations.Datasets.FhirStores.Get(dsName)（以探测方式验证projects/{project}/locations/{region}/datasets/{dataset}是否存在），若返回 404 则报错dataset '%s' not found。也就是说，get-dataset工具背后的数据集在 Toolbox 启动阶段就已被验证过一次。 - 鉴权模式由
useClientOAuth决定。默认走 ADC：initHealthcareConnection 通过google.FindDefaultCredentials(ctx, healthcare.CloudHealthcareScope)获取默认凭证并构造healthcare.Service；开启useClientOAuth后则改用 newHealthcareServiceCreator，在每次调用时用请求携带的令牌现建服务实例。文档中提到的 IAM 角色（如roles/healthcare.fhirResourceReader）要求同样适用于该工具，因为它读取的是 dataset 级资源。
工具配置示例与参数参考
继承自 官方文档 的标准配置示例：
kind: tool name: get_dataset type: cloud-healthcare-get-dataset source: my-healthcare-source description: Use this tool to get healthcare dataset metadata.参数参考表（原文档 Reference 部分）：
| field | type | required | description |
|---|---|---|---|
| type | string | true | Must be "cloud-healthcare-get-dataset"。 |
| source | string | true | 指向的 healthcare source 名称。 |
| description | string | true | 传递给 LLM 的工具描述。 |
从源码 cloudhealthcaregetdataset.go 的Config结构体可以补充两点文档未展开的事实：
description的"必填"是运行时强制的：Initialize 中若cfg.Description == ""会直接返回description is required for tool %q错误，配置无法加载成功；- 结构体还含有一个可选字段
Annotations *tools.ToolAnnotations（yaml:"annotations,omitempty"），不配置时工具默认获得只读注解tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewReadOnlyAnnotations)，即以只读语义暴露给 MCP 客户端。
该工具的配置解析测试见 cloudhealthcaregetdataset_test.go，其中用上面同款的 YAML 走server.UnmarshalPrimitiveConfig完整断言解析结果，可视为配置字段的"官方样例"。
实现原理：从 MCP 请求到 Cloud Healthcare API
工具注册与源兼容性校验
工具类型在 init() 中通过tools.Register("cloud-healthcare-get-dataset", newConfig)注册；newConfig使用 go-yaml 的Decoder将 YAML 块解码为Config。
source 兼容性由一个最小接口约束（cloudhealthcaregetdataset.go#L46-L49）：
type compatibleSource interface { UseClientAuthorization() bool GetDataset(string) (*healthcare.Dataset, error) }即一个 source 只要实现了UseClientAuthorization与GetDataset两个方法即被视为兼容。ValidateSource（cloudhealthcaregetdataset.go#L97-L103）在服务器装配阶段执行该类型断言，source 类型不符时启动即报invalid source for %q tool: source %q is not a compatible type。当前仓库中实现该接口的是 cloud-healthcare source。
调用链：Invoke 与鉴权分支
Invoke 的完整逻辑只有三步：
func (t Tool) Invoke(ctx context.Context, s sources.Source, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) { source, ok := s.(compatibleSource) ... if source.UseClientAuthorization() { tokenStr, err = accessToken.ParseBearerToken() ... } resp, err := source.GetDataset(tokenStr) if err != nil { return nil, util.ProcessGcpError(err) } return resp, nil }- 默认模式（source 未开启
useClientOAuth）：tokenStr保持为空字符串传入GetDataset，source 内部复用 ADC 建好的healthcare.Service； - 客户端授权模式（
useClientOAuth: true）：accessToken.ParseBearerToken()从工具调用请求的Authorization头解析 Bearer 令牌，解析失败返回 401；随后 source 的 getService 用该令牌现场构造服务实例，以最终用户身份发起查询。RequiresClientAuthorization（cloudhealthcaregetdataset.go#L125-L131）同样返回s.UseClientAuthorization()，供 MCP 服务器判断本次调用是否必须携带凭证； - 错误处理：任何 GCP 侧错误统一经
util.ProcessGcpError归一化为ToolboxError返回。
Source 侧的 GetDataset 实现
真正的 API 调用在 cloud_healthcare.go#L466-L478：
func (s *Source) GetDataset(tokenStr string) (*healthcare.Dataset, error) { svc, err := s.getService(tokenStr) ... datasetName := fmt.Sprintf("projects/%s/locations/%s/datasets/%s", s.Project(), s.Region(), s.DatasetID()) dataset, err := svc.Projects.Locations.Datasets.Get(datasetName).Do() if err != nil { return nil, fmt.Errorf("failed to get dataset %q: %w", datasetName, err) } return dataset, nil }即拼接 GCP 资源全名后调用 Cloud Healthcare API 的datasets.get，返回 SDK 的*healthcare.Dataset对象——这正是文档所说"returns the metadata of the healthcare dataset configured in the source"的实现。由于数据集完全由 source 的project/region/dataset三个字段决定，工具没有任何入参也顺理成章。
集成测试如何验证该工具
仓库的 Cloud Healthcare 集成测试 cloud_healthcare_integration_test.go 对该工具做了端到端验证：
- 测试先通过 GCP API 创建真实数据集、FHIR store 与 DICOM store，然后启动
toolbox serve --enable-api进程（cloud_healthcare_integration_test.go#L166-L179）； - runGetDatasetToolInvokeTest 向 REST 端点
http://127.0.0.1:5000/api/tool/my-get-dataset-tool/invoke发送空请求体{}，断言响应包含"name":"projects/{project}/locations/{region}/datasets/{dataset}"（期望串构造见 L181）； - 同一测试还覆盖了客户端授权路径：向
my-auth-get-dataset-tool携带my-google-auth_token请求头发起调用，验证useClientOAuth模式下凭 ID token 换取 access token 后调用依然成功。
这两个用例分别对应前文讲的"默认 ADC 模式"与"客户端授权模式"，是配置该工具后最快的自测参照。
在预置配置中启用 get_dataset
仓库内置的 cloud-healthcare.yaml 展示了生产环境常见的启用方式，source 通过环境变量注入，useClientOAuth使用${VAR:默认值}语法给出默认 false：
kind: source name: healthcare-source type: cloud-healthcare project: ${CLOUD_HEALTHCARE_PROJECT} region: ${CLOUD_HEALTHCARE_REGION} dataset: ${CLOUD_HEALTHCARE_DATASET} useClientOAuth: ${CLOUD_HEALTHCARE_USE_CLIENT_OAUTH:false} --- kind: tool name: get_dataset type: cloud-healthcare-get-dataset description: Use this tool to get the details of a healthcare dataset source: healthcare-source该文件还声明了三个 toolset：cloud_healthcare_dataset_tools（含get_dataset）、cloud_healthcare_fhir_tools、cloud_healthcare_dicom_tools（cloud-healthcare.yaml#L113-L138），MCP 客户端可按需订阅其中一组。使用该预置配置时需要设置CLOUD_HEALTHCARE_PROJECT、CLOUD_HEALTHCARE_REGION、CLOUD_HEALTHCARE_DATASET三个环境变量，并按需设置CLOUD_HEALTHCARE_USE_CLIENT_OAUTH。
适用前提与限制小结
- 适用前提：GCP 项目中已存在 Cloud Healthcare 数据集；执行 Toolbox 的 IAM 身份（ADC 或最终用户的 OAuth 身份）拥有读取该数据集的权限；数据集所在区域与 source 中
region一致。 - 行为限制：工具无参数，无法指定"其他"数据集——想切换数据集必须修改 source 的
dataset配置；返回体是 Cloud Healthcare API 的Dataset资源对象，不含 store 内容，需要进一步列举 FHIR/DICOM store 时应组合cloud-healthcare-list-fhir-stores/cloud-healthcare-list-dicom-stores工具（见 cloudhealthcare 工具文档目录）。 - 鉴权限制：
useClientOAuth: true时，若调用请求未携带可解析的 Bearer 令牌，工具会以 401 类错误终止本次调用，而不是回退到 ADC。
综合来看，cloud-healthcare-get-dataset是一个"配置面极小、行为面明确"的工具：三个必填字段（type、source、description）即完成配置，底层则依托cloud-healthcaresource 的资源名拼接与 ADC/OAuth 双通道鉴权完成datasets.get调用，适合作为 LLM 探索 Cloud Healthcare 资源的起点工具。
【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
