BikeScout MCP-Server

BikeScout ist ein spezialisierter MCP-Server, der für Radfahrer und Mountainbiker entwickelt wurde. Er bietet intelligente Routenempfehlungen durch die Kombination von realen Kartendaten mit fortschrittlicher Routenanalyse.

Hauptfunktionen

• Echte Trail-Entdeckung: Ruft tatsächliche Trail-Namen und Oberflächenbeschaffenheiten von OpenStreetMap ab (via Overpass API).

• Technische Metriken: Berechnet präzise Distanzen in Kilometern und den gesamten Höhenunterschied (Anstieg).

• Schwierigkeits- & technische Bewertung: Bewertet Trails als Anfänger, Mittel oder Experte und analysiert OSM Tracktypes (Grad 1-5), um zwischen glattem Schotter und rauen MTB-Pfaden zu unterscheiden.

• Dynamisches Routing & Oberflächenanalyse: Erstellt Routenvorschläge (Rundkurse) mit einer detaillierten prozentualen Aufschlüsselung der Oberflächenarten (Asphalt, Schotter, Erde usw.).

• Kompatibilität mit dem Fahrrad-Setup: Eine branchenweit erste Funktion, die prüft, ob eine Route für Ihr spezifisches Fahrrad (Rennrad, Gravel oder MTB) und Ihre Reifenbreite geeignet ist, und sofortige Sicherheitswarnungen ausgibt.

• Prädiktive Schlammrisiko-Analyse: Ein spezialisiertes Modell für Offroader, das historische Niederschlagsdaten der letzten 72 Stunden mit der Bodenbeschaffenheit (z. B. Lehm vs. Sand) abgleicht, um die Befahrbarkeit von Trails vorherzusagen.

• Intelligente POI-Suche (Boxenstopp-Finder): Findet automatisch radspezifische Annehmlichkeiten wie Trinkwasserbrunnen, Fahrradreparaturstationen und Berghütten in einem Umkreis von 2 km um Ihre Route.

• Intelligente Sicherheit & Wettervorhersage: Gleicht Standortdaten mit Echtzeit-Wetterdaten ab, damit Sie nicht in einen Sturm geraten.

• Profi-Ausrüstungsberatung: Bietet spezifische technische Ratschläge zu Kleidung und Ausrüstung basierend auf Temperatur-, Wind- und Regenschwellenwerten.

• Nahtlose Standortsuche: Keine GPS-Koordinaten erforderlich. Verwenden Sie natürliche Sprache (z. B. "Finde eine Tour in Albano Laziale") über integriertes Nominatim-Geocoding.

• Sofortige Kartenvorschau: Erstellt automatisch eine statische Karte (.png) der Route, um den Trail direkt in der Chat-Oberfläche zu visualisieren.

• Lokales Expertenwissen: Spezialisierte regionale Prompts für Weltklasse-Destinationen wie die Dolomiten (UNESCO), Moab (USA) und Castelli Romani.

• Profi-Anstiegs-Kategorisierung: Identifiziert und benennt automatisch spezifische Anstiege (von Kategorie 4 bis Hors Catégorie) unter Verwendung professioneller Radsportstandards basierend auf Länge und durchschnittlicher Steigung.

Warum BikeScout? (im Vergleich zu allgemeinen Karten)

Während Google Maps oder Standard-Navigationswerkzeuge hervorragend für das Pendeln in der Stadt geeignet sind, versagen sie, wenn das Gelände technisch wird. BikeScout schließt die Lücke zwischen einer einfachen "Linie auf einer Karte" und der technischen Realität des professionellen Radsports und macht Ihre KI zu einem fachkundigen lokalen Guide.

Wahrheit bei der Höhe (Progressive Filterung)

Rohe Satellitendaten (SRTM) leiden oft unter "Rauschen" und überschätzen den gesamten vertikalen Anstieg in bergigen Gebieten um bis zu 40 % aufgrund plötzlicher Messwertspitzen.

• Allgemeine Karten: Zeigen "zackige" Höhenprofile, die den Aufwand übertreiben und Diagramme unleserlich machen.

• BikeScout: Verwendet einen progressiven Höhenfilter. Unser Algorithmus erkennt und glättet Satellitensensorfehler und liefert einen Gesamtanstiegswert, der mit realen barometrischen Sensoren (Garmin/Wahoo) übereinstimmt.

Jenseits von "befestigt" vs. "unbefestigt" (S-Skala-Bewertung)

Für einen Standard-Navigator ist ein Trail einfach ein Trail. Für einen Radfahrer ist der Unterschied zwischen festem Schotter und einem Bett aus losem Gestein der Unterschied zwischen Spaß und Gefahr.

• Allgemeine Karten: Kennzeichnen wahllos alles, was kein Asphalt ist, als "unbefestigt".

