kinielagpt 1.0.3

MCP server for Spanish football quiniela predictions using LAE probabilities and match analysis

KinielaGPT - Kiniela Game Prediction Tool

KinielaGPT es un servidor MCP (Model Context Protocol) diseñado para potenciar tus predicciones de la Quiniela mediante un análisis avanzado de datos. Combina las probabilidades oficiales de LAE con un análisis contextual profundo: histórico de enfrentamientos, rachas recientes, clasificación y rendimiento como local o visitante. Ofrece tres estrategias de predicción, detección de sorpresas y un análisis pormenorizado partido a partido.

🎯 Características

🎲 Predicción de Resultados

Genera pronósticos mediante tres estrategias: conservadora (máxima probabilidad), arriesgada (balancea probabilidad y contexto) o personalizada (indicando el número de 'unos', 'equis' y 'doses').

📊 Análisis Integral de Partidos

Integra probabilidades de LAE, histórico de duelos (últimos 10 años), rachas, clasificación y contexto para ofrecer una predicción razonada.

🔍 Detección de Sorpresas

Detecta discrepancias entre las probabilidades oficiales y el rendimiento real (rachas, histórico, forma) para anticipar posibles sorpresas.

👥 Estado de Forma de Equipos

Evalúa el rendimiento detallado: últimos marcadores, rachas vigentes, desempeño local/visitante y tendencias clasificatorias.

📈 Consulta Flexible de Datos

Accede tanto a análisis interpretados como a los datos en bruto para sacar tus propias conclusiones.

🔌 Servidor MCP Nativo

Incluye 7 herramientas especializadas, totalmente compatibles con Claude Desktop, VS Code y otros clientes MCP.

---

🏁 Pasos para empezar a usar KinielaGPT

Sigue estos pasos para tener KinielaGPT listo y funcionando en tu equipo:

1. Instala UV o Python 3.10+ en tu PC.
2. Instala KinielaGPT.
3. Configura el servidor MCP, eligiendo Claude o VS Code como cliente.

Una vez completados estos pasos, ¡ya puedes empezar a hacer predicciones y análisis con KinielaGPT!

---

✅ Instalar UV o Python 3.10+

Antes de usar KinielaGPT necesitaras tener instalado UV (recomendado) o Python 3.10+.

A continuación se muestran como instalar las dos opciones, aunque debes elegir una de las dos:

Opción 1: UV (Recomendado) ⚡

UV es un gestor de paquetes y proyectos Python ultrarrápido que simplifica la instalación y ejecución de herramientas Python. No requiere tener Python pre-instalado.

🪟 UV en Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verificar:

uv --version

🍎🐧 UV en macOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Verificar:

uv --version

[!IMPORTANT] Reinicia tu terminal después de la instalación.

Opción 2: Python 3.10+ y pip

Si ya tienes Python instalado y prefieres el método tradicional, puedes usar pip (el gestor de paquetes de Python). Requiere tener Python 3.10 o superior ya instalado en tu sistema.

🪟 Python en Windows

1. Descarga Python 3.10+ desde python.org/downloads
2. Marca "Add Python to PATH" durante la instalación
3. Verifica:

python --version
pip --version

🍎 Python en macOS

macOS:

1. Ve a python.org/downloads
2. Descarga Python 3.10+ para macOS
3. Ejecuta el instalador . pkg

Verifica:

python3 --version
pip3 --version

🐧 Python en Linux (Ubuntu/Debian)

sudo apt update
sudo apt install python3.10 python3-pip python3.10-venv

Verifica:

python3 --version
pip3 --version

🚀 Instalación

Opción 1: Usando UV (recomendado)

Con UV instalado, no necesitas instalar KinielaGPT. Usarás uvx para ejecutarlo directamente - ver Configuración.

Opción 2: Usando pip

Instala KinielaGPT desde PyPI:

pip install kinielagpt

🔧 Configuración

🤖 Configurar para Claude.app

Edita el archivo de configuración claude_desktop_config.json que según tu sistema operativo se encuentra en:

• Windows: %APPDATA%\Roaming\Claude\claude_desktop_config.json
• macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

Añade una de las siguientes configuraciones según tu método de instalación:

