RunCoach

Работает: runcoach-ruby.vercel.app · MCP-конечная точка https://runcoach-ruby.vercel.app/mcp

MCP-сервер, который предоставляет собственные тренировочные данные бегуна — вычисленную тренировочную нагрузку, прогнозы времени забега, сгенерированные планы — в виде инструментов, которые может вызывать LLM.

Смысл в обоснованности. Спросите любого ассистента «стоит ли мне сбавить нагрузку на этой неделе», и он выдаст правдоподобный совет тренера из ничего. RunCoach заставляет тот же вопрос разрешаться на основе реальных записанных активностей спортсмена, а ответ содержит конкретные забеги, из которых он получен:

Вы: Как у меня идут тренировки, и какой результат я мог бы показать на полумарафоне?

Клод (вызывает analyze_training_status, затем predict_race_time): Тренировки последовательны, нагрузка стабильна — 46,8 км/нед за 17 забегов за последние 28 дней, с соотношением острой и хронической нагрузки 1,00 и без перерыва дольше трех дней. Фитнес поддерживается, а не наращивается, что правильно между целями, и стоит изменить, если у вас предстоит гонка.

Для полумарафона: 1:38:49, наиболее вероятно между 1:36:50 и 1:40:48. Это подогнано под вашу собственную кривую дистанция/время по вашим 5 км (21:30, 8 июля), 10 км (44:50, 3 июня) и полумарафону (1:38:48, 29 апреля) — ваш показатель утомления составил 1,059 против среднего по популяции 1,06, так что вы держите темп примерно так же хорошо, как типичный бегун, с ростом дистанции. Одна активность была исключена: 3 км 28 июля, записанная с темпом быстрее мирового рекорда для этой дистанции, почти наверняка ошибка GPS.

Каждая цифра выше — это реальный вывод фиктивного спортсмена из npm test, а не иллюстрация — точные строки находятся в test/readme.test.ts, который падает, если наука меняется, а README не обновляется. Каждый инструмент возвращает уверенность и объяснение того, как было получено его число, а инструкции сервера говорят модели передавать и то, и другое. Прогноз, заявленный без его основы, неотличим от догадки.

Инструменты

Related MCP server: livetrack-mcp

Откуда берутся числа

RunCoach ничего не перереализует. Все вычисления выполняет @runman/core — проверенный на фикстурах научный пакет, который также поддерживает веб-приложение Runman. Задать вопрос Клоду и загрузить соответствующую страницу — это выполнить один и тот же код на одной и той же базе данных.

Этот пакет включен сюда как git-подмодуль, и тесты RunCoach импортируют тот же файл фикстур, который используют тесты Runman — так что «что должны давать эти данные» имеет одно определение в обоих репозиториях, а не два, которые расходятся.

git clone --recursive https://github.com/varun-gangadharan/runcoach
npm install
npm test          # 31 tests, no database or credentials required

Проектные решения, которые стоит объяснить

Инструменты не принимают идентификатор спортсмена. API-ключ разрешается ровно в одного спортсмена, и этот идентификатор становится контекстом инструмента. Если бы модель могла передать идентификатор спортсмена, то инструкция, внедренная в название активности, могла бы попросить её об этом — а полезная нагрузка здесь — чьи-то личные данные о здоровье. Просто нет аргумента, по которому ключ одного спортсмена может читать данные другого. Тест проверяет, что это остается верным.

Отказ — это допустимый ответ. Когда нет данных для поддержки прогноза, инструмент сообщает об этом и инструктирует модель не подставлять оценку. То же самое для генерации плана: если у спортсмена нет недавних тренировок или гонка через три недели, он отказывает с причиной, а не выдает план, построенный на угаданной базе. Модели по умолчанию заполняют пробелы; вывод инструмента должен активно этому противодействовать.

Вывод — это проза, а не JSON. Модели перефразируют предложения более точно, чем читают вложенные объекты, и гораздо реже выдумывают поле, которого не было. Точные цифры все равно появляются — внутри предложений.

Каждый HTTP-запрос создает свой собственный экземпляр сервера. Совместное использование одного экземпляра между вызовами в бессерверной среде рискует перемешать сеансы двух спортсменов внутри теплого контейнера. Это неприемлемый режим отказа здесь.

Развертывание

HTTP-транспорт — это одна функция Vercel. Аутентификация — это bearer-токен — API-ключ, который спортсмен выпускает со страницы профиля Runman, хранящийся только в виде хеша SHA-256.

vercel env add SUPABASE_URL
vercel env add SUPABASE_SERVICE_ROLE_KEY
vercel deploy --prod

Обратите внимание, что точка входа Vercel (api/mcp.js) — это простой JavaScript, реэкспортирующий скомпилированный обработчик из dist/, а не TypeScript, импортирующий src/. Vercel компилирует функцию .ts на месте, но оставляет относительные спецификаторы импорта нетронутыми, поэтому спецификатор .ts сохраняется в развернутом пакете и терпит неудачу во время выполнения, ища файл, который никогда не был отправлен.

После развертывания проверьте его от начала до конца с помощью реального MCP-клиента:

node --experimental-strip-types scripts/verify-deployment.ts \
  https://runcoach-ruby.vercel.app/mcp rc_live_...

Это подключается по сети точно так же, как это сделал бы Клод — рукопожатие, обнаружение инструментов, затем вызов каждого из пяти инструментов — и проверяет, что ответы возвращаются обоснованными, а не просто хорошо сформированными.

Затем добавьте его в любом MCP-клиенте:

{
  "mcpServers": {
    "runcoach": {
      "type": "http",
      "url": "https://runcoach-ruby.vercel.app/mcp",
      "headers": { "Authorization": "Bearer rc_live_..." }
    }
  }
}

Локальный запуск через stdio

Для использования с вашими собственными данными на вашей собственной машине:

{
  "mcpServers": {
    "runcoach": {
      "command": "node",
      "args": ["/absolute/path/to/runcoach/dist/stdio.js"],
      "env": {
        "SUPABASE_URL": "...",
        "SUPABASE_SERVICE_ROLE_KEY": "...",
        "RUNCOACH_API_KEY": "rc_live_..."
      }
    }
  }
}

Сервер stdio не имеет запросов для аутентификации — он работает как дочерний процесс клиента — поэтому спортсмен фиксируется при запуске. Это уместно только на собственной машине спортсмена, поэтому развернутый транспорт делает это по запросу.

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

npm test

31 тест в трех слоях: обработчики инструментов против общего набора фикстур Runman (постоянный бегун, бегун без ЧСС, одна активность, пустая история, история с GPS-сбоем, спорадический бегун, возвращающийся бегун, скачок объема), и сквозной протокольный тест, который подключает реального MCP-клиента к реальному серверу и проводит его через обнаружение инструментов, проверку схемы и вызов. Третий слой фиксирует примерные цифры, приведенные в этом README.

Не в v1

Инструменты на основе Garmin (восстановление, сон, HRV) через проксирование в вышестоящий Garmin MCP-сервер, доступные только после того, как спортсмен связал учетную запись. Намеренно отделяемы, так что спортсмен без Garmin не видит ухудшения.

Лицензия

MIT.