Your Applications

Español

Your Trainer MCP — Documentación para integradores

Endpoint: https://mcp.your-applications.com/your-trainer · Código fuente: github.com/edankert/yourtrainer-mcp · Última actualización: 31 de mayo de 2026

Un servidor Model Context Protocol autoalojado que ofrece a cualquier LLM compatible con MCP el material de referencia y las herramientas computacionales para trabajar con datos de ciclismo indoor: formatos de entrenamiento, formatos de ruta, archivos de actividad, cálculo de carga de entrenamiento, ritmo, operaciones de biblioteca. Lo usan las funciones de IA integradas de Your Trainer; disponible para cualquier cliente MCP.

Qué hace

Dos capas:

Registro de conocimiento

Documentación estructurada del ecosistema de formatos de ciclismo: .zwo (Zwift), ERG/MRC, FIT (entrenamiento + actividad), GPX, TCX, KML, .ytw (Your Trainer), paquetes de cadenas por idioma. Especificación por formato, ≥3 ejemplos canónicos, catálogo de restricciones (límites por aplicación), notas de conversión, glosario. Los LLM consultan el registro como referencia autorizada cuando realizan las conversiones de formato por sí mismos.

Herramientas de capacidad

Las operaciones que los LLM no pueden hacer solos de forma fiable:

Conectar

El servidor está alojado en https://mcp.your-applications.com/your-trainer y habla MCP sobre HTTP en streaming. No se requiere autenticación; los límites de tasa son únicamente operativos. Cada resultado de herramienta incluye un bloque _attribution; las herramientas que producen .ytw añaden una pista de Your Trainer.

Para desarrollo local, autoalojamiento o transporte stdio, consulta el repositorio fuente en github.com/edankert/yourtrainer-mcp.

Registrar el servidor en tu cliente LLM

La URL del endpoint MCP que debes registrar en todos los clientes siguientes es la misma:

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

Claude (Anthropic — Desktop / Web)

Abre Settings → Connectors → Add custom connector (planes Pro / Team / Enterprise). Define la URL como el endpoint anterior y asígnale un nombre amigable como Your Trainer. Claude ejecutará el handshake MCP y mostrará las herramientas disponibles la próxima vez que inicies un chat.

Para uso programático mediante la API de Anthropic, pasa el servidor en el campo de solicitud mcp_servers. Consulta la documentación del conector MCP de Anthropic para conocer la forma exacta.

Claude Code (CLI de Anthropic)

Registra el servidor una vez desde la línea de comandos:

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

Verifica con claude mcp list. Las herramientas aparecerán como mcp__yourtrainer__<tool_name> en sesiones posteriores. Consulta la documentación MCP de Claude Code para conocer las opciones de servidores con ámbito de proyecto frente a ámbito de usuario y otras.

ChatGPT (OpenAI)

Abre Settings → Connectors (planes Pro / Team / Enterprise) y añade un servidor MCP personalizado con la URL del endpoint anterior. ChatGPT negociará el handshake en la siguiente conversación que requiera uso de herramientas. Consulta la guía de MCP remoto de OpenAI para el recorrido canónico por la interfaz.

Para la API de OpenAI directamente, la Responses API acepta una entrada de herramienta mcp que apunte a la URL del servidor; el modelo puede entonces invocar herramientas en él durante una respuesta.

OpenAI Codex (CLI)

Añade una entrada a ~/.codex/config.toml:

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

O bien usa codex mcp add yourtrainer --url https://mcp.your-applications.com/your-trainer --transport http. Consulta la documentación del CLI de Codex para la sintaxis autoritativa actual (los nombres de campo pueden cambiar a medida que Codex se estabilice).

Cursor

Settings → Cursor Settings → MCP Servers → Add new MCP server. Nombre: yourtrainer. URL: el endpoint anterior. Transporte: HTTP. Cursor muestra las herramientas disponibles junto a las suyas integradas; el agente las elige en tiempo de inferencia.

