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+](#antes_de_empezar) en tu PC.
2. [Instala](#instalacion) KinielaGPT.
3. [Configura](#configuracion) 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](https://docs.astral.sh/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
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Verificar:
```powershell
uv --version
```
🍎🐧 UV en macOS/Linux
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Verificar:
```bash
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](https://www.python.org/downloads/)
2. **Marca "Add Python to PATH"** durante la instalación
3. Verifica:
```powershell
python --version
pip --version
```
🍎 Python en macOS
**macOS:**
1. Ve a [python.org/downloads](https://www.python.org/downloads/)
2. Descarga Python 3.10+ para macOS
3. Ejecuta el instalador . pkg
Verifica:
```bash
python3 --version
pip3 --version
```
🐧 Python en Linux (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install python3.10 python3-pip python3.10-venv
```
Verifica:
```bash
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](#configuracion).
### Opción 2: Usando pip
Instala KinielaGPT desde PyPI:
```bash
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
```json
{
"mcpServers": {
"kinielagpt": {
"command": "uvx",
"args": ["kinielagpt"]
}
}
}
```
Usando pip
```json
{
"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:
[](https://insiders.vscode.dev/redirect/mcp/install?name=kinielagpt&config=%7B%22command%22%3A%22python%22%2C%22args%22%3A%5B%22-m%22%2C%22kinielagpt%22%5D%7D)
**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
```json
{
"mcpServers": {
"kinielagpt": {
"command": "uvx",
"args": ["kinielagpt"]
}
}
}
```
Usando pip
```json
{
"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](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
---
## 📖 ¿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](https://ricardomoya.github.io/KinielaGPT/).
---
## 📚 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
```bash
# 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](https://github.com/RicardoMoya/KinielaGPT/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
[](https://www.gnu.org/licenses/agpl-3.0)
Este proyecto está licenciado bajo [GNU Affero General Public License v3.0 (AGPL-3.0)](https://www.gnu.org/licenses/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](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](https://github.com/RicardoMoya/KinielaGPT/issues)
- 💬 [GitHub Discussions](https://github.com/RicardoMoya/KinielaGPT/discussions)
---
⚽ Proyecto creado por Ricardo Moya para que cada quiniela se juegue con cabeza, estrategia y datos.