Usando uvx

{
  "mcpServers": {
    "kinielagpt": {
      "command": "uvx",
      "args": ["kinielagpt"]
    }
  }
}

Usando pip

{
  "mcpServers": {
    "kinielagpt": {
      "command": "python",
      "args": ["-m", "kinielagpt"]
    }
  }
}

[!NOTE] En macOS/Linux, si python no funciona, usa python3 en su lugar.

💻 Configurar para VS Code

Instalación rápida (un clic):

Haz clic en el siguiente botón para instalar automáticamente el servidor MCP en VS Code:

Instalación manual:

Abre la Paleta de Comandos (Ctrl + Shift + P), ejecuta MCP: Open User Configuration y añade una de las siguientes configuraciones:

Usando uvx

{
  "mcpServers": {
    "kinielagpt": {
      "command": "uvx",
      "args": ["kinielagpt"]
    }
  }
}

Usando pip

{
  "mcpServers": {
    "kinielagpt": {
      "command": "python",
      "args": ["-m", "kinielagpt"]
    }
  }
}

[!NOTE] En macOS/Linux, si python no funciona, usa python3 en su lugar.

[!TIP] Como alternativa puedes crear el archivo .vscode/mcp.json en tu workspace para compartir la configuración con otros. Más detalles en la documentación oficial de VS Code MCP.

---

📖 ¿Cómo usar KinielaGPT?

Una vez configurado el MCP, puedes interactuar con tu LLM (Claude, GPT, Gemini, etc.) en lenguaje natural. Simplemente hazle preguntas como las siguientes:

Categoría	Ejemplos de Preguntas
Consultas de información	🔹 "¿Cuál es la última quiniela disponible?" 🔹 "Muéstrame los partidos de la jornada 26 de la temporada 2025/2026" 🔹 "¿Qué probabilidades tiene cada partido de la jornada actual?"
Predicciones de quiniela	🔹 "Dame una predicción conservadora para la jornada actual" 🔹 "Quiero una predicción arriesgada para la próxima jornada" 🔹 "Genera una quiniela personalizada con 7 unos, 4 equis y 4 doses"
Análisis de partidos	🔹 "Analiza el partido qye jugará el Real Madrid esta jornada" 🔹 "¿Qué pasará en el partido Villarreal - Getafe?" 🔹 "Muéstrame el histórico de enfrentamientos del partido Alavés - Real Sociedad"
Detección de sorpresas	🔹 "¿Hay algún partido donde pueda haber sorpresa en esta jornada?" 🔹 "Detecta sorpresas con un umbral más sensible (threshold=20)"
Análisis de equipos	🔹 "¿Cómo está jugando el Rayo Vallecano últimamente?" 🔹 "Analiza el rendimiento del Barcelona actualmente" 🔹 "¿Qué racha tiene el Atletico de Madrid actualmente?"

---

Herramientas Disponibles

Herramienta	Descripción	Parámetros Principales	Devuelve
get_last_quiniela	Obtiene la última quiniela disponible	-	Jornada, temporada y partidos
get_quiniela	Información de jornada específica	jornada, temporada	Partidos programados
get_probabilities	Probabilidades basadas en LAE de una jornada	jornada, temporada	Probabilidades 1/X/2 y goles
predict_quiniela	Predicción completa con estrategias: conservadora, arriesgada, personalizada	jornada, temporada, strategy	Quiniela de 15 partidos
detect_surprises	Detecta inconsistencias en partidos	jornada, temporada, threshold	Lista de partidos con alertas de sorpresas potenciales
analyze_match	Análisis detallado de un partido	jornada, temporada, partido	Predicción y datos contextuales
analyze_team	Rendimiento completo de un equipo	jornada, temporada, equipo	Análisis con rachas y tendencias

Total: 7 herramientas MCP disponibles

Para detalles completos de parámetros y ejemplos, consulta la documentación completa.

---

📚 Documentación

La documentación completa está disponible en: https://ricardomoya.github.io/KinielaGPT/

Incluye:

• Guía de inicio rápido: Instalación, configuración y primeros pasos para usar KinielaGPT en tu entorno.
• Manual de instalación: Instrucciones detalladas para instalar con UV o pip, y requisitos previos.
• Configuración avanzada: Cómo conectar KinielaGPT con Claude Desktop, VS Code y otros clientes MCP.
• Uso y ejemplos: Preguntas frecuentes, ejemplos de comandos y flujos de trabajo recomendados.
• Referencia de API: Explicación de todas las herramientas MCP disponibles, parámetros y ejemplos de uso.
• Contribución: Guía para contribuir al proyecto, abrir issues y enviar pull requests.
• Licencia y créditos: Información legal y reconocimiento a los autores y colaboradores.

---

🧪 Testing

El proyecto incluye una suite completa de tests automatizados que cubren todas las funcionalidades principales. Los tests están organizados por módulo y utilizan pytest para la ejecución.

Tests Disponibles

Archivo de Test	Número de Tests	Descripción
test_data_source.py	4	Tests para la obtención y procesamiento de datos de quiniela desde APIs externas
test_predictor.py	9	Tests para las estrategias de predicción (conservadora, arriesgada, personalizada)
test_detector.py	30	Tests para la detección de sorpresas e inconsistencias en partidos
test_analyzer.py	12	Tests para el análisis de partidos y rendimiento de equipos

Ejecutar Tests Localmente

# Ejecutar todos los tests
pytest tests/ -v

# Ejecutar con cobertura
pytest tests/ -v --cov=kinielagpt --cov-report=term-missing

# Ejecutar un módulo específico
pytest tests/test_predictor.py -v

# Ejecutar tests en paralelo (si tienes pytest-xdist)
pytest tests/ -v -n auto

Cobertura de Código

Los tests proporcionan cobertura completa del código principal. La cobertura actual por módulo es:

Módulo	Cobertura	Descripción
data_source	67%	Funciones de obtención y parsing de datos de quiniela
predictor	84%	Algoritmos de predicción y estrategias (conservadora, arriesgada, personalizada)
detector	88%	Lógica de detección de sorpresas e inconsistencias
analyzer	48%	Análisis de partidos y rendimiento de equipos

CI/CD

Los tests se ejecutan automáticamente en GitHub Actions:

• En cada push/PR a las ramas main y develop
• Programados: Todos los jueves a las 9:00 AM (hora UTC)
• Matrices de testing: Python 3.10, 3.11, 3.12, 3.13 en Ubuntu
• Notificaciones: Email automático con resultados cuando se ejecuta programadamente

Para ver los resultados de CI, visita la pestaña Actions del repositorio.

---

🤝 Contribuir

¡Las contribuciones son bienvenidas! Por favor:

1. Fork el repositorio
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

---

📝 Licencia

Este proyecto está licenciado bajo GNU Affero General Public License v3.0 (AGPL-3.0).

Esto significa que puedes:

• ✅ Usar el código libremente (incluso comercialmente)
• ✅ Modificar y adaptar el proyecto
• ✅ Distribuir copias y versiones modificadas

Bajo las siguientes condiciones:

• 📝 Copyleft: Cualquier modificación debe ser AGPL-3.0 también
• 🌐 Uso en red: Si usas este código en un servidor/servicio, debes compartir el código fuente
• 📦 Código abierto: Toda versión modificada debe distribuirse con código fuente
• ©️ Atribución: Debes mantener los avisos de copyright

Protección especial: La AGPL-3.0 cierra la "laguna del servidor" – incluso si ejecutas este código como servicio web sin distribuir binarios, debes ofrecer el código fuente a tus usuarios.

Ver el archivo LICENSE para el texto legal completo.

[!IMPORTANT] Este proyecto es únicamente para fines de entretenimiento. Las predicciones no garantizan resultados y no deben usarse como única base para decisiones de apuestas. Juega responsablemente.

👨‍💻 Autor - Ricardo Moya

🐙 GitHub: @RicardoMoya
💼 LinkedIn: Ricardo Moya, PhD

📧 Contacto

Para preguntas, sugerencias o reportar issues:

• 📝 GitHub Issues
• 💬 GitHub Discussions

---

⚽ Proyecto creado por Ricardo Moya para que cada quiniela se juegue con cabeza, estrategia y datos.