Fhir MCP

🚀 FHIR Careplan - ユニバーサルFHIRサーバーとツールキット

このプロジェクトは、包括的なFHIR（Fast Healthcare Interoperability Resources）サーバーとツールキットで、医療データの統合、患者のケアプランニング、臨床判断支援を目的として設計されています。複数のFHIRサーバーに対するユニバーサルなインターフェースを提供し、高度なAIによる臨床分析機能を備えています。

🚀 クイックスタート

このセクションでは、プロジェクトの概要、インストール方法、基本的な使い方を説明します。

✨ 主な機能

🔗 マルチサーバーFHIR統合

• ユニバーサルFHIRインターフェース：複数のFHIRサーバー（Epic、Cerner、HAPI、Firelyなど）に接続できます。
• ベンダー非依存：基盤となるFHIRサーバーの実装に関係なく、標準化されたAPIを提供します。
• リアルタイム接続テスト：サーバーのヘルスチェックと診断を自動で行います。
• インテリジェントフェイルオーバー：最適なパフォーマンスを得るために、サーバー間を自動的に切り替えます。

🤖 AIによる臨床分析

• OpenAI統合：自由記述のテキストから臨床キーワードと概念を抽出します。
• セマンティックマッピング：臨床用語を標準化されたFHIRコードにマッピングします。
• 類似患者マッチング：類似した臨床プロファイルを持つ患者を検索します。
• 予測分析：過去のデータに基づいてケアの推奨事項を生成します。

📊 包括的な患者データアクセス

• 完全な患者レコード：人口統計情報、病状、投薬、手術、診療記録などを含みます。
• バイタルサインと検査結果：時系列データを持つカテゴリ別の観察結果が提供されます。
• ケアプランとチーム：治療計画と医療提供者の情報が含まれます。
• アレルギーと手術：完全な医療履歴を追跡します。

🚀 パフォーマンス最適化

• 非同期操作：高性能なデータアクセスのための非ブロッキングI/Oをサポートします。
• インテリジェントキャッシュ：病状コードや頻繁にアクセスされるデータをキャッシュします。
• バッチ処理：複数の患者レコードを効率的に処理します。
• コネクションプーリング：複数のサーバーに対する最適化されたHTTP接続を提供します。

📦 インストール

前提条件

• Python 3.11以上
• OpenAI APIキー（AI機能を使用する場合）
• 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 Trial Pageにアクセスします。
   • フォームに記入し、ライセンスキーをメールで受け取ります。
   • ライセンスファイルを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リクエストを作成します。
   • リクエストタイプをraw JSONに設定します。
   • テストデータバンドルの内容をコピーします。
   • リクエストをベースURL（http://localhost:9090）に送信します。
   • 各データバンドルに対して繰り返します。

これらの手順を完了すると、http://localhost:9090で動作するテストデータベースにアクセスできます。

MCPチャットボットクライアントのセットアップ

MCPチャットボットクライアントは、リポジトリをフォークするか、Dockerを使用してセットアップできます。チャットボットは、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設定に移動します。
   • "Add Server"をクリックします。
   • .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データベースとの対話が可能になります。

🏗 アーキテクチャ

コアコンポーネント

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操作

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")

AIによる臨床分析

1. 臨床テキストの抽出

# 自由記述のテキストから臨床キーワードを抽出する
clinical_note = "45歳の女性、HER2陽性の浸潤性乳管癌、III期A"
keywords = await fhir_server.extract_clinical_keywords(clinical_note)

2. FHIRコードのマッピング

# 臨床用語をFHIRコードにマッピングする
clinical_data = {
    "conditions": ["乳がん", "糖尿病"],
    "age": 45,
    "gender": "女性"
}
fhir_codes = await fhir_server.map_to_fhir_codes_fast(clinical_data)

3. 類似患者の検索

# 類似した臨床プロファイルを持つ患者を検索する
criteria = {
    "age": 45,
    "gender": "女性",
    "conditions": ["乳がん"]
}
similar_patients = await fhir_server.find_similar_patients_simple(criteria)

MCPサーバーの統合

FHIRサーバーは、AIアシスタントとの統合のためのMCPサーバーとして使用できます。

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

