Cobertura de Apple Health MCP

Una capa semántica MCP local y de solo lectura que evita que los intervalos sin uso del Apple Watch, las brechas por descarga del dispositivo, la sincronización retrasada y los ceros de marcador de posición del exportador corrompan silenciosamente las tendencias de salud.

Las observaciones faltantes son desconocidas, no cero. Un cero solo es válido cuando la métrica era realmente observable.

Este proyecto no diagnostica afecciones de salud ni afirma saber si un intervalo sin uso del Watch se debió a que no se llevaba puesto, a una batería agotada o a otro problema del dispositivo.

Problema

Muchos pipelines de Apple Health generan filas diarias incluso cuando el Watch no estaba recopilando datos. Los campos vacíos o los ceros generados pueden hacer que la actividad, la recuperación, el sueño y los ejes de salud personalizados parezcan peores de lo que eran.

Apple Health Coverage MCP separa dos preguntas:

1. ¿Qué valor se observó?

2. ¿Era esa métrica lo suficientemente observable como para interpretar el valor?

Clasifica la cobertura antes de calcular una tendencia y se niega a interpretar periodos por debajo de un umbral de cobertura configurable.

Related MCP server: Apple Health Shortcuts MCP

Alcance actual

La versión actual consume un archivo JSON diario normalizado. Incluye un fixture sintético determinista y ningún dato personal de salud.

Implementado:

• Estados de cobertura completa, parcial, no disponible, sincronización pendiente y desconocida

• Evidencia independiente de disponibilidad del Watch

• Distinción entre cero observado y cero de marcador de posición

• Dependencia del Watch específica de la métrica

• Métricas respaldadas por el teléfono, como los pasos

• Umbrales de tendencia sensibles a la cobertura

• Upserts diarios con llegada tardía o relleno

• MCP structuredContent más respaldo de texto

• Anotaciones MCP de solo lectura, idempotentes y de mundo cerrado

Adaptadores planificados:

• MetricBridge / health-export-mcp

• Apple Health export.xml

• Puente en vivo estilo HealthKite para iPhone

• Definiciones versionadas de ejes de salud personalizados

Estados de cobertura

likely_watch_unavailable devuelve deliberadamente múltiples razones posibles y claimedCause: null.

Semántica de métricas

Cada métrica declara sus propias reglas:

{
  "exercise_minutes": {
    "unit": "min",
    "measurementMode": "cumulative_event",
    "zeroSemantics": "valid_if_observable",
    "wearDependence": "wearable_required"
  },
  "step_count": {
    "unit": "count",
    "measurementMode": "cumulative_event",
    "zeroSemantics": "valid_if_observable",
    "wearDependence": "wearable_preferred"
  }
}

Un exercise_minutes: 0 proporcionado por el exportador se excluye cuando la cobertura del Watch no está disponible. Un cero real de un día observado permanece en el promedio. El step_count respaldado por el teléfono puede seguir siendo utilizable cuando el Watch no está presente.

Herramientas MCP

• health_coverage_day — explica la cobertura de observación de un día

• health_coverage_range — inspecciona la cobertura entre fechas

• health_metric_catalog — descubre reglas de observabilidad específicas de la métrica

• health_metric_trend — calcula solo tendencias respaldadas por cobertura

• health_data_quality — resume la cobertura antes de la interpretación

Todas las herramientas son locales, de solo lectura, idempotentes y de mundo cerrado.

Ejecutar la demo sintética

Requiere Node.js 22 o superior.

npm test
npm run check
npm run demo

La demo consulta health_data_quality a través del servidor real JSON-RPC stdio usando examples/synthetic-health.json.

Configuración del cliente MCP

Usa una ruta absoluta:

{
  "mcpServers": {
    "apple-health-coverage": {
      "command": "node",
      "args": [
        "/absolute/path/apple-health-coverage-mcp/src/server.js",
        "--data",
        "/absolute/path/apple-health-coverage-mcp/examples/synthetic-health.json"
      ]
    }
  }
}

Para datos personales, reemplaza el fixture sintético con una salida de adaptador normalizada almacenada fuera del repositorio Git.

Entrada normalizada

{
  "schemaVersion": "wear-health/v1",
  "metricDefinitions": {},
  "days": [
    {
      "date": "2026-08-18",
      "ingestedAt": "2026-08-19T08:00:00Z",
      "coverageSignals": {
        "skinContactHours": 0,
        "heartRateSamples": 0,
        "phoneActivityPresent": true,
        "watchSeenOnAdjacentDays": true,
        "syncState": "complete"
      },
      "metrics": {
        "exercise_minutes": 0,
        "step_count": 3200
      }
    }
  ]
}

Ese ejemplo clasifica el Watch como probablemente no disponible. El cero de ejercicio se excluye como probable marcador de posición, mientras que los pasos respaldados por el teléfono siguen siendo utilizables.

Modelo de relleno

Los registros de HealthKit pueden llegar o cambiar después de un análisis anterior. upsertDays:

• Usa la fecha como identidad diaria

• Conserva la ingesta más reciente

• Fusiona las métricas recién disponibles

• Marca el registro como backfilled

• Conserva la clasificación de cobertura anterior

Las tendencias derivadas y los futuros ejes de salud siempre deben recalcularse después de un upsert.

Privacidad

• El servidor no abre ninguna conexión de red.

• La salida de la herramienta MCP sigue yendo al modelo de IA que use tu cliente.

• Las exportaciones personales, bases de datos, archivos ZIP y CSV generados están en gitignore.

• Nunca hagas commit de exportaciones de Apple Health ni de conjuntos de datos derivados reales.

• Prefiere consultas agregadas o un modelo local para datos sensibles.

Desarrollo

La implementación usa la biblioteca estándar de Node y el ejecutor de pruebas nativo.

npm test
npm run check

Las pruebas usan registros sintéticos y cubren ceros observados, ceros de marcador de posición, uso parcial, no disponibilidad del Watch, sincronización pendiente, días desconocidos, rechazo de tendencias de baja cobertura, respaldo del teléfono y relleno.

Licencia

MIT