Apple Health Coverage MCP

一个本地、只读的 MCP 语义层，可防止 Apple Watch 未佩戴、设备断连导致的缺口、同步延迟以及导出器占位零值静默污染健康趋势。

缺失的观测值应视为未知，而非零。只有当指标确实可观测时，零值才有效。

本项目不诊断健康状况，也不声称能判断 Watch 数据缺失是由未佩戴、电池耗尽还是其他设备问题所致。

问题

许多 Apple Health 数据管道即使在 Watch 未采集数据时也会生成每日记录。空字段或生成的零值随后可能让活动、恢复、睡眠以及自定义健康指标的趋势看起来比实际情况更差。

Apple Health Coverage MCP 将两个问题分开处理：

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 — 解释单日观测覆盖情况

• 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 服务器查询 health_data_quality，使用 examples/synthetic-health.json。

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