Fhir MCP

🚀 FHIR Careplan - 通用FHIR服務器與工具集

這是一個全面的FHIR（快速醫療互操作性資源）服務器和工具包，專為醫療數據集成、患者護理規劃和臨床決策支持而設計。該項目提供了一個通用接口，可連接多個FHIR服務器，並具備先進的人工智能臨床分析能力。

🚀 快速開始

本項目主要包含兩個核心組件：

1. 通用FHIR MCP服務器 (fhir_server.py) - 一個模型上下文協議（MCP）服務器，用於為多個FHIR服務器提供標準化訪問。
2. FHIR工具庫 (fhir_tools.py) - 一個全面的Python庫，用於FHIR數據的操作、分析以及基於人工智能的臨床洞察。

✨ 主要特性

🔗 多服務器FHIR集成

• 通用FHIR接口：可連接多個FHIR服務器（如Epic、Cerner、HAPI、Firely等）。
• 與供應商無關：無論底層FHIR服務器的實現如何，都提供標準化的API。
• 實時連接測試：自動進行服務器健康檢查和診斷。
• 智能故障轉移：自動在服務器之間切換，以實現最佳性能。

🤖 人工智能驅動的臨床分析

• 集成OpenAI：從自由文本中提取臨床關鍵詞和概念。
• 語義映射：將臨床術語映射到標準化的FHIR代碼。
• 相似患者匹配：查找具有相似臨床特徵的患者。
• 預測分析：根據歷史數據生成護理建議。

📊 全面的患者數據訪問

• 完整的患者記錄：包括人口統計信息、病情、藥物治療、手術記錄和就診記錄。
• 生命體徵和實驗室檢查結果：分類觀察數據，包含時間序列信息。
• 護理計劃和團隊信息：治療計劃和醫療服務提供者信息。
• 過敏史和手術史：完整的醫療歷史跟蹤。

🚀 性能優化

• 異步操作：採用非阻塞I/O，實現高性能數據訪問。
• 智能緩存：緩存條件代碼和常用數據。
• 批量處理：高效處理多個患者記錄。
• 連接池管理：為多個服務器優化HTTP連接。

📦 安裝指南

前提條件

• Python 3.11 或更高版本
• OpenAI API密鑰（用於人工智能功能）
• 訪問FHIR服務器（本地或遠程）

設置MCP服務器

1. 克隆倉庫

   git clone https://github.com/Kushagra-Dutta/Fhir-MCP.git
   cd FHIR-MCP
   

2. 安裝依賴項

   pip install -r requirements.txt
   # 或者使用uv
   uv sync
   

3. 配置環境變量

   # 創建.env文件
   echo "OPENAI_API_KEY=your_openai_api_key" > .env
   

4. 運行FHIR MCP服務器

   python fhir_server.py
   

本地設置Firely測試數據庫

1. 獲取Firely服務器許可證密鑰

   • 訪問 Firely Server試用頁面
   • 填寫表格，通過電子郵件接收許可證密鑰
   • 您將收到許可證密鑰和下載文件（許可證有效期為7天）
   • 將許可證文件保存為 firelyserver-license.json

2. 使用Docker進行設置

   # 拉取Firely服務器鏡像
   docker pull firely/server
   
   # 運行容器
   # 對於Windows CMD：
   docker run -d -p 9090:4080 --name firely.server -v %CD%/firelyserver-license.json:/app/firelyserver-license.json firely/server
   
   # 對於PowerShell或macOS/Linux：
   docker run -d -p 9090:4080 --name firely.server -v ${PWD}/firelyserver-license.json:/app/firelyserver-license.json firely/server
   
   # 驗證容器是否正在運行
   docker ps
   

