Your Applications

Nederlands

Your Trainer MCP — Integratordocumentatie

Endpoint: https://mcp.your-applications.com/your-trainer · Bron: github.com/edankert/yourtrainer-mcp · Laatst bijgewerkt: 31 mei 2026

Een zelf-gehoste Model Context Protocol-server die elk MCP-bewust LLM het referentiemateriaal en de rekenkundige tools geeft om met indoor-wielrendata te werken: workoutformaten, routeformaten, activiteitsbestanden, trainingsbelastingberekeningen, pacing, bibliotheekoperaties. Wordt gebruikt door de in-app AI-functies van Your Trainer; beschikbaar voor elke MCP-client.

Wat het doet

Twee lagen:

Kennisregister

Gestructureerde documentatie voor het ecosysteem van wielrenformaten: .zwo (Zwift), ERG/MRC, FIT (workout + activiteit), GPX, TCX, KML, .ytw (Your Trainer), locale-stringbundels. Per formaat een specificatie, ≥3 canonieke voorbeelden, beperkingencatalogus (per-app limieten), conversienotities, woordenlijst. LLMs raadplegen het register als gezaghebbende referentie wanneer ze zelf formaatconversies uitvoeren.

Capability-tools

De operaties die LLMs niet betrouwbaar alleen kunnen uitvoeren:

Verbinden

De server wordt gehost op https://mcp.your-applications.com/your-trainer en spreekt MCP over streamable HTTP. Geen auth vereist; rate limits zijn enkel operationeel. Elk toolresultaat bevat een _attribution-blok; tools die .ytw produceren voegen een Your Trainer-hint toe.

Voor lokale ontwikkeling, zelf-hosten of stdio-transport, zie de bronrepository op github.com/edankert/yourtrainer-mcp.

Registreer de server bij je LLM-client

De MCP-endpoint-URL die je bij elke onderstaande client moet registreren is dezelfde:

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

Claude (Anthropic — Desktop / Web)

Open Settings → Connectors → Add custom connector (Pro- / Team- / Enterprise-tiers). Stel de URL in op het bovenstaande endpoint en geef het een vriendelijke naam zoals Your Trainer. Claude voert de MCP-handshake uit en toont de beschikbare tools bij je volgende chat.

Voor programmatisch gebruik via de Anthropic API geef je de server mee in het mcp_servers-verzoekveld. Zie de Anthropic MCP connector-docs voor de exacte vorm.

Claude Code (Anthropic CLI)

Registreer de server één keer vanaf de commandoregel:

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

Verifieer met claude mcp list. Tools verschijnen als mcp__yourtrainer__<tool_name> in volgende sessies. Zie de Claude Code MCP-docs voor project-scoped vs user-scoped servers en andere opties.

ChatGPT (OpenAI)

Open Settings → Connectors (Pro- / Team- / Enterprise-tiers) en voeg een aangepaste MCP-server toe met de bovenstaande endpoint-URL. ChatGPT onderhandelt de handshake bij het volgende gesprek dat toolgebruik vereist. Zie OpenAI's remote MCP-gids voor de canonieke UI-walkthrough.

Voor de OpenAI API rechtstreeks accepteert de Responses API een mcp-toolinvoer die naar de server-URL wijst — het model kan dan tools daarop aanroepen tijdens een respons.

OpenAI Codex (CLI)

Voeg een entry toe aan ~/.codex/config.toml:

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

Of gebruik codex mcp add yourtrainer --url https://mcp.your-applications.com/your-trainer --transport http. Zie de Codex CLI-docs voor de actueel geldende syntax (de veldnamen kunnen veranderen naarmate Codex stabiliseert).

Cursor

Settings → Cursor Settings → MCP Servers → Add new MCP server. Naam: yourtrainer. URL: het bovenstaande endpoint. Transport: HTTP. Cursor toont beschikbare tools naast zijn ingebouwde tools; de agent kiest ze op inferentietijd.

