Local Garmin Coach MCP

Приватные инструменты персонального коучинга Garmin для Codex/ChatGPT desktop и Claude. Сервер работает только через локальный stdio: ни Cloudflare, ни Render, ни публичного URL, ни сервиса учётных записей, ни затрат на хостинг.

В основе среды выполнения лежит etweisberg/garmin-connect-mcp в коммите 87d0ea059fb67f1ce65ac05100df74c3c3777c84. Она сохраняет исходную лицензию AGPL-3.0 и указание авторства Taxuspt в NOTICE.

Предварительные требования

• Node.js 20 или новее

• pnpm 10.14.0

• Учётная запись Garmin Connect и синхронизированные часы

Related MCP server: io.github.matisdsp/fartlek

Установка

cd /home/talvak/Desktop/repos/garmin-coach-mcp
pnpm install --frozen-lockfile
pnpm exec playwright install chromium
pnpm build
pnpm auth

pnpm auth открывает отдельный видимый профиль Chrome. Войдите вручную, выполните MFA, затем нажмите Enter в терминале. Браузерная сессия сохраняется в ~/.local/share/garmin-coach/browser-profile. Значения CSRF во время выполнения считываются с текущей аутентифицированной страницы и никогда не сохраняются и не выводятся на экран. Каталоги имеют права 0700, файлы — 0600, сохранение паролей отключено, а файл с именем пользователя/паролем не создаётся.

Получение контракта записи профиля Garmin

Garmin не публикует стабильный API для записи профиля ЧСС. Сервер отказывается угадывать его.

pnpm capture:profile-contract

Команда загружает текущую модель приложения Garmin, просит её сохранить без изменений текущие зоны по умолчанию и блокирует результирующий PUT до доставки. Она проверяет маршрут и точное неизменённое тело, затем сохраняет только обезличенную форму метода/пути/полей и поддерживаемые области в ~/.local/state/garmin-coach/profile-write-contract.json с правами 0600.

Если форму Garmin невозможно подтвердить, контракт не сохраняется, и запись профиля остаётся отключённой.

Подключение Codex и ChatGPT desktop

Сначала соберите проект, затем скопируйте config/codex.toml.example в ~/.codex/config.toml или добавьте эквивалентный сервер через ChatGPT desktop Settings > MCP servers. Codex CLI, расширение IDE и ChatGPT desktop используют общую локальную конфигурацию MCP на одном хосте.

В примере используются:

default_tools_approval_mode = "writes"

Оба инструмента применения также имеют явный approval_mode = "prompt". После настройки перезапустите клиент и используйте /mcp, чтобы проверить подключение.

ChatGPT web не может запустить этот локальный процесс stdio. Для записи в Garmin используйте ChatGPT desktop/Codex.

Подключение Claude

Объедините config/claude.json.example с конфигурацией MCP в Claude или выполните:

claude mcp add garmin-coach -- /home/talvak/snap/code/current/.local/share/pnpm/node /home/talvak/Desktop/repos/garmin-coach-mcp/dist/index.js

Блокировка файловой системы разрешает только одному локальному клиенту одновременно владеть профилем Chromium для Garmin. Остановите сервер в одном клиенте, прежде чем использовать другой.

Инструменты

Безопасный рабочий процесс

1. Вызовите get_coaching_snapshot и сравните результат с Garmin Connect.

2. Вызовите preview_hr_profile_update.

3. Проверьте каждое поле и подтвердите точное каноническое предложение/хэш.

4. Вызовите apply_hr_profile_update; затем синхронизируйте Garmin и визуально проверьте зоны на часах.

5. Вызовите preview_training_week для одной недели, начинающейся с воскресенья.

6. Проверьте его данные о восстановлении, полную полезную нагрузку, предупреждения и хэш.

7. Вызовите apply_training_week с неизменным каноническим предложением/хэшем.

8. Вызовите verify_training_week и подтвердите, что понедельник/пятница — 135-149 bpm; в пятницу должны отображаться фиксированные инструкции 12%.

9. Повторите оба вызова apply, чтобы доказать идемпотентность.

Боль/травма или болезнь блокируют запись тренировок. Восстановление может сохранить, уменьшить или пропустить нагрузку; оно никогда не увеличивает её. Тренировки никогда не удаляются автоматически.

Garmin показывает Treadmill как активность часов в категории Running, а не как вид спорта для структурированных тренировок. Поэтому пятница — это совместимая с бегом тренировка под названием Incline Walk 12%; запускайте её из активности Treadmill на часах. Её указание уклона 12% и целевая зона 135-149 bpm остаются явными.

Утверждённый профиль ЧСС

Эти значения предварительные: возраст 27, ЧСС в покое 55, расчётная максимальная ЧСС 189 и вручную заданный LTHR 181. Флаги автоматического определения сохраняются. Будущие изменения потребуют нового предпросмотра и подтверждения.

Проверка

Обычные тесты выполняются офлайн и никогда не обращаются к Garmin:

pnpm test
pnpm lint
pnpm format:check
pnpm typecheck
pnpm build
git diff --check

См. spec.md с описанием поведения и docs/architecture.md с границами доверия.

Лицензия

AGPL-3.0. См. LICENSE и NOTICE.