Capillus Hermes MCP

Herramientas de seguimiento Bluetooth local-first y MCP para gorras Capillus con Bluetooth.

Este repositorio tiene dos partes:

• monitor/: un monitor BLE en Python que detecta una gorra Capillus cuando se enciende para el tratamiento, registra observaciones locales e infiere sesiones de tratamiento completadas.

• src/: un servidor de solo lectura del Model Context Protocol para Hermes, Claude Desktop o cualquier cliente MCP. Lee los archivos locales del monitor y expone estado, sesiones, adherencia, observaciones e identidad del dispositivo.

No se requiere cuenta de Capillus, API en la nube, endpoint privado, scraping ni automatización de aplicaciones.

Qué Rastrea

Las gorras Capillus con Bluetooth solo aparecen durante la ventana de encendido del tratamiento. El monitor busca un anuncio BLE similar a una gorra y luego registra:

• estado de gorra presente/desconectada

• último RSSI e identidad BLE

• inicio/fin de tratamiento inferido

• sesiones completadas

• duración BLE observada sin procesar, ventana de inferencia, duración de tratamiento acreditada y base de finalización

• adherencia diaria y rachas

El matcher predeterminado busca nombres como Capillus_CAP, claves de datos del fabricante y direcciones fijadas opcionales. Puedes usar tu propia gorra encendiéndola una vez y dejando que el monitor la detecte automáticamente, luego fijando la identidad descubierta en monitor/config.json.

Por defecto, una sesión se marca como completada después de una ventana de tratamiento observada completa de 360 segundos, una ventana de encendido de gorra casi completa dentro de complete_grace_seconds, o una ventana de cierre obsoleto casi completa donde el monitor vio la gorra lo suficientemente reciente como para inferir que el ciclo de tratamiento continuó funcionando después del último anuncio. La ventana BLE sin procesar se conserva como observed_duration_seconds; el intervalo de cierre obsoleto se conserva como inference_window_seconds y close_detected_at; la duración de tratamiento acreditada se expone como inferred_duration_seconds con un completion_basis como observed_full_window, inferred_cap_power_cycle o inferred_stale_power_window. Las observaciones mucho más cortas permanecen incompletas, porque los anuncios BLE perdidos no deberían convertirse en crédito de adherencia falso.

En macOS, el modo subprocess_scanner predeterminado ejecuta cada descubrimiento BLE en un proceso hijo de corta duración. Esto mantiene cualquier crecimiento del heap de Bleak/CoreBluetooth fuera del proceso del monitor siempre activo; si el escáner de la plataforma pierde memoria en descubrimientos repetidos, la memoria se libera cuando el hijo sale. Si el escaneo por subprocesos no está disponible en un contexto de privacidad de macOS, el monitor puede recurrir a escaneos en el mismo proceso y reciclarse limpiamente después de max_runtime_seconds o max_scans_per_process; con launchd KeepAlive, se reinicia automáticamente.

Related MCP server: BLE MCP Server

Instalar el Monitor

mkdir -p ~/.capillus-home-monitor
cp monitor/capillus_monitor.py ~/.capillus-home-monitor/
cp monitor/config.example.json ~/.capillus-home-monitor/config.json
cd ~/.capillus-home-monitor
python3 -m venv .venv
.venv/bin/pip install -r /path/to/capillus-hermes-mcp/monitor/requirements.txt

Ejecuta una vez desde una terminal gráfica y enciende la gorra:

~/.capillus-home-monitor/.venv/bin/python ~/.capillus-home-monitor/capillus_monitor.py --config ~/.capillus-home-monitor/config.json run

En macOS debes otorgar permiso de Bluetooth al proceso de Python en Configuración del Sistema. Para seguimiento siempre activo, edita monitor/deploy/launchd/com.example.capillus-monitor.plist, reemplaza /Users/YOU, cópialo en ~/Library/LaunchAgents/ e inícialo con launchctl.

Sincronización Opcional con Open Brain

Si ejecutas Open Brain localmente, el bucle de sincronización incluido puede capturar hechos de adherencia duraderos a través de la ruta normal capture_thought de Open Brain. Captura cada sesión completada una vez y, después de la hora local de la tarde configurada, captura una alerta de tratamiento faltante si no se ha cumplido el objetivo diario.

En monitor/config.json, habilita y apunta la sincronización a tu checkout local de Open Brain:

{
  "openbrain": {
    "enabled": true,
    "repo_path": "/Users/YOU/open-brain",
    "tenant": "default",
    "time_zone": "America/New_York",
    "person_name": "the wearer",
    "daily_rule": "Daily Capillus treatment is required and non-negotiable."
  }
}

Ejecuta una vez:

/Users/YOU/open-brain/.venv/bin/python ~/.capillus-home-monitor/capillus_openbrain_sync.py --config ~/.capillus-home-monitor/config.json once

Para sincronización siempre activa, edita monitor/deploy/launchd/com.example.capillus-openbrain-sync.plist, reemplaza /Users/YOU, cópialo en ~/Library/LaunchAgents/ e inícialo con launchctl.

Instalar el Servidor MCP

npm install
npm run build

Apunta el MCP a tus datos del monitor:

export CAPILLUS_MONITOR_DATA_DIR="$HOME/.capillus-home-monitor/data"
node dist/src/index.js

Para Hermes, configura un servidor MCP stdio equivalente a:

mcp_servers:
  capillus:
    enabled: true
    command: /usr/local/bin/node
    args:
      - /path/to/capillus-hermes-mcp/dist/src/index.js
    env:
      CAPILLUS_MONITOR_DATA_DIR: /Users/YOU/.capillus-home-monitor/data
      CAPILLUS_TIME_ZONE: America/New_York

Hermes expone las herramientas con su prefijo normal mcp_<servidor>_<herramienta>, por ejemplo mcp_capillus_capillus_today.

Herramientas

• capillus_status: presencia actual, última hora vista, sesión activa, identidad del dispositivo.

• capillus_today: finalización del tratamiento del día local y sesión activa.

• capillus_sessions: sesiones de tratamiento inferidas recientes, incluyendo duración observada, ventana de inferencia, duración acreditada y base de finalización.

• capillus_adherence: adherencia diaria, días perdidos y racha actual.

• capillus_observations: observaciones BLE coincidentes recientes y candidatos cercanos opcionales.

• capillus_device: identidad fijada y notas de servicio BLE propietario observado.

Forma BLE Observada

La gorra observada durante el desarrollo se anunciaba como Capillus_CAP. Una sonda GATT de solo lectura mostró un servicio propietario estilo UART:

• service: 49535343-fe7d-4ae5-8fa9-9fafd205e455

• characteristic: 49535343-1e4d-4bd9-ba61-23c647249616

• characteristic properties: write, notify, indicate, write-without-response

El monitor público no envía comandos de control. Solo utiliza presencia y temporización Bluetooth local.

Seguridad

Esto es telemetría de adherencia, no consejo médico. No evalúa el crecimiento del cabello, altera el tratamiento ni controla la gorra.