Smart EHR MCP Server

Herramientas EHR con MCP y FHIR

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

Este proyecto funciona como un servidor especializado que proporciona herramientas para que los Modelos de Lenguaje Grande (LLM) y otros agentes de IA interactúen con los Registros Clínicos Electrónicos (EHR). Utiliza el estándar SMART en FHIR para el acceso seguro a los datos y el Protocolo de Contexto de Modelo (MCP) para exponer las herramientas.

Piense en ello como una puerta de enlace segura y un conjunto de herramientas que permite a la IA acceder y analizar de forma segura los datos de los pacientes de diversos sistemas EHR.

La idea central

El sistema funciona en tres etapas principales:

1. Cliente SMART en FHIR (implementado en este proyecto): Se conecta de forma segura a un EHR mediante el marco estándar de lanzamiento de aplicaciones SMART. Extrae una amplia gama de información del paciente, incluyendo datos estructurados (como afecciones, medicamentos y análisis de laboratorio) y notas clínicas no estructuradas o archivos adjuntos.
2. Servidor MCP (este proyecto): Toma los datos extraídos del EHR y los pone a disposición mediante un conjunto de potentes herramientas 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 acceder directamente al EHR.
3. Interfaz IA/LLM (consumidor externo): un agente de IA o un modelo de lenguaje grande 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/adjuntos). Ideal para encontrar palabras clave o menciones específicas (p. ej., "diabetes", "aspirina").
• query_record : Ejecuta consultas SQL SELECT de solo lectura directamente en los datos FHIR estructurados. Útil para búsquedas precisas basadas en estructuras de recursos FHIR conocidas (p. ej., encontrar resultados de laboratorio específicos por código LOINC).
• eval_record : Ejecuta código JavaScript personalizado directamente en los datos obtenidos (recursos FHIR + adjuntos). Ofrece máxima flexibilidad para cálculos complejos, la combinación de datos de múltiples fuentes o el formato personalizado.

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

(Los detalles de configuración y uso del desarrollador se pueden encontrar dentro del código base y la documentación del módulo específico).

Componentes y uso

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

1. SMART independiente en el cliente web FHIR

Este proyecto incluye una aplicación web autónoma que permite a los usuarios conectarse a su EHR a través de SMART en FHIR y obtener sus datos.

• Versión alojada: puede utilizar una versión alojada públicamente en:
  https://mcp.fhir.me/ehr-connect#deliver-to-opener:$origin
  (Reemplace $origin con el origen real de la ventana que abre este enlace).
• Filtrado de marcas ( ?brandTags ): Puede filtrar la lista de proveedores de EHR que se muestra en la página de conexión añadiendo el parámetro de consulta brandTags a la URL. Proporcione una lista de etiquetas separadas por comas. Solo se mostrarán las marcas que coincidan con todas las etiquetas proporcionadas (de su configuración en brandFiles ). Admite lógicas OR (separadas por comas) y AND (separadas por signos de intercalación ^ ), con prioridad AND.
  • ?brandTags=epic,sandbox : Muestra las marcas etiquetadas con epic O sandbox .
  • ?brandTags=epic^dev : Muestra las marcas etiquetadas con epic Y dev .
  • ?brandTags=epic^dev,sandbox^prod : Muestra las marcas etiquetadas con ( epic AND dev ) O ( sandbox AND prod ).
  • Si se omite el parámetro, el valor predeterminado es mostrar las marcas etiquetadas con prod .
  • Ejemplo: .../ehr-connect?brandTags=hospital^us : Muestra las marcas etiquetadas con hospital Y us .
• Cómo funciona: Al abrir esta página, el usuario debe seleccionar su proveedor de HCE. A continuación, inicia el flujo estándar de inicio de la aplicación SMART, redirigiendo al usuario a la página de inicio de sesión de su HCE. Tras la autenticación y autorización correctas, el cliente obtiene un conjunto completo de recursos FHIR (Paciente, Afecciones, Observaciones, Medicamentos, Documentos, etc.) e intenta extraer texto sin formato de los archivos adjuntos asociados (como PDF, RTF o HTML, que se encuentran en DocumentReference ).
• Salida de datos ( ClientFullEHR ): Una vez finalizada la obtención, el cliente recopila todos los datos en un objeto JSON ClientFullEHR . Este objeto contiene:
  • fhir : un diccionario donde las claves son tipos de recursos FHIR (por ejemplo, "Paciente") y los valores son matrices de los recursos FHIR correspondientes.
  • attachments : una matriz de objetos adjuntos procesados, cada uno de los cuales incluye metadatos (recurso de origen, 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 a la ventana que lo abrió usando window.opener.postMessage(data, targetOrigin) .

2. Servidor MCP local a través de Stdio ( src/cli.ts )

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

• Proceso de dos pasos:
  1. Obtener datos en la base de datos: Primero, ejecute la interfaz de línea de comandos con los indicadores --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 los datos. En lugar de enviar los datos mediante postMessage , guarda los datos de 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
     Siga las instrucciones (abrirá un enlace en su navegador) para conectarse a su EHR.
  2. Ejecutar el servidor MCP: Una vez creado el archivo de base de datos, vuelva a ejecutar la CLI, apuntando únicamente al archivo de base de datos. Esto carga los datos en la memoria e inicia el servidor MCP, que recibe 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 se basa en un archivo de configuración (p. ej., config.epicsandbox.json ) que define las marcas/puntos terminales de EHR disponibles en una matriz brandFiles . Cada entrada de esta matriz especifica los detalles de la marca, incluyendo:
    • url : Ruta/URL al archivo de definición de marca (como static/brands/epic-sandbox.json ).
    • tags : una matriz de cadenas (por ejemplo, ["epic", "sandbox"] ) que se utiliza para categorización o filtrado.
    • vendorConfig : contiene detalles del cliente SMART en FHIR ( clientId , scopes ).
• Configuración del cliente (p. ej., Cursor): Configure su cliente MCP para ejecutar este comando. Es fundamental usar 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 a través de SSE ( src/sse.ts / index.ts )

Este modo ejecuta un servidor persistente, ideal para escenarios donde varios clientes pueden 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 en FHIR, obtiene los datos de ClientFullEHRdurante el proceso de autorización y los mantiene en la memoria (o en una sesión persistente) mientras dura la conexión del cliente.
• Estado: Si bien es funcional, la especificación MCP para la interacción con clientes OAuth 2.1 aún está en desarrollo. La compatibilidad con este método de autenticación es extremadamente limitada actualmente, lo que dificulta probar este modo con clientes estándar sin herramientas especializadas de desarrollo o depuración. Este modo SSE debe considerarse experimental .