MCP Toolbox 实战cloud-healthcare-get-dicom-store-metrics 工具详解与 DICOM 存储指标获取【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本文以 MCP ToolboxMCP Toolbox for Databases中对接 Cloud Healthcare API 的cloud-healthcare-get-dicom-store-metrics工具为主线完整讲解该工具的 YAML 配置方式、字段与参数语义、storeID参数的“单店豁免”规则并深入源码剖析工具从配置解析到调用 Cloud Healthcare API 的完整链路。读完后你可以直接在 Toolbox 配置文件中启用该工具让 LLM 通过 MCP 协议查询 DICOM 存储如医学影像库的指标信息。1. 工具定位为 DICOM 存储拉取指标cloud-healthcare-get-dicom-store-metrics是 MCP Toolbox 中 Cloud Healthcare 集成下的一个预置工具类型prebuilt tool。它的职责单一而明确为指定 DICOM 存储DICOM store获取指标metrics即把 Cloud Healthcare API 的getDicomStoreMetrics能力封装为可被 LLM 调用的 MCP 工具。在 官方文档 中对该工具的定义为Acloud-healthcare-get-dicom-store-metricstool retrieves metrics for a DICOM store.cloud-healthcare-get-dicom-store-metricsreturns the metrics of a DICOM store.其兼容的 Source 类型为cloud-healthcareCloud Healthcare API Source。这一点在源码中通过接口断言得到印证工具声明了一个compatibleSource接口要求底层 Source 同时提供AllowedDICOMStores()、UseClientAuthorization()和GetDICOMStoreMetrics()三个方法见 工具实现。Cloud Healthcare 的 Source 实现 满足该接口因此成为唯一兼容的数据源。典型应用场景当 Agent 需要评估某个医学影像数据集的规模与使用状况时例如统计研究/序列/实例数量一类的存储级指标LLM 无需直接构造 GCP REST 请求只需调用该工具并传入storeID即可。2. 工具完整配置与字段参考2.1 配置示例文档给出的标准配置如下原文档kind: tool name: get_dicom_store_metrics type: cloud-healthcare-get-dicom-store-metrics source: my-healthcare-source description: Use this tool to get metrics for a DICOM store.各字段含义与文档中的 Reference 表格保持一致fieldtyperequireddescriptiontypestringtrueMust be cloud-healthcare-get-dicom-store-metrics.sourcestringtrueName of the healthcare source.descriptionstringtrueDescription of the tool that is passed to the LLM.补充两点源码层面的事实帮助理解约束从何而来description是硬性必填项。在工具的Initialize中若Description为空会直接报错description is required for tool %q见 Initialize 实现。这与 YAML 校验中的type、source两个validate:required字段见 Config 结构体共同构成了三个必填项。source指向一个已定义的cloud-healthcare数据源。ValidateSource会在服务启动时对源做类型断言若源不是兼容类型则拒绝加载见 ValidateSource。从源码结构看该工具默认带有只读read-only注解tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewReadOnlyAnnotations)即 LLM 客户端可将其识别为不会修改数据的工具除非你在配置中通过annotations字段显式覆盖。2.2 参数Parameters文档中的参数表如下需要特别注意storeID的“条件必填”fieldtyperequireddescriptionstoreIDstringtrue*The DICOM store ID to get metrics for.*If theallowedDICOMStoresin the source has length 1, then thestoreIDparameter is not needed.当 Source 的allowedDICOMStores列表长度为 1 时storeID参数可以省略。3. storeID 的“单店豁免”规则源码级解析storeID的条件必填并非仅停留在文档层面而是由两层机制共同实现的3.1 工具清单Manifest动态裁剪参数工具的GetParameters/Manifest方法会依据 Source 的allowedDicomStores数量决定是否暴露storeID参数// buildParams builds the tools parameters. When the source pins exactly one store // (singleStore), the store param is omitted; otherwise it is included. func buildParams(singleStore bool) parameters.Parameters { params : parameters.Parameters{} if !singleStore { params append(params, parameters.NewStringParameter(common.StoreKey, The DICOM store ID to get metrics for.)) } return params }其中resolveParams传入的判断条件是len(s.AllowedDICOMStores()) 1见 buildParams / resolveParams。也就是说如果 LLM 看到的工具 schema 里根本没有storeID参数说明该工具已被“锁定”到唯一允许的 DICOM 存储上调用时无需也不能指定。3.2 调用时的统一校验ValidateAndFetchStoreID所有 Cloud Healthcare 的 FHIR/DICOM 工具共用一个校验函数common/util.gofunc ValidateAndFetchStoreID(params parameters.ParamValues, allowedStores map[string]struct{}) (string, error) { if len(allowedStores) 1 { for k : range allowedStores { return k, nil } } mapParams : params.AsMap() storeID, ok : mapParams[StoreKey].(string) if !ok { return , fmt.Errorf(invalid or missing %s parameter; expected a string, StoreKey) } if len(allowedStores) 0 { if _, ok : allowedStores[storeID]; !ok { return , fmt.Errorf(store ID %s is not in the list of allowed stores, storeID) } } return storeID, nil }行为归纳为三种情形allowedDicomStores恰好 1 个直接返回该存储 ID忽略传入的参数allowedDicomStores有多个storeID必填且必须命中白名单否则返回store ID ... is not in the list of allowed stores错误allowedDicomStores未配置不做白名单限制storeID必填。storeID对应的键名在源码中定义为常量StoreKey storeID见 common/util.go与文档参数表一致。4. 前置条件配置 cloud-healthcare 数据源工具本身不直接连接 GCP一切依赖它引用的cloud-healthcareSource。Source 的完整字段定义见 Cloud Healthcare API Source 文档fieldtyperequireddescription要点typestringtrue必须为cloud-healthcareprojectstringtrue数据集所在 GCP 项目 IDregionstringtrue数据集所在区域如us-central1、asia-northeast1datasetstringtrue医疗数据集 IDallowedFhirStores[]stringfalse可选的 FHIR 存储白名单单元素时作为预置工具的默认存储allowedDicomStores[]stringfalse可选的 DICOM 存储白名单单元素时作为预置工具的默认存储useClientOAuthboolfalse为 true 时把客户端Authorization头中的 OAuth 访问令牌转发给下游查询ADC 方式的源配置示例来自 source.mdkind: 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结合本工具值得强调的三点Source 初始化即校验。Source 的Initialize会用 ADC 凭证调用 API 验证 dataset 是否存在并逐个验证allowedDicomStores中每个 DICOM 存储是否存在查不到时给出明确的allowedDicomStore ... not found in dataset ...错误见 Initialize 实现。配置错误会在服务启动阶段暴露而不是等到工具被调用时。权限要求。按 Source 文档 的说明ADC 身份需要具备相应 IAM 权限常见角色如roles/healthcare.dicomViewer读取 DICOM 影像等getDicomStoreMetrics属于读取存储元信息的操作应确保凭证具备对该数据集/DICOM 存储的读取权限。客户端 OAuth 模式。当useClientOAuth: true时本工具在Invoke时会从请求的Authorization头解析 Bearer Token并为每次调用动态构造带该 Token 的 Healthcare 服务实例见 getService 与 工具 Invoke以此代表最终用户发起查询。5. 底层调用链从工具调用到 Cloud Healthcare API工具被 LLM 触发后完整链路如下全部可在源码中核对参数校验Tool.Invoke先把 Source 断言为compatibleSource再调用common.ValidateAndFetchStoreID得到最终storeID第 3 节已详述获取服务实例Source.GetService/getService根据是否启用客户端 OAuth 返回对应的*healthcare.ServiceADC 默认凭证或用户 Token拼接资源名并请求 APIfunc (s *Source) GetDICOMStoreMetrics(storeID, tokenStr string) (*healthcare.DicomStoreMetrics, error) { svc, err : s.getService(tokenStr) if err ! nil { return nil, err } storeName : fmt.Sprintf(projects/%s/locations/%s/datasets/%s/dicomStores/%s, s.Project(), s.Region(), s.DatasetID(), storeID) store, err : svc.Projects.Locations.Datasets.DicomStores.GetDICOMStoreMetrics(storeName).Do() if err ! nil { return nil, fmt.Errorf(failed to get metrics for DICOM store %q: %w, storeName, err) } return store, nil }见 GetDICOMStoreMetrics由此可以确认两个实现事实资源名格式固定为projects/{project}/locations/{region}/datasets/{dataset}/dicomStores/{storeID}project/region/dataset来自 Source 配置storeID来自工具参数或唯一白名单返回值是google.golang.org/api/healthcare/v1包中类型化的DicomStoreMetrics资源工具将其原样作为结果返回给 MCP 调用方即工具输出就是 Cloud Healthcare API 返回的存储指标资源本身。6. 预置配置中的用法get_dicom_store_metrics 与 DICOM 工具集仓库内置了一份 Cloud Healthcare 预置配置 cloud-healthcare.yaml其中本工具以get_dicom_store_metrics之名出现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_dicom_store_metrics type: cloud-healthcare-get-dicom-store-metrics description: Use this tool to get metrics about a DICOM store in the healthcare dataset source: healthcare-source并且它与get_dicom_store、search_dicom_studies、search_dicom_series、search_dicom_instances、retrieve_rendered_dicom_instance一起被编入cloud_healthcare_dicom_tools工具集toolset。该预置配置通过环境变量CLOUD_HEALTHCARE_PROJECT、CLOUD_HEALTHCARE_REGION、CLOUD_HEALTHCARE_DATASET注入连接信息适合在部署时以环境变量的方式完成参数化。如果你的 Source 未配置allowedDicomStoresLLM 需要自行例如先调用list_dicom_stores工具确定storeID再调用本工具若配置为单元素白名单则可以省去这一步。7. 测试用例中的行为验证仓库中的测试为上述行为提供了直接证据配置解析单测cloudhealthcaregetdicomstoremetrics_test.go 的TestParseFromYamlHealthcareGetDICOMStoreMetrics用与文档一致的 YAMLkind: tool/type: cloud-healthcare-get-dicom-store-metrics/source/description验证解析结果与期望的Config结构完全匹配端到端集成测试cloud_healthcare_integration_test.go 在真实 GCP 环境中启动 Toolbox 服务需设置HEALTHCARE_PROJECT、HEALTHCARE_REGION、HEALTHCARE_DATASET环境变量动态创建一个 DICOM 存储后调用runGetDICOMStoreMetricsToolInvokeTest(t, dicomStoreID, dicomStoreWant)断言工具响应中包含完整资源名projects/{project}/locations/{region}/datasets/{dataset}/dicomStores/{storeID}印证了第 5 节的资源名拼接逻辑。8. 实践要点小结最小可用配置一段 Sourcecloud-healthcare类型含project/region/dataset 一段 Tooltype: cloud-healthcare-get-dicom-store-metrics含source与description即可启用storeID是否要传取决于allowedDicomStores长度为 1 时参数被自动省略为 0未配置或多元素时必填且多元素时必须在白名单内鉴权二选一默认使用 ADC需为身份配置 Healthcare 相关 IAM 角色开启useClientOAuth后则由每次请求的Authorization头携带用户 Token错误前置dataset 或白名单中的 DICOM 存储在 Source 初始化阶段就会校验存在性配置拼写错误会直接导致服务启动失败便于排查输出形态工具直接返回 Cloud Healthcare API 的DicomStoreMetrics资源未做额外加工便于 LLM 对原始指标做后续推理。以上所有配置示例均基于当前仓库的文档与源码整理字段与行为以 工具文档、Source 文档 及对应 Go 实现为准。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考