EHR Tools with MCP and FHIR

Buscar y consultar datos de la Historia Clínica Electrónica (EHR) del paciente utilizando SMART on FHIR.

Documentación

EHR Tools with MCP and FHIR

EHR Tools Overview

https://youtu.be/K0t6MRyIqZU?si=Mz4d65DcAD3i2YbO

Este proyecto actúa como un servidor especializado que proporciona herramientas para Modelos de Lenguaje de Gran Tamaño (LLMs) y otros agentes de IA para interactuar con Registros de Salud Electrónicos (EHRs). Aprovecha el estándar SMART on FHIR para el acceso seguro a datos y el Protocolo de Contexto de Modelo (MCP) para exponer las herramientas.

Piénsalo como una puerta de enlace segura y un conjunto de herramientas que permite a la IA acceder y analizar de manera segura los datos de los pacientes de diversos sistemas EHR.

La Idea Central

El sistema funciona en tres etapas principales:

Cliente SMART on FHIR (Implementado dentro de este proyecto): Se conecta de forma segura a un EHR utilizando el marco estándar de SMART App Launch. Extrae una amplia gama de información del paciente, incluyendo tanto datos estructurados (como condiciones, medicamentos, laboratorios) como notas clínicas no estructuradas o archivos adjuntos.
Servidor MCP (Este Proyecto): Toma los datos EHR extraídos y los pone a disposición a través de un conjunto de herramientas potentes accesibles mediante el Protocolo de Contexto de Modelo. Estas herramientas permiten que sistemas externos (como modelos de IA) consulten y analicen los datos sin necesidad de acceso directo al EHR en sí.
Interfaz de IA / LLM (Consumidor Externo): Un agente de IA o Modelo de Lenguaje de Gran Tamaño se conecta al Servidor MCP y utiliza las herramientas proporcionadas para "hacer preguntas" sobre el registro del paciente, realizar búsquedas o ejecutar análisis personalizados.

Herramientas Disponibles

El Servidor MCP ofrece varias herramientas para interactuar con los datos EHR cargados:

grep_record: Realiza búsquedas de texto o expresiones regulares en todas las partes del registro obtenido (datos FHIR estructurados + texto de notas/archivos adjuntos). Ideal para encontrar palabras clave o menciones específicas (por ejemplo, "diabetes", "aspirina").
query_record: Ejecuta consultas SQL SELECT de solo lectura directamente contra los datos FHIR estructurados. Útil para búsquedas precisas basadas en estructuras de recursos FHIR conocidas (por ejemplo, encontrar resultados de laboratorio específicos por código LOINC).
eval_record: Ejecuta código JavaScript personalizado directamente sobre los datos obtenidos (recursos FHIR + archivos adjuntos). Ofrece máxima flexibilidad para cálculos complejos, combinación de datos de múltiples fuentes o formato personalizado.

Esta configuración permite que las herramientas de IA aprovechen datos EHR completos a través de una interfaz estandarizada y segura.

(Los detalles de configuración y uso para desarrolladores se pueden encontrar dentro del código base y la documentación específica de los módulos).

Componentes y Uso

Este proyecto ofrece diferentes formas de obtener datos EHR y exponerlos a través de herramientas MCP:

1. Cliente Web SMART on FHIR Independiente

Este proyecto incluye una aplicación web autónoma que permite a los usuarios conectarse a su EHR mediante SMART on FHIR y obtener sus datos.

Versión Alojada: Puedes usar una versión alojada públicamente en:
https://mcp.fhir.me/ehr-connect#deliver-to-opener:$origin
(Reemplaza $origin con el origen real de la ventana que abre este enlace).
Filtrado de Marcas (?brandTags): Puedes filtrar la lista de proveedores de EHR que se muestran en la página de conexión agregando el parámetro de consulta brandTags a la URL. Proporciona una lista separada por comas de etiquetas. Solo se mostrarán las marcas que coincidan con todas las etiquetas proporcionadas (de su configuración en brandFiles). Admite lógica tanto OR (separada por comas) como AND (separada por caret ^), con precedencia para AND.
- ?brandTags=epic,sandbox: Muestra marcas etiquetadas con epic O sandbox.
- ?brandTags=epic^dev: Muestra marcas etiquetadas con epic Y dev.
- ?brandTags=epic^dev,sandbox^prod: Muestra marcas etiquetadas con (epic Y dev) O (sandbox Y prod).
- Si se omite el parámetro, por defecto muestra marcas etiquetadas con prod.
- Ejemplo: .../ehr-connect?brandTags=hospital^us: Muestra marcas etiquetadas con hospital Y us.
Cómo Funciona: Al abrirse, esta página solicita al usuario que seleccione su proveedor de EHR. Luego inicia el flujo estándar de SMART App Launch, redirigiendo al usuario a la página de inicio de sesión de su EHR. Después de la autenticación y autorización exitosas, el cliente obtiene un conjunto completo de recursos FHIR (Paciente, Condiciones, Observaciones, Medicamentos, Documentos, etc.) e intenta extraer texto plano de cualquier archivo adjunto asociado (como PDF, RTF, HTML encontrados en DocumentReference).
Salida de Datos (ClientFullEHR): Una vez completada la obtención, el cliente reúne todos los datos en un objeto JSON ClientFullEHR. Este objeto contiene:
- fhir: Un diccionario donde las claves son tipos de recursos FHIR (por ejemplo, "Patient") y los valores son matrices de los recursos FHIR correspondientes.
- attachments: Una matriz de objetos de archivos adjuntos procesados, cada uno incluyendo metadatos (recurso fuente, ruta, tipo de contenido) y el contenido en sí (contentBase64 para datos sin procesar, contentPlaintext para texto extraído).
Entrega de Datos: Si se abre con el hash #deliver-to-opener:$origin, el cliente solicitará confirmación al usuario y luego enviará el objeto ClientFullEHR de vuelta a la ventana que lo abrió usando window.opener.postMessage(data, targetOrigin).

