Apple Health Coverage MCP

Eine lokale, schreibgeschützte MCP-Semantikschicht, die verhindert, dass Nicht-Tragen der Apple Watch, Lücken durch entladene Geräte, verzögerte Synchronisierung und Exporteur-Platzhalter-Nullen Gesundheitstrends stillschweigend verfälschen.

Fehlende Beobachtungen sind unbekannt, nicht Null. Eine Null ist nur gültig, wenn die Metrik tatsächlich beobachtbar war.

Dieses Projekt diagnostiziert keine Gesundheitszustände und behauptet nicht zu wissen, ob ein fehlendes Watch-Intervall durch Nicht-Tragen, eine entladene Batterie oder ein anderes Geräteproblem verursacht wurde.

Problem

Viele Apple-Health-Pipelines erzeugen tägliche Zeilen, auch wenn die Watch keine Daten erfasst hat. Leere Felder oder generierte Nullen können dann Aktivität, Erholung, Schlaf und benutzerdefinierte Gesundheits-Achsen schlechter erscheinen lassen, als sie waren.

Apple Health Coverage MCP trennt zwei Fragen:

1. Welcher Wert wurde beobachtet?

2. War diese Metrik gut genug beobachtbar, um den Wert zu interpretieren?

Es klassifiziert die Abdeckung, bevor es einen Trend berechnet, und weigert sich, Zeiträume unterhalb eines konfigurierbaren Abdeckungsschwellenwerts zu interpretieren.

Related MCP server: Apple Health Shortcuts MCP

Aktueller Umfang

Die aktuelle Version verarbeitet eine normalisierte tägliche JSON-Datei. Sie enthält eine deterministische synthetische Testvorlage und keine persönlichen Gesundheitsdaten.

Implementiert:

• Vollständige, teilweise, nicht verfügbare, ausstehende Synchronisierung und unbekannte Abdeckungszustände

• Unabhängige Watch-Verfügbarkeitsnachweise

• Unterscheidung zwischen beobachteter Null und Platzhalter-Null

• Metrikspezifische Watch-Abhängigkeit

• Telefonbasierte Metriken wie Schritte

• Abdeckungsbewusste Trend-Schwellenwerte

• Spät eintreffende/backgefillte tägliche Upserts

• MCP structuredContent plus Text-Fallback

• Schreibgeschützte/idempotente/geschlossene-Welt-MCP-Anmerkungen

Geplante Adapter:

• MetricBridge / health-export-mcp

• Apple Health export.xml

• HealthKite-ähnliche Live-iPhone-Brücke

• Versionierte benutzerdefinierte Gesundheits-Achsen-Definitionen

Abdeckungszustände

likely_watch_unavailable liefert bewusst mehrere mögliche Gründe und claimedCause: null.

Metriksemantik

Jede Metrik deklariert ihre eigenen Regeln:

{
  "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"
  }
}

Ein vom Exporter bereitgestelltes exercise_minutes: 0 wird ausgeschlossen, wenn die Watch-Abdeckung nicht verfügbar ist. Eine echte Null von einem beobachteten Tag bleibt im Durchschnitt. Der telefonbasierte step_count bleibt nutzbar, wenn die Watch nicht vorhanden ist.

MCP-Tools

• health_coverage_day — erklärt die Beobachtungsabdeckung eines Tages

• health_coverage_range — untersucht die Abdeckung über Datumsbereiche

• health_metric_catalog — entdeckt metrikspezifische Beobachtbarkeitsregeln

• health_metric_trend — berechnet nur abdeckungsgestützte Trends

• health_data_quality — fasst die Abdeckung vor der Interpretation zusammen

Alle Tools sind lokal, schreibgeschützt, idempotent und geschlossene Welt.

Synthetische Demo ausführen

Erfordert Node.js 22 oder neuer.

npm test
npm run check
npm run demo

Die Demo fragt health_data_quality über den echten JSON-RPC-stdio-Server mit examples/synthetic-health.json ab.

MCP-Client-Konfiguration

Verwenden Sie einen absoluten Pfad:

{
  "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"
      ]
    }
  }
}

Ersetzen Sie für persönliche Daten die synthetische Testvorlage mit einer normalisierten Adapterausgabe, die außerhalb des Git-Repositorys gespeichert ist.

Normalisierte Eingabe

{
  "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
      }
    }
  ]
}

Dieses Beispiel klassifiziert die Watch als wahrscheinlich nicht verfügbar. Die Trainings-Null wird als wahrscheinlicher Platzhalter ausgeschlossen, während telefonbasierte Schritte nutzbar bleiben.

Backfill-Modell

HealthKit-Datensätze können nach einer früheren Analyse eintreffen oder sich ändern. upsertDays:

• Verwendet das Datum als tägliche Identität

• Behält die neuere Erfassung

• Führt neu verfügbare Metriken zusammen

• Markiert den Datensatz als backfilled

• Behält die bisherige Abdeckungsklassifizierung bei

Abgeleitete Trends und zukünftige Gesundheits-Achsen sollten nach einem Upsert immer neu berechnet werden.

Datenschutz

• Der Server öffnet keine Netzwerkverbindung.

• Die MCP-Toolausgabe geht weiterhin an das KI-Modell, das Ihr Client verwendet.

• Persönliche Exporte, Datenbanken, ZIP-Dateien und generierte CSVs sind gitignored.

• Committen Sie niemals Apple-Health-Exporte oder echte abgeleitete Datensätze.

• Bevorzugen Sie Aggregatabfragen oder ein lokales Modell für sensible Daten.

Entwicklung

Die Implementierung verwendet die Standardbibliothek von Node und den nativen Test-Runner.

npm test
npm run check

Tests verwenden synthetische Datensätze und decken beobachtete Nullen, Platzhalter-Nullen, teilweises Tragen, Watch-Nichtverfügbarkeit, ausstehende Synchronisierung, unbekannte Tage, Trend-Verweigerung bei geringer Abdeckung, Telefon-Fallback und Backfill ab.

Lizenz

MIT