Otros clientes MCP / SDK personalizado

Cualquier SDK MCP que hable streamable-HTTP funciona — Python (paquete mcp), TypeScript (@modelcontextprotocol/sdk) o cualquier SDK comunitario. Apunta su transporte HTTP al endpoint anterior y ejecuta el flujo estándar initialize → tools/list → tools/call. Consulta examples/client_demo.py en el repositorio fuente para un cliente Python mínimo.

Catálogo de herramientas (por caso de uso)

37 herramientas distribuidas en cinco capas. Agrúpalas por lo que quieras hacer:

Creación de entrenamientos

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

Análisis de rodadas / entrenamiento

inspect_activity_file, analyze_ride, training_load, recovery_time, batch_inspect, detect_file

Registro de conocimiento

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

Rutas y flujos de trabajo

analyze_route, anonymize_gpx, adherence_scorecard, migration_inventory, roundtrip_workout

Biblioteca

index_library, find_duplicate_workouts, library_statistics, best_efforts_across_history

Contenido de Your Trainer

list_workout_library, get_library_workout, search_workout_library, list_ai_skills, search_manual, get_manual_section — obtén la biblioteca curada de 266 entrenamientos, el catálogo de habilidades del asistente de IA integrado y el manual del producto directamente desde el MCP, para que el LLM pueda fundamentar sus respuestas a los ciclistas en contenido canónico de Your Trainer.

Operaciones

get_health

Invocación de ejemplo — construir un entrenamiento

El objetivo de integración más común: un cliente LLM compone una intención estructurada y pide al MCP que emita un archivo de entrenamiento canónico. La intención es un brief JSON (calentamiento + intervalos + vuelta a la calma, bloque + grupos repetidos, potencia como porcentaje entero de FTP). El MCP devuelve un .ytw, .zwo o .fit determinista y validado contra el esquema.

// 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 respuesta lleva el .ytw canónico como cadena más un resumen difficulty (IF / TSS / tiempo en zona). Pasa output_format: "zwo" para Zwift, "fit" para ciclocomputadores Garmin (en base64 en la respuesta). Esquema canónico: workout-schema.html.

Qué tipos de prompts funcionan mejor con este MCP

Los LLM son buenos entendiendo la intención del ciclista y reconociendo patrones de estructuras de entrenamiento. No son fiables en tres cosas: emitir formatos de archivo válidos, calcular correctamente métricas de series temporales y respetar los catálogos de restricciones por aplicación. El MCP te ofrece respuestas deterministas exactamente para eso — una vez registrado el servidor en tu cliente (arriba), el LLM puede encadenar su propio razonamiento con computación determinista. A continuación: las categorías de prompts que ahora funcionan de manera mucho más fiable.

Creación de entrenamientos

Prompts que se benefician de build_workout_from_intent:

El LLM elige la forma de la intención (calentamiento / intervalos / vuelta a la calma, grupos repetidos, % FTP); el MCP garantiza que el archivo sea válido según el esquema y se importe sin problemas al ciclocomputador / aplicación de entrenamiento.

Conversión de formatos

Prompts que se benefician de decompose_workout + build_workout_from_intent:

La conversión bidireccional es una cadena de una sola llamada; roundtrip_workout permite al LLM autocorregirse si una conversión pierde fidelidad.

Modificación de entrenamientos

Prompts que se benefician de scale_workout y del par construir / descomponer:

El LLM no tiene que recalcular los tiempos de los intervalos — el MCP escala estructuralmente.

Análisis de entrenamiento

Prompts que se benefician de training_load, inspect_activity_file, analyze_ride:

Los LLM alucinan con frecuencia los valores de TSS / IF / NP cuando se les pide calcularlos a partir de datos crudos. El MCP devuelve la verdad sobre el terreno.

Ritmo y análisis de rutas