3. 加載測試數據

   • 使用Postman加載測試數據捆綁包
   • 在Postman中創建一個新的PUT請求
   • 將請求類型設置為原始JSON
   • 複製測試數據捆綁包中的內容
   • 將請求發送到基礎URL (http://localhost:9090)
   • 對每個數據捆綁包重複此操作

完成這些步驟後，您將擁有一個可在 http://localhost:9090 訪問的測試數據庫。

設置MCP聊天機器人客戶端

您可以通過分叉倉庫或使用Docker來設置MCP聊天機器人客戶端。該聊天機器人將作為與FHIR服務器交互的前端界面。

1. 獲取聊天機器人設置

   # 克隆倉庫
   git clone https://github.com/cgoinglove/mcp-client-chatbot.git
   cd mcp-client-chatbot
   

2. 安裝PNPM（如果未安裝）

   npm install -g pnpm
   

3. 選擇設置方法

   Docker Compose設置 🐳

   # 安裝依賴項
   pnpm i
   
   # 配置環境變量
   # 編輯.env文件，添加您的API密鑰（在pnpm i後自動創建）
   
   # 啟動所有服務，包括PostgreSQL
   pnpm docker-compose:up
   

   本地設置 🚀

   # 安裝依賴項
   pnpm i
   
   # 設置環境變量
   pnpm initial:env
   
   # 啟動PostgreSQL（如果已經運行則跳過）
   pnpm docker:pg
   
   # 運行數據庫遷移
   pnpm db:migrate
   
   # 啟動開發服務器
   pnpm dev
   
   # 可選：構建並啟動以進行類似生產環境的測試
   pnpm build:local && pnpm start
   

4. 配置環境變量 創建或編輯 .env 文件，添加所需的API密鑰：

   # LLM提供商API密鑰（添加您計劃使用的密鑰）
   OPENAI_API_KEY=****
   GOOGLE_GENERATIVE_AI_API_KEY=****
   ANTHROPIC_API_KEY=****
   XAI_API_KEY=****
   OPENROUTER_API_KEY=****
   OLLAMA_BASE_URL=http://localhost:11434/api
   
   # 身份驗證配置
   BETTER_AUTH_SECRET=**** # 使用：npx @better-auth/cli@latest secret生成
   BETTER_AUTH_URL= # 可選：您訪問應用的URL
   
   # 數據庫配置
   POSTGRES_URL=postgres://your_username:your_password@localhost:5432/your_database_name
   
   # MCP配置
   FILE_BASED_MCP_CONFIG=false
   
   # 可選的OAuth設置（用於Google/GitHub登錄）
   GOOGLE_CLIENT_ID=
   GOOGLE_CLIENT_SECRET=
   GITHUB_CLIENT_ID=
   GITHUB_CLIENT_SECRET=
   

5. 將MCP服務器連接到聊天機器人

   • 在 http://localhost:3000 訪問聊天機器人
   • 創建賬戶並登錄
   • 轉到MCP配置
   • 點擊“添加服務器”
   • 複製並粘貼您的 .chatbot-config.json 配置

6. 配置系統提示

   • 導航到聊天機器人倉庫中的 src/app/prompts.ts
   • 用 system_prompt.txt 中的自定義提示替換默認系統提示
   • 示例系統提示結構：

     export const defaultSystemPrompt = `您是一個強大的智能AI編碼助手。
     您可以使用一組工具來回答用戶的問題。
     
     <communication>
     1. 保持對話風格，但要專業。
     2. 用第二人稱稱呼用戶，用第一人稱稱呼自己。
     3. 以Markdown格式格式化您的回覆。
     4. 絕不撒謊或編造信息。
     </communication>
     
     <tool_calling>
     遵循以下關於工具調用的規則：
     1. 始終嚴格按照工具調用模式進行操作。
     2. 絕不調用未明確提供的工具。
     3. 僅在必要時調用工具。
     4. 在調用每個工具之前，先向用戶解釋調用原因。
     </tool_calling>
     
     <making_code_changes>
     進行代碼更改時：
     1. 添加所有必要的導入語句和依賴項。
     2. 除非用戶要求，否則絕不向用戶輸出代碼。
     3. 使用適當的代碼編輯工具進行實現。
     </making_code_changes>
     `;
     

   • 根據您的需求自定義提示部分：
     • <communication>：定義AI的交互方式
     • <tool_calling>：指定使用工具的規則
     • <making_code_changes>：設置代碼修改的準則
   • 保存更改並重啟開發服務器

完成這些步驟後，您的聊天機器人將連接到MCP服務器，並準備好與FHIR數據庫進行交互。

💻 使用示例

基礎用法

1. 服務器管理

from fhir_tools import UniversalFhirMcpServer

# 初始化服務器
fhir_server = UniversalFhirMcpServer()
await fhir_server.initialize()

# 測試服務器連接
result = await fhir_server.test_server_connectivity("firely_local")
print(result)

# 切換到不同的服務器
await fhir_server.switch_server("hapi_r4")

2. 患者搜索

# 搜索患者
search_criteria = {
    "family": "Smith",
    "given": "John",
    "birthdate": "1990-01-01"
}
patients = await fhir_server.find_patient(search_criteria)

3. 患者數據檢索

# 獲取全面的患者信息
patient_info = await fhir_server.get_comprehensive_patient_info("patient-123")

# 獲取特定類型的數據
conditions = await fhir_server.get_patient_conditions("patient-123")
medications = await fhir_server.get_patient_medications("patient-123")
vital_signs = await fhir_server.get_vital_signs("patient-123")
lab_results = await fhir_server.get_lab_results("patient-123")

高級用法

1. 人工智能驅動的臨床分析

# 從自由文本中提取臨床關鍵詞
clinical_note = "45歲女性，患有HER2陽性浸潤性導管癌，III期A"
keywords = await fhir_server.extract_clinical_keywords(clinical_note)

# 將臨床術語映射到FHIR代碼
clinical_data = {
    "conditions": ["乳腺癌", "糖尿病"],
    "age": 45,
    "gender": "女性"
}
fhir_codes = await fhir_server.map_to_fhir_codes_fast(clinical_data)

# 查找具有相似臨床特徵的患者
criteria = {
    "age": 45,
    "gender": "女性",
    "conditions": ["乳腺癌"]
}
similar_patients = await fhir_server.find_similar_patients_simple(criteria)

2. MCP服務器集成

FHIR服務器可以用作MCP服務器，以與AI助手集成：

{
  "mcpServers": {
    "fhir-server": {
      "command": "python",
      "args": ["fhir_server.py"],
      "env": {
        "OPENAI_API_KEY": "your-key-here"
      }
    }
  }
}

📚 詳細文檔

架構

核心組件

graph TD
    A[FHIR Server] --> B[Universal FHIR MCP Server]
    B --> C[FHIR Tools Library]
    C --> D[Multiple FHIR Servers]
    C --> E[OpenAI Integration]
    C --> F[Caching Layer]
    
    D --> G[Firely Local]
    D --> H[HAPI R4]
    D --> I[Epic Systems]
    D --> J[Cerner]
    
    E --> K[Clinical Text Analysis]
    E --> L[Code Mapping]
    E --> M[Patient Matching]

服務器註冊表

系統維護了一個全面的FHIR服務器註冊表：

• Firely Local (http://localhost:9090) - 本地開發服務器
• HAPI R4 (http://hapi.fhir.org/baseR4) - 公共測試服務器
• Epic、Cerner、Azure - 企業醫療系統（可配置）

配置

服務器配置

系統支持在 fhir_tools.py 中配置多個FHIR服務器：

servers = {
    "firely_local": {
        "name": "Firely Server Local",
        "base_url": "http://localhost:9090",
        "version": "R4",
        "vendor": "Firely",
        "auth_type": "none"
    },
    "hapi_r4": {
        "name": "HAPI FHIR R4 Public",
        "base_url": "http://hapi.fhir.org/baseR4",
        "version": "R4",
        "vendor": "HAPI",
        "auth_type": "none"
    }
}

環境變量

# 必需
OPENAI_API_KEY=your_openai_api_key

# 可選
FHIR_SERVER_URL=http://localhost:9090
FHIR_SERVER_AUTH_TOKEN=your_auth_token

可用工具

核心FHIR操作

• switch_server(server_name) - 在FHIR服務器之間切換
• test_server_connectivity(server_name) - 測試服務器連接
• find_patient(search_criteria) - 搜索患者
• get_comprehensive_patient_info(patient_id) - 獲取完整的患者數據

臨床數據訪問

• get_patient_observations(patient_id) - 獲取患者觀察數據
• get_patient_conditions(patient_id) - 獲取患者病情信息
• get_patient_medications(patient_id) - 獲取患者用藥信息
• get_vital_signs(patient_id) - 獲取生命體徵數據
• get_lab_results(patient_id) - 獲取實驗室檢查結果
• get_patient_encounters(patient_id) - 獲取患者就診記錄
• get_patient_allergies(patient_id) - 獲取患者過敏史
• get_patient_procedures(patient_id) - 獲取患者手術記錄

人工智能驅動的分析

• extract_clinical_keywords(text) - 從文本中提取臨床信息
• map_to_fhir_codes_fast(clinical_data) - 將術語映射到FHIR代碼
• find_similar_patients_simple(criteria) - 查找相似患者
• extract_condition_codes_from_fhir() - 提取所有病情代碼

系統管理

• list_available_servers() - 列出所有配置的服務器
• get_server_registry() - 獲取完整的服務器註冊表
• diagnose_fhir_server(server_name) - 診斷服務器功能
• clear_condition_cache() - 清除病情代碼緩存
• get_condition_cache_stats() - 獲取緩存性能統計信息

測試工具

MCP檢查器

MCP（模型上下文協議）檢查器是一個強大的開發和測試工具，可幫助調試和驗證FHIR服務器交互。它提供對服務器行為和API響應的實時檢查。

使用MCP檢查器

# 在特定文件上運行MCP檢查器
mcp dev fhir_server.py

# 這將：
# 1. 以開發模式啟動檢查器
# 2. 監控所有FHIR服務器交互
# 3. 將詳細信息記錄到logs/mcp_dev_inspector.log

功能

• 實時監控：實時觀察FHIR服務器交互
• 請求/響應日誌記錄：詳細記錄所有API調用和響應
• 錯誤檢測：立即反饋API錯誤或配置錯誤
• 性能指標：跟蹤響應時間和服務器性能
• 調試模式：增強日誌記錄，用於開發故障排除

日誌文件位置

檢查器將詳細日誌寫入：

logs/mcp_dev_inspector.log

最佳實踐

• 在開發過程中使用MCP檢查器驗證服務器行為
• 監控日誌文件，以發現意外錯誤或性能問題
• 在實現新的FHIR端點時運行檢查器
• 使用它來調試與外部FHIR服務器的連接問題

業務應用

醫院參與平臺

該工具包可支持自動化醫院參與平臺：

1. 患者護理協調

   • 自動生成護理計劃
   • 管理治療時間表
   • 多學科團隊協調

2. 臨床決策支持

   • 基於證據的治療建議
   • 風險評估和早期預警
   • 根據類似病例進行結果預測

3. 資源優化

   • 資源分配的預測分析
   • 自動調度和容量管理
   • 通過數據驅動的洞察實現成本優化

4. 質量改進

   • 自動跟蹤質量指標
   • 合規性監控和報告
   • 性能分析和基準測試

FHIR時間線代理

概述

FHIR時間線代理 (fhir_timeline_agent.py) 是一個專門的代理，用於根據患者查詢，使用真實的FHIR數據生成詳細的臨床治療時間線。它專門配置為與Firely本地FHIR服務器配合使用。

特性

• 自然語言處理：將自由文本患者查詢轉換為結構化臨床數據。
• 真實患者數據分析：使用實際的FHIR患者記錄生成時間線。
• 人工智能驅動的時間線生成：利用OpenAI GPT - 4生成準確的臨床時間線。
• 交互式CLI界面：用戶友好的命令行界面，具有豐富的格式。
• 全面的患者匹配：根據年齡、性別和病情查找相似患者。

使用方法

# 以交互式聊天界面模式運行
python fhir_timeline_agent.py

# 以演示模式運行，使用示例查詢
python fhir_timeline_agent.py --demo

示例查詢

• "45歲男性，患有胰腺癌"
• "62歲女性，患有HER2陽性乳腺癌"
• "58歲男性，患有IIIA期肺腺癌"

時間線生成過程

1. 查詢處理

   • 從自然語言中提取臨床關鍵詞。
   • 識別年齡、性別、病情、階段和生物標誌物。

2. FHIR代碼映射

   • 將臨床術語映射到標準化的FHIR代碼。
   • 使用Firely本地服務器的代碼系統。

3. 相似患者搜索

   • 在FHIR數據庫中查找匹配的患者。
   • 根據年齡、性別和病情對匹配結果進行評分。

4. 數據聚合

   • 收集全面的醫療歷史。
   • 包括手術記錄、用藥記錄和就診記錄。

5. 時間線生成

   • 使用人工智能創建詳細的治療時間線。
   • 按時間順序組織事件，並提供臨床背景信息。

輸出格式

代理生成豐富的格式化輸出，包括：

• 患者概況：人口統計信息、診斷、階段、生物標誌物。
• 治療時間線：按日期排列的逐步臨床事件。
• 臨床結果：治療反應、生存狀態、毒性。
• 數據來源：服務器信息和分析指標。

配置

該代理硬編碼使用：

• Firely本地FHIR服務器 (http://localhost:9090)
• OpenAI GPT - 4進行時間線生成
• 豐富的控制檯輸出進行格式化顯示

要求

• OpenAI API密鑰（在 .env 文件中設置）
• 運行中的Firely本地FHIR服務器
• Python包：

  openai>=1.86.0
  rich>=13.7.0
  python-dotenv>=1.0.0
  aiohttp>=3.8.0
  

最佳實踐

• 在查詢中提供完整的患者信息。
• 包括年齡、性別和主要診斷。
• 如有可用，添加階段和生物標誌物信息。
• 使用特定的臨床術語以獲得更好的匹配效果。

錯誤處理

代理包含強大的錯誤處理機制，用於處理：

• 患者信息缺失
• FHIR服務器連接問題
• 人工智能生成失敗
• 數據解析錯誤

每個錯誤都會顯示有用的解決建議。

🔧 技術細節

安全與合規

• 符合HIPAA標準：設計時考慮了醫療數據隱私。
• 安全通信：所有服務器通信均採用HTTPS/TLS加密。
• 認證支持：支持多種認證方法（OAuth、API密鑰等）。
• 審計日誌：全面的日誌記錄，用於合規性和調試。

性能特性

• 異步操作：非阻塞I/O，實現高吞吐量。
• 連接池管理：高效的HTTP連接管理。
• 智能緩存：緩存病情代碼和元數據。
• 批量處理：高效處理多個記錄。
• 錯誤處理：強大的錯誤處理和重試機制。

測試

運行測試

# 運行基本連接測試
python -c "
import asyncio
from fhir_tools import UniversalFhirMcpServer

async def test():
    server = UniversalFhirMcpServer()
    await server.initialize()
    result = await server.test_server_connectivity('firely_local')
    print(result)

asyncio.run(test())
"

服務器診斷

# 全面的服務器診斷
diagnostics = await fhir_server.diagnose_fhir_server("firely_local")
print(diagnostics)

日誌記錄

系統提供全面的日誌記錄：

import logging

# 配置日誌記錄
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# 日誌自動寫入logs/mcp_dev_inspector.log

🤝 貢獻指南

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 為新功能添加測試
5. 提交拉取請求

📄 許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE 文件。

🆘 支持

如有支持需求或問題：

• 在GitHub倉庫中創建問題
• 查看日誌目錄以獲取詳細的錯誤信息
• 使用診斷工具進行服務器故障排除

🔄 版本歷史

• v0.1.0 - 初始版本，具備核心FHIR功能
• v0.2.0 - 添加人工智能驅動的臨床分析功能
• v0.3.0 - 增強多服務器支持和緩存功能

🎯 路線圖

• [ ] 高級分析儀表盤
• [ ] 實時數據流
• [ ] 機器學習模型集成
• [ ] 增強安全功能
• [ ] 移動應用支持
• [ ] 雲部署模板

---

懷著對醫療互操作性和患者護理改善的熱愛而構建