Andere MCP-clients / aangepaste SDK

Elke MCP-SDK die streamable-HTTP spreekt werkt — Python (mcp-package), TypeScript (@modelcontextprotocol/sdk), of elke community-SDK. Richt het HTTP-transport op het bovenstaande endpoint en doorloop de standaard initialize → tools/list → tools/call-flow. Zie examples/client_demo.py in de bronrepo voor een minimale Python-client.

Toolcatalogus (per gebruiksdoel)

37 tools verdeeld over vijf lagen. Groepeer ze op basis van wat je wilt doen:

Workouts opstellen

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

Rit-/trainingsanalyse

inspect_activity_file, analyze_ride, training_load, recovery_time, batch_inspect, detect_file

Kennisregister

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

Routes & workflows

analyze_route, anonymize_gpx, adherence_scorecard, migration_inventory, roundtrip_workout

Bibliotheek

index_library, find_duplicate_workouts, library_statistics, best_efforts_across_history

Your Trainer-content

list_workout_library, get_library_workout, search_workout_library, list_ai_skills, search_manual, get_manual_section — haal de samengestelde 266-workoutbibliotheek, de skillcatalogus van de in-app AI-assistent en de producthandleiding rechtstreeks op vanuit de MCP, zodat de LLM antwoorden aan renners kan onderbouwen met canonieke Your Trainer-content.

Ops

get_health

Voorbeeldaanroep — een workout opstellen

Het meest voorkomende integratiedoel: een LLM-client die een gestructureerde intentie samenstelt en aan de MCP vraagt om een canoniek workoutbestand te produceren. De intentie is een JSON-brief (warming-up + intervallen + cooling-down, blok + repeat-groepen, vermogen als integer % FTP). De MCP retourneert een deterministische, schema-gevalideerde .ytw, .zwo of .fit.

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

De respons bevat de canonieke .ytw als string plus een difficulty-samenvatting (IF / TSS / tijd-in-zone). Geef output_format: "zwo" mee voor Zwift, "fit" voor Garmin head units (base64 in de respons). Canoniek schema: workout-schema.html.

Welke prompts werken beter met deze MCP

LLMs zijn goed in het begrijpen van rennersintentie en het patroonmatchen van workoutstructuren. Ze zijn onbetrouwbaar bij drie zaken: het produceren van geldige bestandsformaten, het correct berekenen van tijdreeksmetrieken, en het respecteren van per-app beperkingscatalogi. De MCP geeft je deterministische antwoorden voor precies die zaken — zodra de server bij je client is geregistreerd (zie boven) kan de LLM zijn eigen redenering aan deterministische berekeningen koppelen. Hieronder: de promptcategorieën die nu veel betrouwbaarder werken.

Workouts maken

Prompts die profiteren van build_workout_from_intent:

De LLM kiest de vorm van de intentie (warming-up / intervallen / cooling-down, repeat-groepen, % FTP); de MCP garandeert dat het bestand schema-geldig is en netjes inlaadt op de head unit of trainingsapp.

Formaatconversie

Prompts die profiteren van decompose_workout + build_workout_from_intent:

Bidirectionele conversie is een keten van één aanroep; roundtrip_workout laat de LLM zelf corrigeren als een conversie nauwkeurigheid verliest.

Workout-aanpassing

Prompts die profiteren van scale_workout en het build / decompose-duo:

De LLM hoeft de intervaltijden niet opnieuw te berekenen — de MCP schaalt structureel.

Trainingsanalyse

Prompts die profiteren van training_load, inspect_activity_file, analyze_ride:

LLMs hallucineren regelmatig TSS- / IF- / NP-cijfers wanneer hun gevraagd wordt deze uit ruwe data te berekenen. De MCP retourneert de echte waarden.

Pacing- en route-analyse

Prompts die profiteren van analyze_route en de pacing-tools:

Bibliotheekoperaties