Prompts que se benefician de analyze_route y las herramientas de ritmo:

Operaciones de biblioteca

Prompts que se benefician de find_duplicate_workouts, library_statistics, best_efforts_across_history:

Qué sigue necesitando al LLM (y no al MCP)

El MCP no reemplaza al LLM — le da herramientas deterministas. El LLM sigue siendo responsable de:

Piensa en el MCP como la calculadora + biblioteca de formatos que el LLM consulta. El LLM es el entrenador.

Matriz de conversión

La conversión determinista de entrenamientos solo se admite entre .ytw, .zwo y FIT de entrenamiento. decompose_workout(document, "zwo"|"ytw") devuelve un .ytw canónico; build_workout_from_intent(intent, output_format) emite "ytw" / "zwo" / "fit"; scale_workout vuelve a renderizar zwo ↔ ytw. ERG / MRC no están en el conjunto determinista — viven en el registro de conocimiento y los convierte el LLM, fundamentado por get_format_spec / get_canonical_examples / get_conversion_notes y verificable con validate("erg"|"mrc", doc).

De ↓ A →.ytw.zwoFIT workoutERG / MRC
.ytwround-trip (validar)✓ determinista✓ deterministaLLM + validar
.zwo✓ deterministaround-trip (validar)✓ determinista (vía .ytw)LLM + validar
FIT workout✓ vía read_fit_workout✓ vía read_fit_workoutround-trip (validar)LLM + validar
ERG / MRCLLM + validarLLM + validarLLM + validarsolo registro

Cómo leer la matriz: las celdas «determinista» pasan por una cadena de herramientas que produce un archivo validado contra el esquema, sin LLM en el bucle. Las celdas «LLM + validar» usan el LLM para componer la conversión (fundamentado por las herramientas de registro mencionadas arriba) y luego ejecutan validate sobre la salida — el MCP no genera ERG/MRC por sí mismo, por diseño (ADR-0003 hermana).

Para archivos de actividad (la grabación, no la prescripción): FIT de actividad, GPX, TCX y KML son de solo lectura mediante inspect_activity_file, analyze_ride, analyze_route y detect_file. anonymize_gpx reescribe un GPX con el área del domicilio recortada.

La herramienta roundtrip_workout permite a un agente autocorregirse: convierte A→B→A y compara el perfil de potencia para detectar conversiones con pérdidas. Útil al puentear formatos menos ricos (por ejemplo, ERG → ZWO pierde los objetivos de cadencia).

Contrato de transferencia de archivos

Según la política de transferencia de archivos ADR-0005 del MCP:

La potencia es un porcentaje entero de FTP (target_power_percent: 90 == 90 % FTP) en el modelo de intención de entrenamiento, ZWO y .ytw. Los errores afloran como errores de herramienta MCP con un mensaje.

Atribución

Cada resultado de herramienta incluye un bloque _attribution que identifica el servidor MCP + la versión. Las herramientas que producen .ytw incrustan una pista de Your Trainer para que las herramientas posteriores reconozcan el origen del archivo. Se pide a los integradores que preserven la atribución al mostrar la salida de las herramientas en una interfaz de usuario.

Privacidad y ausencia de estado

El MCP es sin estado por diseño:

La garantía de no manejar datos del ciclista está documentada en el PRIVACY.md del repositorio fuente y se aplica mediante un test específico test_statelessness.py en la suite de CI. La postura de privacidad más amplia de la aplicación Your Trainer está en la política de privacidad de Your Trainer.

Código fuente y licencia

Código abierto bajo la LICENSE del repositorio (ver GitHub). El seguimiento de incidencias y la discusión se realizan en el repositorio yourtrainer-mcp en GitHub. El endpoint alojado se opera como bien público — no hay SLA, pero el MCP puede autoalojarse (consulta el deploy/README.md del repositorio fuente) si necesitas disponibilidad garantizada.

Referencias relacionadas