health-os

health-os

Registro de salud personal local-first, expuesto a través de MCP. Tus análisis de laboratorio, diagnósticos, medicamentos, datos de dispositivos portátiles y registro de alimentos viven en tu propio Postgres; cualquier cliente MCP — ya sea uno que ejecute un modelo local o un asistente en la nube — puede leerlos y actualizarlos mediante herramientas protegidas. Los valores críticos, las reglas de seguridad de medicamentos y los calendarios de cribado son código determinista, no juicio de un LLM.

Aviso médico. Esto no es un dispositivo médico y no proporciona asesoramiento médico. Las alertas de valores críticos y los recordatorios de cribado son solo una señal para contactar a un médico — nunca un diagnóstico y nunca una razón para retrasar la atención. Úsalo bajo tu propio riesgo.

Qué hace

• Resultados de laboratorio — sube un PDF o una foto a tu cliente MCP; el modelo extrae los valores, health-os normaliza los nombres (sinónimos uk/ru/en/Latin) y las unidades, y prepara el panel como pendiente. Nada cuenta como hecho hasta que lo apruebes.
• Red de seguridad en código — los valores críticos alertan de inmediato (registro, notificación de macOS, Telegram opcional); los hallazgos críticos en informes narrativos se marcan; las preguntas sobre interacciones de medicamentos se rechazan y se redirigen a un médico/farmacéutico (solo se ejecutan comprobaciones deterministas: paracetamol diario total entre productos, biotina antes de análisis de laboratorio); una herramienta de crisis devuelve una respuesta fija con líneas de ayuda, independiente del modelo.
• Tendencias y análisis — tendencias de Mann-Kendall, líneas base personales y anomalías, calculadoras de riesgo por edad, un calendario de cribado, un informe semanal, un resumen para la visita al médico.
• Registro de alimentos — comidas con un perfil de 41 nutrientes, %RDA, indicadores de deficiencia/exceso, plantillas de comidas.
• Dispositivos — exportación de Apple Health e importación de Garmin.
• 28 herramientas MCP + instrucciones del servidor — las reglas de seguridad se envían a cada cliente al conectarse; consulta mcp_server/README.md.

Pruébalo con un solo comando

Solo se necesita Docker. Inicia una base de datos desechable con un paciente ficticio — dos años de análisis (LDL aumentando gradualmente), presión arterial, medicamentos, un registro de alimentos y un panel de laboratorio pendiente de aprobación:

git clone https://github.com/andronaft/health-os && cd health-os/demo
docker compose up -d --build

Apunta tu cliente MCP hacia él:

{
  "mcpServers": {
    "health-os-demo": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "health-os-demo",
               "-e", "DATABASE_URL=postgresql+psycopg://health:demo@db:5432/health_os",
               "health-os:local"]
    }
  }
}

Pregunta "muestra mi resumen de salud", "¿mi LDL está en tendencia al alza?", "¿qué está pendiente de revisión?", "¿qué me falta nutricionalmente?". Elimínalo todo con docker compose down -v.

Instalación para tus propios datos

Requiere Docker y Python 3.12+.

git clone https://github.com/andronaft/health-os && cd health-os
cp .env.example .env                  # set the passwords
docker compose up -d db               # Postgres 16 + pgvector
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/alembic upgrade head        # schema
.venv/bin/python -m seed.load         # marker catalog, synonyms, units, nutrients
.venv/bin/python -m seed.demo         # optional: a fictional demo patient to play with

Luego conecta un cliente MCP — la configuración para LM Studio, Open WebUI, Ollama CLI y Claude está en mcp_server/README.md. Prueba: "muestra mi resumen de salud", "tendencia de LDL", "¿qué me falta nutricionalmente esta semana?".

Modelos locales: el servidor habla MCP estándar a través de stdio, por lo que cualquier cliente MCP que ejecute un modelo local puede usarlo. Verificado hasta ahora: el propio servidor con el cliente Python MCP oficial (CI + la demo de Docker). Aún no verificado de extremo a extremo con un modelo local — consulta #9; se agradecen informes.

Cómo funciona

MCP client (local or cloud model)
        │ stdio
   mcp_server/  ── read tools ──▶ approved views (read-only role, 5s timeout, row limits)
        │        ── write tools ─▶ core/services: normalize → status → critical rules → pending
        │
   safety/    critical values, narrative flags, interactions, crisis, alerts
   analytics/ trends, baselines, calculators, screening, nutrition, weekly report
        │
   PostgreSQL 16 + pgvector  ◀── ingestion/ (Apple Health, Garmin, embeddings)

Directorio	Qué contiene
core/	configuración, BD, normalización, servicios, deduplicación, resumen de salud
mcp_server/	servidor MCP, herramientas de lectura y escritura
safety/	reglas de seguridad deterministas y entrega de alertas
analytics/	tendencias, líneas base, calculadoras, cribado, nutrición, informes
ingestion/	esquema de extracción, puntuación de confianza, importadores de dispositivos, embeddings
migrations/	esquema de Alembic
seed/	catálogo de referencia + el paciente de demostración
evals/	escenarios de red team (inyecciones, valores críticos ocultos, trucos de unidades)
scripts/	copia de seguridad/restauración (restic + launchd), configuración de rol de solo lectura, importadores

Privacidad / local-first

• Tus datos permanecen en tu propia base de datos. Postgres se ejecuta localmente en Docker; data/ y .env están fuera de git. health-os no envía nada a ningún lugar por sí mismo.
• Lo que sale de la máquina depende del cliente MCP que conectes. Con un modelo local (LM Studio, Open WebUI + Ollama, …) nada sale. Con un asistente en la nube, lo que devuelven las herramientas se envía a ese proveedor — usa uno cuyos términos se adapten a datos médicos (sin entrenamiento con tus datos, retención cero o corta).
• El objetivo es totalmente local: modelos locales para chat y extracción, embeddings locales para búsqueda (ya compatible a través de fastembed). Los clientes en la nube siguen siendo opcionales.
• El canal de alertas opcional (Telegram) envía solo un texto genérico "revisa tu sistema de salud", nunca valores.
• Cifra el disco (FileVault / LUKS / BitLocker) — los archivos de la base de datos están en texto plano en reposo.
• Nunca pongas datos médicos reales en issues, PRs o pruebas — solo datos sintéticos.

Pruebas

make test              # everything (needs Postgres for the integration part)
make test-unit         # pure unit tests — no database needed
make test-integration  # only tests marked `integration`

Las pruebas de integración nunca tocan la base de datos de trabajo: tests/conftest.py elimina y recrea <POSTGRES_DB>_test en el mismo servidor (migraciones + datos iniciales) en cada ejecución. Anula con TEST_DATABASE_URL (el nombre debe terminar en _test). Sin Postgres, las pruebas de integración se omiten localmente; CI establece REQUIRE_DB=1 para que fallen en su lugar.

Historial de desarrollo: PROGRESS.md.

Licencia

AGPL-3.0-o-posterior. Puedes usar, modificar y bifurcar health-os; si lo distribuyes o ejecutas una versión modificada como servicio de red, debes publicar tu código fuente bajo la misma licencia.

¿Quieres usarlo en un producto de código cerrado o comercial sin esas obligaciones? Una licencia comercial separada está disponible del autor — contacta a través de GitHub (@andronaft).

Las contribuciones son bienvenidas — consulta CONTRIBUTING.md (incluye un CLA breve).