Tyme Wear MCP Server

Сервер Model Context Protocol, который подключает Claude к платформе дыхательных датчиков Tyme Wear. Анализируйте данные вентиляции, активности, пороги и тренировочные зоны напрямую через Claude.

Построен на той же архитектуре, что и trainingpeaks-mcp.

Что такое Tyme Wear?

Tyme Wear производит нагрудный ремень VitalPro — носимый дыхательный датчик, который измеряет показатели вентиляции (частота дыхания, дыхательный объем, минутная вентиляция) вместе с частотой сердечных сокращений. Он использует вентиляционные пороги (VT1, VT2) для определения персонализированных тренировочных зон. Используется командой Team Visma | Lease a Bike.

Related MCP server: Strava MCP Server

Возможности

• 40 MCP-инструментов для профиля, активностей, данных дыхания, порогов VE, компактного поактивного анализа, файлов/обнаружения активностей, планов тренировок, рекомендаций по тренировкам, интеграций, подписки/аккаунта, физиологии покоя/максимума и экспорта

• Безопасное хранение учетных данных через системную связку ключей (связка ключей macOS / диспетчер учетных данных Windows) с резервным AES-256-GCM зашифрованным файлом

• Автоаутентификация с кэшированием токенов и автоматической повторной аутентификацией по истечении срока

• Умные данные дыхания с режимами summary, window и full для предотвращения переполнения контекста

• Поактивная аналитика (tw_get_activity_insights): обнаруженные VT1/VT2/VO2max с измеренной мощностью на пороге, показатели уверенности, флаг усеченного теста и время/калории по зонам — одним вызовом, без парсинга FIT

• Компактный анализ активности (tw_get_activity_analysis): согласованные временные метки, помеченные сводки и состояния возможностей, поканальные processed/new-processed/FIT fallback, детерминированное слияние по прошедшим секундам и пагинация

• Компактные полезные нагрузки активностей: tw_get_activity и tw_get_activity_workout_zone_detection по умолчанию отбрасывают многомегабайтные массивы посекундных данных (можно вернуть с помощью include=[...])

• Публичный режим Streamable HTTP со статическим bearer-токеном или OAuth-аутентификацией (коннектор claude.ai в один клик), однопользовательский, привязанный к аккаунту оператора Tyme Wear

Быстрый старт

1. Установка

git clone https://github.com/tkelkermans/tymewear-mcp.git
cd tymewear-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

2. Аутентификация

tymewear-mcp auth

Введите ваши email и пароль от Tyme Wear. Учетные данные безопасно сохраняются в системной связке ключей с резервным зашифрованным файлом.

3. Настройка Claude Desktop

Добавьте в конфигурацию Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

{
  "mcpServers": {
    "tymewear": {
      "command": "/path/to/tymewear-mcp/.venv/bin/tymewear-mcp",
      "args": ["serve"]
    }
  }
}

Или выполните tymewear-mcp config, чтобы сгенерировать фрагмент с правильным путем.

4. Перезапустите Claude Desktop

Инструменты Tyme Wear появятся в списке инструментов Claude.

Команды CLI

Публичное интернет-развертывание

serve-public предоставляет конечную точку Streamable HTTP MCP для размещенных развертываний. Она аутентифицирована и не сохраняет состояние; это не анонимный публичный API.

Публичный сервер

Установите публичный URL и один или несколько MCP bearer-токенов через переменные окружения. Каждый bearer-токен должен быть длиной не менее 32 символов; используйте сгенерированный случайный секрет.

export TYMEWEAR_PUBLIC_URL="https://mcp.example.com/mcp"
export TYMEWEAR_PUBLIC_BEARER_TOKENS="replace-with-a-long-random-secret-of-32-plus-chars"

tymewear-mcp serve-public \
  --host 0.0.0.0 \
  --port 8000 \
  --public-url "$TYMEWEAR_PUBLIC_URL"

Конечная точка MCP по умолчанию — /mcp. /healthz возвращает только {"status":"ok"} и не раскрывает данные клиентов.

Контейнер

Включенный Dockerfile запускает публичный сервер от имени непривилегированного пользователя. Внедрите секреты во время выполнения:

docker build -t tymewear-mcp-public .

docker run --rm -p 8000:8000 \
  -e TYMEWEAR_PUBLIC_URL="https://mcp.example.com/mcp" \
  -e TYMEWEAR_PUBLIC_BEARER_TOKENS="replace-with-a-long-random-secret-of-32-plus-chars" \
  tymewear-mcp-public

Vercel

