Healsens FHIR MCP

healsens-fhirmcp

适用于 FHIR R4 和 R5 的开源、符合性感知 MCP 服务。

healsens-fhirmcp 是 Healsens 为医疗系统实现的 MCP 服务，适用于已提供 FHIR、并希望安全、可预测地让 AI Agent 使用这些数据，且获得远胜于轻量代理的架构感知能力的场景。它面向配置的 FHIR 基础 URL，提供精简的只读 MCP 接口，用于读取资源、执行类型化搜索、发现符合性信息以及执行安全的只读操作。

核心理念很简单：当服务端帮助模型理解目标 FHIR API 时，模型的表现会更好。此项目内置了与版本匹配的 FHIR 符合性工件，并将其与所连接服务端的实时 CapabilityStatement 结合起来，确保工具调用以实际端点的结构、语义和能力为依据。

项目缘起

大多数医疗 AI 集成都会以可预见的方式失败：通用 HTTP 封装暴露过多接口，模型猜测搜索参数，而不同服务端之间的 FHIR 差异会让原本简单的任务变成脆弱的提示词工程。healsens-fhirmcp 正是为直接解决这个问题而设计的。

它为团队提供了实用的 MCP 层，具备以下特点：

• 了解 FHIR，而非与端点无关
• 以真实的符合性元数据为依据，而非仅依赖提示词假设
• 通过只读工具集和固定的目标服务，从设计上确保安全
• 可在生产集成流程中通过 stdio 或原生 SSE 使用

本仓库以开源形式发布，旨在为实施人员提供可信、具体的医疗 MCP 部署基础，而不仅仅是一个玩具示例。

演示访问

项目提供在线演示，供团队评估。如需申请访问权限，请发送邮件至 contact[at]healsens[dot]com。

提供的功能

• 单个已配置的 FHIR 目标服务
• 只读 MCP 工具接口
• 支持 FHIR R4 和 R5
• 内置核心 StructureDefinition 和 OperationDefinition 注册表
• 获取实时 CapabilityStatement 并进行缓存
• 类型化读取和类型化搜索
• 谨慎调用只读操作
• 在 fhirmcp:// URI 方案下提供发现和架构资源
• 原生 stdio 和 SSE 托管模式

MCP 工具

• fhir_read
• fhir_search
• fhir_capability_statement
• fhir_structure_definition
• fhir_operation_definition
• fhir_invoke_operation

MCP 资源

• fhirmcp://server/guide
• fhirmcp://server/overview
• fhirmcp://server/capability-statement
• fhirmcp://schema/structure-definitions
• fhirmcp://schema/structure-definition/{selector}
• fhirmcp://schema/operation-definitions
• fhirmcp://schema/operation-definition/{selector}
• fhirmcp://server/search-guide

设计原则

• 符合性优先：服务端结合使用内置 FHIR 工件和目标服务的实时 CapabilityStatement，以确定工具行为。
• 从设计上保持只读：此实现有意专注于安全检索、发现和受支持的只读操作。
• 可预测的集成接口：单个已配置目标、明确的架构、受限的行为。
• 面向现实互操作：支持 FHIR R4 和 R5，并在启动时发现服务端特定能力。

本项目有意不将自身定位为完整的 FHIR SDK、通用代理或支持写入的编排层。

快速开始

1. 复制 examples/config.yaml，并将 target.base_url 设置为你的 FHIR R4 或 R5 服务端。
2. 如果服务端要求身份验证，请导出配置中指定的 bearer 令牌环境变量。
3. 同步供应的符合性工件。
4. 通过 stdio 或 SSE 构建并运行服务端。

./scripts/sync_fhir_core_defs.sh
go mod tidy
go build -o bin/healsens-fhirmcp ./cmd/healsens-fhirmcp
FHIRMCP_CONFIG=./examples/config.yaml ./bin/healsens-fhirmcp

设置 server.transport: stdio 时，二进制程序会作为传统子进程 MCP 服务，通过 stdin 和 stdout 进行通信。设置 server.transport: sse 时，它会默认在 http://127.0.0.1:8081/sse 提供原生 SSE MCP 端点。

SSE 模式

在 examples/config.yaml 中设置传输配置块：

server:
	transport: sse
	listen_address: 127.0.0.1:8081
	sse_path: /sse
	cors:
		enabled: true
		allowed_origins:
			- http://localhost:8788

然后启动服务：

go build -o bin/healsens-fhirmcp ./cmd/healsens-fhirmcp
FHIRMCP_CONFIG=./examples/config.yaml ./bin/healsens-fhirmcp

MCP SSE 端点为：

http://127.0.0.1:8081/sse

如果客户端在浏览器环境中运行，server.cors 会控制 SSE 端点及其 POST 消息端点的跨源访问。allowed_origins 应包含你信任的确切浏览器来源。

开发

• make sync-core 刷新 vendored FHIR R4 和 R5 构件。
• make build 为 stdio 或 SSE 模式构建服务二进制文件。
• make test 运行单元测试和集成测试。