Servidor MCP BikeScout

BikeScout es un servidor MCP especializado diseñado para ciclistas y ciclistas de montaña. Proporciona recomendaciones inteligentes de rutas combinando datos de mapas del mundo real con un análisis de rutas avanzado.

Características principales

• Descubrimiento de rutas reales: Obtiene nombres de senderos reales y tipos de superficie de OpenStreetMap (a través de la API de Overpass).

• Métricas técnicas: Calcula la distancia precisa en kilómetros y el desnivel positivo total (ascenso).

• Clasificación de dificultad y técnica: Evalúa las rutas como Principiante, Moderada o Experta y analiza los OSM Tracktypes (Grado 1-5) para distinguir entre grava lisa y caminos de MTB accidentados.

• Análisis dinámico de rutas y superficies: Genera bucles sugeridos (viajes de ida y vuelta) con un desglose porcentual detallado de los tipos de superficie (asfalto, grava, tierra, etc.).

• Compatibilidad con la configuración de la bicicleta: Una característica pionera que comprueba si una ruta es adecuada para tu bicicleta específica (Carretera, Grava o MTB) y el ancho de neumático, proporcionando advertencias de seguridad instantáneas.

• Análisis predictivo de riesgo de barro: Un modelo especializado para ciclistas todoterreno que cruza las precipitaciones históricas de 72 horas con la geología del suelo (p. ej., arcilla frente a arena) para predecir la transitabilidad de la ruta.

• Búsqueda inteligente de PDI (Buscador de paradas): Localiza automáticamente servicios específicos para ciclistas como fuentes de agua potable, estaciones de reparación de bicicletas y refugios de montaña en un radio de 2 km de tu ruta.

• Seguridad inteligente y pronóstico del tiempo: Cruza los datos de ubicación con el clima en tiempo real para garantizar que no te atrape una tormenta.

• Consejos de equipamiento profesional: Proporciona consejos técnicos específicos sobre ropa y equipo basados en los umbrales de temperatura, viento y lluvia.

• Búsqueda de ubicación fluida: No se requieren coordenadas GPS. Usa lenguaje natural (p. ej., "Encuentra una ruta en Albano Laziale") a través de la geocodificación integrada de Nominatim.

• Vistas previas de mapas instantáneas: Genera automáticamente un mapa estático (.png) de la ruta para visualizar el sendero directamente dentro de la interfaz de chat.

• Conocimiento experto local: Prompts regionales especializados para destinos de clase mundial como los Dolomitas (UNESCO), Moab (EE. UU.) y Castelli Romani.

• Categorización de ascensos profesionales: Identifica y nombra automáticamente ascensos específicos (desde Categoría 4 hasta Hors Catégorie) utilizando estándares de ciclismo profesional basados en la longitud y la pendiente media.

¿Por qué BikeScout? (frente a mapas genéricos)

Aunque Google Maps o las herramientas de navegación estándar son excelentes para los desplazamientos urbanos, fallan cuando el terreno se vuelve técnico. BikeScout cierra la brecha entre una simple "línea en un mapa" y la realidad técnica del ciclismo profesional, convirtiendo a tu IA en un guía local experto.

Verdad en la elevación (filtrado progresivo)

Los datos satelitales sin procesar (SRTM) a menudo sufren de "ruido", sobreestimando el desnivel vertical total hasta en un 40% en áreas montañosas debido a picos repentinos en las lecturas.

• Mapas genéricos: Muestran perfiles de elevación "irregulares" que inflan el esfuerzo y hacen que los gráficos sean ilegibles.

• BikeScout: Utiliza un Filtro de Elevación Progresivo. Nuestro algoritmo reconoce y suaviza los errores de los sensores satelitales, devolviendo un valor de ascenso total que coincide con los sensores barométricos del mundo real (Garmin/Wahoo).

Más allá de "pavimentado" frente a "no pavimentado" (clasificación S-Scale)

Para un navegador estándar, un sendero es solo un sendero. Para un ciclista, la diferencia entre grava compactada y un lecho de rocas sueltas es la diferencia entre la diversión y el peligro.

• Mapas genéricos: Etiquetan indiscriminadamente todo lo que no es asfalto como "no pavimentado".

