MCP-сервер BikeScout

BikeScout — это специализированный MCP-сервер, разработанный для велосипедистов и любителей горного велосипеда. Он предоставляет интеллектуальные рекомендации по маршрутам, объединяя реальные картографические данные с расширенным анализом маршрутизации.

Основные возможности

• Поиск реальных маршрутов: Получает названия троп и типы покрытия из OpenStreetMap (через Overpass API).

• Технические метрики: Рассчитывает точное расстояние в километрах и общий набор высоты.

• Оценка сложности и технического уровня: Классифицирует маршруты как «Новичок», «Средний» или «Эксперт» и анализирует OSM Tracktypes (уровни 1-5), чтобы различать гладкий гравий и пересеченную местность для MTB.

• Динамическая маршрутизация и анализ покрытия: Генерирует предлагаемые петли (круговые маршруты) с подробной процентной разбивкой типов покрытия (асфальт, гравий, грунт и т. д.).

• Совместимость с типом велосипеда: Уникальная функция, которая проверяет, подходит ли маршрут для вашего конкретного велосипеда (шоссейный, гравийный или MTB) и ширины покрышек, предоставляя мгновенные предупреждения о безопасности.

• Прогноз риска грязи: Специализированная модель для внедорожного катания, которая сопоставляет исторические данные об осадках за 72 часа с типом почвы (например, глина против песка) для прогнозирования проходимости маршрута.

• Умный поиск POI (поиск остановок): Автоматически находит объекты инфраструктуры, такие как питьевые фонтанчики, станции ремонта велосипедов и горные приюты в радиусе 2 км от вашего маршрута.

• Безопасность и прогноз погоды: Сопоставляет данные о местоположении с прогнозом погоды в реальном времени, чтобы вы не попали в шторм.

• Советы по экипировке: Предоставляет технические рекомендации по одежде и снаряжению на основе температуры, ветра и уровня осадков.

• Удобный поиск локаций: GPS-координаты не требуются. Используйте естественный язык (например, "Найди маршрут в Альбано-Лациале") через встроенное геокодирование Nominatim.

• Мгновенные превью карт: Автоматически генерирует статичную карту (.png) маршрута для визуализации прямо в чате.

• Локальные экспертные знания: Специализированные региональные промпты для таких направлений, как Доломиты (ЮНЕСКО), Моаб (США) и Кастелли-Романи.

• Классификация подъемов: Автоматически определяет и называет конкретные подъемы (от 4-й категории до Hors Catégorie) по профессиональным стандартам на основе длины и среднего градиента.

Почему BikeScout? (в сравнении с обычными картами)

Хотя Google Maps или стандартные навигаторы отлично подходят для поездок по городу, они пасуют, когда местность становится технически сложной. BikeScout заполняет разрыв между простой «линией на карте» и технической реальностью профессионального велоспорта, превращая ваш ИИ в экспертного местного гида.

Точность высоты (прогрессивная фильтрация)

Сырые спутниковые данные (SRTM) часто содержат «шум», завышая общий набор высоты до 40% в горных районах из-за резких скачков в показаниях.

• Обычные карты: Отображают «зубчатые» профили высот, которые завышают сложность и делают графики нечитаемыми.

• BikeScout: Использует прогрессивный фильтр высот. Наш алгоритм распознает и сглаживает ошибки спутниковых датчиков, возвращая значение набора высоты, соответствующее реальным барометрическим датчикам (Garmin/Wahoo).

Больше, чем «асфальт» против «грунта» (S-шкала)

Для обычного навигатора тропа — это просто тропа. Для велосипедиста разница между укатанным гравием и россыпью камней — это разница между удовольствием и опасностью.

• Обычные карты: Без разбора помечают всё, что не является асфальтом, как «грунтовку».

• BikeScout: Анализирует метаданные OpenStreetMap для извлечения MTB-шкалы (S0-S5) и SAC-шкалы. Он предупредит вас, если вы столкнетесь с уровнем S0 (легко) или S3 (технически сложно, с камнями и ступенями), позволяя решить, подходит ли ваш велосипед.

Больше, чем традиционные POI

