sharp-fhir-mcp

대화형 MCP-UI 임상 대시보드를 갖춘 클린룸 SHARP-on-MCP 호환 FHIR R4 MCP 서버입니다.

Prompt Opinion "Build the Future of Healthcare AI" 해커톤을 위해 구축된 이 서버는 서버 측 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`	에이전트 호스트가 이미 발행한 Bearer 토큰
`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` 헤더에서 Bearer 토큰 읽기	✅
기본 환자 컨텍스트를 위한 선택적 `X-Patient-ID` 헤더	✅
`capabilities.experimental.fhir_context_required` 광고	✅
서버 측 OAuth / 토큰 저장 없음	✅
벤더 중립적 FHIR R4 클라이언트	✅
헤더 부재 시 구조화된 `fhir_context_required` 오류 발생	✅
선택적 엄격한 403 강제 적용 (`--strict-context`)	✅

라이선스

MIT — LICENSE 참조.

sharp-on-fhir-mcp