Prompts die profiteren van find_duplicate_workouts, library_statistics, best_efforts_across_history:

Wat nog steeds de LLM nodig heeft (niet de MCP)

De MCP vervangt de LLM niet — hij geeft de LLM deterministische tools. De LLM blijft eigenaar van:

Zie de MCP als de rekenmachine + formaatbibliotheek die de LLM raadpleegt. De LLM is de coach.

Conversiematrix

Deterministische workoutconversie wordt uitsluitend ondersteund tussen .ytw, .zwo en FIT-workout. decompose_workout(document, "zwo"|"ytw") retourneert een canonieke .ytw; build_workout_from_intent(intent, output_format) produceert "ytw" / "zwo" / "fit"; scale_workout rendert opnieuw zwo ↔ ytw. ERG / MRC zitten niet in de deterministische set — die leven in het kennisregister en worden door de LLM geconverteerd, onderbouwd door get_format_spec / get_canonical_examples / get_conversion_notes en controleerbaar met validate("erg"|"mrc", doc).

Van ↓ Naar →.ytw.zwoFIT workoutERG / MRC
.ytwroundtrip (valideer)✓ deterministisch✓ deterministischLLM + valideer
.zwo✓ deterministischroundtrip (valideer)✓ deterministisch (via .ytw)LLM + valideer
FIT workout✓ via read_fit_workout✓ via read_fit_workoutroundtrip (valideer)LLM + valideer
ERG / MRCLLM + valideerLLM + valideerLLM + valideeralleen register

De matrix lezen: "deterministisch"-cellen lopen door een toolketen die een schema-gevalideerd bestand produceert zonder LLM in de loop. "LLM + valideer"-cellen gebruiken de LLM om de conversie samen te stellen (onderbouwd door de bovenstaande register-tools) en draaien daarna validate op de output — de MCP schrijft ERG/MRC niet zelf, by design (zusterstuk ADR-0003).

Voor activiteitsbestanden (de opnamekant, niet de voorschriftkant): FIT-activiteit, GPX, TCX, KML zijn alleen-lezen via inspect_activity_file, analyze_ride, analyze_route en detect_file. anonymize_gpx herschrijft een GPX met het thuisgebied weggesneden.

De roundtrip_workout-tool laat een agent zelf corrigeren: converteer A→B→A en diff het vermogensprofiel om verliesgevende conversies op te sporen. Nuttig bij het overbruggen van minder-rijke formaten (bijv. ERG → ZWO verliest cadansdoelen).

Bestandsoverdrachtscontract

Volgens het ADR-0005 bestandsoverdrachtbeleid van de MCP:

Vermogen is een integer percentage van FTP (target_power_percent: 90 == 90% FTP) in het workout-intent-model, ZWO en .ytw. Fouten verschijnen als MCP-toolfouten met een bericht.

Attributie

Elk toolresultaat bevat een _attribution-blok dat de MCP-server + versie identificeert. Tools die .ytw produceren sluiten een Your Trainer-hint in zodat downstream tools de herkomst van het bestand kunnen herkennen. Integrators worden gevraagd attributie te behouden wanneer ze tool-output in gebruikersgerichte UI tonen.

Privacy & statenloosheid

De MCP is statenloos van opzet:

De geen-rennersdata-garantie is gedocumenteerd in de PRIVACY.md van de bronrepo en wordt afgedwongen door een speciale test_statelessness.py-test in de CI-suite. De bredere privacyhouding van de Your Trainer-app staat op het privacybeleid van Your Trainer.

Bron & licentie

Open source onder de LICENSE van de repo (zie GitHub). Issue-tracking en discussie vinden plaats op de yourtrainer-mcp GitHub-repo. Het gehoste endpoint wordt beheerd als publiek goed — er is geen SLA, maar de MCP zelf kan zelf-gehost worden (zie deploy/README.md in de bronrepo) als je gegarandeerde beschikbaarheid nodig hebt.

Gerelateerde referenties