sharp-fhir-mcp

Ein Clean-Room SHARP-on-MCP-konformer FHIR R4 MCP-Server mit interaktiven MCP-UI-Klinik-Dashboards.

Entwickelt für den Prompt Opinion "Build the Future of Healthcare AI" Hackathon — ein herstellerneutraler MCP-Server, in den sich jede SMART-on-FHIR-App, jeder Agent oder LLM-Host ohne serverseitiges OAuth, API-Schlüssel oder proprietäre Auth-Flows einklinken kann.

Warum SHARP?

Die SHARP (Standardised Healthcare Agent Remote Protocol)-Spezifikation beschreibt ein Header-basiertes Kontextmodell für MCP- Server im Gesundheitswesen:

Gemäß SHARP §3.2 führt der MCP-Server selbst niemals einen OAuth-Vorgang durch. Der Agent- Host (z. B. ein SMART-on-FHIR-Launch-Container) erhält das Token und leitet es bei jedem Aufruf weiter. Das bedeutet, dass eine einzige Bereitstellung dieses Servers mit Epic, Cerner, MEDITECH, athenahealth, eClinicalWorks, ConnectEHR, HAPI oder jedem anderen FHIR R4-Endpunkt funktioniert — es gibt nichts herstellerspezifisches.

Der Server kündigt capabilities.experimental.fhir_context_required = true bei jeder Initialisierungsantwort an, damit SHARP-fähige Clients wissen, dass sie diese Header automatisch weiterleiten müssen.

Was ist enthalten

🩺 Klinische FHIR-Tools

• fhir_get_capability_statement — den verbundenen FHIR-Server entdecken

• fhir_get_patient, fhir_search, fhir_read, fhir_patient_everything — generischer R4-Zugriff

• 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 — konsolidierte Datensatz-Abfrage

• clinical_get_context — vollständiger Besuchskontext (Demografie + Allergien + Medikamente + Probleme + Labor + Vitalwerte + Begegnungen + Warnungen) parallel

🔬 Labor, Vitalwerte & Bildgebung

• lab_get_results, lab_get_vital_signs, lab_get_diagnostic_reports

• imaging_get_documents — DocumentReference-Suche

🧠 Optionaler persistenter Speicher (SimpleMem)

Wenn SIMPLEMEM_API_URL und SIMPLEMEM_ACCESS_TOKEN gesetzt sind:

• memory_store_encounter — eine Besuchszusammenfassung speichern

• memory_store_alert — klinische Bedenken für den nächsten Besuch markieren

• memory_search_history — semantische Suche über vergangene Begegnungen

• memory_get_patient_history — alle gespeicherten Erinnerungen für den aktuellen Patienten auflisten

📊 MCP-UI-Visualisierungen

• visualize_lab_trend — Chart.js-Liniendiagramm eines Laborwerts über die Zeit

• visualize_vitals — Multi-Chart-Vitalwerte-Dashboard

• visualize_patient_dashboard — vollständige HTML-Klinikseite (Demografie, Warnungen, Allergien, Medikamente, Probleme, Labor, Begegnungen, Impfungen + Chart.js-Trends)

Alle visuellen Tools geben MCP-UI ui://-Ressourcen zurück, die der Host in seinem Inspector-Bereich rendert.

Schnellstart

1. Installation

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

2. Server starten

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

Der MCP-Endpunkt ist http://localhost:8000/mcp.

Hinweis: localhost bezieht sich hier auf den lokalen Host der Maschine, auf der Sie den Server ausführen. Um remote darauf zuzugreifen, stellen Sie den Server bereit (siehe unten) oder leiten Sie den Port auf Ihre lokale Instanz weiter.

3. Verbindung von einem SHARP-fähigen MCP-Client

Senden Sie diese Header bei jeder JSON-RPC-Anfrage:

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. Eine öffentliche Sandbox ausprobieren, ohne eine SMART-App zu schreiben

Die HAPI öffentliche FHIR R4-Sandbox ist schreibgeschützt und erfordert keine Authentifizierung — nützlich zum Ausprobieren:

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"}'

Bereitstellung

Vercel (Python serverless)

Dieser Server läuft als zustandsloser Streamable-HTTP-Endpunkt, der auf Vercel sofort einsatzbereit ist. Sie können ein bestehendes Next.js MCP-Gerüst wiederverwenden, indem Sie entweder:

1. Den Python ASGI-Handler hinzufügen — fügen Sie die app Starlette-Instanz in api/index.py ein:

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

   plus eine minimale vercel.json:

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

2. Oder ihn als Sidecar hinter Ihrem bestehenden Vercel-Frontend ausführen und /mcp per Reverse-Proxy an einen langlebigeren Host (Fly.io, Railway, Render) weiterleiten.

Der Server respektiert die von Vercel injizierte PORT-Umgebungsvariable.

Lokale Entwicklung

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

Docker (optional)

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

Architektur

┌─────────────────────────────────────────────────────────────┐
│  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 / …)

Siehe CLAUDE.md für detaillierte modulweise Notizen und die SHARP-Compliance-Checkliste.

SHARP-Compliance-Checkliste

Lizenz

MIT — siehe LICENSE.