RunCoach

Live: runcoach-ruby.vercel.app · MCP-Endpunkt https://runcoach-ruby.vercel.app/mcp

Ein MCP-Server, der die eigenen Trainingsdaten eines Läufers – berechnete Trainingsbelastung, Wettkampfzeit-Vorhersagen, generierte Pläne – als Werkzeuge bereitstellt, die ein LLM aufrufen kann.

Der Punkt ist die Fundierung. Fragen Sie einen beliebigen Assistenten „Sollte ich diese Woche kürzertreten?“, und er wird plausible Trainingsratschläge aus dem Nichts produzieren. RunCoach lässt dieselbe Frage anhand der tatsächlich aufgezeichneten Aktivitäten des Athleten beantworten, wobei die Antwort die spezifischen Läufe enthält, aus denen sie stammt:

Sie: Wie läuft mein Training, und was könnte ich auf der Halbmarathon-Distanz laufen?

Claude (ruft analyze_training_status, dann predict_race_time auf): Das Training ist konstant und die Belastung stabil – 46,8 km/Woche über 17 Läufe in den letzten 28 Tagen, mit einem Akut-zu-Chronisch-Verhältnis von 1,00 und keiner längeren Pause als drei Tagen. Die Fitness wird erhalten, nicht aufgebaut, was zwischen Zielen der richtige Stand ist und eine Änderung wert, wenn ein Wettkampf ansteht.

Für den Halbmarathon: 1:38:49, höchstwahrscheinlich zwischen 1:36:50 und 1:40:48. Dies wurde an Ihre eigene Distanz/Zeit-Kurve über Ihren 5K (21:30, 8. Juli), 10K (44:50, 3. Juni) und Halbmarathon (1:38:48, 29. April) angepasst – Ihr Ermüdungsexponent betrug 1,059 gegenüber einem Bevölkerungsdurchschnitt von 1,06, Sie halten das Tempo also mit zunehmender Distanz etwa so gut wie üblich. Eine Aktivität wurde ausgeschlossen: ein 3 km-Lauf vom 28. Juli, der mit einem Tempo aufgezeichnet wurde, das schneller als der Weltrekord für diese Distanz ist, mit ziemlicher Sicherheit ein GPS-Fehler.

Jede obige Zahl ist eine echte Ausgabe von npm test's Fixture-Athleten, keine Veranschaulichung – die genauen Zeichenfolgen erscheinen in test/readme.test.ts, das fehlschlägt, wenn sich die Wissenschaft ändert und die README nicht aktualisiert wird. Jedes Werkzeug gibt eine Konfidenz und eine Erklärung zurück, wie seine Zahl abgeleitet wurde, und die Anweisungen des Servers sagen dem Modell, beide durchzutragen. Eine ohne ihre Grundlage angegebene Vorhersage ist von einer Schätzung nicht zu unterscheiden.

Werkzeuge

Related MCP server: livetrack-mcp

Woher die Zahlen kommen

RunCoach implementiert nichts neu. Jede Berechnung stammt von @runman/core, dem fixture-getesteten Wissenschaftspaket, das auch die Runman-Web-App unterstützt. Eine Frage an Claude zu stellen und die entsprechende Seite zu laden, führt denselben Code gegen dieselbe Datenbank aus.

Dieses Paket ist hier als Git-Submodul eingebunden, und RunCoach's Tests importieren dieselbe Fixture-Datei, die Runman's Tests verwenden – sodass „was diese Daten produzieren sollen“ eine Definition über beide Repos hinweg hat, anstatt zwei, die auseinanderdriften.

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

Erwähnenswerte Designentscheidungen

Werkzeuge akzeptieren keine Athleten-ID. Der API-Schlüssel löst sich in genau einen Athleten auf, und diese ID wird zum Werkzeugkontext. Wenn ein Modell eine Athleten-ID übergeben könnte, könnte eine prompt-injizierte Anweisung in einem Aktivitätstitel es dazu auffordern – und die Nutzlast hier sind die persönlichen Gesundheitsdaten von jemandem. Es gibt schlicht kein Argument, mit dem der Schlüssel eines Athleten die Daten eines anderen lesen kann. Ein Test stellt sicher, dass dies so bleibt.