• BikeScout: Analiza los metadatos profundos de OpenStreetMap para extraer la MTB-Scale (S0-S5) y la SAC-Scale. Te advierte si encontrarás un Grado S0 (fácil) o un S3 (técnico con rocas y escalones), permitiéndote decidir si tu configuración es apropiada.

Más allá de los PDI tradicionales

Los mapas genéricos a menudo priorizan resultados patrocinados o restaurantes. BikeScout sondea etiquetas profundas de OpenStreetMap como amenity=drinking_water y shop=bicycle. Estos puntos a menudo son verificados por la comunidad ciclista, asegurando que encuentres una fuente que funcione en un paso de montaña en lugar de un supermercado cerrado.

Datos meteorológicos históricos

Los pronósticos estándar solo te dicen si lloverá. BikeScout analiza lo que ya ha sucedido. Dado que el suelo rico en arcilla puede permanecer intransitable durante días después de una tormenta mientras que el suelo arenoso se seca en horas, esta herramienta proporciona el contexto específico necesario para la toma de decisiones todoterreno.

Inteligencia específica de la disciplina

El esfuerzo es relativo a tu equipo. 500 m de ascenso se sienten diferentes en una bicicleta de carretera de 7 kg que en una bicicleta de enduro de 16 kg con neumáticos de tacos de 2.4".

• Mapas genéricos: Proporcionan tiempos de viaje y dificultad "estándar" basados en promedios genéricos.

• BikeScout: Cuenta con un Motor de Esfuerzo Dinámico. Calcula la dificultad y la categorización de ascensos (desde Cat 4 hasta Hors Catégorie) basándose específicamente en tu Tipo de Bicicleta (Carretera, Grava, MTB, Enduro) y tu Configuración de Neumáticos.

Orquestación de IA nativa (MCP)

BikeScout no es solo un script aislado; es una extensión nativa para modelos de lenguaje grandes de próxima generación.

• Mapas genéricos: Requieren búsquedas manuales, capturas de pantalla e interpretación visual por parte del usuario.

• BikeScout: Es un servidor de Model Context Protocol (MCP). Permite que Claude, Cursor u otros LLM "razonen" como un guía local, cruzando automáticamente el clima, el tipo de suelo y la configuración técnica en un solo flujo conversacional.

Comparación de un vistazo

Noticias, blog y demostración en vivo

Mantente actualizado con la última inteligencia táctica de ciclismo, informes de misión y noticias del ecosistema MCP.

• Sitio web oficial: https://hifly81.github.io/bikescout

• Blog táctico: https://hifly81.github.io/bikescout/site/blog.html

Requisitos previos

• Python 3.10+

• Clave de API de OpenRouteService: Obtén una clave gratuita en openrouteservice.org.

• Cliente MCP: Como Claude Desktop.

Instalación

BikeScout está disponible en PyPI. Puedes instalarlo directamente usando pip o uv.

Recomendamos instalar BikeScout en un entorno virtual:

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

Configura tu clave de API de OpenRouteService:

export ORS_API_KEY=YOUR_OPENROUTE_SERVICE_API_KEY

Configuración para Claude Desktop

• Clona el repositorio en una carpeta local:

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

• Crea un entorno virtual de Python desde la carpeta local:

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

Agrega el servidor a tu claude_desktop_config.json:

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

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

Debes reemplazar los marcadores de posición en la configuración JSON con tus rutas absolutas locales al archivo de script de Python. PATH/TO/YOUR/BIKESCOUT_FOLDER/src/bikescout/mcp_server.py

Ejemplo:

• 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"
      }
    }
  }
}

Uso de BikeScout con VS Code

Si tu objetivo es probar el servidor BikeScout mientras programas, no necesitas la aplicación Claude Desktop. Puedes usar VS Code junto con las extensiones Cline (anteriormente Claude Dev) o Continue.

• Instala la extensión:

  Ve al Marketplace de VS Code e instala la extensión Cline (o Continue). Estas extensiones actúan como un "puente" entre la IA y tu máquina local.

• Clona el repositorio en una carpeta local:

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

• Crea un entorno virtual de Python desde la carpeta local:

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

• Abre la configuración de MCP:

  En la configuración de la extensión (generalmente un icono de engranaje o una pestaña específica "MCP" dentro del panel lateral de la extensión), busca la sección titulada "Configure MCP Servers".

• Agrega la configuración JSON:

  Pega la siguiente configuración JSON en el archivo de configuración (asegúrate de actualizar la ruta a tu directorio real):

