金大哥 - langcare-mcp-fhir MCP 详情

article

README

🚀 LangCare MCP FHIR Server

LangCare MCP FHIR Server 是一款企业级的 MCP 服务器，专为基于 FHIR 的电子病历系统（EMRs）设计，可在自主 AI 平台中实现强大部署。它完全采用 Go 语言编写，具备企业级安全特性和通用的 FHIR 操作，支持任何 FHIR R4 资源类型。此外，该服务器还附带一个包含 40 多种临床技能的库，涵盖药物管理、实验室检查解读、临床决策支持、文档记录、人群健康管理等多个方面。同时，它还新增了对 MCP Apps 的支持，提供交互式临床用户界面；推出了 Healthcare Voice Agent，实现实时语音 AI 服务；以及提供了 LangCare CLI，方便不原生支持 MCP 的 AI 代理框架使用。

🚀 快速开始

安装

可以通过 npm 进行安装：

npm install -g @langcare/langcare-mcp-fhir

也可以直接使用，无需安装：

npx @langcare/langcare-mcp-fhir -config /path/to/config.yaml

快速配置

LangCare MCP FHIR 可将 Claude 连接到基于 FHIR 的 EMR 系统。你需要一个指向后端的 YAML 配置文件。

获取配置模板：根据你的后端选择相应的配置模板：
- EPIC：config.epic.example.yaml
- Cerner：config.cerner.example.yaml
- GCP Healthcare API：config.gcp.example.yaml
- 任何 FHIR R4 服务器：config.base.example.yaml
配置 Claude Desktop：在你的 Claude Desktop 配置文件（~/.config/Claude/claude_desktop_config.json）中添加以下内容：

{
  "mcpServers": {
    "langcare-mcp-fhir": {
      "command": "langcare-mcp-fhir",
      "args": ["-config", "/path/to/your/config.yaml"]
    }
  }
}

在 macOS 上，配置文件通常位于：

~/Library/Application\ Support/Claude/claude_desktop_config.json

重启 Claude Desktop：关闭并重新打开 Claude Desktop，此时 FHIR 工具将可用。

若需要详细的设置帮助，请参阅本地测试指南。

✨ 主要特性

企业级安全：实现了两层安全模型，支持多种认证方法，确保 HIPAA 合规的医疗数据访问。
通用 FHIR 操作：提供 4 种通用的 FHIR 操作，支持任何 FHIR R4 资源类型。
临床技能库：包含 40 多种与代理无关的临床工作流指南，可帮助 AI 代理执行复杂的医疗任务。
MCP Apps：内置交互式 UI 视图，提供丰富的可视化和交互控制，无需 LLM 参与数据检索。
Healthcare Voice Agent：实时语音 AI 服务，让患者可以通过语音查询健康记录。
LangCare CLI：命令行界面，方便不原生支持 MCP 的 AI 代理框架使用。

📦 安装指南

从源代码构建

make build

本地运行（stdio 模式）

make run
# 或者
./bin/langcare-mcp-fhir -config configs/config.local.yaml

以 HTTP 模式运行（可流式 HTTP）

make run-http
# 或者
./bin/langcare-mcp-fhir -http -port 8080 -config configs/config.yaml

启动服务器后，可通过 /mcp 进行可流式 HTTP 传输，通过 /health 进行健康检查。

运行测试

make test

代码检查

make lint

部署到 Fly.io（远程可流式 HTTP）

将其部署为远程 MCP 服务器，支持可流式 HTTP 传输，任何兼容 MCP 的 AI 代理都可以从任何地方访问。

# 安装 Fly CLI
brew install flyctl
fly auth login

# 创建应用
fly apps create --name langcare-mcp-dev

# 在 fly/fly.dev.toml [env] 块中为你的提供商（EPIC 或 GCP）设置 CONFIG_FILE
# 然后设置密钥（以 EPIC 为例）：
fly secrets set \
  EPIC_BASE_URL="https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4" \
  EPIC_CLIENT_ID="your-client-id" \
  EPIC_TOKEN_URL="https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token" \
  EPIC_PRIVATE_KEY_B64="$(base64 < keys/epic/private-key.pem)" \
  MCP_AUTH_TOKENS="your-token" \
  --app langcare-mcp-dev

