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

• Живой мост iPhone в стиле HealthKite

• Версионированные определения пользовательских осей здоровья

Состояния покрытия

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

Демонстрация запрашивает health_data_quality через реальный JSON-RPC stdio-сервер, используя 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 всё равно передаётся той модели ИИ, которую использует ваш клиент.

• Личные экспорты, базы данных, ZIP-файлы и сгенерированные CSV-файлы игнорируются Git.

• Никогда не коммитьте экспорты Apple Health или реальные производные наборы данных.

• Для чувствительных данных предпочитайте агрегированные запросы или локальную модель.

Разработка

Реализация использует стандартную библиотеку Node и встроенный тестовый раннер.

npm test
npm run check

Тесты используют синтетические записи и охватывают наблюдаемые нули, нули-заглушки, частичное ношение, недоступность Watch, ожидание синхронизации, неизвестные дни, отказ от тренда при низком покрытии, запасной вариант телефона и дополнение.

Лицензия

MIT