fastslack/heural-hermes repository overview

⁠Heural Hermes

Servidor de terminología SNOMED CT, autocontenido y listo para producción.

Un solo docker run. La edición argentina completa de SNOMED CT, búsqueda full-text en español y una API REST — sin importaciones, sin dependencias externas, sin configuración.

⁠Qué es

Integrar terminología SNOMED CT en un sistema de salud suele llevar días de descarga de RF2, importación, indexado y tuning. Heural Hermes empaqueta Hermes⁠ — el motor de terminología clínica de Mark Wardle — dentro de una imagen Docker que ya trae la base SNOMED CT importada, indexada y compactada. La imagen arranca y sirve.

docker run -d -p 8080:8080 fastslack/heural-hermes:v5

Eso es todo lo que hay que hacer.

⁠Inicio rápido

⁠Desde Docker Hub (recomendado)

docker run -d --name hermes -p 8080:8080 fastslack/heural-hermes:v5

Verificá que responde:

curl "http://localhost:8080/v1/snomed/search?s=diabetes&maxHits=3"

[
  { "id": 2157527011, "conceptId": 405751000, "term": "Diabetes type", "preferredTerm": "Diabetes type" },
  { "id": 3377131000209115, "conceptId": 11530004, "term": "diabetes lábil", "preferredTerm": "Brittle diabetes mellitus" },
  { "id": 1778601012, "conceptId": 399144008, "term": "Bronze diabetes", "preferredTerm": "Bronze diabetes" }
]

⁠Compilando desde el fuente

git clone https://gitlab.com/heural/heural-hermes-service.git
cd heural-hermes-service
docker compose build      # tag: fastslack/heural-hermes:v5
docker compose up -d

⁠API REST

Base: http://localhost:8080

Ejemplos

# Buscar un diagnóstico
curl "http://localhost:8080/v1/snomed/search?s=infarto+agudo+de+miocardio"

# Resolver un concepto por ID (73211009 = Diabetes mellitus)
curl "http://localhost:8080/v1/snomed/concepts/73211009"

# Búsqueda restringida por ECL: descendientes de "Diabetes mellitus"
curl "http://localhost:8080/v1/snomed/search?s=diabetes&constraint=<<73211009"

⁠Integración MCP (Model Context Protocol)

Hermes expone MCP⁠ de forma nativa: un asistente de IA puede buscar conceptos, resolver SCTIDs, hacer cross-mapping y evaluar ECL directamente contra la terminología, sin pasar por la API HTTP.

Levantar el servidor MCP

# Vía Docker Compose (perfil dedicado)
docker compose --profile mcp run --rm -i hermes-mcp

# Vía Docker directo
docker run --rm -i fastslack/heural-hermes:v5 /start-mcp.sh

# Local, sin Docker
java --add-modules jdk.incubator.vector \
     --enable-native-access=ALL-UNNAMED \
     -jar data/hermes/hermes.jar --db data/hermes/snomed.db mcp --locale es

Configuración para clientes MCP (Claude Desktop → claude_desktop_config.json; Claude Code → .mcp.json del proyecto):

{
  "mcpServers": {
    "hermes": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "fastslack/heural-hermes:v5", "/start-mcp.sh"]
    }
  }
}

Tools disponibles

⁠Despliegue

El repositorio incluye un docker-compose.yml con la política de reinicio y la red pensadas para producción:

services:
  hermes:
    image: fastslack/heural-hermes:v5   # pull del registry en DEV/PROD
    build:                              # o build local con el mismo tag
      context: ./data/hermes
      args: { hermes_jar: ./hermes.jar, snomed_db: ./snomed.db }
    restart: unless-stopped             # se recupera solo tras reboot/crash del host
    ports: ['8080:8080']
    networks: [elastic_net]

En un servidor que consume la imagen publicada:

docker compose pull hermes
docker compose up -d hermes

⁠Stack técnico

Flujo de datos: RF2 → import LMDB → index Lucene → snomed.db → Hermes JAR → Jetty HTTP → REST/MCP.

⁠Seguridad

La línea v3+ corre sobre el stack Jetty 12 / Java 21 endurecido, que resuelve las vulnerabilidades reportadas en las bases Jetty 9.4.x anteriores:

• Jetty 9.4.x → 12.0.31 — elimina CVE-2025-5115, CVE-2024-6763, CVE-2024-8184
• Logback → 1.5.21 — elimina CVE-2025-11226
• commons-fileupload removido (reemplazado por la implementación interna de Jetty 12)
• OpenSSL y libtasn1 parcheados; base OS moderna con glibc 2.39

El servidor expone únicamente lectura de terminología: no persiste datos de pacientes ni acepta escrituras clínicas.

⁠Versiones

⁠Licencia

Copyright © 2024 Heural — Creador: Matías Aguirre

Software libre bajo la GNU General Public License v3⁠.

Hermes es desarrollado por Mark Wardle⁠ bajo licencia EPL-2.0. SNOMED CT® es marca registrada de SNOMED International⁠; su uso requiere la licencia de afiliado correspondiente.