Apple Health Coverage MCP

Apple Watchの非装着、バッテリー切れによるデータ欠落、同期遅延、エクスポーターのプレースホルダーゼロが、健康トレンドを静かに歪めるのを防ぐ、ローカルで読み取り専用のMCPセマンティックレイヤーです。

欠測は不明であり、ゼロではありません。ゼロが有効なのは、その指標が実際に観測可能だった場合のみです。

このプロジェクトは健康状態を診断するものではなく、Watchの欠落区間が非装着、バッテリー切れ、または他のデバイスの問題によるものかを判断できると主張するものでもありません。

問題

多くのApple Healthパイプラインは、Watchがデータを収集していない場合でも日次行を生成します。空のフィールドや生成されたゼロは、活動、回復、睡眠、カスタム健康軸を実際よりも悪く見せることがあります。

Apple Health Coverage MCPは2つの問いを分離します：

1. どのような値が観測されたか？

2. その指標は値を解釈するのに十分に観測可能だったか？

トレンドを計算する前にカバレッジを分類し、設定可能なカバレッジしきい値を下回る期間の解釈を拒否します。

Related MCP server: Apple Health Shortcuts MCP

現在の範囲

現在のリリースは、正規化された日次JSONファイルを消費します。決定論的な合成フィクスチャを含み、個人の健康データは含まれません。

実装済み：

• 完全、部分、利用不可、同期保留中、不明のカバレッジ状態

• Watch装着可能性の独立したエビデンス

• 観測されたゼロとプレースホルダーゼロの区別

• 指標固有の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カバレッジが利用不可の場合は除外されます。観測された日の実際のゼロは平均に残ります。電話バックアップの step_count は、Watchが不在でも使用可能なままです。

MCPツール

• health_coverage_day — 1日の観測カバレッジを説明

• 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が利用不可の可能性が高いと分類されます。運動ゼロはプレースホルダーの可能性が高いとして除外され、電話バックアップの歩数は使用可能なままです。

バックフィルモデル

HealthKitレコードは、以前の分析後に到着または変更されることがあります。upsertDays：

• 日付を日次アイデンティティとして使用

• 新しい取り込みを保持

• 新しく利用可能になった指標をマージ

• レコードを backfilled としてマーク

• 以前のカバレッジ分類を保持

派生トレンドと将来の健康軸は、アップサート後は常に再計算する必要があります。

プライバシー

• サーバーはネットワーク接続を開きません。

• MCPツールの出力は、クライアントが使用するAIモデルに送信されます。

• 個人のエクスポート、データベース、ZIPファイル、生成されたCSVはgitignoreされます。

• Apple Healthのエクスポートや実際の派生データセットをコミットしないでください。

• 機密データには集計クエリまたはローカルモデルを優先してください。

開発

実装はNodeの標準ライブラリとネイティブテストランナーを使用します。

npm test
npm run check

テストは合成レコードを使用し、観測されたゼロ、プレースホルダーゼロ、部分装着、Watch利用不可、同期保留中、不明な日、低カバレッジのトレンド拒否、電話フォールバック、バックフィルをカバーします。

ライセンス

MIT