Репозиторий также содержит корневую точку входа Python ASGI для Vercel (main.py). Фреймворк Python Vercel направляет запросы непосредственно в приложение ASGI, поэтому vercel.json не должен переписывать /mcp, /healthz или /.well-known/* на внутренний путь функции. Свяжите локальный каталог с целевым проектом Vercel, подключите этот проект к Git-репозиторию, затем настройте как минимум TYMEWEAR_PUBLIC_BEARER_TOKENS для Production и Preview. Точка входа завершается с ошибкой, если переменная окружения публичного bearer-токена отсутствует. Используйте отдельный bearer-токен для Preview, чтобы ограничить область действия учетных данных. TYMEWEAR_PUBLIC_URL рекомендуется для псевдонимов продакшена, но развертывания preview могут получить его из URL развертывания Vercel.

PRODUCTION_TOKEN_FILE=/path/to/generated-production-bearer-token
PREVIEW_TOKEN_FILE=/path/to/generated-preview-bearer-token
chmod 600 "$PRODUCTION_TOKEN_FILE" "$PREVIEW_TOKEN_FILE"
vercel link
vercel git connect
vercel env add TYMEWEAR_PUBLIC_BEARER_TOKENS production --sensitive --yes < "$PRODUCTION_TOKEN_FILE"
vercel env add TYMEWEAR_PUBLIC_BEARER_TOKENS preview --sensitive --yes < "$PREVIEW_TOKEN_FILE"

Храните файлы токенов доступными только для чтения их владельцем; обертка развертывания отклоняет файлы токенов, доступные для группы или других пользователей. Используйте vercel env update TYMEWEAR_PUBLIC_BEARER_TOKENS production --sensitive --yes < "$PRODUCTION_TOKEN_FILE" при ротации существующего токена. Не передавайте bearer-токены через vercel deploy --env, shell echo или другие аргументы команд, которые могут попасть в историю оболочки или списки процессов.

Тот же путь используется скриптом scripts/deploy_public_vercel.sh для ручного восстановления развертываний. Он требует существующей ссылки на проект Vercel, загружает токен из файла, развертывает продакшен и запускает scripts/verify_public_endpoint.py для проверки развернутого URL MCP:

scripts/deploy_public_vercel.sh --token-file "$PRODUCTION_TOKEN_FILE"

Установите PYTHON=/path/to/python, если верификатор должен работать с конкретным интерпретатором, например, с виртуальным окружением репозитория.

Автоматизированное развертывание (CI/CD)

.github/workflows/deploy.yml запускает заблокированный набор тестов (ruff + mypy + pytest) при каждом push и pull request. Он не содержит учетных данных Vercel и не развертывает приложение.

Связанная интеграция Git с Vercel создает preview-развертывания для функциональных веток и pull request, а затем создает production-развертывание при обновлении main. Секрет VERCEL_TOKEN GitHub Actions не требуется. Переменные времени выполнения, такие как TYMEWEAR_PUBLIC_BEARER_TOKENS, остаются управляемыми в проекте Vercel и сохраняются между Git-развертываниями.

Коннектор claude.ai (OAuth)

Статический bearer-токен работает для клиентов, поддерживающих заголовки (Claude Code: claude mcp add --transport http <url> --header "Authorization: Bearer <token>"). Коннектор claude.ai вместо этого аутентифицируется через OAuth, поэтому для добавления MCP туда сервер работает как OAuth защищенный ресурс: он проверяет JWT-токены доступа от управляемого провайдера (например, WorkOS AuthKit или Stytch) и применяет белый список email. Он остается однопользовательским — каждый авторизованный пользователь читает данные оператора через серверные учетные данные.

Установите эти (чувствительные) переменные окружения Vercel для включения:

Настройка провайдера (пример WorkOS AuthKit): создайте приложение, включите вход через Google/email, включите Dynamic Client Registration, чтобы claude.ai мог зарегистрироваться самостоятельно, и скопируйте URL эмитента в TYMEWEAR_PUBLIC_ISSUER_URL. Затем добавьте коннектор в claude.ai — он обнаружит провайдера через /.well-known/oauth-protected-resource сервера, зарегистрируется и запустит хостинговый вход; будут допущены только email из белого списка.

Статический путь TYMEWEAR_PUBLIC_BEARER_TOKENS продолжает работать вместе с OAuth (двухрежимный). Без TYMEWEAR_PUBLIC_ISSUER_URL OAuth отключен, и активен только bearer-путь.

Проверка после развертывания

После развертывания проверьте публичную конечную точку без вывода секретов:

TYMEWEAR_PUBLIC_URL="https://mcp.example.com/mcp" \
python scripts/verify_public_endpoint.py --bearer-token-file "$TOKEN_FILE"

Верификатор проверяет /healthz, отклонение неаутентифицированного /mcp, аутентифицированный MCP initialize, аутентифицированный tools/list, необходимые инструменты compact-analysis/profile, а также публичные заголовки безопасности/без кэширования. Он также подтверждает, что публичные развертывания не рекламируют чтение сырых активностей или экспорт на диск, а развертывания по умолчанию не рекламируют инструменты модификации.

Аутентификация публичного клиента

Публичный режим однопользовательский: он аутентифицируется вышестоящим Tyme Wear с собственными учетными данными оператора из TYMEWEAR_EMAIL / TYMEWEAR_PASSWORD (серверная переменная окружения), поэтому каждый авторизованный вызывающий читает данные оператора. Клиенты должны только доказать, что им разрешено подключаться — никакого токена Tyme Wear на каждый запрос нет.

Клиенты, поддерживающие заголовки (например, Claude Code), отправляют статический gateway bearer-токен:

Authorization: Bearer <TYMEWEAR_PUBLIC_BEARER_TOKENS entry>

Когда OAuth включен (установлен TYMEWEAR_PUBLIC_ISSUER_URL), клиенты, такие как коннектор claude.ai, вместо этого отправляют JWT, выданный провайдером, полученный через хостинговый вход; сервер проверяет его (подпись через JWKS, эмитент, необязательная аудитория) и допускает только email из белого списка. Оба пути работают одновременно (двухрежимный).

В более ранних версиях требовался заголовок X-Tymewear-Token для каждого запроса. Однопользовательский режим удалил его — теперь учетные данные находятся на стороне сервера.

Политика данных в публичном режиме

В публичном режиме:

• Доступ ограничен статическим bearer-токеном и/или белым списком email OAuth; подключаются только идентификаторы из белого списка.

• Учетные данные Tyme Wear оператора хранятся только в серверной переменной окружения (храните их в менеджере секретов). Они читаются непосредственно из окружения — публичный режим не затрагивает локальную связку ключей или зашифрованный файл учетных данных (они пишут в $HOME, который доступен только для чтения в serverless).

• Каждый результат инструмента и стабильная публичная ошибка проходят через одну неизменяющую рекурсивную проекцию конфиденциальности перед JSON-сериализацией. Она удаляет не-JSON значения, неконечные числа, email, UUID пользователей/аккаунтов/профилей, идентификаторы/серийные номера устройств, токены, подписанные/callback/загрузочные URL, S3 или временные пути, тяжелые сырые поля и координаты за пределами явного контракта местоположения анализа.

• tw_get_activity_analysis — это публичный компактный интерфейс сырых выборок. Он сохраняет помеченную доступность, возможности, каналы, происхождение, сводку и данные выборок с пагинацией. include_location должен быть литеральным boolean true; только raw_samples.data[*].position_lat/position_long и соответствующие метаданные канала могут тогда сохраниться. Домашние, общие и несвязанные координаты всегда удаляются.

• Публичные ответы включают Cache-Control: no-store, Pragma: no-cache, X-Robots-Tag: noindex, nofollow, HSTS для публичных URL по HTTPS и базовые заголовки безопасности для уменьшения случайного кэширования, индексации и утечки данных клиентов через браузер.

• Инструменты модификации профиля/активности скрыты и по умолчанию возвращают PUBLIC_MUTATIONS_DISABLED. Включайте их только с помощью --allow-mutations или TYMEWEAR_PUBLIC_ALLOW_MUTATIONS=true для доверенных развертываний.

• Инструменты экспорта CSV, FIT и strap-файлов возвращают PUBLIC_EXPORTS_DISABLED, так как локальная реализация записывает файлы на диск.

• tw_get_processed_data, tw_get_new_processed_data, tw_get_activity_logs и tw_get_activity_strap_files скрыты и возвращают PUBLIC_RAW_DATA_DISABLED, даже если включены мутации. Локальный режим stdio сохраняет эти инструменты. Компактное обнаружение тренировочных зон остается публичным.

Ошибки публичных инструментов стабильны и не возвращают текст исключений вышестоящего потока:

Усиление защиты в промышленной среде

• Завершайте TLS на границе сети и укажите TYMEWEAR_PUBLIC_URL равным каноническому HTTPS-адресу MCP.

• Следите, чтобы путь TYMEWEAR_PUBLIC_URL совпадал с подключенным путём MCP (по умолчанию /mcp). Публичный режим отвергает строки запроса URL, фрагменты и несовпадения маршрута/пути при запуске.

• Передавайте TYMEWEAR_PUBLIC_BEARER_TOKENS из менеджера секретов, а не из истории командной оболочки или системы контроля версий. Токены короче 32 символов отклоняются при запуске.

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

• Для недоверенных клиентов перед serve-public используйте OAuth-прокси или прокси с идентификацией; регулярно меняйте статические Bearer-токены.

• При использовании прокси или сервера авторизации с поддержкой OAuth установите TYMEWEAR_PUBLIC_ISSUER_URL или --issuer-url, чтобы MCP-клиенты могли обнаруживать метаданные защищённого ресурса.

• Тела публичных HTTP-запросов по умолчанию ограничены 1 МиБ, включая фрагментированные/потоковые тела. Изменяйте с помощью TYMEWEAR_PUBLIC_MAX_BODY_BYTES или --max-body-bytes только в том случае, если доверенному развертыванию нужны более крупные JSON-RPC-запросы.

• Отключите журналирование заголовка авторизации, тела запроса и тела ответа на обратном прокси и платформе приложения.

• Ограничьте исходящий сетевой трафик хостами API Tyme Wear, если ваша платформа это поддерживает.

• Устанавливайте явные значения --allowed-host и --allowed-origin, если хост публичного URL не является единственным допустимым хостом/источником. Публичный режим отклоняет недоверенные заголовки Host на всех маршрутах, запрещает конфигурацию хоста/источника с подстановочным знаком *, требует, чтобы разрешённые источники были точными http(s)-источниками без путей, и требует использования HTTPS для источников не на localhost.

Доступные инструменты

Авторизация и профиль

Активности

Данные дыхания

Файлы активностей и обнаружение

Планы тренировок и тренировки

Интеграции и аккаунт

Пороги и зоны

Максимальные значения

Экспорты

Примеры запросов

После настройки вы можете задавать Claude такие вопросы:

• "Покажи мои последние 10 велосипедных активностей"

• "Проанализируй данные дыхания с моей вчерашней поездки — каковы были средние VE и время в каждой зоне?"

• "Какие у меня текущие пороги VT1 и VT2 для велоспорта?"

• "Извлеки инсайты из моего последнего порогового теста — какова моя мощность на VT2 и достиг ли я VO2max?"

• "Экспортируй мою последнюю активность в файл FIT"

• "Сравни мои целевые показатели VE для бега и велоспорта"

• "Покажи мой текущий план тренировок и рекомендации по тренировке"

• "Проверь, есть ли у моей последней поездки strap-файлы, логи или результаты определения workout-zone"

• "Перечисли мои подключенные интеграции и статус подписки"

Безопасность

• Учетные данные хранятся в системной связке ключей (предпочтительно) или в зашифрованном файле AES-256-GCM с выводом ключа PBKDF2 (600 000 итераций, машинно-специфичная соль)

• Токены и учетные данные никогда не возвращаются в результатах инструментов MCP (очищаются перед передачей Claude)

• Для CI/контейнеров доступна аутентификация через переменные окружения: TYMEWEAR_EMAIL + TYMEWEAR_PASSWORD

• Права доступа к файлам с зашифрованными учетными данными установлены в 600 (только чтение/запись владельца)

• Публичный режим требует аутентификации через bearer или OAuth и является однопользовательским: вышестоящая аутентификация Tyme Wear использует серверные переменные окружения TYMEWEAR_EMAIL/TYMEWEAR_PASSWORD (никогда не локальную связку ключей или зашифрованный файл, которые доступны только для чтения в serverless), каждый результат скрывает приватные данные, а инструменты экспорта сырых/файловых данных отключены

Архитектура

tymewear-mcp/
├── src/tymewear_mcp/
│   ├── cli.py              # CLI entry point
│   ├── server.py           # MCP server + 40 tool registrations
│   ├── public.py           # Public Streamable HTTP server + bearer/OAuth auth
│   ├── auth/               # Credential storage (keyring → encrypted → env) + OIDC verifier (oidc.py)
│   ├── client/             # Async HTTP client + Pydantic models
│   └── tools/              # Tool implementations (incl. threshold_analysis.py, _slimming.py)
└── tests/                  # 340 tests

Технологический стек: Python 3.10+, MCP SDK, httpx, Pydantic, keyring, cryptography, PyJWT

Разработка

pip install -e ".[dev]"
pytest tests/ -v          # Run tests
ruff check src tests      # Lint
mypy src/                 # Type check

Лицензия

MIT