RunCoach

En vivo: runcoach-ruby.vercel.app · MCP endpoint https://runcoach-ruby.vercel.app/mcp

Un servidor MCP que expone los datos de entrenamiento propios de un corredor — carga de entrenamiento calculada, predicciones de tiempo de carrera, planes generados — como herramientas que un LLM puede invocar.

El objetivo es la base factual. Pregúntale a cualquier asistente "¿debería tomármelo con calma esta semana?" y producirá un consejo de entrenamiento plausible partiendo de la nada. RunCoach hace que la misma pregunta se resuelva contra las actividades reales registradas del atleta, con la respuesta llevando las carreras específicas de las que proviene:

Tú: ¿Cómo va mi entrenamiento, y qué podría correr en una media maratón?

Claude (llama a analyze_training_status, luego predict_race_time): El entrenamiento es consistente y la carga es estable — 46.8 km/week en 17 carreras en los últimos 28 días, con una relación agudo-crónico de 1.00 y sin brecha de más de tres días. La condición física se está manteniendo más que construyendo, que es el lugar adecuado entre metas y vale la pena cambiar si tienes una carrera próxima.

Para la media: 1:38:49, muy probablemente entre 1:36:50 y 1:40:48. Eso se ajusta a tu propia curva distancia/tiempo en tus 5K (21:30, 8 de julio), 10K (44:50, 3 de junio) y media (1:38:48, 29 de abril) — tu exponente de fatiga resultó ser 1.059 frente a un promedio poblacional de 1.06, por lo que mantienes el ritmo aproximadamente tan bien como es típico a medida que la distancia crece. Se excluyó una actividad: un 3 km el 28 de julio registrado a un ritmo más rápido que el récord mundial para esa distancia, casi con certeza un error de GPS.

Cada cifra anterior es salida real del atleta de prueba de npm test, no una ilustración — las cadenas exactas aparecen en test/readme.test.ts, que falla si la ciencia cambia y el README no se actualiza con ella. Cada herramienta devuelve una confianza y una explicación de cómo se derivó su número, y las instrucciones del servidor le dicen al modelo que transmita ambas. Una predicción expresada sin su base es indistinguible de una suposición.

Herramientas

Related MCP server: livetrack-mcp

De dónde provienen los números

RunCoach no reimplementa nada. Cada cálculo proviene de @runman/core, el paquete científico probado con datos de prueba que también respalda la aplicación web Runman. Hacerle una pregunta a Claude y cargar la página correspondiente ejecutan el mismo código contra la misma base de datos.

Ese paquete está incluido aquí como un submódulo de git, y las pruebas de RunCoach importan el mismo archivo de datos de prueba que usan las pruebas de Runman — así que "qué debería producir estos datos" tiene una definición en ambos repositorios en lugar de dos que divergen.

git clone --recursive https://github.com/varun-gangadharan/runcoach
npm install
npm test          # 31 tests, no database or credentials required

Decisiones de diseño que vale la pena explicar

Las herramientas no toman un ID de atleta. La clave API se resuelve exactamente a un atleta, y ese ID se convierte en el contexto de la herramienta. Si un modelo pudiera pasar un ID de atleta, una instrucción inyectada por prompt en un título de actividad podría pedírselo — y la carga aquí son datos personales de salud de alguien. Simplemente no hay argumento por el cual la clave de un atleta pueda leer los datos de otro. Una prueba asegura que esto se mantenga.

Una negativa es una respuesta válida. Cuando no hay datos que respalden una predicción, la herramienta lo dice y le indica al modelo que no sustituya una estimación. Lo mismo para la generación de planes: si el atleta no tiene entrenamiento reciente, o la carrera es dentro de tres semanas, se niega con una razón en lugar de producir un plan basado en una línea base supuesta. Los modelos llenan los vacíos por defecto; la salida de la herramienta debe contrarrestar activamente.

La salida es prosa, no JSON. Los modelos parafrasean oraciones de manera más fiel que leer objetos anidados, y son mucho menos propensos a inventar un campo que no estaba allí. Las cifras precisas aún aparecen — dentro de las oraciones.

Cada solicitud HTTP construye su propia instancia de servidor. Compartir una entre invocaciones en un entorno serverless corre el riesgo de intercalar las sesiones de dos atletas dentro de un contenedor cálido. Ese no es un modo de fallo aceptable aquí.

Despliegue

El transporte HTTP es una única función de Vercel. La autenticación es un token bearer — una clave API que el atleta emite desde la página de perfil de Runman, almacenada solo como un hash SHA-256.

vercel env add SUPABASE_URL
vercel env add SUPABASE_SERVICE_ROLE_KEY
vercel deploy --prod

Ten en cuenta que el punto de entrada de Vercel (api/mcp.js) es JavaScript plano que reexporta el manejador compilado desde dist/, en lugar de TypeScript importando src/. Vercel compila una función .ts en su lugar pero deja los especificadores de importación relativos intactos, por lo que un especificador .ts sobrevive en el paquete desplegado y falla en tiempo de ejecución buscando un archivo que nunca se envió.

Después de desplegar, verifícalo de extremo a extremo con un cliente MCP real:

node --experimental-strip-types scripts/verify-deployment.ts \
  https://runcoach-ruby.vercel.app/mcp rc_live_...

Eso se conecta a través de la red exactamente como lo haría Claude — handshake, descubrimiento de herramientas, luego una llamada a cada una de las cinco herramientas — y asegura que las respuestas vuelven fundamentadas en lugar de meramente bien formadas.

Luego agrégalo en cualquier cliente MCP:

{
  "mcpServers": {
    "runcoach": {
      "type": "http",
      "url": "https://runcoach-ruby.vercel.app/mcp",
      "headers": { "Authorization": "Bearer rc_live_..." }
    }
  }
}

Ejecución local sobre stdio

Para usar contra tus propios datos en tu propia máquina:

{
  "mcpServers": {
    "runcoach": {
      "command": "node",
      "args": ["/absolute/path/to/runcoach/dist/stdio.js"],
      "env": {
        "SUPABASE_URL": "...",
        "SUPABASE_SERVICE_ROLE_KEY": "...",
        "RUNCOACH_API_KEY": "rc_live_..."
      }
    }
  }
}

Un servidor stdio no tiene solicitudes que autenticar — se ejecuta como un proceso hijo del cliente — por lo que el atleta se fija en el inicio. Eso solo es apropiado en la propia máquina del atleta, por lo que el transporte desplegado lo hace por solicitud en su lugar.

Pruebas

npm test

31 pruebas en tres capas: los manejadores de herramientas contra el conjunto de datos de prueba compartido de Runman (corredor consistente, corredor sin frecuencia cardíaca, actividad única, historial vacío, historial con fallo de GPS, corredor esporádico, corredor que regresa, pico de volumen), y una prueba de protocolo de extremo a extremo que conecta un cliente MCP real a un servidor real y lo conduce a través del descubrimiento de herramientas, validación de esquema e invocación. La tercera capa fija las cifras de ejemplo citadas en este README.

No incluido en v1

Herramientas con fuente de Garmin (recuperación, sueño, HRV) mediante proxy a un servidor MCP de Garmin ascendente, controlado por el atleta que haya vinculado una cuenta. Deliberadamente separable, para que un atleta sin Garmin no vea degradación.

Licencia

MIT.