• BikeScout: Analysiert tiefgreifende OpenStreetMap-Metadaten, um die MTB-Skala (S0-S5) und SAC-Skala zu extrahieren. Es warnt Sie, wenn Sie auf einen Grad S0 (einfach) oder S3 (technisch mit Felsen und Stufen) stoßen, sodass Sie entscheiden können, ob Ihr Setup angemessen ist.

Jenseits traditioneller POIs

Allgemeine Karten priorisieren oft gesponserte Ergebnisse oder Restaurants. BikeScout durchsucht tiefgreifende OpenStreetMap-Tags wie amenity=drinking_water und shop=bicycle. Diese Punkte werden oft von der Radsport-Community verifiziert, um sicherzustellen, dass Sie auf einem Gebirgspass einen funktionierenden Brunnen finden und keinen geschlossenen Supermarkt.

Historische Wetterdaten

Standardvorhersagen sagen Ihnen nur, ob es regnen wird. BikeScout analysiert, was bereits passiert ist. Da lehmhaltiger Boden nach einem Sturm tagelang unbefahrbar bleiben kann, während sandiger Boden in Stunden trocknet, bietet dieses Tool den spezifischen Kontext, der für Offroad-Entscheidungen erforderlich ist.

Disziplinspezifische Intelligenz

Anstrengung ist relativ zu Ihrer Ausrüstung. 500 Höhenmeter fühlen sich auf einem 7 kg schweren Rennrad anders an als auf einem 16 kg schweren Enduro-Bike mit 2,4" Stollenreifen.

• Allgemeine Karten: Bieten "Standard"-Reisezeiten und Schwierigkeitsgrade basierend auf allgemeinen Durchschnittswerten.

• BikeScout: Verfügt über eine Dynamic Effort Engine. Sie berechnet Schwierigkeit und Anstiegskategorisierung (von Kat 4 bis Hors Catégorie) spezifisch basierend auf Ihrem Fahrradtyp (Rennrad, Gravel, MTB, Enduro) und Ihrem Reifen-Setup.

Native KI-Orchestrierung (MCP)

BikeScout ist nicht nur ein isoliertes Skript; es ist eine native Erweiterung für Large Language Models der nächsten Generation.

• Allgemeine Karten: Erfordern manuelle Suchen, Screenshots und visuelle Interpretation durch den Benutzer.

• BikeScout: Ist ein Model Context Protocol (MCP) Server. Er ermöglicht es Claude, Cursor oder anderen LLMs, wie ein lokaler Guide zu "denken" und Wetter, Bodenbeschaffenheit und technisches Setup automatisch in einem einzigen Gesprächsfluss abzugleichen.

Vergleich auf einen Blick

Neuigkeiten, Blog & Live-Demo

Bleiben Sie auf dem Laufenden mit der neuesten taktischen Radsport-Intelligenz, Missionsberichten und Neuigkeiten aus dem MCP-Ökosystem.

• Offizielle Website: https://hifly81.github.io/bikescout

• Taktischer Blog: https://hifly81.github.io/bikescout/site/blog.html

Voraussetzungen

• Python 3.10+

• OpenRouteService API-Schlüssel: Holen Sie sich einen kostenlosen Schlüssel unter openrouteservice.org.

• MCP-Client: Wie z. B. Claude Desktop.

Installation

BikeScout ist auf PyPI verfügbar. Sie können es direkt mit pip oder uv installieren.

Wir empfehlen, BikeScout in einer virtuellen Umgebung zu installieren:

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

Konfigurieren Sie Ihren OpenRouteService API-Schlüssel:

export ORS_API_KEY=YOUR_OPENROUTE_SERVICE_API_KEY

Konfiguration für Claude Desktop

• Klonen Sie das Repo in einen lokalen Ordner:

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

• Erstellen Sie eine Python Virtual Env aus dem lokalen Ordner:

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

Fügen Sie den Server zu Ihrer claude_desktop_config.json hinzu:

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

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

Sie müssen die Platzhalter in der JSON-Konfiguration durch Ihre lokalen absoluten Pfade zur Python-Skriptdatei ersetzen. PFAD/ZU/IHREM/BIKESCOUT_ORDNER/src/bikescout/mcp_server.py

Beispiel:

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

Verwendung von BikeScout mit VS Code

Wenn Ihr Ziel darin besteht, den BikeScout-Server während des Codierens zu testen, benötigen Sie die Claude Desktop-App nicht. Sie können VS Code zusammen mit den Erweiterungen Cline (ehemals Claude Dev) oder Continue verwenden.

• Installieren Sie die Erweiterung:

  Gehen Sie zum VS Code Marketplace und installieren Sie die Cline-Erweiterung (oder Continue). Diese Erweiterungen fungieren als "Brücke" zwischen der KI und Ihrem lokalen Computer.

