sharp-fhir-mcp

Un servidor MCP FHIR R4 compatible con SHARP-on-MCP de sala limpia con paneles clínicos interactivos MCP-UI.

Creado para el Hackathon Prompt Opinion "Build the Future of Healthcare AI" — un servidor MCP neutral respecto al proveedor que cualquier aplicación SMART-on-FHIR, agente o host de LLM puede conectar sin OAuth del lado del servidor, claves de API o flujos de autenticación propietarios.

¿Por qué SHARP?

La especificación SHARP (Standardised Healthcare Agent Remote Protocol) describe un modelo de contexto basado en encabezados para servidores MCP en el ámbito sanitario:

Según SHARP §3.2, el servidor MCP nunca ejecuta un proceso de OAuth por sí mismo. El host del agente (por ejemplo, un contenedor de lanzamiento SMART-on-FHIR) obtiene el token y lo reenvía en cada llamada. Esto significa que una única implementación de este servidor funciona con Epic, Cerner, MEDITECH, athenahealth, eClinicalWorks, ConnectEHR, HAPI o cualquier otro endpoint FHIR R4; no hay nada específico de un proveedor.

El servidor anuncia capabilities.experimental.fhir_context_required = true en cada respuesta de inicialización para que los clientes compatibles con SHARP sepan reenviar esos encabezados automáticamente.

Qué incluye

🩺 Herramientas clínicas FHIR

• fhir_get_capability_statement — descubrir el servidor FHIR conectado

• fhir_get_patient, fhir_search, fhir_read, fhir_patient_everything — acceso genérico 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 — registro consolidado de una sola vez

• clinical_get_context — contexto completo de la visita (datos demográficos + alergias + medicamentos + problemas + laboratorios + signos vitales + encuentros + alertas) en paralelo

🔬 Laboratorios, signos vitales e imágenes

• lab_get_results, lab_get_vital_signs, lab_get_diagnostic_reports

• imaging_get_documents — búsqueda de DocumentReference

🧠 Memoria persistente opcional (SimpleMem)

Cuando se configuran SIMPLEMEM_API_URL y SIMPLEMEM_ACCESS_TOKEN:

• memory_store_encounter — guardar un resumen de la visita

• memory_store_alert — marcar preocupaciones clínicas para la próxima visita

• memory_search_history — búsqueda semántica en encuentros pasados

• memory_get_patient_history — listar todas las memorias almacenadas para el paciente actual

📊 Visualizaciones MCP-UI

• visualize_lab_trend — gráfico de líneas de Chart.js de un laboratorio a lo largo del tiempo

• visualize_vitals — panel de múltiples gráficos de signos vitales

• visualize_patient_dashboard — página clínica HTML completa (datos demográficos, alertas, alergias, medicamentos, problemas, laboratorios, encuentros, inmunizaciones + tendencias de Chart.js)

Todas las herramientas visuales devuelven recursos ui:// de MCP-UI que el host renderiza en su panel de inspector.

Inicio rápido

1. Instalación

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

2. Ejecutar el servidor

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

El endpoint MCP es http://localhost:8000/mcp.

Nota: localhost aquí se refiere al localhost de la máquina donde estás ejecutando el servidor. Para acceder a él de forma remota, despliega el servidor (ver más abajo) o redirige el puerto a tu instancia local.

3. Conectar desde cualquier cliente MCP compatible con SHARP

Envía estos encabezados en cada solicitud 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. Probar un sandbox público sin escribir una aplicación SMART

El sandbox público FHIR R4 de HAPI es de solo lectura y no requiere autenticación — útil para probar el terreno:

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

Despliegue

Vercel (Python serverless)

Este servidor se ejecuta como un endpoint Streamable-HTTP sin estado, que funciona en Vercel de forma inmediata. Puedes reutilizar un andamio MCP de Next.js existente mediante:

1. Añadir el manejador ASGI de Python — coloca la instancia app de Starlette en api/index.py:

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

   más un vercel.json mínimo:

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

2. O ejecutarlo como un sidecar detrás de tu front-end de Vercel existente y haciendo proxy inverso de /mcp a un host de mayor duración (Fly.io, Railway, Render).

El servidor respeta la variable de entorno PORT inyectada por Vercel.

Desarrollo local

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

Docker (opcional)

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

Arquitectura

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

Consulta CLAUDE.md para obtener notas detalladas módulo por módulo y la lista de verificación de cumplimiento de SHARP.

Lista de verificación de cumplimiento de SHARP

Licencia

MIT — ver LICENSE.