2. Servidor MCP Local vía Stdio (`src/cli.ts`)

Este modo es ideal para ejecutar el servidor MCP localmente, a menudo utilizado con herramientas como Cursor u otros clientes de IA de línea de comandos.

Proceso de Dos Pasos:
1. Obtener Datos a la Base de Datos: Primero, ejecuta la interfaz de línea de comandos con las banderas --create-db y --db. Esto inicia un servidor web temporal y utiliza la misma lógica del cliente web SMART on FHIR descrita anteriormente para obtener datos. En lugar de enviar los datos vía postMessage, guarda los datos ClientFullEHR en un archivo de base de datos SQLite local.
```
# Example: Fetch data and save to data/my_record.sqlite
bun run src/cli.ts --create-db --db ./data/my_record.sqlite
```
  Sigue las indicaciones (abriendo un enlace en tu navegador) para conectarte a tu EHR.
2. Ejecutar el Servidor MCP: Una vez creado el archivo de base de datos, ejecuta la CLI nuevamente, apuntando solo al archivo de base de datos. Esto carga los datos en memoria e inicia el servidor MCP, escuchando comandos en la entrada/salida estándar.
```
# Example: Start the MCP server using the saved data
bun run src/cli.ts --db ./data/my_record.sqlite
```
- Configuración (config.*.json): Este proceso depende de un archivo de configuración (por ejemplo, config.epicsandbox.json) que define las marcas/puntos finales de EHR disponibles en una matriz brandFiles. Cada entrada en esta matriz especifica los detalles de la marca, incluyendo:
  - url: Ruta/URL al archivo de definición de la marca (como static/brands/epic-sandbox.json).
  - tags: Una matriz de cadenas (por ejemplo, ["epic", "sandbox"]) utilizadas para categorización o filtrado.
  - vendorConfig: Contiene los detalles del cliente SMART on FHIR (clientId, scopes).

Configuración del Cliente (por ejemplo, Cursor): Configura tu cliente MCP para ejecutar este comando. Crucialmente, usa rutas absolutas tanto para src/cli.ts como para el archivo de base de datos.

{
  "mcpServers": {
    "local-ehr": {
      "name": "Local EHR Search",
      "command": "bun", // Or the absolute path to bun
      "args": [
          "/home/user/projects/smart-mcp/src/cli.ts", // Absolute path to cli.ts
          "--db",
          "/home/user/projects/smart-mcp/data/my_record.sqlite" // Absolute path to DB file
        ]
    }
  }
}

3. Servidor MCP Completo vía SSE (`src/sse.ts` / `index.ts`)

Este modo ejecuta un servidor persistente adecuado para escenarios donde múltiples clientes podrían conectarse a través de la red. Utiliza Eventos Enviados por el Servidor (SSE) para el canal de comunicación MCP.

Autenticación: La autenticación del cliente se basa en OAuth 2.1, según lo especificado por el Protocolo de Contexto de Modelo. El servidor proporciona puntos finales estándar (/authorize, /token, /register, etc.).
Obtención de Datos: Cuando un cliente inicia una conexión OAuth, el servidor maneja el flujo SMART on FHIR por sí mismo, obtiene los datos ClientFullEHR durante el proceso de autorización y los mantiene en memoria (o en una sesión persistida) durante la duración de la conexión del cliente.
Estado: Aunque es funcional, la especificación MCP para la interacción del cliente OAuth 2.1 aún está evolucionando. El soporte del cliente para este método de autenticación es extremadamente limitado en la actualidad, lo que dificulta probar este modo con clientes estándar fuera de herramientas especializadas de desarrollo o depuración. Este modo SSE debe considerarse experimental.

EHR Tools with MCP and FHIR

Documentación