• Klonen Sie das Repo in einen lokalen Ordner:

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

• Erstellen Sie eine Python Virtual Env aus dem lokalen Ordner:

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

• Öffnen Sie die MCP-Einstellungen:

  Suchen Sie in den Erweiterungseinstellungen (normalerweise ein Zahnradsymbol oder ein spezifischer "MCP"-Tab im Seitenpanel der Erweiterung) nach dem Abschnitt "Configure MCP Servers".

• Fügen Sie die JSON-Konfiguration hinzu:

  Fügen Sie die folgende JSON-Konfiguration in die Einstellungsdatei ein (stellen Sie sicher, dass Sie den Pfad zu Ihrem tatsächlichen Verzeichnis aktualisieren):

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

• Starten Sie das Scouting Sobald gespeichert, können Sie direkt in VS Code mit der KI chatten. Sie erkennt BikeScout automatisch als "Tool". Sie können dann fragen: "Finde mir eine landschaftlich reizvolle 30 km MTB-Route, die an meinen aktuellen Koordinaten startet." Die KI führt das Python-Skript aus, ruft die Daten von OpenStreetMap und OpenRouteService ab und präsentiert die Ergebnisse direkt in Ihrem Chat-Fenster.

Debugging und Testen

Sie können BikeScout mit dem MCP Inspector testen, einem webbasierten Tool zum Testen von MCP-Servern.

Verwendung des Inspectors

Um den Inspector zu starten und manuell mit den Tools zu interagieren, führen Sie den folgenden Befehl aus dem Stammverzeichnis aus:

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

Was zu prüfen ist:

• List Tools: Stellen Sie sicher, dass alle Tools (geocode_location, trail_scout usw.) sichtbar sind.

• Run Tool: Testen Sie das Tool geocode_location, indem Sie einen Stadtnamen (z. B. "Rom") übergeben, um die Nominatim-Integration zu verifizieren.

Beispielabfragen

Sie können BikeScout komplexe, mehrstufige Anfragen stellen. Es kombiniert Echtzeitdaten mit technischer Radsport-Intelligenz, um Antworten auf Expertenniveau zu liefern.

Erweiterte Planung (Multi-Tool)

• "Ich bin am Monte Cavo mit meinem Gravel-Bike (40mm Reifen). Plane eine 25 km Runde für mich. Prüfe, ob das Gelände mit meinem Fahrrad kompatibel ist, verifiziere die Regenwahrscheinlichkeit am Nachmittag und schlage eine 'Fraschetta' für das Ziel vor. Verwende den Castelli Romani Guide."

• "Ich möchte morgen in Moab fahren. Ich habe ein Hardtail MTB. Finde mir eine 20 km Route, die nicht zu technisch ist (vermeide Grad 4/5 Tracks), prüfe die Hitzeprognose und gib mir die Sicherheitscheckliste für die Wüste."

Fahrrad-Setup & Oberflächenintelligenz

• "Prüfe diese Route [LAT, LON] für eine 15 km Runde. Ich bin auf einem Rennrad mit 25mm Reifen. Ist sie kompatibel? Gib mir den genauen Prozentsatz von Schotter vs. Asphalt."

• "Ich plane eine Fahrt in Kyoto, Japan. Finde eine 30 km Runde, die zu mindestens 70% aus Schotter besteht, aber nur, wenn die Regenwahrscheinlichkeit für die nächsten 4 Stunden unter 10% liegt."

Lokale Expertise

• "Verwende den Dolomiti Local Guide, um eine Rennradroute ab Cortina zu planen. Ich benötige mindestens 800 Höhenmeter. Empfiehl außerdem den richtigen Reifendruck für Abfahrten in großer Höhe und eine Berghütte für einen Strudel-Stopp."

• "Gibt es benannte Trails in der Nähe von Vancouver, Kanada? Analysiere die Oberflächenarten und sag mir, ob sie für einen Anfänger auf einem E-MTB geeignet sind."

Schnelle Technik-Checks

• "Gib mir die Sicherheitscheckliste und berechne den Reifendruck für einen 90 kg Fahrer auf 2,3" Tubeless-Reifen für eine schlammige Fahrt."

• "Wie ist die Geländezusammensetzung für eine 10 km Fahrt in Taichung? Ich muss wissen, ob ich auf technische 'Grad 5' Segmente stoße."

Beispielantworten

Unten ist ein Beispiel für die detaillierten Informationen, die BikeScout bereitstellen kann:

Ich habe eine MTB-Runde in der Nähe von Frascati, Italien gefunden. Hier sind die Details:

📊 Routendetails

• 📍 Distanz: 11,26 km

• ⛰️ Gesamtanstieg: 856 Meter

• 🏷️ Schwierigkeit: Experte (Anspruchsvolle Distanz oder sehr steile Anstiege)