Proyecto propio · Open source
Hevy Coach MCP
Conectar un asistente con el registro de entrenamiento para que pueda trabajar con datos reales y cálculos explícitos, en lugar de estimar el progreso a partir de una conversación.
El problema: dar contexto fiable al asistente
Los entrenamientos, las rutinas y las medidas están en Hevy. Para analizarlos en una conversación hace falta conectar ese historial y convertirlo en información comparable. Construí un servidor MCP que consulta la API de Hevy y calcula métricas de progreso, volumen y constancia.
La decisión: consultar y calcular antes de interpretar
El servidor obtiene los datos en vivo y realiza los cálculos; el cliente MCP recibe los resultados para elaborar una respuesta. Esta separación hace explícita la diferencia entre una métrica calculada y la interpretación del asistente.
- API de Hevy: entrenamientos, rutinas, ejercicios y medidas.
- Servidor MCP: herramientas de consulta, cálculo y escritura con responsabilidades separadas.
- Cliente compatible: conversación, interpretación y controles de autorización.
No hay una caché local ni una base de datos de entrenamientos. Así se evita mantener una segunda copia sincronizada. El compromiso es depender de la disponibilidad, latencia y límites de la API en cada consulta.
Los límites de escritura forman parte del diseño
El proyecto permite crear y actualizar rutinas, crear carpetas y registrar medidas corporales. No escribe en el historial de entrenamientos, que es la base de los cálculos.
Las herramientas llevan indicaciones de lectura o escritura para el cliente MCP. Esas indicaciones ayudan al cliente a decidir cuándo pedir confirmación; no son, por sí solas, una garantía de consentimiento impuesta por el servidor.
La clave de Hevy no ofrece permisos granulares. Por eso es importante distinguir lo que permite la credencial de las operaciones que este servidor expone.
Diseñar para una escritura que no se puede deshacer
Un error HTTP no siempre significa que una operación no haya ocurrido. Si una creación llega a Hevy pero la respuesta falla, repetirla puede generar un duplicado. La integración no dispone de una operación de borrado para compensarlo. Esa restricción cambia cómo se preparan y ejecutan las escrituras.
- Resolver antes de enviar. Al crear una rutina, primero se resuelven los nombres de todos sus ejercicios. Si uno es desconocido o ambiguo, la herramienta devuelve el problema y no envía una rutina incompleta.
- Reintentar según la operación. El cliente permite reintentos acotados ante respuestas 5xx en lecturas, pero no en escrituras. Las respuestas 429 se tratan aparte. Se acepta devolver un error antes que arriesgar una creación duplicada.
- Leer antes de actualizar. Cuando la API reemplaza un registro completo, omitir campos puede borrarlos. La herramienta recupera el estado existente: preserva las medidas no indicadas y, al cambiar el título de una rutina, los descansos y rangos de repeticiones de sus ejercicios. Reemplazar explícitamente los ejercicios sigue siendo una operación destructiva.
Son defensas frente a fallos concretos, no una transacción distribuida ni una garantía de ejecución exactamente una vez. Una modificación concurrente entre la lectura y la escritura sigue siendo un límite de este enfoque.
Ausencia de datos no significa progreso cero
El motor de cálculo recibe datos y devuelve resultados sin consultar la API. Esto permite comprobar fórmulas con entradas conocidas y mantener la interpretación fuera de la aritmética. Para estimar la repetición máxima, una serie sin peso o repeticiones válidas se excluye; si ninguna serie sirve, el resultado es nulo. Una sola medición de peso tampoco se convierte en una tendencia.
La alternativa de rellenar esos huecos con ceros produciría una respuesta más completa en apariencia, pero confundiría falta de información con un resultado medido. El asistente debe poder decir que no tiene datos suficientes.
Las pruebas públicas incluyen nombres ambiguos que no producen escrituras, conservación de campos al actualizar, creaciones fallidas que no se repiten y series que no pueden puntuarse. Estas pruebas comprueban reglas del servidor con datos controlados; no demuestran por sí solas la disponibilidad de Hevy ni la calidad de las respuestas de un modelo.
Una forma de comprobarlo
Con una cuenta Hevy PRO y una clave API configurada en un cliente compatible, se puede empezar por comprobar la conexión y comparar dos periodos:
Comprueba la conexión con Hevy. Compara el número de entrenamientos y el volumen de las últimas cuatro semanas con las cuatro anteriores. Explica qué datos has utilizado y qué no puedes concluir.
Es una propuesta de consulta, no una captura de un resultado real. El repositorio incluye las instrucciones de conexión, las herramientas disponibles y sus límites.
Consultar la guía de conexión (abre en otra pestaña)Qué demuestra este proyecto
Una integración entre una API externa y clientes de IA, con cálculos separados de la conversación y un alcance de escritura delimitado. El resultado verificable es el código y su documentación pública; no se presentan métricas de adopción ni mejoras deportivas no medidas.
Código y pruebas públicas revisados el 27 de septiembre de 2026. Los enlaces técnicos apuntan al commit c3a2326 para mantener verificables las decisiones descritas.