Your Applications

Deutsch

Your Trainer MCP — Integrator-Dokumentation

Endpunkt: https://mcp.your-applications.com/your-trainer · Quelle: github.com/edankert/yourtrainer-mcp · Zuletzt aktualisiert: 31. Mai 2026

Ein selbst gehosteter Model Context Protocol-Server, der jedem MCP-fähigen LLM das Referenzmaterial und die Berechnungswerkzeuge bietet, um mit Indoor-Cycling-Daten zu arbeiten: Workout-Formate, Streckenformate, Aktivitätsdateien, Trainingsbelastungs-Mathematik, Pacing, Bibliotheksoperationen. Wird von den In-App-AI-Funktionen von Your Trainer verwendet; verfügbar für jeden MCP-Client.

Was es tut

Zwei Schichten:

Wissensregister

Strukturierte Dokumentation für das Cycling-Format-Ökosystem: .zwo (Zwift), ERG/MRC, FIT (Workout + Aktivität), GPX, TCX, KML, .ytw (Your Trainer), Locale-String-Bundles. Pro Format Spezifikation, ≥3 kanonische Beispiele, Constraint-Katalog (App-spezifische Grenzwerte), Konvertierungshinweise, Glossar. LLMs fragen das Register als autoritative Referenz ab, wenn sie Formatkonvertierungen selbst durchführen.

Capability-Tools

Die Operationen, die LLMs nicht zuverlässig allein durchführen können:

Verbinden

Der Server wird unter https://mcp.your-applications.com/your-trainer gehostet und spricht MCP über streamable HTTP. Keine Authentifizierung erforderlich; Rate-Limits dienen nur dem Betrieb. Jedes Tool-Ergebnis enthält einen _attribution-Block; Tools, die .ytw erzeugen, fügen einen Your Trainer-Hinweis hinzu.

Für lokale Entwicklung, Self-Hosting oder stdio-Transport siehe das Quell-Repository unter github.com/edankert/yourtrainer-mcp.

Server bei deinem LLM-Client registrieren

Die MCP-Endpunkt-URL, die du bei jedem der folgenden Clients registrierst, ist dieselbe:

https://mcp.your-applications.com/your-trainer

Claude (Anthropic — Desktop / Web)

Öffne Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen (Pro- / Team- / Enterprise-Tarife). Setze die URL auf den oben genannten Endpunkt und gib ihm einen sprechenden Namen wie Your Trainer. Claude führt den MCP-Handshake aus und listet die verfügbaren Tools beim nächsten Chat-Start auf.

Für programmatische Nutzung über die Anthropic-API übergibst du den Server im Anfragefeld mcp_servers. Siehe die Anthropic MCP-Connector-Dokumentation für die genaue Form.

Claude Code (Anthropic CLI)

Registriere den Server einmalig über die Kommandozeile:

claude mcp add yourtrainer https://mcp.your-applications.com/your-trainer --transport http

Verifiziere mit claude mcp list. Tools erscheinen in folgenden Sitzungen als mcp__yourtrainer__<tool_name>. Siehe die Claude Code MCP-Dokumentation für projekt- vs. benutzergebundene Server und weitere Optionen.

ChatGPT (OpenAI)

Öffne Einstellungen → Connectors (Pro- / Team- / Enterprise-Tarife) und füge einen benutzerdefinierten MCP-Server mit der oben genannten Endpunkt-URL hinzu. ChatGPT verhandelt den Handshake bei der nächsten Konversation, die Tool-Nutzung erfordert. Siehe OpenAIs Remote-MCP-Leitfaden für die kanonische UI-Anleitung.

Direkt für die OpenAI-API akzeptiert die Responses-API einen mcp-Tool-Eintrag, der auf die Server-URL zeigt — das Modell kann dann während einer Antwort Tools darauf aufrufen.

OpenAI Codex (CLI)

Füge einen Eintrag in ~/.codex/config.toml hinzu:

[mcp_servers.yourtrainer]
url = "https://mcp.your-applications.com/your-trainer"
transport = "http"

Oder verwende codex mcp add yourtrainer --url https://mcp.your-applications.com/your-trainer --transport http. Siehe die Codex CLI-Dokumentation für die aktuell autoritative Syntax (die Feldnamen können sich noch ändern, während Codex stabilisiert wird).

Cursor

Settings → Cursor Settings → MCP Servers → Add new MCP server. Name: yourtrainer. URL: der oben genannte Endpunkt. Transport: HTTP. Cursor listet die verfügbaren Tools neben seinen eingebauten auf; der Agent wählt sie zur Inferenzzeit aus.

Andere MCP-Clients / Custom-SDK

