使用说明

🏋️ 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

Ve a ChatGPT → Create a GPT
Configure → Actions
Click Import from URL
Pega: https://freelytics-rober.duckdns.org/openapi.json
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

Fork este repo
Nuevo proyecto en Railway → Import from GitHub
Añadir PostgreSQL addon
Configurar variables de entorno:
- DB_HOST
- DB_NAME
- DB_USER
- DB_PASSWORD
- ENCRYPTION_KEY
Deploy automático al hacer push

Render

Fork este repo
New Web Service → Connect repository
Runtime: Python 3
Build: pip install -r requirements.txt
Start: uvicorn main:app --host 0.0.0.0 --port $PORT
Añadir PostgreSQL service
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

#� �f�r�e�e�l�y�t�i�c�s�-�m�c�p� � �