Обычные карты часто отдают приоритет спонсорским результатам или ресторанам. BikeScout глубоко сканирует теги OpenStreetMap, такие как amenity=drinking_water и shop=bicycle. Эти точки часто проверены вело-сообществом, что гарантирует, что вы найдете работающий фонтанчик на горном перевале, а не закрытый супермаркет.

Исторические данные о погоде

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

Интеллект, специфичный для дисциплины

Усилие относительно вашего снаряжения. 500 метров набора высоты ощущаются иначе на 7-килограммовом шоссейнике, чем на 16-килограммовом эндуро-байке с 2.4-дюймовыми покрышками.

• Обычные карты: Предоставляют «стандартное» время в пути и сложность на основе общих средних значений.

• BikeScout: Оснащен движком динамических усилий. Он рассчитывает сложность и категорию подъема (от 4-й до Hors Catégorie) на основе вашего типа велосипеда (шоссе, гравий, MTB, эндуро) и настроек покрышек.

Нативная ИИ-оркестрация (MCP)

BikeScout — это не просто изолированный скрипт; это нативное расширение для больших языковых моделей нового поколения.

• Обычные карты: Требуют ручного поиска, скриншотов и визуальной интерпретации пользователем.

• BikeScout: Является сервером Model Context Protocol (MCP). Он позволяет Claude, Cursor или другим LLM «рассуждать» как местный гид, автоматически сопоставляя погоду, тип почвы и технические характеристики в едином диалоговом потоке.

Сравнение

Новости, блог и демо

Будьте в курсе последних тактических данных, отчетов и новостей экосистемы MCP.

• Официальный сайт: https://hifly81.github.io/bikescout

• Тактический блог: https://hifly81.github.io/bikescout/site/blog.html

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

• Python 3.10+

• API-ключ OpenRouteService: Получите бесплатный ключ на openrouteservice.org.

• MCP-клиент: Например, Claude Desktop.

Установка

BikeScout доступен на PyPI. Вы можете установить его напрямую через pip или uv.

Рекомендуем устанавливать BikeScout в виртуальном окружении:

python -m venv venv
source venv/bin/activate 
pip install bikescout

Настройте ваш API-ключ OpenRouteService:

export ORS_API_KEY=YOUR_OPENROUTE_SERVICE_API_KEY

Настройка для Claude Desktop

• Клонируйте репозиторий в локальную папку:

  git clone git@github.com:hifly81/bikescout.git <your_local_folder_path>

• Создайте виртуальное окружение Python из локальной папки:

  python3 -m venv venv
  source venv/bin/activate
  pip install bikescout

Добавьте сервер в ваш claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Вы должны заменить плейсхолдеры в JSON-конфигурации на ваши локальные абсолютные пути к файлу Python-скрипта. PATH/TO/YOUR/BIKESCOUT_FOLDER/src/bikescout/mcp_server.py

Пример:

• Linux/macOS: /home/username/bikescout/src/bikescout/mcp_server.py

• Windows: C:/Users/Username/Documents/bikescout/src/bikescout/mcp_server.py

{
  "mcpServers": {
    "bikescout": {
      "command": "PATH/TO/YOUR/BIKESCOUT_FOLDER/venv/bin/python3",
       "args": [
          "-u",
          "-m",
          "bikescout.mcp_server"
       ],
      "env": {
        "PYTHONPATH": "PATH/TO/YOUR/BIKESCOUT_FOLDER/src", 
        "ORS_API_KEY": "YOUR_OPENROUTE_SERVICE_API_KEY"
      }
    }
  }
}

Использование BikeScout с VS Code

Если ваша цель — протестировать сервер BikeScout во время разработки, вам не обязательно использовать приложение Claude Desktop. Вы можете использовать VS Code вместе с расширениями Cline (ранее Claude Dev) или Continue.

• Установите расширение:

  Перейдите в Marketplace VS Code и установите расширение Cline (или Continue). Эти расширения действуют как «мост» между ИИ и вашей локальной машиной.

• Клонируйте репозиторий в локальную папку:

git clone git@github.com:hifly81/bikescout.git <your_local_folder_path>

• Создайте виртуальное окружение Python из локальной папки:

  python3 -m venv venv
  source venv/bin/activate
  pip install bikescout

