Apple Health Coverage MCP

A local, read-only MCP semantic layer that prevents Apple Watch non-wear, discharged-device gaps, delayed sync, and exporter placeholder zeros from silently corrupting health trends.

Missing observations are unknown, not zero. A zero is valid only when the metric was actually observable.

This project does not diagnose health conditions and does not claim to know whether a missing Watch interval was caused by non-wear, a depleted battery, or another device problem.

Problem

Many Apple Health pipelines produce daily rows even when the Watch was not collecting data. Empty fields or generated zeroes can then make activity, recovery, sleep, and custom health axes look worse than they were.

Apple Health Coverage MCP separates two questions:

1. What value was observed?
2. Was that metric observable well enough to interpret the value?

It classifies coverage before calculating a trend and refuses to interpret periods below a configurable coverage threshold.

Current scope

The current release consumes a normalized daily JSON file. It includes a deterministic synthetic fixture and no personal health data.

Implemented:

• Full, partial, unavailable, pending-sync, and unknown coverage states
• Independent Watch-availability evidence
• Distinction between observed zero and placeholder zero
• Metric-specific Watch dependence
• Phone-backed metrics such as steps
• Coverage-aware trend thresholds
• Late-arriving/backfilled daily upserts
• MCP structuredContent plus text fallback
• Read-only/idempotent/closed-world MCP annotations

Planned adapters:

• MetricBridge / health-export-mcp
• Apple Health export.xml
• HealthKite-style live iPhone bridge
• Versioned custom health-axis definitions

Coverage states

State	Meaning	Trend behavior
observed	At least 18 hours of skin-contact evidence	Eligible
partial_coverage	Some Watch evidence, but not a full day	Eligible only when metric rules permit
likely_watch_unavailable	Phone activity exists but Watch skin-contact evidence does not	Watch-required values excluded
sync_pending	Recent samples may still arrive	Temporarily excluded
unknown	Neither Watch nor phone provides enough evidence	Excluded

likely_watch_unavailable deliberately returns multiple possible reasons and claimedCause: null.

Metric semantics

Every metric declares its own rules:

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

An exporter-provided exercise_minutes: 0 is excluded when Watch coverage is unavailable. A real zero from an observed day remains in the average. Phone-backed step_count can remain usable when the Watch is absent.

MCP tools

• health_coverage_day — explain one day's observation coverage
• health_coverage_range — inspect coverage across dates
• health_metric_catalog — discover metric-specific observability rules
• health_metric_trend — calculate only coverage-supported trends
• health_data_quality — summarize coverage before interpretation

All tools are local, read-only, idempotent, and closed-world.

Run the synthetic demo

Requires Node.js 22 or newer.

npm test
npm run check
npm run demo

The demo queries health_data_quality through the real JSON-RPC stdio server using examples/synthetic-health.json.

MCP client configuration

Use an absolute path:

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

For personal data, replace the synthetic fixture with a normalized adapter output stored outside the Git repository.

Normalized input

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

That example classifies the Watch as likely unavailable. The exercise zero is excluded as a likely placeholder, while phone-backed steps remain usable.

Backfill model

HealthKit records may arrive or change after a previous analysis. upsertDays:

• Uses date as the daily identity
• Keeps the newer ingestion
• Merges newly available metrics
• Marks the record backfilled
• Preserves the previous coverage classification

Derived trends and future health axes should always be recomputed after an upsert.

Privacy

• The server opens no network connection.
• MCP tool output still goes to whichever AI model your client uses.
• Personal exports, databases, ZIP files, and generated CSVs are gitignored.
• Never commit Apple Health exports or real derived datasets.
• Prefer aggregate queries or a local model for sensitive data.

Development

The implementation uses Node's standard library and native test runner.

npm test
npm run check

Tests use synthetic records and cover observed zeroes, placeholder zeroes, partial wear, Watch unavailability, pending sync, unknown days, low-coverage trend refusal, phone fallback, and backfill.

License

MIT