Polar MCP

Этот репозиторий реализует границы, описанные в ADR 0001: переиспользуемое ядро Polar на Python с тонкими адаптерами только для чтения для локального MCP и Claude Agent SDK.

Реализация намеренно ориентирована в первую очередь на v4. Она предоставляет:

• автоматическое обновление токенов AccessLink v4;

• изолированные клиенты v4 и дополнительный v3;

• ограниченные диапазоны дат с исключающим концом и автоматическую разбивку запросов v4 на части;

• нормализованные ответные конверты с указанием источника API и единиц измерения;

• рекурсивное редактирование учётных данных, идентификаторов пользователя/устройства и точного местоположения;

• ограниченные вложенные временные ряды и результаты верхнего уровня;

• встроенный TTL-кэш в памяти, который никогда не сохраняет данные о здоровье;

• инструменты MCP и Agent SDK, которые могут только читать очищенные данные;

• отдельный CLI для аутентификации с локальным файлом токенов, доступным только владельцу.

Установка

Требуется Python 3.11 или новее.

python -m venv .venv
source .venv/bin/activate
pip install -e '.[mcp]'

Зарегистрируйте приложение в Polar AccessLink, затем задайте серверные учётные данные. Не помещайте эти значения в файл конфигурации MCP, который может прочитать модель.

export POLAR_CLIENT_ID='...'
export POLAR_CLIENT_SECRET='...'

Сгенерируйте URL авторизации с параметром state, который ваш обратный вызов проверяет:

polar-auth authorization-url \
  --redirect-uri 'http://127.0.0.1:8787/callback' \
  --state "$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

После одобрения доступа обменяйте полученный код. Если опустить --code, он будет прочитан без вывода на экран и без попадания в историю оболочки.

polar-auth exchange --redirect-uri 'http://127.0.0.1:8787/callback'
polar-auth status

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

Related MCP server: health-mcp

Запуск локального MCP

polar-mcp

Сервер использует stdio; он не открывает сетевой прослушиватель. Он предоставляет только:

• polar_get_activity

• polar_get_sleep

• polar_get_recovery

• polar_get_training_sessions

• polar_get_heart_rate

Все значения end_date являются исключающими. Схемы инструментов намеренно не содержат флагов необработанных данных или местоположения. Код вне агента может использовать PolarService.query с явным DisclosureGrant, но грант требует отдельного задокументированного подтверждения пользователя, а ответы остаются ограниченными по размеру.

Тестирование

В тестах используется только стандартный библиотечный тестовый раннер и имитируемые HTTP-транспорты:

PYTHONPATH=src python -m unittest discover -s tests -v

Ни один тест не требует учётных данных Polar и не отправляет данные о здоровье по сети.

Текущий статус валидации

Этот код реализует долговечную архитектуру, но не претендует на доказательство концепции на реальном устройстве, необходимое для принятия ADR 0001. ADR остаётся в статусе Proposed до завершения задокументированных проверок на реальном Polar Pacer.