Jedes MCP-SDK, das streamable-HTTP spricht, funktioniert — Python (mcp-Paket), TypeScript (@modelcontextprotocol/sdk) oder jedes Community-SDK. Richte seinen HTTP-Transport auf den oben genannten Endpunkt und durchlaufe den Standard-Flow initialize → tools/list → tools/call. Siehe examples/client_demo.py im Quell-Repo für einen minimalen Python-Client.

Tool-Katalog (nach Anwendungsfall)

37 Tools auf fünf Ebenen. Gruppiere sie danach, was du tun möchtest:

Workout-Erstellung

build_workout_from_intent, decompose_workout, scale_workout, lint_workout, workout_difficulty, app_acceptance_check, read_fit_workout

Fahrt-/Trainingsanalyse

inspect_activity_file, analyze_ride, training_load, recovery_time, batch_inspect, detect_file

Wissensregister

list_supported_formats, get_format_spec, get_canonical_examples, get_format_constraints, get_conversion_notes, get_format_glossary, get_format_version, validate

Strecken & Workflows

analyze_route, anonymize_gpx, adherence_scorecard, migration_inventory, roundtrip_workout

Bibliothek

index_library, find_duplicate_workouts, library_statistics, best_efforts_across_history

Your Trainer-Inhalte

list_workout_library, get_library_workout, search_workout_library, list_ai_skills, search_manual, get_manual_section — rufe die kuratierte 266-Workout-Bibliothek, den Skill-Katalog des In-App-AI-Assistenten und das Produkthandbuch direkt vom MCP ab, damit das LLM Antworten an Fahrer auf kanonischen Your Trainer-Inhalten verankern kann.

Ops

get_health

Beispielaufruf — ein Workout erstellen

Das häufigste Integrationsziel: ein LLM-Client komponiert einen strukturierten Intent und bittet den MCP, eine kanonische Workout-Datei auszugeben. Der Intent ist ein JSON-Brief (Aufwärmen + Intervalle + Auslaufen, Block- + Wiederholungsgruppen, Leistung als ganzzahliger Prozentwert der FTP). Der MCP gibt eine deterministische, schemavalidierte .ytw-, .zwo- oder .fit-Datei zurück.

// Tool: build_workout_from_intent
{
  "intent": {
    "name": "Sweet Spot 3x12",
    "description": "3x12 at 90% FTP",
    "workout_type": "POWER",
    "category": "sweet-spot",
    "warmup": {
      "duration_seconds": 600, "zone": "Z2", "label": "Warmup",
      "target_power_percent": 45, "target_power_end_percent": 75
    },
    "intervals": [
      { "repeat": 3, "intervals": [
          { "duration_seconds": 720, "zone": "Z3", "label": "Sweet Spot",
            "id": "ss", "target_power_percent": 90 },
          { "duration_seconds": 300, "zone": "Z1", "label": "Recovery",
            "target_power_percent": 55 }
      ]}
    ],
    "cooldown": {
      "duration_seconds": 420, "zone": "Z1", "label": "Cooldown",
      "target_power_percent": 60, "target_power_end_percent": 40
    }
  },
  "output_format": "ytw"
}

Die Antwort enthält die kanonische .ytw als String plus eine difficulty-Zusammenfassung (IF / TSS / Zeit-in-Zone). Übergib output_format: "zwo" für Zwift, "fit" für Garmin-Headunits (Base64 in der Antwort). Kanonisches Schema: workout-schema.html.

Welche Arten von Prompts funktionieren mit diesem MCP besser

LLMs sind gut darin, Fahrer-Absichten zu verstehen und Workout-Strukturen per Mustererkennung zu identifizieren. Sie sind unzuverlässig in drei Dingen: gültige Dateiformate auszugeben, Zeitreihen-Metriken korrekt zu berechnen und App-spezifische Constraint-Kataloge zu respektieren. Der MCP liefert dir deterministische Antworten genau dafür — sobald der Server bei deinem Client registriert ist (siehe oben), kann das LLM seine eigene Argumentation mit deterministischer Berechnung verketten. Im Folgenden: die Prompt-Kategorien, die jetzt deutlich zuverlässiger funktionieren.

Workout-Erstellung

Prompts, die von build_workout_from_intent profitieren:

Das LLM wählt die Intent-Form (Aufwärmen / Intervalle / Auslaufen, Wiederholungsgruppen, % FTP); der MCP garantiert, dass die Datei schemavalid ist und sauber in die Headunit / Trainings-App importiert wird.

Formatkonvertierung

Prompts, die von decompose_workout + build_workout_from_intent profitieren:

Bidirektionale Konvertierung ist eine Ein-Aufruf-Kette; roundtrip_workout lässt das LLM sich selbst korrigieren, wenn eine Konvertierung an Treue verliert.

Workout-Modifikation

Prompts, die von scale_workout und dem Build-/Decompose-Paar profitieren:

Das LLM muss keine Intervall-Timings neu berechnen — der MCP skaliert strukturell.

Trainingsanalyse

