# 🎟️ Lotería MCP

MCP Server para consultar loterías y resultados mediante la [API de Resultados de Loterías](https://api-resultadosloterias.com/).

Expone dos herramientas que cualquier cliente MCP compatible (Claude Desktop, Cursor, etc.) puede invocar directamente desde el chat.

---

## 📋 Requisitos

| Herramienta | Versión mínima |
|-------------|---------------|
| Python      | 3.10+         |
| [uv](https://docs.astral.sh/uv/) | latest |

---

## ⚙️ Instalación

### 1. Clonar el repositorio

```bash
git clone https://github.com/parrotsoft/loteria-mcp
cd loteria
```

### 2. Crear entorno virtual e instalar dependencias con `uv`

```bash
uv sync
```

Esto creará automáticamente el entorno `.venv` e instalará todas las dependencias declaradas en `pyproject.toml`.

---

## 🚀 Uso con Claude Desktop

Agrega la siguiente configuración al archivo de Claude Desktop:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "loteria": {
      "command": "uv",
      "args": [
        "--directory",
        "/ruta/absoluta/al/proyecto/loteria",
        "run",
        "loteria.py"
      ]
    }
  }
}
```

> **Nota:** Reemplaza `/ruta/absoluta/al/proyecto/loteria` con la ruta real del proyecto en tu máquina.

Reinicia Claude Desktop y el servidor quedará disponible.

---

## 🛠️ Herramientas disponibles

### `get_lotteries`

Retorna el listado completo de loterías disponibles en la API.

**Sin parámetros.**

**Ejemplo de respuesta:**
```json
{
  "data": [
    { "id": 1, "name": "Lotería Nacional", "country": "MX" },
    { "id": 2, "name": "Melate", "country": "MX" }
  ]
}
```

---

### `get_resultados`

Retorna los resultados de loterías para una fecha específica.

| Parámetro | Tipo   | Descripción                                         |
|-----------|--------|-----------------------------------------------------|
| `date`    | `str`  | Fecha en formato `YYYY-MM-DD`. Vacío = más recientes |

**Ejemplo de respuesta:**
```json
{
  "data": [
    { "lottery": "Lotería Nacional", "result": "1234", "date": "2026-04-24" }
  ]
}
```

---

## 🧪 Ejecutar en modo desarrollo

Para probar el servidor directamente desde la terminal:

```bash
uv run mcp dev loteria.py
```

Esto abre el MCP Inspector en el navegador, donde puedes llamar las herramientas de forma interactiva.

---

## 📦 Dependencias

| Paquete   | Descripción                              |
|-----------|------------------------------------------|
| `httpx`   | Cliente HTTP async para llamadas a la API |
| `mcp[cli]`| Framework Model Context Protocol         |

---

## 📁 Estructura del proyecto

```
loteria/
├── loteria.py        # Servidor MCP con las herramientas expuestas
├── main.py           # Punto de entrada alternativo
├── pyproject.toml    # Configuración del proyecto y dependencias
├── uv.lock           # Lock file de dependencias (uv)
├── .gitignore
└── README.md
```

---

## 📄 Licencia

MIT