# Futtebol — Guía para Agentes y LLMs (llms.txt)
> Versión: 4.0 (Agent-First)
> Plataforma: SaaS de Análisis Deportivo Cuantitativo & Simulación Monte Carlo
> Base de Datos: 10 Competiciones Oficiales, +36.000 partidos históricos

## 1. ¿Qué es Futtebol?
Futtebol es un motor analítico deportivo que combina modelos matemáticos rigurosos (Dixon-Coles bivariado con Poisson), Machine Learning supervisado (XGBoost con calibración Platt e isotónica por liga) y simulaciones Monte Carlo de hasta 100.000 iteraciones.

Los agentes inteligentes consumen datos de fixture, predicciones reconciliadas, probabilidades reales y cuotas justas sin margen de casa de apuestas. **Ninguna herramienta inventa datos**: si un identificador no existe, la respuesta es un error explícito con los identificadores válidos.

---

## 2. Competiciones Oficiales Soportadas (Exactamente 10)
- `COL-Primera A`: Liga BetPlay Dimayor (Colombia)
- `SUD-Copa Sudamericana`: CONMEBOL Sudamericana (Sudamérica)
- `UCL-Champions League`: UEFA Champions League (Europa)
- `UEL-Europa League`: UEFA Europa League (Europa)
- `LIB-Copa Libertadores`: CONMEBOL Libertadores (Sudamérica)
- `GER-Bundesliga`: Bundesliga (Alemania)
- `ENG-Championship`: Championship (Inglaterra)
- `POR-Liga Portugal`: Liga Portugal (Portugal)
- `USA-MLS`: Major League Soccer (EE.UU.)
- `UNL-UEFA Nations League`: UEFA Nations League (Europa)

---

## 3. Motores de Predicción & Consenso
- **Dixon-Coles + Poisson**: Distribución de goles esperados y ajuste de correlación de empates en bajas anotaciones (tau).
- **XGBoost Calibrado**: 63 features por partido (forma reciente, diferencia de PPG, factor local/visitante, ratings de ataque/defensa). Calibrado con Platt scaling y regresión isotónica por liga.
- **Monte Carlo**: 1.000 a 100.000 iteraciones, determinista con semilla fija, para probabilidades conjuntas y mercados exóticos.
- **Reconciliación Post-Predicción**: Garantiza consistencia lógica estricta: 1X2 suma 100, Over 0.5 ≥ 1.5 ≥ 2.5 ≥ 3.5 ≥ 4.5 y BTTS ≤ Over 1.5. No existen marcadores contradictorios con los totales.

---

## 4. Mercados Disponibles
1. **Resultado Final (1X2)**: Probabilidad y cuota justa de Local (1), Empate (X) y Visitante (2).
2. **Doble Oportunidad**: 1X, 12, X2.
3. **Totales de Goles (Over/Under)**: Líneas 0.5, 1.5, 2.5, 3.5 y 4.5.
4. **Ambos Equipos Marcan (BTTS)**: Sí / No (con dampener 0.88 para copas internacionales).
5. **Hándicap Asiático & Totales Asiáticos**: Líneas de cuarto y media (+0.25, -0.25, 2.25, 2.75).
6. **Marcador Exacto**: Marcadores más probables.

---

## 5. Integración para Agentes (MCP & API)

### 5.1 Conectar en 30 segundos (recomendado)

El servidor MCP está **publicado en npm** (`@futtebol/mcp-server@1.10.26`, público) y también se puede usar sin instalar nada, por HTTP.

**Opción A — instalar en caliente (sin tocar el proyecto):**
```
npx -y @futtebol/mcp-server
npx -y @futtebol/mcp-server --version    # 1.10.26
```

**Opción B — configuración lista para pegar:** descarga `https://futtebol.com/mcp.json` y cópialo en el archivo de MCP de tu cliente (Claude Desktop, Cursor, Claude Code, Kilo, Cline):

```json
{ "mcpServers": { "futtebol": { "command": "npx", "args": ["-y", "@futtebol/mcp-server"] } } }
```