Prompts, die von training_load, inspect_activity_file, analyze_ride profitieren:

LLMs halluzinieren häufig TSS-/IF-/NP-Zahlen, wenn sie diese aus Rohdaten berechnen sollen. Der MCP liefert die Ground Truth.

Pacing- und Streckenanalyse

Prompts, die von analyze_route und den Pacing-Tools profitieren:

Bibliotheksoperationen

Prompts, die von find_duplicate_workouts, library_statistics, best_efforts_across_history profitieren:

Was weiterhin das LLM braucht (nicht den MCP)

Der MCP ersetzt das LLM nicht — er gibt ihm deterministische Tools. Das LLM bleibt zuständig für:

Stell dir den MCP als den Taschenrechner + die Formatbibliothek vor, die das LLM konsultiert. Das LLM ist der Coach.

Konvertierungsmatrix

Deterministische Workout-Konvertierung wird ausschließlich zwischen .ytw, .zwo und FIT-Workout unterstützt. decompose_workout(document, "zwo"|"ytw") liefert eine kanonische .ytw; build_workout_from_intent(intent, output_format) gibt "ytw" / "zwo" / "fit" aus; scale_workout rendert zwo ↔ ytw neu. ERG / MRC gehören nicht zum deterministischen Satz — sie leben im Wissensregister und werden vom LLM konvertiert, verankert durch get_format_spec / get_canonical_examples / get_conversion_notes und überprüfbar mit validate("erg"|"mrc", doc).

Von ↓ Nach →.ytw.zwoFIT-WorkoutERG / MRC
.ytwRoundtrip (validieren)✓ deterministisch✓ deterministischLLM + validieren
.zwo✓ deterministischRoundtrip (validieren)✓ deterministisch (via .ytw)LLM + validieren
FIT-Workout✓ via read_fit_workout✓ via read_fit_workoutRoundtrip (validieren)LLM + validieren
ERG / MRCLLM + validierenLLM + validierenLLM + validierennur Registry

So liest sich die Matrix: „deterministische" Zellen durchlaufen eine Tool-Kette, die eine schemavalidierte Datei ohne LLM im Loop produziert. „LLM + validieren"-Zellen nutzen das LLM, um die Konvertierung zu komponieren (verankert durch die obigen Registry-Tools), und führen anschließend validate auf der Ausgabe aus — der MCP erstellt ERG/MRC bewusst nicht selbst (siehe Schwester-ADR-0003).

Für Aktivitätsdateien (die Aufzeichnungsseite, nicht die Vorgabeseite): FIT-Aktivität, GPX, TCX, KML sind nur lesbar über inspect_activity_file, analyze_ride, analyze_route und detect_file. anonymize_gpx schreibt ein GPX mit beschnittenem Heimatgebiet neu.

Das Tool roundtrip_workout lässt einen Agenten sich selbst korrigieren: konvertiere A→B→A und vergleiche das Leistungsprofil, um verlustbehaftete Konvertierungen zu erkennen. Nützlich, wenn weniger reichhaltige Formate überbrückt werden (z. B. ERG → ZWO verliert Trittfrequenz-Ziele).

Dateiübertragungs-Vertrag

Gemäß der MCP-eigenen ADR-0005 Dateiübertragungs-Richtlinie:

Leistung ist im Workout-Intent-Modell, ZWO und .ytw ein ganzzahliger Prozentwert der FTP (target_power_percent: 90 == 90% FTP). Fehler werden als MCP-Tool-Fehler mit einer Nachricht zurückgegeben.

Attribution

Jedes Tool-Ergebnis enthält einen _attribution-Block, der den MCP-Server + die Version identifiziert. Tools, die .ytw erzeugen, betten einen Your Trainer-Hinweis ein, damit nachgelagerte Tools den Ursprung der Datei erkennen können. Integratoren werden gebeten, die Attribution zu erhalten, wenn sie Tool-Ausgaben in benutzerorientierten UIs darstellen.

Datenschutz & Zustandslosigkeit

Der MCP ist zustandslos by design:

Die No-Rider-Data-Garantie ist in der PRIVACY.md des Quell-Repos dokumentiert und wird durch einen dedizierten test_statelessness.py-Test in der CI-Suite durchgesetzt. Die umfassendere Datenschutzhaltung der Your Trainer-App findest du in der Your Trainer-Datenschutzerklärung.

Quelle & Lizenz

Open Source unter der LICENSE des Repos (siehe GitHub). Issue-Tracking und Diskussion finden im yourtrainer-mcp GitHub-Repo statt. Der gehostete Endpunkt wird als öffentliches Gut betrieben — es gibt kein SLA, aber der MCP selbst kann selbst gehostet werden (siehe deploy/README.md im Quell-Repo), falls du garantierte Verfügbarkeit brauchst.

Verwandte Referenzen