# 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:

```json
{
  "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.

```bash
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:

```json
{
  "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

```json
{
  "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.

```bash
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