Servidor MCP de Intervals.icu y Entrenador de Running con IA

Un Servidor de Protocolo de Contexto de Modelo (MCP) de nivel oficial y un Sistema de Inteligencia de Entrenador de Running con IA para Intervals.icu.

Potencia a tus asistentes de IA (Claude Desktop, Antigravity, Cursor, VS Code Cline / Roo-Code) para leer telemetría en tiempo real, evaluar la carga de entrenamiento aguda y crónica (CTL/ATL/TSB/ACWR), calcular el VDOT de Jack Daniels y las zonas de ritmo, calcular la deriva cardíaca y el desacoplamiento aeróbico, predecir tiempos de carrera, planificar la puesta a punto y publicar entrenamientos estructurados directamente en tu calendario de Intervals.icu.

📑 Índice de Contenidos

• ✨ Capacidades Clave

• 🚀 Inicio Rápido en 3 Minutos

• ⚙️ Configuración (Clave API e ID de Atleta)

• 🔌 Guías de Configuración de Clientes MCP

  • Claude Desktop

  • Antigravity

  • Cursor

  • VS Code (Cline / Roo-Code)

• 🤖 Directorio de Flujos de Trabajo de IA y Comandos de Barra

• 👤 Personalización de tu Perfil de Atleta

• 💬 Ejemplos de Prompts de Chat

• 🛠️ Referencia Completa de Herramientas MCP

• 🧪 Desarrollo y Pruebas

• 📄 Licencia

Related MCP server: Intervals.icu MCP Server

✨ Capacidades Clave

• 🏃 Telemetría en Tiempo Real e Ingestión de Flujos de Datos: Extrae vatios, frecuencia cardíaca, cadencia, velocidad y parciales de intervalos de sesiones completadas.

• ⚡ Motor de Desacoplamiento Aeróbico y Deriva Cardíaca: Calcula el Factor de Eficiencia (EF) $H_1$ vs $H_2$ para detectar deriva cardiovascular (>5%) o deshidratación.

• 🩹 Puntuación Unificada de Recuperación y Disposición: Puntuación compuesta del 0–100% que combina TSB, ACWR, Puntuación de Sueño, VFC y Pico de FCR en señales de acción Verde/Amarillo/Rojo.

• 🏆 Predictor de Tiempos de Carrera y Planificador de Puesta a Punto: Fórmula VDOT de Jack Daniels + ajustes de forma física CTL y frescura TSB + generador de reducción de volumen de 2–3 semanas.

• ⚖️ ACWR y Presupuesto de Carga Semanal: Límites seguros de progresión de volumen (Rodaje Largo 30–35%, Calidad 15–20%, Suave 45–55%) basados en una línea base móvil de 42 días.

• 📅 Constructor de Entrenamientos Estructurados: Publica entrenamientos en el calendario de Intervals.icu usando el DSL de texto nativo de Intervals (Warmup, Main Set Nx, Cooldown).

🚀 Inicio Rápido en 3 Minutos

1. Requisitos Previos

• Node.js: >= 18.0.0

• Gestor de Paquetes: pnpm (recomendado), npm o yarn

• Cuenta de Intervals.icu y Clave API

2. Clonar y Compilar

git clone https://github.com/hadidwirsty/intervals-icu-mcp.git
cd intervals-icu-mcp
pnpm install
pnpm run build

⚙️ Configuración

Obtén tus credenciales en Configuración de Intervals.icu:

1. Desplázate hasta la sección Developer.

2. Copia tu Clave API (p. ej. your_api_key_here).

3. Anota tu ID de Atleta (se encuentra en la configuración o en la URL del perfil, p. ej. i12345 o usa self).

Variables de Entorno

🔌 Guías de Configuración de Clientes MCP

1. Claude Desktop

Añade lo siguiente a tu claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "YOUR_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "self"
      }
    }
  }
}

2. Antigravity

En tu configuración MCP de Antigravity o en .gemini/config/mcp.json:

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "YOUR_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "self"
      }
    }
  }
}

3. Cursor

En Configuración de Cursor > Funciones > Servidores MCP o en .cursor/mcp.json:

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "YOUR_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "self"
      }
    }
  }
}

4. VS Code (Cline / Roo-Code)

En cline_mcp_settings.json:

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "YOUR_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "self"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

🤖 Directorio de Flujos de Trabajo de IA y Comandos de Barra

Este repositorio viene precargado con 11 Flujos de Trabajo de IA listos para producción en .agents/workflows/ que puedes activar usando comandos de barra:

👤 Personalización de tu Perfil de Atleta

Para dar a tu Asistente de IA un contexto de entrenamiento preciso, configura tu perfil en .agents/skills/running-coach-analysis/SKILL.md:

1. Sección 2 (Perfil de Atleta): Rellena tu nombre, edad, peso de respaldo y objetivos de carrera.

2. Sección 3 (Línea Base Fisiológica): Proporciona CP/FTP, FCL, FC Máx y FC en Reposo de respaldo (nota: los valores activos se sincronizan automáticamente de forma dinámica mediante MCP).

3. Sección 4 (Estructura Semanal y Planes Base): Define tu frecuencia semanal de entrenamiento, las sesiones preferidas (p. ej. Subumbral, VO2Max, Rodaje Largo) y los objetivos específicos de potencia/ritmo.

💬 Ejemplos de Prompts de Chat

Aquí tienes ejemplos de cómo puedes chatear con tu Entrenador de Running con IA:

1. Evaluación Diaria Post-Carrera

"Aquí tienes mi entrenamiento de esta mañana. Por favor, ejecuta /run-report en mi última actividad. El RPE fue 6/10, las piernas se sentían elásticas durante el 3er intervalo."