# 部署
fly deploy -c fly/fly.dev.toml --app langcare-mcp-dev

# 验证
curl https://langcare-mcp-dev.fly.dev/health

将任何 MCP 客户端连接到：

URL:   https://langcare-mcp-dev.fly.dev/mcp
Auth:  Authorization: Bearer your-token

Claude Desktop (claude_desktop_config.json)：

{
  "mcpServers": {
    "langcare-fhir": {
      "url": "https://langcare-mcp-dev.fly.dev/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

支持 EPIC 和 GCP Healthcare API 提供商。有关提供商设置、密钥和完整部署指南，请参阅 fly/README.md。

本地使用 EPIC 进行测试

有关设置 EPIC 凭证和本地测试的详细步骤说明，请参阅 📖 本地测试指南。该指南涵盖了生成 RSA 密钥和 JWKS、配置 EPIC 凭证、本地运行服务器、使用 Claude Desktop 进行测试以及解决常见问题等内容。

快速凭证测试：

# 在运行服务器之前测试你的 EPIC 凭证
go run test/test_epic_token.go "your-client-id" "/path/to/private-key.pem"

💻 使用示例

基础用法

1. fhir_read

读取指定类型和 ID 的 FHIR 资源：

{
  "resourceType": "Patient",
  "id": "example-123"
}

2. fhir_search

使用查询参数搜索 FHIR 资源：

{
  "resourceType": "Patient",
  "queryParams": "name=John&birthdate=gt1990-01-01"
}

3. fhir_create

创建新的 FHIR 资源：

{
  "resourceType": "Observation",
  "resource": {
    "resourceType": "Observation",
    "status": "final",
    "code": { ... },
    "subject": { "reference": "Patient/123" }
  }
}

4. fhir_update

更新现有的 FHIR 资源：

{
  "resourceType": "Patient",
  "id": "example-123",
  "resource": {
    "resourceType": "Patient",
    "id": "example-123",
    "name": [{ "family": "Smith" }]
  }
}

📚 详细文档

入门指南

📖 本地开发与测试指南 - 本地设置和测试的完整指南
🚀 安装与配置 - 上述快速设置指南

代理集成

🤖 代理提示指南 - AI 代理使用 LangCare MCP FHIR 的完整指南（工具示例、工作流、最佳实践）

安全与认证

🛡️ 安全文档 - 完整的安全架构和 HIPAA 合规性说明
🔐 EPIC 设置指南 - JWT 认证、密钥生成和 JWKS 注册
📋 EPIC 范围参考 - FHIR 资源的完整 OAuth2 范围指南
🔑 认证方法 - 支持的认证方法

部署

Fly.io 部署指南 - 远程可流式 HTTP 部署、提供商配置、密钥、Docker

开发与测试

🧪 测试方法 - Claude Desktop、MCP 检查器、手动测试和自动化测试
📦 项目结构 - 目录布局和架构
🔧 构建命令 - 开发工作流程

🔧 技术细节

架构

该 MCP 服务器充当 AI 代理和 FHIR R4 服务器之间的智能代理。它通过模型上下文协议（MCP）公开 4 种通用的 FHIR 操作，为任何 FHIR 资源类型实现基于 AI 的工作流。

MCP SDK：官方 github.com/modelcontextprotocol/go-sdk（由 Anthropic/Google 维护）
FHIR 客户端：通用 HTTP 客户端，可与任何 FHIR R4 服务器配合使用
传输方式：stdio 和可流式 HTTP
后端：代理到现有的 FHIR 服务器（无数据库）
语言：100% 使用 Go 语言，以实现高性能和可靠性

安全架构

LangCare MCP FHIR 实现了两层安全模型，用于 HIPAA 合规的医疗数据访问：

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│   Claude    │ Auth1   │  MCP Server  │ Auth2   │  FHIR API   │
│   Client    │────────▶│   (Go)       │────────▶│   (EMR)     │
└─────────────┘         └──────────────┘         └─────────────┘

Auth1: MCP 客户端认证（Bearer Token/API Key）
Auth2: FHIR 后端认证（Bearer/OAuth2/SMART on FHIR）

安全特性

✅ TLS 1.3 加密用于 HTTP 传输
✅ 日志中的 PHI 清理（默认启用）
✅ HIPAA 合规的审计日志记录
✅ 无持久 PHI 存储（无状态代理）
✅ 通过环境变量管理密钥（从不存储在配置文件中）
✅ OAuth 2.0 支持自动令牌刷新
✅ mTLS 支持服务到服务的通信
✅ 每个客户端的速率限制

支持的认证方法

Bearer Token - 简单的 API 密钥认证
OAuth2 - 完整的 OAuth2 流程，支持令牌刷新
SMART on FHIR - EPIC、Cerner 和其他 EMR 标准
Basic Auth - 用户名/密码认证
Custom - 可扩展以支持其他认证方法

如需完整的安全文档，请参阅安全指南，其中包括 HIPAA 合规性清单、EPIC/Cerner/GCP 的 OAuth 配置、Kubernetes 安全清单、凭证管理程序和审计日志记录实现等内容。

MCP Apps（交互式 UI）

LangCare MCP FHIR 内置了 MCP Apps，这些交互式、丰富的 UI 视图可以直接在支持 MCP 的主机（如 Claude Desktop）中运行。与传统的基于聊天的工具输出不同，MCP Apps 使用相同的底层 FHIR 工具，同时渲染基于 React 的完整界面，包含图表、表格和交互式控件。

工作原理

每个应用程序都是一个单文件 HTML 包（React + TypeScript，使用 Vite 编译），在编译时通过 go:embed 嵌入到 Go 二进制文件中。在运行时，MCP 服务器将每个应用程序注册为 MCP 资源（text/html;profile=mcp-app）和专用的 MCP 工具，通过 _meta.ui.resourceUri 进行链接。当 MCP 主机调用该工具时，它会获取资源并渲染 UI。应用程序通过 app.callServerTool() 回调到服务器的通用 FHIR 工具（fhir_search、fhir_read 等），无需 LLM 往返进行数据获取。

与普通工具输出相比的优势

丰富的可视化 - SVG 图表、颜色编码的卡片、可展开的详细面板
交互式控件 - 搜索字段、日期范围选择器、点击展开行
确定性数据获取 - 应用程序直接调用 FHIR 工具，数据检索无需 LLM 参与
零外部依赖 - 所有内容内联到单个 HTML 文件中，嵌入到二进制文件中
离线工作 - 无需 CDN、外部脚本，除了 FHIR API 调用外无需网络请求

内置应用程序

| 应用程序 | 工具 | 描述 | |-----|------|-------------| | FHIR 资源浏览器 | fhir_explorer | 交互式 FHIR 资源浏览器。通过 JSON 详细视图搜索、读取、创建和更新任何 FHIR R4 资源类型。 | | 患者病历审查 | patient_chart_review | 临床仪表盘，显示患者的人口统计信息、当前病情、药物、生命体征、实验室检查结果和生命体征趋势图表（血压 + 体重随时间变化）。 |

这两个应用程序都是展示 MCP Apps 模式的参考实现。有关架构细节和如何构建新应用程序，请参阅 apps/README.md。

代理使用

AI 代理使用 LangCare MCP FHIR Server 通过 4 种 FHIR 工具帮助医疗专业人员访问和管理患者健康记录。服务器处理 EMR 认证，使代理能够专注于临床工作流，同时保持严格的隐私和准确性标准。

代理功能

搜索、读取、创建、更新 - 任何 FHIR R4 资源（患者、观察结果、药物等）
患者隐私 - 使用部分标识符，在更新前确认身份
临床准确性 - 验证数据，使用标准代码（LOINC、SNOMED、RxNorm）
专业沟通 - 以结构化的方式响应，包含上下文、发现和下一步步骤

常见工作流

患者查找：按姓名/出生日期搜索 → 验证身份 → 读取完整详细信息
临床审查：检索实验室检查结果、生命体征、药物 → 显示参考范围
文档记录：提取结构化数据 → 映射到 FHIR 资源 → 确认 → 创建
更新操作：验证现有资源 → 修改 → 确认更改 → 更新

系统支持

支持任何 FHIR R4 资源类型（包括 DocumentReference、Binary、Media 等 60 多种类型）
自动认证和 EPIC、Cerner、GCP Healthcare API 的令牌刷新
HIPAA 合规的 PHI 处理，带有审计日志记录
全面的 OAuth2 范围，用于临床数据访问

完整指南：代理提示指南 - 系统提示、工具示例、工作流和错误处理

临床技能库（可选）

提供 40 多种与代理无关的临床工作流指南，教导 AI 代理如何使用 MCP 服务器的 4 种 FHIR 工具（fhir_search、fhir_read、fhir_create、fhir_update）执行复杂的医疗任务。

可选 - MCP 服务器无需这些指南即可工作
可移植 - 可与 Claude、ChatGPT、Gemini 或任何 AI 代理配合使用
基于证据 - 基于 USPSTF、ADA、ACC/AHA、CDC、ACOG、KDIGO 等协会的指南构建
可直接复制粘贴 - 将技能的 SKILL.md 添加到你的代理的系统提示或自定义指令中

技能类别（40 种技能）

| 类别 | 技能数量 | 示例 | |----------|--------|----------| | 患者数据与摘要 | 5 | 人口统计信息、临床摘要（CCD 风格）、问题列表审核、过敏审查、保险覆盖范围 | | 药物管理 | 5 | 药物核对、药物相互作用（CYP450）、依从性（MPR/PDC）、Beers 标准、阿片类药物风险（ORT/MME） | | 实验室与诊断 | 5 | 实验室检查解读、临界值（CAP/CLIA）、术前实验室检查、糖尿病检查（ADA）、肾功能（KDIGO） | | 临床决策支持 | 5 | 败血症（qSOFA/SOFA）、心血管风险（ASCVD/HEART）、静脉血栓栓塞（Wells/Caprini）、跌倒风险（Morse）、肺炎（CURB-65） | | 护理协调 | 5 | 出院计划（LACE）、转诊、护理差距（USPSTF）、护理过渡（I-PASS）、随访任务 | | 文档记录 | 5 | SOAP 笔记、病史与体格检查、进展笔记、出院小结、手术笔记 | | 人群健康 | 5 | 面板概述、质量指标（HEDIS）、慢性病登记、免疫接种状态（CDC）、预防保健合规性 | | 专科 | 5 | 产前护理（ACOG）、儿科生长（WHO/CDC）、心理健康（PHQ-9/GAD-7）、肿瘤学（TNM/RECIST）、慢性疼痛 |

完整目录及链接：skills/README.md

使用技能的方法

浏览 skills/core/ 目录并选择一个技能
复制技能的 SKILL.md 内容到你的 AI 代理的系统提示或自定义指令中
参考文件 每个技能的 references/ 子目录包含详细的临床知识（评分标准、代码表、阈值），可根据需要包含以提高临床准确性

# 示例：将药物核对技能添加到你的代理
skills/core/medication-management/medication-reconciliation/
├── SKILL.md              # 复制此文件到代理指令中
└── references/
    ├── reconciliation-process.md   # 联合委员会标准
    └── high-risk-medications.md    # ISMP 高警示药物列表

集成指南

Claude | ChatGPT | Gemini

欢迎社区贡献 - 有关指南，请参阅 CONTRIBUTING.md。

项目结构

langcare-mcp-fhir/
├── cmd/
│   └── server/
│       └── main.go                          # 入口点
├── internal/
│   ├── apps/                                # MCP Apps（嵌入式 UI）
│   │   ├── embed.go                         # go:embed 指令，用于 HTML 包
│   │   ├── registry.go                      # 应用程序元数据、工具名称、资源 URI
│   │   └── dist/                            # 构建后的 HTML 包（由构建过程复制）
│   │       ├── fhir-explorer.html           # FHIR 资源浏览器单文件包
│   │       └── patient-chart-review.html    # 患者病历审查单文件包
│   ├── audit/
│   │   └── logger.go                        # HIPAA 审计日志记录
│   ├── config/
│   │   └── config.go                        # YAML 配置加载
│   ├── fhir/
│   │   ├── client.go                        # FHIR HTTP 客户端接口
│   │   ├── types.go                         # FHIR 客户端类型
│   │   └── providers/                       # 后端实现
│   │       ├── base.go                      # 基础 HTTP 提供商
│   │       ├── epic.go                      # EPIC OAuth2 提供商
│   │       ├── cerner.go                    # Cerner OAuth2 提供商
│   │       └── gcp.go                       # GCP Healthcare API 提供商
│   ├── mcp/
│   │   └── server.go                        # MCP 服务器 + 应用程序注册
│   ├── middleware/
│   │   ├── auth.go                          # MCP 认证
│   │   └── rate_limit.go                    # 速率限制
│   ├── tools/                               # MCP 工具实现
│   │   ├── registry.go                      # 工具注册表
│   │   ├── fhir_read.go                     # 读取 FHIR 资源
│   │   ├── fhir_search.go                   # 搜索 FHIR 资源
│   │   ├── fhir_create.go                   # 创建 FHIR 资源
│   │   └── fhir_update.go                   # 更新 FHIR 资源
│   └── transport/
│       ├── stdio.go                         # stdio 传输（Claude Desktop）
│       └── http.go                          # 可流式 HTTP 传输（生产环境）
├── apps/                                    # MCP App 源代码（React + TypeScript）
│   ├── README.md                            # 应用程序开发指南
│   ├── package.json                         # 共享依赖项（React 19、MCP Apps SDK）
│   ├── vite.config.ts                       # Vite 构建配置（单文件输出）
│   ├── tsconfig.json                        # TypeScript 配置
│   ├── fhir-explorer/                       # FHIR 资源浏览器应用程序
│   │   ├── index.html
│   │   └── src/
│   │       ├── app.tsx
│   │       └── global.css
│   └── patient-chart-review/                # 患者病历审查应用程序
│       ├── index.html
│       └── src/
│           ├── app.tsx
│           └── global.css
├── scripts/
│   ├── build-apps.sh                        # 构建所有应用程序 → internal/apps/dist/
│   └── create_jwks.sh                       # 从公钥生成 JWKS（EPIC）
├── pkg/
│   └── types/
│       └── errors.go                        # 自定义错误类型
├── configs/
│   ├── config.epic.example.yaml             # EPIC 示例配置
│   ├── config.cerner.example.yaml           # Cerner 示例配置
│   ├── config.gcp.example.yaml              # GCP 示例配置
│   └── config.base.example.yaml             # 任何 FHIR R4 服务器的示例配置
├── docs/
│   ├── AGENT_PROMPT.md                      # AI 代理系统提示
│   ├── EPIC-APP-SECURITY.md                 # EPIC 认证设置
│   ├── EPIC-SCOPES.md                       # OAuth2 范围参考
│   ├── LOCAL-TESTING.md                     # 本地开发指南
│   └── SECURITY.md                          # 生产环境安全指南
├── test/
│   ├── README.md                            # 测试文档
│   └── test_epic_token.go                   # EPIC OAuth2 令牌测试器
├── fly/
│   ├── Dockerfile                           # Fly.io 的多阶段 Go 构建
│   ├── docker-entrypoint.sh                 # 密钥实例化 + 服务器启动
│   ├── fly.dev.toml                         # Fly.io 开发部署配置
│   ├── config.fly.epic.yaml                 # Fly.io EPIC 提供商配置
│   ├── config.fly.gcp.yaml                  # Fly.io GCP 提供商配置
│   └── README.md                            # Fly.io 部署指南
├── bin/                                     # 构建输出（git 忽略）
│   └── langcare-mcp-fhir                    # 编译后的二进制文件
├── go.mod                                   # Go 模块定义
├── go.sum                                   # Go 模块校验和
├── Makefile                                 # 构建命令
└── README.md                                # 此文件

注意：以下文件被 git 忽略，不会提交：

keys/ - 私钥和凭证
config.local.*.yaml - 本地配置文件
bin/ - 编译后的二进制文件
.env - 环境变量
apps/node_modules/, apps/dist/, apps/dist-tmp/ - 应用程序构建工件

Healthcare Voice Agent

实时语音 AI 服务，让患者可以询问他们的健康记录，并直接从他们的 EMR 中获取语音回答。

技术栈

PipeCat（开源，Daily.co）用于语音管道，包括语音识别（STT）、LLM 编排和语音合成（TTS），延迟低于 3 秒。
Claude 用于临床推理和工具调用。
LangCare MCP FHIR Server（开源，Go）作为无状态代理，连接到任何 FHIR R4 EMR，如 Epic、Cerner、GCP Healthcare API。

工作原理

MCP 是整个系统的粘合剂。PipeCat 的原生 MCP 客户端在启动时会自动发现 FHIR 工具。当患者询问“我正在服用哪些药物？”时，Claude 会调用 fhir_search，PipeCat 将其路由到 MCP 服务器，数据返回后，Claude 以自然语音进行回复，无需手动设置工具架构。

三层 HIPAA 认证

在会话开始前验证调用者身份，使用 bearer token 进行 MCP 认证，使用 OAuth2/SMART on FHIR 进行 EMR 认证，且不存储任何 PHI 数据。

可替换性

可以将 Claude 替换为 Gemini，将 DeepGram 替换为 Google STT，将 Daily 替换为 WebSocket，而 MCP FHIR 层和临床提示保持不变。

完整文档和设置指南：pipecat-agent/README.md

LangCare CLI

命令行界面，将 4 种 FHIR MCP 工具（fhir_search、fhir_read、fhir_create、fhir_update）封装为 CLI 子命令，通过 HTTP 进行调用。它专为不原生支持 MCP 的 AI 代理框架设计，如 LangChain、smolagents、CrewAI、AutoGen 以及任何可以调用子进程的框架。CLI 会在内部处理 MCP 会话握手，因此代理可以在 stdout 上获得干净的 JSON 数据，无需了解协议细节。

安装

pip install "langcare-cli @ git+https://github.com/langcare/langcare-mcp-fhir.git#subdirectory=cli"

使用

langcare fhir search Patient --query "name=John"
langcare fhir read Patient 123
langcare fhir create Observation --data @obs.json
langcare fhir update Patient 123 --data @patient.json

技能库中的 40 多种临床技能可以直接使用，因为技能引用的是抽象的工具名称，而不是传输方式。在你的代理框架中注册 CLI 作为子进程工具，技能可以无需修改即可运行。

完整文档和设置指南：cli/README.md

📄 许可证

请参阅 LICENSE 文件。

由 LangCare 团队和贡献者用心打造

通过更好的 AI 基础设施改善医疗保健

langcare-mcp-fhir

README

🚀 LangCare MCP FHIR Server

🚀 快速开始

安装

快速配置

✨ 主要特性

📦 安装指南

从源代码构建

本地运行（stdio 模式）

以 HTTP 模式运行（可流式 HTTP）

运行测试

代码检查

部署到 Fly.io（远程可流式 HTTP）

本地使用 EPIC 进行测试

💻 使用示例

基础用法

1. fhir_read

2. fhir_search

3. fhir_create

4. fhir_update

📚 详细文档

入门指南

代理集成

安全与认证

部署

开发与测试

🔧 技术细节

架构

安全架构

安全特性

支持的认证方法

MCP Apps（交互式 UI）

工作原理

与普通工具输出相比的优势

内置应用程序

代理使用

代理功能

常见工作流

系统支持

临床技能库（可选）

技能类别（40 种技能）

使用技能的方法

集成指南

项目结构

Healthcare Voice Agent

技术栈

工作原理

三层 HIPAA 认证

可替换性

LangCare CLI

安装

使用

📄 许可证

运行方式说明

托管运行

本地运行 / 其它方式