Your Applications

Français

Your Trainer MCP — Documentation pour intégrateurs

Point de terminaison : https://mcp.your-applications.com/your-trainer · Source : github.com/edankert/yourtrainer-mcp · Dernière mise à jour : 31 mai 2026

Un serveur Model Context Protocol auto-hébergé qui fournit à tout LLM compatible MCP la documentation de référence et les outils de calcul pour travailler avec les données de cyclisme en intérieur : formats de séances, formats de parcours, fichiers d'activité, calculs de charge d'entraînement, allure, opérations de bibliothèque. Utilisé par les fonctionnalités IA intégrées de Your Trainer ; disponible pour tout client MCP.

Ce qu'il fait

Deux couches :

Registre de connaissances

Documentation structurée pour l'écosystème des formats de cyclisme : .zwo (Zwift), ERG/MRC, FIT (séance + activité), GPX, TCX, KML, .ytw (Your Trainer), bundles de chaînes localisées. Spécification par format, ≥3 exemples canoniques, catalogue de contraintes (limites par application), notes de conversion, glossaire. Les LLM interrogent le registre comme référence faisant autorité lorsqu'ils effectuent eux-mêmes des conversions de formats.

Outils de capacité

Les opérations que les LLM ne peuvent pas réaliser de manière fiable seuls :

Se connecter

Le serveur est hébergé sur https://mcp.your-applications.com/your-trainer et parle MCP via HTTP streamable. Aucune authentification requise ; les limites de débit sont uniquement opérationnelles. Chaque résultat d'outil inclut un bloc _attribution ; les outils qui produisent du .ytw ajoutent un indice Your Trainer.

Pour le développement local, l'auto-hébergement ou le transport stdio, voir le dépôt source à github.com/edankert/yourtrainer-mcp.

Enregistrer le serveur auprès de votre client LLM

L'URL du point de terminaison MCP à enregistrer avec chaque client ci-dessous est la même :

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

Claude (Anthropic — Desktop / Web)

Ouvrez Paramètres → Connecteurs → Ajouter un connecteur personnalisé (niveaux Pro / Team / Enterprise). Définissez l'URL sur le point de terminaison ci-dessus et donnez-lui un nom convivial comme Your Trainer. Claude exécutera le handshake MCP et listera les outils disponibles au prochain démarrage d'une conversation.

Pour une utilisation programmatique via l'API Anthropic, transmettez le serveur dans le champ de requête mcp_servers. Voir la documentation du connecteur MCP Anthropic pour la forme exacte.

Claude Code (CLI Anthropic)

Enregistrez le serveur une fois depuis la ligne de commande :

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

Vérifiez avec claude mcp list. Les outils apparaissent sous la forme mcp__yourtrainer__<tool_name> dans les sessions suivantes. Voir la documentation MCP de Claude Code pour les serveurs à portée projet vs utilisateur et d'autres options.

ChatGPT (OpenAI)

Ouvrez Paramètres → Connecteurs (niveaux Pro / Team / Enterprise) et ajoutez un serveur MCP personnalisé avec l'URL du point de terminaison ci-dessus. ChatGPT négociera le handshake lors de la prochaine conversation nécessitant l'utilisation d'outils. Voir le guide MCP distant d'OpenAI pour la procédure canonique dans l'interface.

Pour l'API OpenAI directement, l'API Responses accepte une entrée d'outil mcp pointant vers l'URL du serveur — le modèle peut alors appeler des outils dessus pendant une réponse.

OpenAI Codex (CLI)

Ajoutez une entrée à ~/.codex/config.toml :

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

Ou utilisez codex mcp add yourtrainer --url https://mcp.your-applications.com/your-trainer --transport http. Voir la documentation du CLI Codex pour la syntaxe actuellement faisant autorité (les noms de champs peuvent évoluer pendant que Codex se stabilise).

Cursor