2. Verificación de Disposición Pre-Entrenamiento

"/readiness-check — ¿Estoy bien recuperado para la sesión de intervalos Subumbral de hoy, o debería limitar la intensidad a la Zona 2?"

3. Asignación de Volumen Semanal

"/weekly-budget distance — ¿Cuál es mi kilometraje total recomendado y el límite de Rodaje Largo para esta semana?"

4. Predicción del Día de Carrera y Puesta a Punto

"/predict-race — Mi VDOT activo es 50 y mi carrera objetivo de Medio Maratón es el 2026-10-15. Dame la predicción del tiempo de llegada y el programa de puesta a punto de 2 semanas."

5. Programar un Entrenamiento en el Calendario

"/create-workout — Programa una sesión Subumbral de 50 minutos (Calentamiento 12m, 6x3m @ 95-98% CP con 1m de descanso, Enfriamiento 6m) para mañana."

🛠️ Referencia Completa de Herramientas MCP

El servidor expone más de 20 herramientas agrupadas por categoría:

🏃 1. Actividades y Flujos de Datos

• get_activities: Obtiene actividades dentro de un rango de fechas (oldest, newest, type).

• get_activity_details: Recupera la telemetría completa, las métricas y los valores fisiológicos del atleta para un ID de actividad.

• get_activity_intervals: Extrae el desglose de vueltas e intervalos de trabajo/descanso.

• get_activity_streams: Accede a los datos brutos de series temporales (watts, heartrate, cadence, velocity_smooth, altitude).

• get_activity_messages: Lee comentarios y notas de la actividad.

• add_activity_message: Publica comentarios de entrenamiento en una actividad.

👤 2. Biometría y Zonas del Atleta

• get_athlete_profile: Recupera el perfil del atleta (FTP, FCL, FC Máx, peso, FC en reposo).

• get_training_zones: Accede a los límites de las zonas de entrenamiento de potencia, frecuencia cardíaca y ritmo.

🧮 3. Fisiología e Inteligencia de Resistencia (Offline)

• calculate_vdot: Calcula el VDOT de Jack Daniels y el VO₂máx a partir de una prueba de ritmo/temporal.

• calculate_pace_zones: Calcula las 5 zonas de ritmo de entrenamiento (Suave, Maratón, Umbral, Intervalo, Repetición) en MM:SS/km.

• predict_race_time: Predice el tiempo de llegada y el ritmo de carrera (5K, 10K, MM, FM o km personalizado) a partir del VDOT con ajustes de forma física CTL y frescura TSB.

• calculate_taper_plan: Genera un programa semanal de reducción de volumen (75% → 50% → 30%) para alcanzar la máxima frescura TSB el día de la carrera.

• analyze_cardiac_drift: Calcula el Factor de Eficiencia (EF) y el % de Desacoplamiento Aeróbico a partir de flujos de datos de telemetría brutos (heartrateStream, powerOrSpeedStream).

• calculate_readiness_score: Calcula la puntuación unificada de recuperación (0–100%, Verde/Amarillo/Rojo) combinando TSB, ACWR, Sueño, VFC y FCR.

⚖️ 4. Carga de Entrenamiento y Periodización (Offline)

• analyze_training_load: Calcula el ACWR (ATL/CTL), clasifica las zonas de disposición TSB y evalúa el riesgo de lesión por ramp rate.

• calculate_weekly_budget: Calcula el presupuesto semanal seguro de entrenamiento (Volumen Total, Rodaje Largo 30–35%, Calidad 15–20%, Suave 45–55%) basado en el promedio móvil de 42 días.

📅 5. Calendario y Constructor de Entrenamientos

• get_events: Recupera elementos del calendario (entrenamientos planificados, notas, carreras) en un rango de fechas.

• get_event_by_id: Obtiene datos detallados de un evento por ID.

• create_running_workout: Constructor de Entrenamientos Estructurados — Valida y publica entrenamientos estructurados en el calendario de Intervals.icu usando el DSL de texto.

• add_or_update_planned_workout: Crea o actualiza eventos de entrenamiento planificados.

• add_or_update_note: Añade notas de texto a fechas del calendario.

• delete_event: Elimina eventos del calendario por ID.

• get_workout_library: Busca en la biblioteca de plantillas de entrenamiento.

• get_workout_by_id: Obtiene los detalles de una plantilla de entrenamiento.

🚴 6. Equipamiento y Curvas de Potencia

• get_gear_list: Lista bicicletas, zapatillas y equipamiento registrados con kilometraje (caché de 30 min).

• get_athlete_power_curves: Obtiene las curvas de duración de potencia (caché de 60 min).

💚 7. Series Temporales de Bienestar y Forma Física

• get_wellness_data: Recuperar entradas diarias de bienestar (puntuación de sueño, VFC, FC en reposo, fatiga, dolor muscular, peso).

• get_fitness_chart: Recuperar datos de fitness en series temporales (ctl, atl, tsb, rampRate, eftp).

🧪 Desarrollo y Pruebas

Ejecuta la suite completa de pruebas unitarias:

# Run Vitest unit tests
pnpm test

# Build TypeScript
pnpm run build

# Watch mode during development
pnpm exec vitest

Incluye más de 59 pruebas unitarias que cubren el reintento automático del cliente API en HTTP 429, caché LRU con TTL, matemáticas de VDOT de Jack Daniels, predicción de carrera, análisis de deriva cardíaca, puntuación de recuperación, análisis ACWR y validación del DSL de entrenamiento.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT © Muhammad Hadid Wiransetyo.