MCP Toolbox 中 cloud-healthcare-list-fhir-stores 工具详解列出 Cloud Healthcare 数据集中的 FHIR 存储【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本文基于 MCP Toolbox 仓库中的工具参考文档讲解cloud-healthcare-list-fhir-stores工具的用途、YAML 配置方式与字段语义并结合源码剖析它如何调用 Cloud Healthcare API 的FhirStores.List、如何通过allowedFhirStores白名单过滤结果以及两种认证模式ADC 与客户端 OAuth下工具的实际执行链路。读完本文你可以直接在自己的 toolbox.yaml 中配置该工具并理解其返回结果背后的实现细节与安全边界。1. 工具定位它解决什么问题cloud-healthcare-list-fhir-stores用于列出cloud-healthcare数据源对应数据集dataset中所有可用的 FHIR 存储FHIR stores并返回这些存储的详细信息。它是 Cloud Healthcare 数据发现discovery链路的第一步LLM 或客户端在不知道数据集里有哪些 FHIR store 时先调用本工具获取列表再用返回的 store ID 去驱动cloud-healthcare-get-fhir-store、cloud-healthcare-fhir-patient-search等需要storeID参数的下游工具。该工具不接受任何额外入参它只需要绑定一个cloud-healthcare类型的 source执行时自动作用于该 source 配置中指定的 project / region / dataset。2. 配置示例继承自官方参考文档官方参考文档 cloud-healthcare-list-fhir-stores.md 给出的标准配置如下kind: tool name: list_fhir_stores type: cloud-healthcare-list-fhir-stores source: my-healthcare-source description: Use this tool to list FHIR stores in the healthcare dataset.其中source: my-healthcare-source指向一个必须先定义的cloud-healthcaresource。完整的 source 配置示例来自 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如果需要让 LLM 以“代表客户端身份”查询而非服务器侧身份在 source 中追加useClientOAuth: true即可本工具会自动切换为解析请求头中的 OAuth token。3. 工具字段参考表字段类型必填说明typestring是必须为cloud-healthcare-list-fhir-storessourcestring是对应的 healthcare source 名称descriptionstring是传递给 LLM 的工具描述该工具没有声明任何调用参数parameters。从源码可以看到Initialize中构造的allParameters是空的parameters.Parameters{}因此 MCP 协议下该工具的 input schema 不含额外字段见 cloudhealthcarelistfhirstores.go 中Initialize方法约 L65-L80。4. 兼容的数据源cloud-healthcare source工具声明的兼容 source 接口很小要求 source 实现两个方法type compatibleSource interface { UseClientAuthorization() bool ListFHIRStores(string) ([]*healthcare.FhirStore, error) }见 cloudhealthcarelistfhirstores.go 约 L46-L49在仓库中实现该接口的就是cloud-healthcaresourcecloud_healthcare.go。其配置结构体为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 Dataset string yaml:dataset validate:required AllowedFHIRStores []string yaml:allowedFhirStores AllowedDICOMStores []string yaml:allowedDicomStores UseClientOAuth bool yaml:useClientOAuth }cloud_healthcare.go 约 L67-L77。要点project/region/dataset三者共同定位数据集source 初始化时会调用FhirStores.Get(datasetName)校验数据集真实存在不存在则直接报错allowedFhirStores是可选白名单初始化时会逐个校验其存在性一旦配置ListFHIRStores的返回结果会被过滤见下节useClientOAuth决定认证方式。source 初始化时的数据集与白名单校验从 cloud_healthcare.go 的Initialize方法约 L83-L143可以看到source 启动阶段就做了三件事通过google.FindDefaultCredentials(ctx, healthcare.CloudHealthcareScope)获取 ADC 凭据并构造healthcare.ServiceuseClientOAuth: true时则改为构造一个按 token 创建 service 的 creator后续每次调用用客户端 token 新建 service拼接资源名projects/{project}/locations/{region}/datasets/{dataset}调用 FHIR store 的 Get 验证数据集存在404 时报dataset ... not found遍历allowedFhirStores逐个调用FhirStores.Get验证 store 存在构建allowedFHIRStores集合。也就是说白名单里的 store ID 写错会导致toolbox 启动即失败而不是运行时才报错。5. 执行链路从 MCP 调用到 ListFHIRStores 过滤工具侧的Invoke方法cloudhealthcarelistfhirstores.go 约 L105-L123逻辑非常清晰断言 source 实现compatibleSource接口否则返回 500若source.UseClientAuthorization()为 true则通过accessToken.ParseBearerToken()从请求的Authorization头解析 Bearer token失败返回 401否则 token 为空串调用source.ListFHIRStores(tokenStr)错误经util.ProcessGcpError(err)转换后返回成功则直接返回[]*healthcare.FhirStore结果。Source 侧的ListFHIRStorescloud_healthcare.go 约 L581-L607实现如下func (s *Source) ListFHIRStores(tokenStr string) ([]*healthcare.FhirStore, error) { svc, err : s.getService(tokenStr) // ... datasetName : fmt.Sprintf(projects/%s/locations/%s/datasets/%s, s.Project(), s.Region(), s.DatasetID()) stores, err : svc.Projects.Locations.Datasets.FhirStores.List(datasetName).Do() // ... var filtered []*healthcare.FhirStore for _, store : range stores.FhirStores { if len(s.AllowedFHIRStores()) 0 { filtered append(filtered, store) continue } if len(store.Name) 0 { continue } parts : strings.Split(store.Name, /) if _, ok : s.AllowedFHIRStores()[parts[len(parts)-1]]; ok { filtered append(filtered, store) } } return filtered, nil }两个关键行为值得注意未配置allowedFhirStores时返回数据集中全部 FHIR store配置后按 store 资源名最后一段store ID与白名单求交集过滤。这实现了“把 LLM 可见的数据范围收敛到指定 store”的访问控制目标返回类型是[]*healthcare.FhirStoreGoogle API 客户端库的完整 FHIR store 资源对象包含name、version、basicHapiFhirConfig、labels等字段MCP 层将其 JSON 序列化后返回给调用方。getService(tokenStr)约 L291-L302体现了双认证模式默认用初始化时创建的共享 serviceADC 身份开启useClientOAuth时用该次请求携带的 token 现场构造新 service实现“代表用户身份on-behalf-of”查询。相应地工具方法RequiresClientAuthorization约 L125-L131会让 MCP 层在useClientOAuth: true时强制要求请求携带 Authorization 头。另外该工具在注册时默认使用tools.NewReadOnlyAnnotationscloudhealthcarelistfhirstores.go 约 L75即可在 MCP 能力元数据中标记为只读操作——它只查询不修改任何 Cloud Healthcare 资源。6. 预构建配置一行--prebuilt即可获得该工具仓库内置了cloud-healthcare预构建配置cloud-healthcare.yaml其中包含本工具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: list_fhir_stores type: cloud-healthcare-list-fhir-stores description: Use this tool to list the FHIR stores in the healthcare dataset source: healthcare-source运行toolbox serve --prebuilt cloud-healthcare并设置四个环境变量CLOUD_HEALTHCARE_PROJECT、CLOUD_HEALTHCARE_REGION、CLOUD_HEALTHCARE_DATASET、可选的CLOUD_HEALTHCARE_USE_CLIENT_OAUTH默认false即可得到包含list_fhir_stores在内的全部 Cloud Healthcare 工具。该预构建配置还把它组织进了cloud_healthcare_dataset_tools工具集与get_dataset、list_dicom_stores并列以及更完整的 FHIR / DICOM 工具集划分详见 预构建配置文档。权限方面ADC 身份通常需要roles/healthcare.fhirResourceReader读取/检索 FHIR 资源或roles/healthcare.dicomViewer检索 DICOM 图像等角色useClientOAuth: true时则要求客户端 OAuth 身份具备相应 IAM 权限见 source 文档 的 Requirements 一节。7. 验证与测试依据配置解析测试cloudhealthcarelistfhirstores_test.go 中的TestParseFromYamlHealthcareListFHIRStores验证了上述 YAML 能正确解析为Type、Source、Description三个字段且无额外参数集成测试cloud_healthcare_integration_test.go 定义了listFHIRStoresToolType cloud-healthcare-list-fhir-stores需要设置HEALTHCARE_PROJECT、HEALTHCARE_REGION及HEALTHCARE_DATASET环境变量后对真实数据集跑通列表查询测试框架还会基于 store 的created_at标签清理遗留 store说明集成测试依赖可写的数据集环境。8. 小结cloud-healthcare-list-fhir-stores是 MCP Toolbox 面向 Cloud Healthcare API 的数据集级发现工具零参数、绑定一个cloud-healthcaresource 即可列出全部或allowedFhirStores白名单内的FHIR store。其实现上的三个要点是——启动期校验数据集与白名单存在性、运行期按白名单过滤 List 结果、以及 ADC / 客户端 OAuth 双认证路径。把它作为工具链的第一步配合get_fhir_store、fhir_patient_search、fhir_fetch_page等同组工具见 tools 目录即可让 LLM 在受控范围内安全地浏览和查询 FHIR 数据。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考