Eine Ablehnung ist eine gültige Antwort. Wenn es keine Daten zur Untermauerung einer Vorhersage gibt, sagt das Werkzeug dies und weist das Modell an, keine Schätzung zu substituieren. Gleiches gilt für die Planerstellung: Wenn der Athlet kein aktuelles Training hat oder der Wettkampf drei Wochen entfernt ist, lehnt es mit einem Grund ab, anstatt einen Plan zu erstellen, der auf einer geschätzten Basislinie beruht. Modelle füllen standardmäßig Lücken; die Werkzeugausgabe muss aktiv dagegenhalten.

Die Ausgabe ist Prosa, kein JSON. Modelle paraphrasieren Sätze treuer, als sie verschachtelte Objekte lesen, und erfinden weitaus seltener ein Feld, das nicht vorhanden war. Präzise Zahlen erscheinen dennoch – innerhalb von Sätzen.

Jede HTTP-Anfrage erstellt ihre eigene Serverinstanz. Die gemeinsame Nutzung einer Instanz über Aufrufe hinweg in einer serverlosen Umgebung riskiert die Vermischung der Sitzungen zweier Athleten innerhalb eines warmen Containers. Das ist hier kein akzeptabler Fehlermodus.

Bereitstellung

Der HTTP-Transport ist eine einzelne Vercel-Funktion. Die Authentifizierung erfolgt über ein Bearer-Token – einen API-Schlüssel, den der Athlet auf der Runman-Profilseite ausstellt, der nur als SHA-256-Hash gespeichert wird.

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

Beachten Sie, dass der Vercel-Einstiegspunkt (api/mcp.js) einfaches JavaScript ist, das den kompilierten Handler aus dist/ reexportiert, anstatt TypeScript, das src/ importiert. Vercel kompiliert eine .ts-Funktion an Ort und Stelle, lässt aber relative Import-Spezifizierer unberührt, sodass ein .ts-Spezifizierer im bereitgestellten Bundle überlebt und zur Laufzeit fehlschlägt, wenn er nach einer Datei sucht, die nie ausgeliefert wurde.

Überprüfen Sie nach der Bereitstellung Ende-zu-Ende mit einem echten MCP-Client:

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

Das verbindet sich genau so über das Netzwerk wie Claude – Handshake, Werkzeugerkennung, dann ein Aufruf jedes der fünf Werkzeuge – und stellt sicher, dass die Antworten fundiert und nicht nur wohlgeformt zurückkommen.

Fügen Sie es dann in einem beliebigen MCP-Client hinzu:

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

Lokales Ausführen über stdio

Zur Verwendung mit Ihren eigenen Daten auf Ihrem eigenen Rechner:

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

Ein stdio-Server hat keine zu authentifizierenden Anfragen – er läuft als Kindprozess des Clients –, sodass der Athlet beim Start festgelegt wird. Das ist nur auf dem eigenen Rechner des Athleten angemessen, weshalb der bereitgestellte Transport es stattdessen pro Anfrage tut.

Testen

npm test

31 Tests über drei Ebenen: die Werkzeug-Handler gegen Runman's gemeinsamen Fixture-Satz (konsistenter Läufer, Läufer ohne Herzfrequenz, einzelne Aktivität, leere Historie, GPS-Ausrutscher-Historie, sporadischer Läufer, zurückkehrender Läufer, Volumenspitze), und ein Ende-zu-Ende-Protokolltest, der einen echten MCP-Client mit einem echten Server verbindet und ihn durch Werkzeugerkennung, Schema-Validierung und Aufruf führt. Die dritte Ebene fixiert die in dieser README zitierten Beispielfiguren.

Nicht in v1

Garmin-basierte Werkzeuge (Erholung, Schlaf, HRV) durch Proxy in einen vorgelagerten Garmin-MCP-Server, geschützt hinter der Verknüpfung eines Kontos durch den Athleten. Bewusst trennbar, sodass ein Athlet ohne Garmin keine Verschlechterung sieht.

Lizenz

MIT.