@futtebol/mcp-server

Servidor MCP de Futtebol: 10 competiciones oficiales con Dixon-Coles, XGBoost calibrado y simulación Monte Carlo, pensado para agentes autónomos.

Instalación

Proyecto Futtebol v01.10.26 — publicado en npm desde el 2026-09-27 (paquete v1.10.26, público).

npx -y @futtebol/mcp-server --version    # 1.10.26

Configuración mínima para Claude Desktop, Cursor o Kilo:

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

El servidor habla JSON-RPC 2.0 sobre stdio. Acepta NDJSON (un mensaje por línea), varios objetos JSON concatenados y JSON multilínea indentado. Responde con un mensaje por línea y nunca escribe logs en stdout.

Opciones

| Opción | Efecto | |---|---| | --base-url <url> | Servidor HTTP de Futtebol para datos remotos (por defecto https://futtebol.com) | | --data-mode <modo> | local, remote o auto (por defecto auto: usa data/ local si existe y cae a remoto si no) | | -v, --version | Imprime la versión | | -h, --help | Imprime la ayuda |

Variables de entorno equivalentes: FUTTEBOL_BASE_URL, FUTTEBOL_DATA_MODE.

Herramientas

| Herramienta | Entrada | Salida | |---|---|---| | get_leagues | — | Catálogo de las 10 competiciones con temporada y frescura del dato | | get_matches | league_id (+ status, team, date_from, date_to, limit, cursor) | Partidos reales con match_id estable y paginación por cursor | | get_match_predictions | match_id | 1X2, cuotas justas, doble oportunidad, Over/Under 0.5-4.5, BTTS, goles esperados, marcadores probables y desglose por motor | | run_simulation | home_team, away_team (+ league_id, iterations, seed) | Monte Carlo 1.000-100.000 iteraciones, reproducible con semilla |

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

Contrato para agentes

• Los league_id admiten id canónico (COL-Primera A), código de país (COL) o nombre de liga.
• Los match_id tienen el formato league_id::home_id::away_id::timestamp_unix y deben copiarse literalmente desde get_matches.
• Todas las probabilidades son porcentajes enteros 0-100; las cuotas justas son 100 / probabilidad, sin margen.
• Reconciliación garantizada: 1X2 suma 100, Over 0.5 ≥ 1.5 ≥ 2.5 ≥ 3.5 ≥ 4.5 y BTTS ≤ Over 1.5.
• Un identificador inexistente produce result.isError = true con error.code = "not_found" y los valores válidos en el hint. El servidor nunca devuelve probabilidades inventadas.
• Identificadores ambiguos o Unknown tools producen hint accionable en lugar de un error genérico.

Publicación

El paquete se publica desde el propio repositorio con verificación de precondiciones (motor empaquetado sincronizado, manifiesto coherente, suite MCP en verde, tarball sin secretos ni datos de partidos):

pnpm run mcp:publish:check          # solo verifica, no publica
node scripts/publish_mcp.mjs --publish

Requiere un token de npm con permiso de publicación en el scope @futtebol (NPM_TOKEN=... o npm login).

Publicar una versión nueva

El primer publish ya está hecho (v4.0.0). Para versiones siguientes:

# 1. sube la version en mcp-server/package.json y regenera el manifiesto
# 2. publica (el token con bypass 2FA sigue siendo necesario hasta enero de 2027)
node scripts/publish_mcp.mjs --publish

Migración recomendada a Trusted Publishing (antes de enero de 2027)

npm retira la publicación directa con token de acceso granular el enero de 2027. El sustituto es Trusted Publishing (OIDC) desde GitHub Actions, sin tokens de larga duración:

1. En npmjs.com → Packages → @futtebol/mcp-server → Settings → Trusted publishing → GitHub Actions (Organization/user, Repository, Workflow filename = publish.yml)
2. Añade un workflow con permissions: id-token: write y npm CLI ≥ 11.5.1 / Node ≥ 22.14
3. En Settings → Publishing access selecciona "Require two-factor authentication and disallow tokens"

Referencia: cómo se hizo el primer publishing

1. Crear la cuenta: https://www.npmjs.com/signup
2. Crear la organización (el nombre de la organización es el scope): https://www.npmjs.com/org/create
   • Nombre: futtebol
   • Plan: Unlimited public packages (gratis; el de pago es para paquetes privados)
3. Crear el token: https://www.npmjs.com/settings/~/tokens → Generate New Token → tipo Automation → marcar Allow publishing
4. Autenticarse: npm login (o export NPM_TOKEN=npm_xxx)
5. Publicar: node scripts/publish_mcp.mjs --publish (ya incluye --access public)
6. Verificar: npx -y @futtebol/mcp-server --version

Si el token pide contraseña y dice "incorrecta": casi siempre es que la cuenta se creó con GitHub o Google y por tanto no tiene contraseña propia. Fíjala en https://www.npmjs.com/settings/~/profile → Edit profile → campo de contraseña, o usa npm login en la terminal (flujo web, funciona con cuentas SSO). Ojo: desde agosto de 2026 npm exige siempre un reto 2FA interactivo para crear o gestionar tokens, así que ten el código OTP de tu app a mano.

Para automatizar en el futuro: Trusted Publishing (OIDC) desde GitHub Actions elimina el token de larga duración. Requiere npm CLI >= 11.5.1 y Node >= 22.14 en el runner, y no permite publicar con tokens a partir de enero de 2027. Se configura por paquete en npmjs.com → Packages → tu paquete → Settings → Trusted publishing (necesita que el paquete ya exista, por lo que el primer publish es manual).

autonomy note

El motor de cálculo (Dixon-Coles + Monte Carlo) va empaquetado dentro del paquete (lib/engine.local.mjs), así que las predicciones funcionan sin red una vez descargado. Los datos de fixture se resuelven en local si existe data/ y se descargan del sitio en caso contrario.

Licencia

UNLICENSED. Proyecto interno Futtebol.