NHL MCP Server

NHL MCP Server

Un servidor integral del Protocolo de Contexto de Modelos (MCP) para la API de la NHL, construido con FastMCP. Este servidor proporciona acceso a todos los endpoints documentados de la API de la NHL a través de herramientas MCP, permitiendo que los asistentes de IA accedan a datos en vivo de la NHL.

🏒 Características

Este servidor MCP proporciona acceso a más de 40 endpoints de la API de la NHL, incluyendo:

Información de Jugadores

• Registros de juegos de jugadores (temporadas actuales e históricas)
• Información detallada de jugadores y estadísticas de carrera
• Jugadores destacados y en primer plano
• Páginas de destino de jugadores y datos biográficos

Estadísticas

• Líderes de estadísticas de patinadores actuales e históricos
• Líderes de estadísticas de porteros actuales e históricos
• Categorías estadísticas y límites personalizables
• Totales de temporada y carrera

Información de Equipos

• Clasificaciones de equipos (actuales e históricas por fecha)
• Estadísticas de equipos y métricas de rendimiento
• Plantillas de equipos con detalles de jugadores
• Calendarios de equipos y próximos juegos
• Estadísticas de clubes y comparaciones de equipos

Información de Juegos

• Puntajes diarios y marcadores en vivo
• Datos de jugada por jugada con eventos detallados
• Boxscores de juegos y resúmenes estadísticos
• Historias de juegos y resúmenes de partidos
• Páginas de destino de juegos

Información de la Liga

• Calendarios de la liga y calendarios de temporada
• Calendarios de TV e información de transmisión
• Disponibilidad de streaming ("dónde ver")
• Calendarios de televisión por red

Información de Playoffs

• Resúmenes de playoffs y brackets de torneos
• Calendarios de playoffs e información de series
• Estadísticas y récords de postemporada

Características Adicionales

• Información de temporada y datos de draft
• Información de metadatos y utilidades de API
• Referencias de códigos de equipos y ayudas de formato
• Manejo integral de errores

🚀 Instalación

1. Clona o descarga este repositorio
2. Instala las dependencias requeridas:

pip install -r requirements.txt

Dependencias:

• fastmcp>=2.8.0 - Marco FastMCP para la creación del servidor MCP
• requests>=2.31.0 - Biblioteca HTTP para llamadas a la API
• typing-extensions - Soporte mejorado de sugerencias de tipos

📖 Uso

Ejecutando el Servidor

Inicia el servidor MCP:

python nhl_mcp_server.py

El servidor se iniciará y escuchará conexiones MCP.

Configuración del Cliente MCP

Agrega este servidor a la configuración de tu cliente MCP (por ejemplo, Claude Desktop):

{
  "mcpServers": {
    "nhl-api": {
      "command": "python",
      "args": ["/path/to/nhl_mcp_server.py"]
    }
  }
}

Probando el Servidor

Ejecuta los scripts de prueba para verificar la funcionalidad:

# Test the underlying NHL API client
python test_client.py

# Test the MCP server backend
python test_mcp_server.py

# Run a comprehensive demo
python demo.py

🛠️ Herramientas Disponibles

El servidor expone las siguientes herramientas MCP:

Herramientas de Jugadores

• get_player_info(player_id) - Obtener información detallada del jugador
• get_player_game_log(player_id, season, game_type) - Obtener registros de juegos del jugador
• get_player_spotlight() - Obtener jugadores destacados

Herramientas de Equipos

• get_standings_now() - Obtener clasificaciones actuales de la NHL
• get_club_stats_now(team) - Obtener estadísticas del equipo
• get_team_roster(team) - Obtener plantilla del equipo
• get_team_schedule(team) - Obtener calendario del equipo

Herramientas de Juegos

• get_daily_scores_now() - Obtener puntajes de hoy
• get_play_by_play(game_id) - Obtener jugada por jugada del juego
• get_game_boxscore(game_id) - Obtener boxscore del juego

Herramientas de Estadísticas

• get_current_skater_stats_leaders() - Obtener líderes de estadísticas de patinadores
• get_current_goalie_stats_leaders() - Obtener líderes de estadísticas de porteros

Herramientas de Calendario

• get_schedule_now() - Obtener calendario actual
• get_tv_schedule_now() - Obtener calendario de TV

Herramientas de Utilidades

