Your Applications

Italiano

Your Trainer MCP — Documentazione per integratori

Endpoint: https://mcp.your-applications.com/your-trainer · Sorgente: github.com/edankert/yourtrainer-mcp · Ultimo aggiornamento: 31 maggio 2026

Un server Model Context Protocol self-hosted che fornisce a qualsiasi LLM compatibile con MCP il materiale di riferimento e gli strumenti computazionali per lavorare con i dati del ciclismo indoor: formati di workout, formati di percorso, file di attività, calcoli di carico di allenamento, pacing, operazioni di libreria. Utilizzato dalle funzioni AI integrate di Your Trainer; disponibile per qualsiasi client MCP.

Cosa fa

Due livelli:

Registro delle conoscenze

Documentazione strutturata per l'ecosistema dei formati di ciclismo: .zwo (Zwift), ERG/MRC, FIT (workout + attività), GPX, TCX, KML, .ytw (Your Trainer), bundle di stringhe di localizzazione. Specifica per formato, ≥3 esempi canonici, catalogo dei vincoli (limiti per app), note di conversione, glossario. Gli LLM interrogano il registro come riferimento autorevole quando eseguono autonomamente conversioni di formato.

Strumenti di capacità

Le operazioni che gli LLM non riescono a fare da soli in modo affidabile:

Connessione

Il server è ospitato su https://mcp.your-applications.com/your-trainer e parla MCP su HTTP streamable. Nessuna autenticazione richiesta; i limiti di rate sono solo operativi. Ogni risultato di strumento include un blocco _attribution; gli strumenti che producono .ytw aggiungono un indicatore Your Trainer.

Per sviluppo locale, self-hosting o trasporto stdio, vedi il repository sorgente su github.com/edankert/yourtrainer-mcp.

Registra il server con il tuo client LLM

L'URL dell'endpoint MCP da registrare con ciascun client elencato sotto è lo stesso:

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

Claude (Anthropic — Desktop / Web)

Apri Impostazioni → Connettori → Aggiungi connettore personalizzato (piani Pro / Team / Enterprise). Imposta l'URL all'endpoint sopra e dagli un nome descrittivo come Your Trainer. Claude eseguirà l'handshake MCP ed elencherà gli strumenti disponibili alla prossima chat.

Per l'uso programmatico tramite l'API Anthropic, passa il server nel campo della richiesta mcp_servers. Consulta la documentazione del connettore MCP Anthropic per la forma esatta.

Claude Code (CLI Anthropic)

Registra il server una volta dalla riga di comando:

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

Verifica con claude mcp list. Gli strumenti compaiono come mcp__yourtrainer__<tool_name> nelle sessioni successive. Consulta la documentazione MCP di Claude Code per server con scope di progetto vs scope utente e altre opzioni.

ChatGPT (OpenAI)

Apri Impostazioni → Connettori (piani Pro / Team / Enterprise) e aggiungi un server MCP personalizzato con l'URL dell'endpoint sopra. ChatGPT negozierà l'handshake nella prossima conversazione che richiede l'uso di strumenti. Consulta la guida MCP remoto di OpenAI per la procedura canonica nell'interfaccia.

Per l'API OpenAI diretta, l'API Responses accetta una voce di strumento mcp che punta all'URL del server — il modello può quindi chiamare strumenti su di esso durante una risposta.

OpenAI Codex (CLI)

Aggiungi una voce in ~/.codex/config.toml:

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

In alternativa usa codex mcp add yourtrainer --url https://mcp.your-applications.com/your-trainer --transport http. Consulta la documentazione della CLI Codex per la sintassi autorevole corrente (i nomi dei campi potrebbero cambiare man mano che Codex si stabilizza).

Cursor

Settings → Cursor Settings → MCP Servers → Add new MCP server. Nome: yourtrainer. URL: l'endpoint sopra. Trasporto: HTTP. Cursor elenca gli strumenti disponibili insieme ai suoi integrati; l'agente li sceglie al momento dell'inferenza.

