Freelytics MCP

🏋️ Freeletics MCP - GPT Integration Backend

Backend FastAPI para integrar Freeletics con GPTs personalizados de ChatGPT.

🎯 Arquitectura

Usuario → GPT personalizado → Actions (API REST) → Este Backend → freeletics-python → API Freeletics

🚀 Características

• ✅ Autenticación con API Key (una sola vez)
• ✅ Credenciales encriptadas en PostgreSQL
• ✅ Auto-deploy con GitHub Actions
• ✅ Schema OpenAPI automático para GPTs
• ✅ HTTPS con certificados SSL

📦 Stack Tecnológico

• Backend: FastAPI + Python 3
• Base de Datos: PostgreSQL
• Encriptación: Fernet (cryptography)
• Cliente Freeletics: freeletics-python
• Server: Uvicorn + PM2
• Proxy: Nginx + Certbot (SSL)

🔧 Setup Local

1. Clonar el repositorio

git clone https://github.com/roberwild/freelytics-mcp.git
cd freelytics-mcp

2. Crear entorno virtual e instalar dependencias

Linux/Mac:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

Windows (CMD):

python -m venv venv
venv\Scripts\activate.bat
pip install -r requirements.txt

⚠️ Importante: La librería freeletics-python requiere Python >= 3.8 y < 3.12. Si tienes Python 3.12+, instala Python 3.11 desde python.org

3. Generar encryption key

python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

4. Configurar variables de entorno

cp .env.sample .env
# Editar .env con tus valores reales

5. Iniciar base de datos PostgreSQL

# Crear base de datos
createdb freelytics

# O con psql:
psql -U postgres
CREATE DATABASE freelytics;

6. Ejecutar el servidor

uvicorn main:app --reload --port 3001

El servidor estará disponible en http://localhost:3001

📡 Endpoints

GET /

Health check básico

GET /health

Estado del servicio

POST /register

Registra un nuevo usuario y devuelve API key

Request:

{
  "freeletics_username": "tu_usuario",
  "freeletics_password": "tu_password"
}

Response:

{
  "api_key": "flt_abc123...",
  "message": "Registration successful. Save this API key for your GPT."
}

GET /profile

Obtiene el perfil del usuario (requiere API key)

GET /workouts

Obtiene los entrenamientos del usuario (requiere API key)

GET /stats

Obtiene estadísticas del usuario (requiere API key)

DELETE /unregister

Elimina la cuenta del usuario (requiere API key)

🤖 Configurar GPT en ChatGPT

1. Registrar tu usuario

curl -X POST https://freelytics-rober.duckdns.org/register \
  -H "Content-Type: application/json" \
  -d '{
    "freeletics_username": "tu_usuario",
    "freeletics_password": "tu_password"
  }'

IMPORTANTE: Guarda el API key devuelto

2. Obtener OpenAPI Schema

Visita: https://freelytics-rober.duckdns.org/openapi.json

3. Crear GPT en ChatGPT

1. Ve a ChatGPT → Create a GPT
2. Configure → Actions
3. Click Import from URL
4. Pega: https://freelytics-rober.duckdns.org/openapi.json
5. Authentication → API Key

- Auth Type: Custom - Header Name: X-API-Key - API Key: flt_abc123... (el que guardaste)

4. Instructions del GPT

Eres FreeFit AI, un asistente personal de fitness que ayuda al usuario a gestionar y entender sus entrenamientos de Freeletics.

CAPACIDADES:
- Consultar el perfil del usuario
- Ver historial de entrenamientos
- Mostrar estadísticas y progreso
- Dar recomendaciones basadas en los datos

COMPORTAMIENTO:
- Habla de forma cercana y motivadora
- Cuando el usuario pregunte por sus entrenamientos, usa la acción getWorkouts
- Cuando pregunte por su progreso o estadísticas, usa getStats
- Presenta los datos de forma clara y visual cuando sea posible
- Si hay un error de autenticación, indica al usuario que debe configurar su API key

FORMATO:
- Usa emojis con moderación 💪
- Presenta tablas cuando muestres datos comparativos
- Resume los datos largos, no los vuelques en bruto

PRIMER USO:
Si el usuario no ha configurado su API key, explícale:
1. Ir a https://freelytics-rober.duckdns.org/register
2. Introducir sus credenciales de Freeletics
3. Copiar el API key generado
4. Volver aquí y cuando se le pida, pegar el API key

🐳 Deploy en Raspberry Pi

Ver guía completa en FREELETICS_SETUP_GUIDE.md

Resumen rápido:

# 1. Instalar PostgreSQL
sudo apt install postgresql postgresql-contrib -y

# 2. Crear base de datos
sudo -u postgres psql
CREATE DATABASE freelytics;

# 3. Clonar proyecto
git clone https://github.com/roberwild/freelytics-mcp.git
cd freelytics-mcp

# 4. Configurar entorno virtual
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 5. Configurar ecosystem.config.cjs con valores reales

# 6. Iniciar con PM2
pm2 start ecosystem.config.cjs
pm2 save

🌐 Deploy en Railway/Render

Railway

1. Fork este repo
2. Nuevo proyecto en Railway → Import from GitHub
3. Añadir PostgreSQL addon
4. Configurar variables de entorno:

- DB_HOST - DB_NAME - DB_USER - DB_PASSWORD - ENCRYPTION_KEY

1. Deploy automático al hacer push

Render

1. Fork este repo
2. New Web Service → Connect repository
3. Runtime: Python 3
4. Build: pip install -r requirements.txt
5. Start: uvicorn main:app --host 0.0.0.0 --port $PORT
6. Añadir PostgreSQL service
7. Configurar variables de entorno

🔒 Seguridad

• Las credenciales de Freeletics se encriptan con Fernet antes de guardarse
• Cada usuario recibe un API key único de un solo uso
• Las credenciales nunca se exponen en las respuestas
• HTTPS obligatorio para GPT Actions

📝 Notas Importantes

• ⚠️ La API de Freeletics es no oficial (reverse-engineered)
• ⚠️ Los tokens pueden expirar - el cliente maneja el refresh automáticamente
• ⚠️ Freeletics podría cambiar su API en cualquier momento

🤝 Contribuir

Pull requests son bienvenidos. Para cambios mayores, abre un issue primero.

📄 Licencia

MIT

🔗 Enlaces

• Librería freeletics-python: https://github.com/mkb79/freeletics-python
• FastAPI Docs: https://fastapi.tiangolo.com
• OpenAI GPT Actions: https://platform.openai.com/docs/actions

Hecho con 💪 para conectar Freeletics con ChatGPT

freelytics-mcp