Paramètres → Cursor Settings → MCP Servers → Add new MCP server. Nom : yourtrainer. URL : le point de terminaison ci-dessus. Transport : HTTP. Cursor liste les outils disponibles aux côtés des siens ; l'agent les sélectionne au moment de l'inférence.

Autres clients MCP / SDK personnalisé

Tout SDK MCP qui parle HTTP streamable fonctionne — Python (paquet mcp), TypeScript (@modelcontextprotocol/sdk) ou tout SDK communautaire. Pointez son transport HTTP vers le point de terminaison ci-dessus et exécutez le flux standard initialize → tools/list → tools/call. Voir examples/client_demo.py dans le dépôt source pour un client Python minimal.

Catalogue d'outils (par cas d'usage)

37 outils répartis sur cinq couches. Regroupez-les selon ce que vous souhaitez faire :

Création de séances

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

Analyse de sortie / d'entraînement

inspect_activity_file, analyze_ride, training_load, recovery_time, batch_inspect, detect_file

Registre de connaissances

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

Parcours & workflows

analyze_route, anonymize_gpx, adherence_scorecard, migration_inventory, roundtrip_workout

Bibliothèque

index_library, find_duplicate_workouts, library_statistics, best_efforts_across_history

Contenu Your Trainer

list_workout_library, get_library_workout, search_workout_library, list_ai_skills, search_manual, get_manual_section — récupérez la bibliothèque organisée de 266 séances, le catalogue de compétences de l'assistant IA intégré, et le manuel produit directement depuis le MCP, afin que le LLM puisse fonder ses réponses aux cyclistes sur le contenu canonique de Your Trainer.

Ops

get_health

Exemple d'invocation — construire une séance

La cible d'intégration la plus courante : un client LLM composant une intention structurée et demandant au MCP d'émettre un fichier de séance canonique. L'intention est un brief JSON (échauffement + intervalles + retour au calme, blocs + groupes de répétitions, puissance en pourcentage entier de FTP). Le MCP retourne un .ytw, .zwo ou .fit déterministe et validé par schéma.

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

La réponse contient le .ytw canonique sous forme de chaîne plus un résumé difficulty (IF / TSS / temps en zone). Passez output_format: "zwo" pour Zwift, "fit" pour les compteurs Garmin (base64 dans la réponse). Schéma canonique : workout-schema.html.

Quels types de prompts fonctionnent mieux avec ce MCP

Les LLM sont doués pour comprendre l'intention du cycliste et reconnaître des structures de séances. Ils sont peu fiables sur trois points : émettre des formats de fichiers valides, calculer correctement les métriques de séries temporelles, et respecter les catalogues de contraintes propres à chaque application. Le MCP vous donne des réponses déterministes pour exactement ces points-là — une fois le serveur enregistré auprès de votre client (ci-dessus), le LLM peut chaîner son propre raisonnement avec du calcul déterministe. Ci-dessous : les catégories de prompts qui fonctionnent désormais beaucoup plus fiablement.

Création de séance

Prompts qui bénéficient de build_workout_from_intent :

Le LLM choisit la forme de l'intention (échauffement / intervalles / retour au calme, groupes de répétitions, % FTP) ; le MCP garantit que le fichier est valide selon le schéma et s'importe proprement dans le compteur / l'application d'entraînement.

Conversion de format

Prompts qui bénéficient de decompose_workout + build_workout_from_intent :

La conversion bidirectionnelle est une chaîne en un seul appel ; roundtrip_workout permet au LLM de s'auto-corriger si une conversion perd en fidélité.

Modification de séance

Prompts qui bénéficient de scale_workout et de la paire build / decompose :

Le LLM n'a pas à recalculer les minutages d'intervalles — le MCP met à l'échelle de manière structurelle.

Analyse d'entraînement

Prompts qui bénéficient de training_load, inspect_activity_file, analyze_ride :

Les LLM hallucinent fréquemment les chiffres TSS / IF / NP lorsqu'on leur demande de les calculer à partir des données brutes. Le MCP retourne la vérité terrain.

Allure et analyse de parcours