**Opción C — sin instalar nada, por HTTP:**
```
POST https://futtebol.com/api/agent/mcp        (JSON-RPC 2.0, admite lotes)
GET  https://futtebol.com/api/agent/mcp        (ficha de capacidades)
```

**Opción D — solo datos, sin MCP:**
```
GET https://futtebol.com/data/index.json
GET https://futtebol.com/data/teams.json
GET https://futtebol.com/ml/manifest.json
```

Tras conectar, tu primera llamada debe ser `tools/list`, y la segunda `get_leagues`: nunca inventes un `league_id` ni un `match_id`.

### 5.1.1 Servidor MCP (detalle)

Transporte stdio con JSON-RPC 2.0 (NDJSON, también acepta JSON concatenado o multilínea). Configuración mínima:

```json
{ "mcpServers": { "futtebol": { "command": "npx", "args": ["-y", "@futtebol/mcp-server"] } } }
```

Endpoint HTTP equivalente: `POST https://futtebol.com/api/agent/mcp` (JSON-RPC 2.0, admite lotes; `GET` devuelve las capacidades sin handshake). Protocolos negociados: `2025-06-18`, `2025-03-26`, `2024-11-05`.

### 5.2 Herramientas MCP

| Herramienta | Para qué sirve | Entrada mínima |
|---|---|---|
| `get_leagues` | Catálogo de las 10 competiciones con temporada y frescura del dato | ninguna |
| `get_matches` | Partidos reales con `match_id` estable, filtros de estado/equipo/fecha y paginación por cursor | `league_id` |
| `get_match_predictions` | Informe reconciliado: 1X2, cuotas justas, doble oportunidad, Over/Under, BTTS, goles esperados, marcadores probables | `match_id` |
| `run_simulation` | Monte Carlo (1.000-100.000 iteraciones, semilla reproducible) para contrastar el motor | `home_team`, `away_team` |

Recursos MCP: `futtebol://leagues`, `futtebol://llms.txt`, `futtebol://standings/{league_id}`.

Ejemplo de ciclo completo (JSON-RPC sobre HTTP):

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_matches","arguments":{"league_id":"COL-Primera A","status":"upcoming","limit":3}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_match_predictions","arguments":{"match_id":"COL-Primera A::fortaleza-c-e-i-f::tolima::1790550300"}}}
```

Un `match_id` inexistente devuelve `result.isError = true` con `error.code = "not_found"` y un `hint` con los identificadores válidos: nunca se inventan probabilidades.

### 5.3 Formato de los identificadores

- `league_id`: id canónico de la tabla de la sección 2 (también se acepta el código de país o el nombre de la liga).
- `match_id`: `league_id::home_id::away_id::timestamp_unix`, por ejemplo `COL-Primera A::jaguares-de-cordoba::alianza::1790542800`. **Cópialo literalmente** desde `get_matches`.
- Estados normalizados: `upcoming`, `live`, `finished`.
- **Escala**: todas las probabilidades son porcentajes enteros 0-100 y las cuotas justas son `100 / probabilidad`, sin margen.

### 5.4 Endpoints Gateway (REST, equivalentes JSON de las herramientas)

- `GET /api/agent/status`: chequeo de salud, versiones de protocolo, número de herramientas.
- `GET /api/agent/leagues`: catálogo de competiciones.
- `GET /api/agent/matches?league={LEAGUE_ID}&status={STATUS}&limit={N}`: partidos con su `match_id`.
- `GET /api/agent/predictions?match_id={MATCH_ID}`: consenso matemático de todos los mercados.
- `GET /api/agent/simulate?home_team={ID}&away_team={ID}&iterations={N}`: Monte Carlo.
- `POST /api/auth/request-otp` y `POST /api/auth/verify-otp`: token Bearer **opcional** para attributable de uso.

Todos los endpoints de lectura son anónimos. Límite: 120 peticiones por minuto y por IP; al superarlo responden HTTP 429 con el código JSON-RPC `-32002`.