Altri client MCP / SDK personalizzati

Qualsiasi SDK MCP che parli HTTP streamable funziona — Python (pacchetto mcp), TypeScript (@modelcontextprotocol/sdk) o qualsiasi SDK della community. Punta il suo trasporto HTTP all'endpoint sopra ed esegui il flusso standard initialize → tools/list → tools/call. Consulta examples/client_demo.py nel repository sorgente per un client Python minimale.

Catalogo strumenti (per caso d'uso)

37 strumenti distribuiti su cinque livelli. Raggruppali in base a ciò che vuoi fare:

Creazione di workout

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

Analisi di uscite / allenamento

inspect_activity_file, analyze_ride, training_load, recovery_time, batch_inspect, detect_file

Registro delle conoscenze

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

Percorsi e flussi di lavoro

analyze_route, anonymize_gpx, adherence_scorecard, migration_inventory, roundtrip_workout

Libreria

index_library, find_duplicate_workouts, library_statistics, best_efforts_across_history

Contenuti di Your Trainer

list_workout_library, get_library_workout, search_workout_library, list_ai_skills, search_manual, get_manual_section — recuperano la libreria curata di 266 workout, il catalogo delle skill dell'assistente AI integrato e il manuale del prodotto direttamente dall'MCP, in modo che l'LLM possa fondare le risposte ai ciclisti su contenuti canonici di Your Trainer.

Operazioni

get_health

Esempio di invocazione — creare un workout

Il caso d'integrazione più comune: un client LLM che compone un intento strutturato e chiede all'MCP di emettere un file di workout canonico. L'intento è un brief JSON (Riscaldamento + intervalli + Defaticamento, gruppi block + repeat, potenza come % intera di FTP). L'MCP restituisce un file .ytw, .zwo o .fit deterministico e validato dallo schema.

// 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 risposta porta il .ytw canonico come stringa più un riepilogo difficulty (IF / TSS / tempo in Zona). Passa output_format: "zwo" per Zwift, "fit" per i ciclocomputer Garmin (base64 nella risposta). Schema canonico: workout-schema.html.

Quali tipi di prompt funzionano meglio con questo MCP

Gli LLM sono bravi a comprendere l'intento del ciclista e a riconoscere pattern nelle strutture di workout. Sono inaffidabili in tre cose: emettere formati di file validi, calcolare correttamente metriche su serie temporali e rispettare i cataloghi di vincoli per app. L'MCP ti fornisce risposte deterministiche proprio per quelle — una volta registrato il server con il tuo client (sopra), l'LLM può concatenare il proprio ragionamento con il calcolo deterministico. Di seguito: le categorie di prompt che ora funzionano in modo molto più affidabile.

Creazione di workout

Prompt che traggono beneficio da build_workout_from_intent:

L'LLM sceglie la forma dell'intento (Riscaldamento / intervalli / Defaticamento, gruppi repeat, % FTP); l'MCP garantisce che il file sia validato dallo schema e venga importato correttamente nel ciclocomputer / app di allenamento.

Conversione di formato

Prompt che traggono beneficio da decompose_workout + build_workout_from_intent:

La conversione bidirezionale è una catena in una singola chiamata; roundtrip_workout permette all'LLM di autocorreggersi se una conversione perde fedeltà.

Modifica di workout

Prompt che traggono beneficio da scale_workout e dalla coppia build / decompose:

L'LLM non deve ricalcolare i tempi degli intervalli — l'MCP scala strutturalmente.

Analisi dell'allenamento

Prompt che traggono beneficio da training_load, inspect_activity_file, analyze_ride:

Gli LLM allucinano frequentemente i valori di TSS / IF / NP quando viene loro chiesto di calcolarli da dati grezzi. L'MCP restituisce la verità a terra.

Pacing e analisi del percorso

Prompt che traggono beneficio da analyze_route e dagli strumenti di pacing:

Operazioni di libreria

Prompt che traggono beneficio da find_duplicate_workouts, library_statistics, best_efforts_across_history:

Cosa serve ancora all'LLM (non all'MCP)

