Langcare MCP Fhir

🚀 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 配置文件。

1. 获取配置模板：根据你的后端选择相应的配置模板：
   • EPIC：config.epic.example.yaml
   • Cerner：config.cerner.example.yaml
   • GCP Healthcare API：config.gcp.example.yaml
   • 任何 FHIR R4 服务器：config.base.example.yaml
2. 配置 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

3. 重启 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 调用外无需网络请求

内置应用程序

这两个应用程序都是展示 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 种技能）

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

使用技能的方法

1. 浏览 skills/core/ 目录并选择一个技能
2. 复制 技能的 SKILL.md 内容到你的 AI 代理的系统提示或自定义指令中
3. 参考文件 每个技能的 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 基础设施改善医疗保健