Apple Health Coverage MCP

Apple Watch 미착용, 방전된 기기로 인한 공백, 지연된 동기화, 내보내기 도구의 자리 표시자 0값이 건강 트렌드를 조용히 왜곡하는 것을 방지하는 로컬 전용, 읽기 전용 MCP 의미 계층입니다.

누락된 관측값은 0이 아니라 알 수 없음입니다. 0값은 해당 지표가 실제로 관측 가능했을 때만 유효합니다.

이 프로젝트는 건강 상태를 진단하지 않으며, 누락된 Watch 구간이 미착용, 배터리 방전, 또는 다른 기기 문제로 인한 것인지 알 수 있다고 주장하지 않습니다.

문제

많은 Apple Health 파이프라인은 Watch가 데이터를 수집하지 않았을 때도 일별 행을 생성합니다. 빈 필드나 생성된 0값은 활동, 회복, 수면, 맞춤 건강 축이 실제보다 나빠 보이게 만들 수 있습니다.

Apple Health Coverage MCP는 두 가지 질문을 분리합니다:

1. 어떤 값이 관측되었는가?

2. 해당 지표가 값을 해석할 수 있을 만큼 충분히 관측 가능했는가?

트렌드를 계산하기 전에 커버리지를 분류하고, 구성 가능한 커버리지 임계값 미만의 구간은 해석을 거부합니다.

Related MCP server: Apple Health Shortcuts MCP

현재 범위

현재 릴리스는 정규화된 일별 JSON 파일을 사용합니다. 결정론적 합성 픽스처를 포함하며 개인 건강 데이터는 포함하지 않습니다.

구현됨:

• 전체, 부분, 사용 불가, 동기화 대기 중, 알 수 없음 커버리지 상태

• 독립적인 Watch 가용성 증거

• 관측된 0값과 자리 표시자 0값의 구분

• 지표별 Watch 의존성

• 휴대폰 기반 지표(예: 걸음 수)

• 커버리지 인식 트렌드 임계값

• 지연 도착/백필된 일별 업서트

• MCP structuredContent 및 텍스트 폴백

• 읽기 전용/멱등/폐쇄 세계 MCP 어노테이션

계획된 어댑터:

• MetricBridge / health-export-mcp

• Apple Health export.xml

• HealthKite 스타일 라이브 iPhone 브리지

• 버전 관리되는 맞춤 건강 축 정의

커버리지 상태

likely_watch_unavailable은 의도적으로 여러 가능한 원인과 claimedCause: null을 반환합니다.

지표 의미론

모든 지표는 자체 규칙을 선언합니다:

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

내보내기 도구가 제공한 exercise_minutes: 0은 Watch 커버리지를 사용할 수 없을 때 제외됩니다. 관측된 날의 실제 0값은 평균에 유지됩니다. 휴대폰 기반 step_count는 Watch가 없을 때도 사용 가능하게 유지될 수 있습니다.

MCP 도구

• health_coverage_day — 하루의 관측 커버리지 설명

• health_coverage_range — 날짜 범위의 커버리지 검사

• health_metric_catalog — 지표별 관측 가능성 규칙 탐색

• health_metric_trend — 커버리지가 지원하는 트렌드만 계산

• health_data_quality — 해석 전 커버리지 요약

모든 도구는 로컬, 읽기 전용, 멱등, 폐쇄 세계입니다.

합성 데모 실행

Node.js 22 이상 필요.

npm test
npm run check
npm run demo

데모는 실제 JSON-RPC stdio 서버를 통해 examples/synthetic-health.json을 사용하여 health_data_quality를 쿼리합니다.

MCP 클라이언트 구성

절대 경로를 사용하세요:

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

개인 데이터의 경우 합성 픽스처를 Git 저장소 외부에 저장된 정규화된 어댑터 출력으로 교체하세요.

정규화된 입력

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

해당 예시는 Watch를 사용 불가능할 가능성이 높은 것으로 분류합니다. 운동 0값은 자리 표시자일 가능성이 높은 것으로 제외되며, 휴대폰 기반 걸음 수는 사용 가능하게 유지됩니다.

백필 모델

HealthKit 레코드는 이전 분석 이후 도착하거나 변경될 수 있습니다. upsertDays:

• 날짜를 일별 정체성으로 사용

• 더 새로운 수집을 유지

• 새로 사용 가능한 지표 병합

• 레코드를 backfilled로 표시

• 이전 커버리지 분류 보존

파생 트렌드와 향후 건강 축은 업서트 후 항상 다시 계산해야 합니다.

개인정보 보호

• 서버는 네트워크 연결을 열지 않습니다.

• MCP 도구 출력은 여전히 클라이언트가 사용하는 AI 모델로 전달됩니다.

• 개인 내보내기, 데이터베이스, ZIP 파일, 생성된 CSV는 gitignore됩니다.

• Apple Health 내보내기나 실제 파생 데이터셋을 커밋하지 마세요.

• 민감한 데이터에는 집계 쿼리나 로컬 모델을 선호하세요.

개발

구현은 Node의 표준 라이브러리와 네이티브 테스트 러너를 사용합니다.

npm test
npm run check

테스트는 합성 레코드를 사용하며 관측된 0값, 자리 표시자 0값, 부분 착용, Watch 사용 불가, 동기화 대기 중, 알 수 없는 날, 낮은 커버리지 트렌드 거부, 휴대폰 폴백, 백필을 다룹니다.

라이선스

MIT