• get_team_codes() - Obtener lista de códigos de equipos de la NHL
• get_season_format_help() - Obtener ayuda de formato para temporadas y parámetros

📋 Formatos de Parámetros

Códigos de Equipos

Usa las abreviaturas estándar de equipos de la NHL:

• TOR (Toronto Maple Leafs), MTL (Montreal Canadiens)
• NYR (New York Rangers), BOS (Boston Bruins)
• EDM (Edmonton Oilers), CGY (Calgary Flames)
• Y todos los demás equipos de la NHL

Formato de Temporada

Las temporadas usan un formato de 8 dígitos: YYYYYYYY

• 20232024 para la temporada 2023-24
• 20222023 para la temporada 2022-23

Tipos de Juegos

• 2 - Juegos de temporada regular
• 3 - Juegos de playoffs

Formato de Fecha

Usa el formato de fecha ISO: YYYY-MM-DD

• 2024-01-15 para el 15 de enero de 2024

💡 Ejemplos de Consultas

Una vez conectado a un cliente MCP, puedes preguntar:

• "¿Cuáles son las clasificaciones actuales de la NHL?"
• "Muéstrame las estadísticas de Connor McDavid esta temporada"
• "¿Qué juegos hay hoy?"
• "Obtén la plantilla de los Toronto Maple Leafs"
• "¿Quiénes son los líderes actuales de goles?"
• "Muéstrame los puntajes de los juegos de ayer"
• "Obtén el bracket de playoffs"

🏗️ Arquitectura

El proyecto consiste en:

1. nhl_api_client.py - Cliente principal de la API de la NHL con más de 40 funciones de endpoints
2. nhl_mcp_server.py - Servidor FastMCP que expone las funciones de la API como herramientas MCP
3. test_client.py - Script de prueba para el cliente de la API de la NHL
4. test_mcp_server.py - Script de prueba para el backend del servidor MCP
5. demo.py - Demostración integral de las capacidades del servidor
6. requirements.txt - Dependencias de Python
7. mcp_config_example.json - Ejemplo de configuración de cliente MCP

✅ Pruebas y Validación

El servidor ha sido probado exhaustivamente con:

• Datos en Vivo de la NHL: Todos los endpoints probados con datos de la temporada actual de la NHL
• Manejo de Errores: Manejo robusto de errores para fallos de API y parámetros inválidos
• Validación de Respuestas: Manejo adecuado de diferentes tipos de respuestas (dict, list, etc.)
• Cumplimiento MCP: Compatibilidad total con los estándares del protocolo MCP

Resultados de Pruebas:

• ✅ Más de 40 endpoints de la API de la NHL funcionando correctamente
• ✅ Recuperación de datos en vivo (clasificaciones, puntajes, estadísticas de jugadores)
• ✅ Registro y exposición de herramientas MCP
• ✅ Manejo de errores y validación
• ✅ Documentación y ejemplos

🔧 Manejo de Errores

El servidor incluye manejo integral de errores:

• Errores HTTP: Tiempos de espera de red, fallos de conexión, indisponibilidad de la API
• Análisis JSON: Respuestas malformadas y estructuras de datos inesperadas
• Validación de Parámetros: Códigos de equipos, IDs de jugadores y formatos de fecha inválidos
• Límites de Tasa: Manejo elegante de los límites de tasa de la API

Todos los errores se devuelven como mensajes descriptivos para ayudar con la depuración.

🤝 Contribuciones

Siéntete libre de contribuir:

• Agregando nuevos endpoints de la API de la NHL a medida que estén disponibles
• Mejorando el manejo de errores y la validación
• Agregando pruebas más completas
• Mejorando la documentación y los ejemplos
• Reportando errores o sugiriendo mejoras

📄 Licencia

Este proyecto es de código abierto. La API de la NHL es proporcionada por la National Hockey League y está sujeta a sus términos de servicio.

🖼️ Capturas de Pantalla

NHL MCP Server en Acción

Captura de pantalla que muestra el NHL MCP Server proporcionando datos en vivo de la NHL, incluyendo clasificaciones actuales, información de jugadores, puntajes de juegos y estadísticas. El servidor se integra exitosamente con clientes MCP para llevar datos completos de hockey a asistentes de IA.

---

🏒 ¡Listo para llevar datos en vivo de la NHL a tu asistente de IA!