🔧 技術詳細

サーバー設定

システムは、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) - 患者の手術情報を取得する

AIによる分析

• 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（Model Context Protocol）インスペクターは、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. 品質改善

   • 自動化された品質指標の追跡
   • コンプライアンスの監視と報告
   • パフォーマンス分析とベンチマーク

🔐 セキュリティとコンプライアンス

• 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 - AIによる臨床分析機能を追加
• v0.3.0 - マルチサーバーサポートとキャッシュ機能を強化

🎯 ロードマップ

• [ ] 高度な分析ダッシュボード
• [ ] リアルタイムデータストリーミング
• [ ] 機械学習モデルの統合
• [ ] 強化されたセキュリティ機能
• [ ] モバイルアプリケーションのサポート
• [ ] クラウドデプロイメントテンプレート

🕒 FHIRタイムラインエージェント

FHIRタイムラインエージェント (fhir_timeline_agent.py) は、実際のFHIRデータを使用して患者のクエリから詳細な臨床治療タイムラインを生成するために設計された特殊なエージェントです。Firely Local FHIRサーバーと連携するように構成されています。

機能

• 自然言語処理：自由記述の患者クエリを構造化された臨床データに変換します。
• 実際の患者データ分析：実際のFHIR患者レコードを使用してタイムラインを生成します。
• AIによるタイムライン生成：OpenAI GPT - 4を利用して正確な臨床タイムラインを生成します。
• 対話型CLIインターフェース：リッチなフォーマットのユーザーフレンドリーなコマンドラインインターフェースを提供します。
• 包括的な患者マッチング：年齢、性別、病状に基づいて類似した患者を検索します。

使用方法

# チャットインターフェースで対話モードで実行する
python fhir_timeline_agent.py

# サンプルクエリでデモモードで実行する
python fhir_timeline_agent.py --demo

クエリの例

• "45歳の男性、膵臓腺癌"
• "62歳の女性、HER2陽性乳がん"
• "58歳の男性、III期A肺腺癌"

タイムライン生成プロセス

1. クエリ処理

   • 自然言語から臨床キーワードを抽出します。
   • 年齢、性別、病状、ステージ、バイオマーカーを特定します。

2. FHIRコードマッピング

   • 臨床用語を標準化されたFHIRコードにマッピングします。
   • Firely Localサーバーのコードシステムを使用します。

3. 類似患者検索

   • FHIRデータベース内で一致する患者を検索します。
   • 年齢、性別、病状に基づいてマッチングスコアを付けます。

4. データ集約

   • 包括的な医療履歴を収集します。
   • 手術、投薬、診療記録を含みます。

5. タイムライン生成

   • AIを使用して詳細な治療タイムラインを作成します。
   • 臨床的なコンテキストを持ってイベントを時系列に整理します。

出力形式

エージェントは、以下のようなリッチなフォーマットの出力を生成します。

• 患者プロファイル：人口統計情報、診断、ステージ、バイオマーカー
• 治療タイムライン：日付付きの段階的な臨床イベント
• 臨床結果：治療反応、生存状況、毒性
• データソース：サーバー情報と分析指標

設定

エージェントは、以下の設定でハードコードされています。

• Firely Local FHIRサーバー (http://localhost:9090)
• タイムライン生成にOpenAI GPT - 4を使用
• フォーマット表示のためのリッチなコンソール出力

要件

• OpenAI APIキー（.envファイルに設定）
• 稼働中のFirely Local FHIRサーバー
• Pythonパッケージ：

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

ベストプラクティス

• クエリに完全な患者情報を提供してください。
• 年齢、性別、主要な診断を含めてください。
• 可能な場合は、ステージとバイオマーカー情報を追加してください。
• より良いマッチングのために、具体的な臨床用語を使用してください。

エラーハンドリング

エージェントは、以下のエラーに対する堅牢なエラーハンドリングを備えています。

• 患者情報が不足している場合
• FHIRサーバーの接続問題
• AI生成の失敗
• データ解析エラー

各エラーは、解決策の提案とともに表示されます。

医療の相互運用性と患者ケアの改善のために愛を込めて開発されました