sharp-fhir-mcp

インタラクティブな MCP-UI 臨床ダッシュボードを備えた、クリーンルームの SHARP-on-MCP 準拠FHIR R4 MCPサーバー。

Prompt Opinion "Build the Future of Healthcare AI" Hackathon のために構築されました。サーバーサイドのOAuth、APIキー、または独自の認証フローを必要とせず、あらゆるSMART-on-FHIRアプリ、エージェント、またはLLMホストが接続できるベンダーニュートラルなMCPサーバーです。

なぜSHARPなのか？

SHARP (Standardised Healthcare Agent Remote Protocol) 仕様は、ヘルスケア分野におけるMCPサーバーのための ヘッダーベースのコンテキストモデル を記述しています：

ヘッダー	目的
`X-FHIR-Server-URL`	患者のFHIR R4エンドポイントのベースURL
`X-FHIR-Access-Token`	エージェントホストによって既に発行されたベアラートークン
`X-Patient-ID`	オプションのデフォルト `Patient` リソースID

SHARP §3.2に基づき、MCPサーバー自体がOAuthフローを実行することはありません。エージェントホスト（例：SMART-on-FHIR起動コンテナ）がトークンを取得し、すべての呼び出しでそれを転送します。つまり、このサーバーを一度デプロイすれば、Epic、Cerner、MEDITECH、athenahealth、eClinicalWorks、ConnectEHR、HAPI、またはその他のFHIR R4エンドポイントに対して機能し、ベンダー固有の要素は一切ありません。

サーバーはすべての初期化レスポンスで capabilities.experimental.fhir_context_required = true を通知するため、SHARP対応クライアントはそれらのヘッダーを自動的に転送すべきであることを認識します。

含まれるもの

🩺 臨床FHIRツール

fhir_get_capability_statement — 接続されたFHIRサーバーの検出
fhir_get_patient, fhir_search, fhir_read, fhir_patient_everything — 汎用的なR4アクセス
clinical_search_patients, clinical_get_patient_summary
clinical_get_appointments, clinical_get_encounters
clinical_get_problems, clinical_get_medications, clinical_get_allergies, clinical_get_immunizations
clinical_get_health_record — ワンショットの統合記録
clinical_get_context — 完全な受診コンテキスト（人口統計 + アレルギー + 投薬 + 問題 + 検査 + バイタル + 受診歴 + アラート）を並列で取得

🔬 検査、バイタル、画像診断

lab_get_results, lab_get_vital_signs, lab_get_diagnostic_reports
imaging_get_documents — DocumentReference検索

🧠 オプションの永続メモリ (SimpleMem)

SIMPLEMEM_API_URL および SIMPLEMEM_ACCESS_TOKEN が設定されている場合：

memory_store_encounter — 受診サマリーの保存
memory_store_alert — 次回受診のための臨床的懸念事項のフラグ立て
memory_search_history — 過去の受診歴に対するセマンティック検索
memory_get_patient_history — 現在の患者の保存されたすべてのメモリをリスト表示

📊 MCP-UI可視化

visualize_lab_trend — 検査項目の時系列Chart.js折れ線グラフ
visualize_vitals — バイタルダッシュボード（マルチチャート）
visualize_patient_dashboard — 完全なHTML臨床ページ（人口統計、アラート、アレルギー、投薬、問題、検査、受診歴、予防接種 + Chart.jsトレンド）

すべての視覚化ツールは、ホストがインスペクターペインでレンダリングするMCP-UI ui:// リソースを返します。

クイックスタート

1. インストール

git clone https://github.com/your-org/sharp-fhir-mcp.git
cd sharp-fhir-mcp
pip install -e .

2. サーバーの実行

sharp-fhir-mcp                     # streamable-http on 0.0.0.0:8000
sharp-fhir-mcp --port 9000         # custom port
sharp-fhir-mcp --strict-context    # 403 on non-handshake without FHIR headers

MCPエンドポイントは http://localhost:8000/mcp です。

注: ここでの localhost は、サーバーを実行しているマシンのローカルホストを指します。リモートからアクセスするには、サーバーをデプロイするか（下記参照）、ローカルインスタンスにポートフォワードしてください。

3. SHARP対応MCPクライアントからの接続

すべてのJSON-RPCリクエストで以下のヘッダーを送信してください：

