KinielaGPT

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.

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

uv --version

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

uv --version

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 --version
pip --version

python3 --version
pip3 --version

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

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:

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

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

💻 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:

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

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

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:

Herramientas Disponibles

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

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:

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.