MCP Toolbox for Databasescloud-healthcare-search-dicom-studies 工具详解——在 DICOM 库中按条件检索影像研究【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox在基于 MCPModel Context Protocol的医疗数据 Agent 场景中MCP Toolbox 通过cloud-healthcare-search-dicom-studies工具让 LLM 能够按患者、日期、检查编号等条件在 Google Cloud Healthcare API 的 DICOM 库中检索影像研究Study。阅读本文后你将掌握该工具的 YAML 配置方式、全部参数取值规则包括模糊匹配与 includeField 的精确语义以及它在 Toolbox 源码中的调用链、storeID 的可选性逻辑和错误处理方式从而把它正确接入自己的 MCP 服务器配置。工具概述cloud-healthcare-search-dicom-studies工具用于根据一组条件在指定的 DICOM store 中搜索 DICOM 影像研究study并返回所有匹配的研究列表。它是 Toolbox 中 Cloud Healthcare 集成下三个 DICOM 检索工具之一study / series / instance 三个粒度专门对应 DICOM Web 的 Study 级搜索。其工具类型常量在源码中定义为cloud-healthcare-search-dicom-studies见 cloudhealthcaresearchdicomstudies.go并在包初始化时注册到工具注册表见该文件 init 函数。兼容的数据源该工具仅兼容cloud-healthcare类型的数据源。源码中通过接口断言实现了这一约束type compatibleSource interface { AllowedDICOMStores() map[string]struct{} UseClientAuthorization() bool SearchDICOM(string, string, string, string, []googleapi.CallOption) (any, error) }见 cloudhealthcaresearchdicomstudies.go#L55-L59ValidateSource会在工具初始化时检查数据源是否实现该接口若不满足则报错 invalid source for ... tool: source ... is not a compatible type见 cloudhealthcaresearchdicomstudies.go#L106-L112。Cloud Healthcare API 数据源的配置方式project、region、dataset、allowedDicomStores、useClientOAuth等字段可参考 source.md。配置示例在 MCP Toolbox 的 YAML 配置中声明该工具kind: tool name: search_dicom_studies type: cloud-healthcare-search-dicom-studies source: my-healthcare-source description: Use this tool to search for DICOM studies in the DICOM store.对应的数据源声明示例kind: source name: my-healthcare-source type: cloud-healthcare project: my-project-id region: us-central1 dataset: my-healthcare-dataset-id allowedDicomStores: - my_dicom_store_1仓库中内置的预构建配置cloud-healthcare正是这样定义该工具的且将其归入cloud_healthcare_dicom_tools工具集可通过--prebuilt cloud-healthcare直接启用见 cloud-healthcare.yaml 与 工具集定义。启用预构建配置所需的环境变量为CLOUD_HEALTHCARE_PROJECT、CLOUD_HEALTHCARE_REGION、CLOUD_HEALTHCARE_DATASET以及可选的CLOUD_HEALTHCARE_USE_CLIENT_OAUTH见 google-cloud-healthcare-api.md。配置字段参考字段类型必填说明kindstring是必须为tool。namestring是工具名称。typestring是必须为cloud-healthcare-search-dicom-studies。sourcestring是数据源名称须为cloud-healthcare类型。descriptionstring是传递给 LLM 的工具描述用于帮助模型决定是否调用该工具。源码中的Config结构与之一致type、source均标注了validate:required且Initialize会在description为空时直接返回 description is required for tool ... 错误见 cloudhealthcaresearchdicomstudies.go#L61-L89。此外该结构体还支持可选的annotations字段用于声明工具注解未显式指定时默认使用只读注解NewReadOnlyAnnotations见 cloudhealthcaresearchdicomstudies.go#L82-L88。工具在 YAML 解析层面的行为有单元测试覆盖给定一段最小 YAML 配置server.UnmarshalPrimitiveConfig应解析出Type: cloud-healthcare-search-dicom-studies的Config见 cloudhealthcaresearchdicomstudies_test.go#L27-L70。调用参数参考参数类型必填说明StudyInstanceUIDstring否DICOM 研究的 UID。PatientNamestring否患者姓名。PatientIDstring否患者 ID。AccessionNumberstring否研究的登记号accession number。ReferringPhysicianNamestring否转诊医生姓名。StudyDatestring否研究日期格式为YYYYMMDD也可用YYYYMMDD-YYYYMMDD表示日期范围。fuzzymatchingboolean否是否对 PatientName 启用模糊匹配。开启后会对查询值与存储值做分词和归一化只要任意搜索 token 是任意存储 token 的前缀即算匹配。例如存储的 PatientName 为 John^Doe 时jo、Do、John Doe 均能匹配而 ohn 不匹配。默认false。includefield[]string否需要在输出中包含的属性 ID 列表DICOM tag ID 或关键字设为[all]可返回全部可用 tag。默认空数组。storeIDstring视情况要搜索的 DICOM store ID。若数据源的allowedDICOMStores长度为 1则无需提供。storeID 的可选性由数据源决定storeID参数是否出现在工具的参数 schema 中是在工具解析阶段根据数据源动态决定的// resolveParams builds the tools parameters using the sources configured FHIR/DICOM stores. func (t Tool) resolveParams(source sources.Source) (parameters.Parameters, error) { ... return buildParams(len(s.AllowedDICOMStores()) 1), nil }见 cloudhealthcaresearchdicomstudies.go#L169-L181buildParams(singleStore)在singleStore为true时不注册storeID参数见 cloudhealthcaresearchdicomstudies.go#L150-L167。运行时的取值逻辑在公共函数ValidateAndFetchStoreID中数据源只允许 1 个 DICOM store 时直接返回该 store不读取参数允许多个或未配置allowedDicomStores时从参数中读取storeID并要求其为字符串若配置了允许列表还会校验storeID在列表内否则报错 store ID ... is not in the list of allowed stores。见 util.go#L37-L57这带来一个实用结论在数据源中把allowedDicomStores收敛为单个 store可以让 Agent 少传一个参数同时天然把检索范围限定在一个库内。参数如何转化为 API 查询Invoke将各参数解析为 Google API 客户端的googleapi.CallOption即 query parameter核心逻辑在common.ParseDICOMSearchParameters见 util.go#L59-L91六个字符串条件StudyInstanceUID、PatientName、PatientID、AccessionNumber、ReferringPhysicianName、StudyDate中非空值会原样作为同名 query parameter 下发fuzzymatching无论取值都会以true/false字符串形式下发includefield会被转换为逗号分隔的字符串后作为includefield查询参数下发若非空数组的字符串切片会报错 invalid includefield parameter; expected a string array。调用链与底层实现工具执行时Invoke方法见 cloudhealthcaresearchdicomstudies.go#L114-L140的完整流程如下将传入的 source 断言为compatibleSource失败则返回 500 错误通过common.ValidateAndFetchStoreID校验并解析出最终使用的storeID若数据源启用了useClientOAuth从请求的Authorization头解析 Bearer token失败返回 401通过ParseDICOMSearchParameters把参数转换为[]googleapi.CallOption以dicomWebPath : studies调用source.SearchDICOM(toolType, storeID, studies, tokenStr, opts)。数据源侧的SearchDICOM见 cloud_healthcare.go#L636-L673按工具类型分发到 Cloud Healthcare API 客户端cloud-healthcare-search-dicom-studies走DicomStores.SearchForStudies请求路径拼装为projects/{project}/locations/{region}/datasets/{dataset}/dicomStores/{storeID}。响应处理要点状态码 299 时返回 search: status ... 错误并附带响应体空响应体返回空切片[]即未找到匹配结果时会得到空列表而非报错正常响应被反序列化为 JSON 列表返回给 LLM。关于认证默认情况下工具使用 ADCApplication Default Credentials对应的凭据当数据源设置useClientOAuth: true时改为用客户端请求中携带的 OAuth token 逐次构造 service 实例实现代表最终用户的鉴权见 cloud_healthcare.go#L145-L193 与 cloud_healthcare.go#L291-L302。GCP 侧的错误最终由util.ProcessGcpError统一转换为 Toolbox 错误见 cloudhealthcaresearchdicomstudies.go#L136-L138。数据源初始化时还会做一次启动即校验Initialize会依次调用 FHIR store 的 Get 验证 dataset 存在、并对allowedDicomStores中每个 store 逐一调用DicomStores.Get验证存在性任一 store 不存在即报 allowedDicomStore ... not found in dataset ...见 cloud_healthcare.go#L102-L133。这保证了storeID白名单在配置阶段就与云上资源保持一致。在检索工作流中的位置在实际 Agent 工作流中search_dicom_studies通常是 DICOM 检索的起点先按患者名/日期等条件搜出 study 列表拿到StudyInstanceUID再逐级调用同族的cloud-healthcare-search-dicom-series和cloud-healthcare-search-dicom-instances定位 series 与 instance最后可用cloud-healthcare-retrieve-rendered-dicom-instance获取渲染后的 JPEG 图像base64。这三个搜索工具共享同一套参数解析与 storeID 校验逻辑公共常量storeID、fuzzymatching、includefield定义在 util.go#L26-L35因此本文中的参数语义与 storeID 可选性规则对 series/instance 级检索同样适用。小结cloud-healthcare-search-dicom-studies以极简的四个配置字段接入 MCP Toolbox却把 DICOM 检索的关键工程细节都封装在内部按数据源白名单动态收敛的storeID参数、面向 LLM 的参数描述尤其是模糊匹配前缀语义、非空才下发 query parameter 的条件拼装以及 ADC 与用户 OAuth 双认证模式。配置该工具时建议优先在数据源层用allowedDicomStores限定可访问的 DICOM store并在 IAM 上为执行身份授予 DICOM 读取权限如roles/healthcare.dicomViewer见 source.md即可让 LLM 在受控范围内安全地检索影像研究。【免费下载链接】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：cloud-healthcare-search-dicom-studies 工具详解——在 DICOM 库中按条件检索影像研究
MCP Toolbox for Databasescloud-healthcare-search-dicom-studies 工具详解——在 DICOM 库中按条件检索影像研究【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox在基于 MCPModel Context Protocol的医疗数据 Agent 场景中MCP Toolbox 通过cloud-healthcare-search-dicom-studies工具让 LLM 能够按患者、日期、检查编号等条件在 Google Cloud Healthcare API 的 DICOM 库中检索影像研究Study。阅读本文后你将掌握该工具的 YAML 配置方式、全部参数取值规则包括模糊匹配与 includeField 的精确语义以及它在 Toolbox 源码中的调用链、storeID 的可选性逻辑和错误处理方式从而把它正确接入自己的 MCP 服务器配置。工具概述cloud-healthcare-search-dicom-studies工具用于根据一组条件在指定的 DICOM store 中搜索 DICOM 影像研究study并返回所有匹配的研究列表。它是 Toolbox 中 Cloud Healthcare 集成下三个 DICOM 检索工具之一study / series / instance 三个粒度专门对应 DICOM Web 的 Study 级搜索。其工具类型常量在源码中定义为cloud-healthcare-search-dicom-studies见 cloudhealthcaresearchdicomstudies.go并在包初始化时注册到工具注册表见该文件 init 函数。兼容的数据源该工具仅兼容cloud-healthcare类型的数据源。源码中通过接口断言实现了这一约束type compatibleSource interface { AllowedDICOMStores() map[string]struct{} UseClientAuthorization() bool SearchDICOM(string, string, string, string, []googleapi.CallOption) (any, error) }见 cloudhealthcaresearchdicomstudies.go#L55-L59ValidateSource会在工具初始化时检查数据源是否实现该接口若不满足则报错 invalid source for ... tool: source ... is not a compatible type见 cloudhealthcaresearchdicomstudies.go#L106-L112。Cloud Healthcare API 数据源的配置方式project、region、dataset、allowedDicomStores、useClientOAuth等字段可参考 source.md。配置示例在 MCP Toolbox 的 YAML 配置中声明该工具kind: tool name: search_dicom_studies type: cloud-healthcare-search-dicom-studies source: my-healthcare-source description: Use this tool to search for DICOM studies in the DICOM store.对应的数据源声明示例kind: source name: my-healthcare-source type: cloud-healthcare project: my-project-id region: us-central1 dataset: my-healthcare-dataset-id allowedDicomStores: - my_dicom_store_1仓库中内置的预构建配置cloud-healthcare正是这样定义该工具的且将其归入cloud_healthcare_dicom_tools工具集可通过--prebuilt cloud-healthcare直接启用见 cloud-healthcare.yaml 与 工具集定义。启用预构建配置所需的环境变量为CLOUD_HEALTHCARE_PROJECT、CLOUD_HEALTHCARE_REGION、CLOUD_HEALTHCARE_DATASET以及可选的CLOUD_HEALTHCARE_USE_CLIENT_OAUTH见 google-cloud-healthcare-api.md。配置字段参考字段类型必填说明kindstring是必须为tool。namestring是工具名称。typestring是必须为cloud-healthcare-search-dicom-studies。sourcestring是数据源名称须为cloud-healthcare类型。descriptionstring是传递给 LLM 的工具描述用于帮助模型决定是否调用该工具。源码中的Config结构与之一致type、source均标注了validate:required且Initialize会在description为空时直接返回 description is required for tool ... 错误见 cloudhealthcaresearchdicomstudies.go#L61-L89。此外该结构体还支持可选的annotations字段用于声明工具注解未显式指定时默认使用只读注解NewReadOnlyAnnotations见 cloudhealthcaresearchdicomstudies.go#L82-L88。工具在 YAML 解析层面的行为有单元测试覆盖给定一段最小 YAML 配置server.UnmarshalPrimitiveConfig应解析出Type: cloud-healthcare-search-dicom-studies的Config见 cloudhealthcaresearchdicomstudies_test.go#L27-L70。调用参数参考参数类型必填说明StudyInstanceUIDstring否DICOM 研究的 UID。PatientNamestring否患者姓名。PatientIDstring否患者 ID。AccessionNumberstring否研究的登记号accession number。ReferringPhysicianNamestring否转诊医生姓名。StudyDatestring否研究日期格式为YYYYMMDD也可用YYYYMMDD-YYYYMMDD表示日期范围。fuzzymatchingboolean否是否对 PatientName 启用模糊匹配。开启后会对查询值与存储值做分词和归一化只要任意搜索 token 是任意存储 token 的前缀即算匹配。例如存储的 PatientName 为 John^Doe 时jo、Do、John Doe 均能匹配而 ohn 不匹配。默认false。includefield[]string否需要在输出中包含的属性 ID 列表DICOM tag ID 或关键字设为[all]可返回全部可用 tag。默认空数组。storeIDstring视情况要搜索的 DICOM store ID。若数据源的allowedDICOMStores长度为 1则无需提供。storeID 的可选性由数据源决定storeID参数是否出现在工具的参数 schema 中是在工具解析阶段根据数据源动态决定的// resolveParams builds the tools parameters using the sources configured FHIR/DICOM stores. func (t Tool) resolveParams(source sources.Source) (parameters.Parameters, error) { ... return buildParams(len(s.AllowedDICOMStores()) 1), nil }见 cloudhealthcaresearchdicomstudies.go#L169-L181buildParams(singleStore)在singleStore为true时不注册storeID参数见 cloudhealthcaresearchdicomstudies.go#L150-L167。运行时的取值逻辑在公共函数ValidateAndFetchStoreID中数据源只允许 1 个 DICOM store 时直接返回该 store不读取参数允许多个或未配置allowedDicomStores时从参数中读取storeID并要求其为字符串若配置了允许列表还会校验storeID在列表内否则报错 store ID ... is not in the list of allowed stores。见 util.go#L37-L57这带来一个实用结论在数据源中把allowedDicomStores收敛为单个 store可以让 Agent 少传一个参数同时天然把检索范围限定在一个库内。参数如何转化为 API 查询Invoke将各参数解析为 Google API 客户端的googleapi.CallOption即 query parameter核心逻辑在common.ParseDICOMSearchParameters见 util.go#L59-L91六个字符串条件StudyInstanceUID、PatientName、PatientID、AccessionNumber、ReferringPhysicianName、StudyDate中非空值会原样作为同名 query parameter 下发fuzzymatching无论取值都会以true/false字符串形式下发includefield会被转换为逗号分隔的字符串后作为includefield查询参数下发若非空数组的字符串切片会报错 invalid includefield parameter; expected a string array。调用链与底层实现工具执行时Invoke方法见 cloudhealthcaresearchdicomstudies.go#L114-L140的完整流程如下将传入的 source 断言为compatibleSource失败则返回 500 错误通过common.ValidateAndFetchStoreID校验并解析出最终使用的storeID若数据源启用了useClientOAuth从请求的Authorization头解析 Bearer token失败返回 401通过ParseDICOMSearchParameters把参数转换为[]googleapi.CallOption以dicomWebPath : studies调用source.SearchDICOM(toolType, storeID, studies, tokenStr, opts)。数据源侧的SearchDICOM见 cloud_healthcare.go#L636-L673按工具类型分发到 Cloud Healthcare API 客户端cloud-healthcare-search-dicom-studies走DicomStores.SearchForStudies请求路径拼装为projects/{project}/locations/{region}/datasets/{dataset}/dicomStores/{storeID}。响应处理要点状态码 299 时返回 search: status ... 错误并附带响应体空响应体返回空切片[]即未找到匹配结果时会得到空列表而非报错正常响应被反序列化为 JSON 列表返回给 LLM。关于认证默认情况下工具使用 ADCApplication Default Credentials对应的凭据当数据源设置useClientOAuth: true时改为用客户端请求中携带的 OAuth token 逐次构造 service 实例实现代表最终用户的鉴权见 cloud_healthcare.go#L145-L193 与 cloud_healthcare.go#L291-L302。GCP 侧的错误最终由util.ProcessGcpError统一转换为 Toolbox 错误见 cloudhealthcaresearchdicomstudies.go#L136-L138。数据源初始化时还会做一次启动即校验Initialize会依次调用 FHIR store 的 Get 验证 dataset 存在、并对allowedDicomStores中每个 store 逐一调用DicomStores.Get验证存在性任一 store 不存在即报 allowedDicomStore ... not found in dataset ...见 cloud_healthcare.go#L102-L133。这保证了storeID白名单在配置阶段就与云上资源保持一致。在检索工作流中的位置在实际 Agent 工作流中search_dicom_studies通常是 DICOM 检索的起点先按患者名/日期等条件搜出 study 列表拿到StudyInstanceUID再逐级调用同族的cloud-healthcare-search-dicom-series和cloud-healthcare-search-dicom-instances定位 series 与 instance最后可用cloud-healthcare-retrieve-rendered-dicom-instance获取渲染后的 JPEG 图像base64。这三个搜索工具共享同一套参数解析与 storeID 校验逻辑公共常量storeID、fuzzymatching、includefield定义在 util.go#L26-L35因此本文中的参数语义与 storeID 可选性规则对 series/instance 级检索同样适用。小结cloud-healthcare-search-dicom-studies以极简的四个配置字段接入 MCP Toolbox却把 DICOM 检索的关键工程细节都封装在内部按数据源白名单动态收敛的storeID参数、面向 LLM 的参数描述尤其是模糊匹配前缀语义、非空才下发 query parameter 的条件拼装以及 ADC 与用户 OAuth 双认证模式。配置该工具时建议优先在数据源层用allowedDicomStores限定可访问的 DICOM store并在 IAM 上为执行身份授予 DICOM 读取权限如roles/healthcare.dicomViewer见 source.md即可让 LLM 在受控范围内安全地检索影像研究。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