• Откройте настройки MCP:

  В настройках расширения (обычно иконка шестеренки или вкладка "MCP" на боковой панели) найдите раздел "Configure MCP Servers".

• Добавьте JSON-конфигурацию:

  Вставьте следующую JSON-конфигурацию в файл настроек (не забудьте обновить путь к вашей директории):

{
   "mcpServers": {
      "bikescout": {
         "command": "PATH/TO/YOUR/BIKESCOUT_FOLDER/venv/bin/python3",
         "args": [
            "-u",
            "-m",
            "bikescout.mcp_server"
         ],
         "env": {
            "PYTHONPATH": "PATH/TO/YOUR/BIKESCOUT_FOLDER/src",
            "ORS_API_KEY": "YOUR_OPENROUTE_SERVICE_API_KEY"
         }
      }
   }
}

• Начните разведку После сохранения вы можете общаться с ИИ прямо в VS Code. Он автоматически обнаружит BikeScout как "инструмент". Вы можете спросить: "Найди мне живописный 30-километровый MTB-маршрут, начинающийся от моих текущих координат." ИИ выполнит скрипт, получит данные из OpenStreetMap и OpenRouteService и представит результаты прямо в окне чата.

Отладка и тестирование

Вы можете протестировать BikeScout, используя MCP Inspector, веб-инструмент для тестирования MCP-серверов.

Использование Inspector

Чтобы запустить инспектор и взаимодействовать с инструментами вручную, выполните следующую команду из корневой директории:

export ORS_API_KEY=YOUR_OPENROUTE_SERVICE_API_KEY
PYTHONPATH=./src npx @modelcontextprotocol/inspector ./venv/bin/python3 -m bikescout.mcp_server

Что проверить:

• List Tools: Убедитесь, что все инструменты (geocode_location, trail_scout и т.д.) видны.

• Run Tool: Протестируйте инструмент geocode_location, передав название города (например, "Rome"), чтобы проверить интеграцию с Nominatim.

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

Вы можете задавать BikeScout сложные многошаговые запросы. Он объединяет данные в реальном времени с техническими знаниями о велоспорте для предоставления экспертных ответов.

Продвинутое планирование (Multi-Tool)

• "Я на Монте-Каво на своем гравийном велосипеде (покрышки 40 мм). Спланируй для меня 25-километровую петлю. Проверь, совместима ли местность с моим велосипедом, проверь вероятность дождя днем и предложи 'Fraschetta' для финиша. Используй гид по Кастелли-Романи."

• "Я хочу покататься в Моабе завтра. У меня хардтейл MTB. Найди мне 20-километровый маршрут, который не слишком техничен (избегай трасс 4/5 уровня), проверь прогноз жары и дай мне чек-лист безопасности для пустыни."

Настройка велосипеда и анализ покрытия

• "Проверь этот маршрут [LAT, LON] на 15-километровую петлю. Я на шоссейном велосипеде с покрышками 25 мм. Совместим ли он? Дай мне точный процент гравия против асфальта."

• "Я планирую поездку в Киото, Япония. Найди 30-километровую петлю, которая состоит как минимум на 70% из гравия, но только если вероятность дождя ниже 10% на ближайшие 4 часа."

Локальная экспертиза

• "Используй локальный гид по Доломитам, чтобы спланировать шоссейный маршрут, начинающийся из Кортины. Мне нужно как минимум 800 м набора высоты. Также порекомендуй правильное давление в шинах для спусков с большой высоты и горную хижину для остановки на штрудель."

• "Есть ли именованные тропы рядом с Ванкувером, Канада? Проанализируй типы покрытия и скажи, подходят ли они для новичка на E-MTB."

Быстрые технические проверки

• "Дай мне чек-лист безопасности и рассчитай давление в шинах для 90-килограммового гонщика на 2.3-дюймовых бескамерных покрышках для поездки по грязи."

• "Какова разбивка местности для 10-километровой поездки в Тайчжуне? Мне нужно знать, встречу ли я какие-либо технические сегменты '5-го уровня'."

Примеры ответов

Ниже приведен пример подробной информации, которую может предоставить BikeScout:

Я нашел MTB-петлю рядом с Фраскати, Италия. Вот детали:

📊 Детали маршрута

• 📍 Расстояние: 1