L'MCP non sostituisce l'LLM — gli fornisce strumenti deterministici. L'LLM continua a possedere:

Pensa all'MCP come alla calcolatrice + libreria di formati che l'LLM consulta. L'LLM è l'allenatore.

Matrice di conversione

La conversione deterministica dei workout è supportata solo tra .ytw, .zwo e FIT workout. decompose_workout(document, "zwo"|"ytw") restituisce un .ytw canonico; build_workout_from_intent(intent, output_format) emette "ytw" / "zwo" / "fit"; scale_workout ri-renderizza zwo ↔ ytw. ERG / MRC non rientrano nell'insieme deterministico — risiedono nel registro delle conoscenze e vengono convertiti dall'LLM, ancorati a get_format_spec / get_canonical_examples / get_conversion_notes e verificabili con validate("erg"|"mrc", doc).

Da ↓ A →.ytw.zwoFIT workoutERG / MRC
.ytwroundtrip (validate)✓ deterministico✓ deterministicoLLM + validate
.zwo✓ deterministicoroundtrip (validate)✓ deterministico (via .ytw)LLM + validate
FIT workout✓ via read_fit_workout✓ via read_fit_workoutroundtrip (validate)LLM + validate
ERG / MRCLLM + validateLLM + validateLLM + validateregistry-only

Come leggere la matrice: le celle "deterministico" passano attraverso una catena di strumenti che produce un file validato dallo schema senza LLM nel ciclo. Le celle "LLM + validate" usano l'LLM per comporre la conversione (ancorato dagli strumenti del registro sopra) e poi eseguono validate sull'output — l'MCP non genera ERG/MRC di propria iniziativa, per scelta progettuale (ADR-0003 correlato).

Per i file di attività (lato registrazione, non lato prescrizione): FIT attività, GPX, TCX, KML sono in sola lettura tramite inspect_activity_file, analyze_ride, analyze_route e detect_file. anonymize_gpx riscrive un GPX con l'area domestica ritagliata.

Lo strumento roundtrip_workout consente a un agente di autocorreggersi: converte A→B→A e confronta il profilo di potenza per rilevare conversioni con perdita. Utile quando si fa da ponte tra formati meno ricchi (ad es. ERG → ZWO perde gli obiettivi di Cadenza).

Contratto di trasferimento file

Secondo la policy di trasferimento file ADR-0005 dell'MCP:

La potenza è una percentuale intera di FTP (target_power_percent: 90 == 90% FTP) nel modello workout-intent, in ZWO e in .ytw. Gli errori emergono come errori di strumento MCP con un messaggio.

Attribuzione

Ogni risultato di strumento include un blocco _attribution che identifica il server MCP + versione. Gli strumenti che producono .ytw incorporano un indicatore Your Trainer in modo che gli strumenti a valle possano riconoscere l'origine del file. Si chiede agli integratori di preservare l'attribuzione quando mostrano l'output degli strumenti in un'interfaccia utente.

Privacy e statelessness

L'MCP è stateless by design:

La garanzia di assenza di dati del ciclista è documentata in PRIVACY.md del repository sorgente ed è verificata da un test dedicato test_statelessness.py nella suite CI. La posizione più ampia sulla privacy dell'app Your Trainer è sulla policy sulla privacy di Your Trainer.

Sorgente e licenza

Open source sotto la LICENSE del repository (vedi GitHub). Il tracciamento delle issue e la discussione avvengono sul repo GitHub yourtrainer-mcp. L'endpoint ospitato è gestito come bene pubblico — non c'è SLA, ma l'MCP stesso può essere self-hosted (vedi deploy/README.md nel repository sorgente) se hai bisogno di disponibilità garantita.

Riferimenti correlati