Prompts qui bénéficient de analyze_route et des outils d'allure :

Opérations de bibliothèque

Prompts qui bénéficient de find_duplicate_workouts, library_statistics, best_efforts_across_history :

Ce qui nécessite encore le LLM (pas le MCP)

Le MCP ne remplace pas le LLM — il lui donne des outils déterministes. Le LLM possède toujours :

Considérez le MCP comme la calculatrice + la bibliothèque de formats que le LLM consulte. Le LLM est l'entraîneur.

Matrice de conversion

La conversion déterministe de séance est prise en charge entre .ytw, .zwo et FIT-séance uniquement. decompose_workout(document, "zwo"|"ytw") retourne un .ytw canonique ; build_workout_from_intent(intent, output_format) émet "ytw" / "zwo" / "fit" ; scale_workout re-rend zwo ↔ ytw. ERG / MRC ne font pas partie de l'ensemble déterministe — ils vivent dans le registre de connaissances et sont convertis par le LLM, fondés par get_format_spec / get_canonical_examples / get_conversion_notes et vérifiables avec validate("erg"|"mrc", doc).

De ↓ Vers →.ytw.zwoFIT workoutERG / MRC
.ytwaller-retour (validate)✓ déterministe✓ déterministeLLM + validate
.zwo✓ déterministealler-retour (validate)✓ déterministe (via .ytw)LLM + validate
FIT workout✓ via read_fit_workout✓ via read_fit_workoutaller-retour (validate)LLM + validate
ERG / MRCLLM + validateLLM + validateLLM + validateregistre uniquement

Lecture de la matrice : les cellules « déterministe » passent par une chaîne d'outils qui produit un fichier validé par schéma sans LLM dans la boucle. Les cellules « LLM + validate » utilisent le LLM pour composer la conversion (fondé par les outils de registre ci-dessus) puis exécutent validate sur la sortie — le MCP ne crée pas d'ERG/MRC lui-même, par conception (ADR-0003 frère).

Pour les fichiers d'activité (le côté enregistrement, pas le côté prescription) : FIT activity, GPX, TCX, KML sont en lecture seule via inspect_activity_file, analyze_ride, analyze_route et detect_file. anonymize_gpx réécrit un GPX en tronquant la zone de domicile.

L'outil roundtrip_workout permet à un agent de s'auto-corriger : convertir A→B→A et comparer le profil de puissance pour détecter les conversions à perte. Utile lors du pontage entre formats moins riches (par ex. ERG → ZWO perd les cibles de cadence).

Contrat de transfert de fichiers

Selon la politique de transfert de fichiers ADR-0005 du MCP :

La puissance est un pourcentage entier de FTP (target_power_percent: 90 == 90 % FTP) dans le modèle d'intention de séance, ZWO et .ytw. Les erreurs remontent sous forme d'erreurs d'outil MCP avec un message.

Attribution

Chaque résultat d'outil inclut un bloc _attribution identifiant le serveur MCP + sa version. Les outils qui produisent du .ytw intègrent un indice Your Trainer afin que les outils en aval puissent reconnaître l'origine du fichier. Il est demandé aux intégrateurs de préserver l'attribution lorsqu'ils exposent la sortie d'outil dans une interface utilisateur.

Confidentialité & absence d'état

Le MCP est sans état par conception :

La garantie d'absence de données cyclistes est documentée dans le PRIVACY.md du dépôt source et appliquée par un test dédié test_statelessness.py dans la suite CI. La posture de confidentialité plus large de l'application Your Trainer figure dans la politique de confidentialité Your Trainer.

Source & licence

Open source sous la LICENSE du dépôt (voir GitHub). Le suivi des issues et la discussion ont lieu sur le dépôt GitHub yourtrainer-mcp. Le point de terminaison hébergé est exploité comme un bien public — il n'y a pas de SLA, mais le MCP lui-même peut être auto-hébergé (voir le deploy/README.md du dépôt source) si vous avez besoin d'une disponibilité garantie.

Références associées