X-FHIR-Server-URL: https://hapi.fhir.org/baseR4
X-FHIR-Access-Token: <bearer token from your SMART launch>
X-Patient-ID: 12345          # optional

4. SMARTアプリを作成せずにパブリックサンドボックスを試す

HAPIパブリックFHIR R4サンドボックスは読み取り専用で 認証を必要としません — 動作確認に便利です：

curl -X POST http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'X-FHIR-Server-URL: https://hapi.fhir.org/baseR4' \
  -H 'X-FHIR-Access-Token: anonymous' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

デプロイメント

Vercel (Pythonサーバーレス)

このサーバーはステートレスなStreamable-HTTPエンドポイントとして動作し、Vercelでそのまま機能します。既存の Next.js MCPスキャフォールドを再利用するには、以下のいずれかを行います：

Python ASGIハンドラーの追加 — app Starletteインスタンスを api/index.py に配置します：

# api/index.py
from sharp_fhir_mcp.server import app  # noqa: F401

および最小限の vercel.json：

{
  "builds": [{"src": "api/index.py", "use": "@vercel/python"}],
  "routes": [{"src": "/(.*)", "dest": "api/index.py"}]
}

またはサイドカーとして実行 — 既存のVercelフロントエンドの背後で実行し、/mcp をより長期間稼働するホスト（Fly.io, Railway, Render）にリバースプロキシします。

サーバーはVercelが注入する PORT 環境変数を尊重します。

ローカル開発

cp .env.example .env             # set FHIR_SERVER_URL etc. for fallbacks
sharp-fhir-mcp                   # http://localhost:8000/mcp

Docker (オプション)

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install -e .
EXPOSE 8000
CMD ["sharp-fhir-mcp", "--host", "0.0.0.0", "--port", "8000"]

アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│  MCP Client / Agent / LLM host (Claude, Cursor, custom)     │
│  • Knows the patient's FHIR endpoint + access token         │
│  • Sends X-FHIR-Server-URL, X-FHIR-Access-Token headers     │
└────────────────────────┬────────────────────────────────────┘
                         │ Streamable HTTP (SHARP-on-MCP)
            POST /mcp + JSON-RPC + SHARP headers
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  sharp-fhir-mcp                                             │
│                                                             │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ SharpContextMiddleware                                 │ │
│  │ • Parses X-FHIR-Server-URL / X-FHIR-Access-Token       │ │
│  │ • Stores in ContextVar for the request scope           │ │
│  └─────────────────────────┬──────────────────────────────┘ │
│                            ▼                                │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ FastMCP tool registry                                  │ │
│  │ ├─ fhir_*           (generic R4 search/read)           │ │
│  │ ├─ clinical_*       (patient/encounter/medication/…)   │ │
│  │ ├─ lab_* / imaging_*(observations, reports, docs)      │ │
│  │ ├─ memory_*         (optional SimpleMem)               │ │
│  │ └─ visualize_*      (MCP-UI Chart.js dashboards)       │ │
│  └─────────────────────────┬──────────────────────────────┘ │
│                            ▼                                │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Vendor-neutral FHIR R4 client (httpx, async)           │ │
│  └─────────────────────────┬──────────────────────────────┘ │
└────────────────────────────┼────────────────────────────────┘
                             ▼
            FHIR R4 server (Epic / Cerner / HAPI / …)

モジュールごとの詳細なメモとSHARPコンプライアンスチェックリストについては CLAUDE.md を参照してください。

SHARPコンプライアンスチェックリスト

要件	ステータス
Streamable-HTTPトランスポート (stdioは対象外)	✅
`X-FHIR-Server-URL` ヘッダーからのFHIRエンドポイント読み取り	✅
`X-FHIR-Access-Token` ヘッダーからのベアラートークン読み取り	✅
デフォルトの患者コンテキストのためのオプションの `X-Patient-ID` ヘッダー	✅
`capabilities.experimental.fhir_context_required` の通知	✅
サーバーサイドのOAuth / トークンストレージなし	✅
ベンダーニュートラルなFHIR R4クライアント	✅
ヘッダー欠落時の構造化された `fhir_context_required` エラー	✅
オプションの厳格な403強制 (`--strict-context`)	✅

ライセンス

MIT — LICENSE を参照してください。

sharp-on-fhir-mcp