{
   "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"
         }
      }
   }
}

• Comienza a explorar Una vez guardado, puedes chatear con la IA directamente dentro de VS Code. Detectará automáticamente a BikeScout como una "herramienta". Luego puedes preguntar: "Encuéntrame una ruta de MTB escénica de 30 km comenzando desde mis coordenadas actuales". La IA ejecutará el script de Python, obtendrá los datos de OpenStreetMap y OpenRouteService, y presentará los resultados directamente en tu ventana de chat.

Depuración y pruebas

Puedes probar BikeScout usando el Inspector MCP, una herramienta basada en web para probar servidores MCP.

Uso del inspector

Para iniciar el inspector e interactuar con las herramientas manualmente, ejecuta el siguiente comando desde el directorio raíz:

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

Qué verificar:

• Listar herramientas: Asegúrate de que todas las herramientas (geocode_location, trail_scout, etc.) sean visibles.

• Ejecutar herramienta: Prueba la herramienta geocode_location pasando un nombre de ciudad (p. ej., "Roma") para verificar la integración de Nominatim.

Consultas de ejemplo

Puedes hacerle a BikeScout solicitudes complejas de varios pasos. Combina datos en tiempo real con inteligencia técnica de ciclismo para proporcionar respuestas de nivel experto.

Planificación avanzada (Multi-herramienta)

• "Estoy en Monte Cavo con mi bicicleta de grava (neumáticos de 40 mm). Planifica un bucle de 25 km para mí. Comprueba si el terreno es compatible con mi bicicleta, verifica la probabilidad de lluvia por la tarde y sugiere una 'Fraschetta' para el final. Usa la guía de Castelli Romani."

• "Quiero montar en Moab mañana. Tengo una MTB rígida. Encuéntrame una ruta de 20 km que no sea demasiado técnica (evita pistas de Grado 4/5), verifica el pronóstico de calor y dame la lista de verificación de seguridad del desierto."

Inteligencia de configuración de bicicleta y superficie

• "Comprueba esta ruta [LAT, LON] para un bucle de 15 km. Estoy en una bicicleta de carretera con neumáticos de 25 mm. ¿Es compatible? Dame el porcentaje exacto de grava frente a asfalto."

• "Estoy planeando un viaje en Kioto, Japón. Encuentra un bucle de 30 km que sea al menos 70% grava, pero solo si la probabilidad de lluvia es inferior al 10% durante las próximas 4 horas."

Experiencia local

• "Usa la guía local de Dolomiti para planificar una ruta de ciclismo de carretera comenzando desde Cortina. Necesito al menos 800 m de desnivel positivo. Además, recomienda la presión de neumáticos correcta para descensos a gran altitud y un refugio de montaña para una parada de strudel."

• "¿Hay senderos con nombre cerca de Vancouver, Canadá? Analiza los tipos de superficie y dime si son adecuados para un principiante en una E-MTB."

Verificaciones técnicas rápidas

• "Dame la lista de verificación de seguridad y calcula la presión de los neumáticos para un ciclista de 90 kg con neumáticos sin cámara de 2.3" para un viaje con barro."

• "¿Cuál es el desglose del terreno para un viaje de 10 km en Taichung? Necesito saber si encontraré algún segmento técnico de 'Grado 5'."

Respuestas de ejemplo

A continuación se muestra un ejemplo de la información detallada que BikeScout puede proporcionar:

Encontré un bucle de MTB cerca de Frascati, Italia. Aquí están los detalles:

📊 Detalles de la ruta

• 📍 Distancia: 11.26 km

• ⛰️ Ascenso total: 856 metros

• 🏷️ Dificultad: Experto (Distancia desafiante o ascensos muy empinados)

• 🛤️ Senderos incluidos: Viale Moderno, Via dei Sepolcri

• 🔗 Mapa: Ver en Google Maps

• 🔗 Imagen del mapa de ruta: mtb_route_map.png

Características clave de la ruta

• Terreno técnico: Senderos de bicicleta de montaña con secciones técnicas

• Perfil de elevación: Descenso significativo desde Rocca di Papa (703 m) hasta Albano Laziale (542 m)

• Superficies de sendero: Mezcla de grava, tierra y caminos forestales

• Paisaje: Hermosas vistas de las colinas de Alban y la campiña romana

Lista de verificación de equipo

• **Bic