NHL MCP Server

Um servidor MCP para a API da NHL, fornecendo acesso a todos os endpoints documentados.

GitHub
3
Experimente este MCPPatrocinado

Documentação

NHL MCP Server

Um servidor abrangente do Model Context Protocol (MCP) para a API da NHL, construído com FastMCP. Este servidor fornece acesso a todos os endpoints documentados da API da NHL por meio de ferramentas MCP, permitindo que assistentes de IA acessem dados ao vivo da NHL.

🏒 Recursos

Este servidor MCP fornece acesso a mais de 40 endpoints da API da NHL, incluindo:

Informações de Jogadores

  • Registros de jogos de jogadores (temporadas atuais e históricas)
  • Informações detalhadas de jogadores e estatísticas de carreira
  • Destaques de jogadores e jogadores em evidência
  • Páginas de perfil de jogadores e dados biográficos

Estatísticas

  • Líderes de estatísticas de patinadores atuais e históricos
  • Líderes de estatísticas de goleiros atuais e históricos
  • Categorias estatísticas personalizáveis e limites
  • Totais de temporada e carreira

Informações de Times

  • Classificações de times (atuais e históricas por data)
  • Estatísticas de times e métricas de desempenho
  • Elencos de times com detalhes de jogadores
  • Calendários de times e próximos jogos
  • Estatísticas de clubes e comparações entre times

Informações de Jogos

  • Placar diário e placares ao vivo
  • Dados de jogada a jogada com eventos detalhados
  • Boxscores de jogos e resumos estatísticos
  • Histórias de jogos e resumos de partidas
  • Páginas de jogos

Informações da Liga

  • Calendários da liga e calendários de temporada
  • Programações de TV e informações de transmissão
  • Disponibilidade de streaming ("onde assistir")
  • Programações de televisão em rede

Informações de Playoffs

  • Visões gerais dos playoffs e chaves de torneio
  • Programações de playoffs e informações de séries
  • Estatísticas e recordes de pós-temporada

Recursos Adicionais

  • Informações de temporada e dados de draft
  • Informações de metadados e utilitários da API
  • Referências de códigos de times e auxiliares de formato
  • Tratamento abrangente de erros

🚀 Instalação

  1. Clone ou baixe este repositório
  2. Instale as dependências necessárias:
pip install -r requirements.txt

Dependências:

  • fastmcp>=2.8.0 - Framework FastMCP para criação do servidor MCP
  • requests>=2.31.0 - Biblioteca HTTP para chamadas de API
  • typing-extensions - Suporte aprimorado a dicas de tipo

📖 Uso

Executando o Servidor

Inicie o servidor MCP:

python nhl_mcp_server.py

O servidor iniciará e ficará aguardando conexões MCP.

Configuração do Cliente MCP

Adicione este servidor à configuração do seu cliente MCP (ex.: Claude Desktop):

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

Testando o Servidor

Execute os scripts de teste para verificar a funcionalidade:

# 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

🛠️ Ferramentas Disponíveis

O servidor expõe as seguintes ferramentas MCP:

Ferramentas de Jogadores

  • get_player_info(player_id) - Obter informações detalhadas de jogadores
  • get_player_game_log(player_id, season, game_type) - Obter registros de jogos de jogadores
  • get_player_spotlight() - Obter jogadores em destaque

Ferramentas de Times

  • get_standings_now() - Obter classificações atuais da NHL
  • get_club_stats_now(team) - Obter estatísticas de times
  • get_team_roster(team) - Obter elenco de times
  • get_team_schedule(team) - Obter calendário de times

Ferramentas de Jogos

  • get_daily_scores_now() - Obter placares de hoje
  • get_play_by_play(game_id) - Obter jogada a jogada de jogos
  • get_game_boxscore(game_id) - Obter boxscore de jogos

Ferramentas de Estatísticas

  • get_current_skater_stats_leaders() - Obter líderes de estatísticas de patinadores
  • get_current_goalie_stats_leaders() - Obter líderes de estatísticas de goleiros

Ferramentas de Calendário

  • get_schedule_now() - Obter calendário atual
  • get_tv_schedule_now() - Obter programação de TV

Ferramentas Utilitárias

  • get_team_codes() - Obter lista de códigos de times da NHL
  • get_season_format_help() - Obter ajuda de formato para temporadas e parâmetros

📋 Formatos de Parâmetros

Códigos de Times

Use as abreviações padrão dos times da NHL:

  • TOR (Toronto Maple Leafs), MTL (Montreal Canadiens)
  • NYR (New York Rangers), BOS (Boston Bruins)
  • EDM (Edmonton Oilers), CGY (Calgary Flames)
  • E todos os outros times da NHL

Formato de Temporada

As temporadas usam o formato de 8 dígitos: YYYYYYYY

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

Tipos de Jogos

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

Formato de Data

Use o formato de data ISO: YYYY-MM-DD

  • 2024-01-15 para 15 de janeiro de 2024

💡 Exemplos de Consultas

Uma vez conectado a um cliente MCP, você pode perguntar:

  • "Quais são as classificações atuais da NHL?"
  • "Mostre-me as estatísticas de Connor McDavid nesta temporada"
  • "Quais jogos acontecem hoje?"
  • "Obtenha o elenco do Toronto Maple Leafs"
  • "Quem são os atuais líderes em gols?"
  • "Mostre-me os placares dos jogos de ontem"
  • "Obtenha a chave dos playoffs"

🏗️ Arquitetura

O projeto consiste em:

  1. nhl_api_client.py - Cliente principal da API da NHL com mais de 40 funções de endpoints
  2. nhl_mcp_server.py - Servidor FastMCP que expõe funções da API como ferramentas MCP
  3. test_client.py - Script de teste para o cliente da API da NHL
  4. test_mcp_server.py - Script de teste para o backend do servidor MCP
  5. demo.py - Demonstração abrangente das capacidades do servidor
  6. requirements.txt - Dependências Python
  7. mcp_config_example.json - Exemplo de configuração de cliente MCP

✅ Testes e Validação

O servidor foi testado minuciosamente com:

  • Dados ao Vivo da NHL: Todos os endpoints testados com dados da temporada atual da NHL
  • Tratamento de Erros: Tratamento robusto de erros para falhas de API e parâmetros inválidos
  • Validação de Respostas: Tratamento adequado de diferentes tipos de resposta (dict, list, etc.)
  • Conformidade com MCP: Compatibilidade total com os padrões do protocolo MCP

Resultados dos Testes:

  • ✅ Mais de 40 endpoints da API da NHL funcionando corretamente
  • ✅ Recuperação de dados ao vivo (classificações, placares, estatísticas de jogadores)
  • ✅ Registro e exposição de ferramentas MCP
  • ✅ Tratamento de erros e validação
  • ✅ Documentação e exemplos

🔧 Tratamento de Erros

O servidor inclui tratamento abrangente de erros:

  • Erros HTTP: Timeouts de rede, falhas de conexão, indisponibilidade da API
  • Análise JSON: Respostas malformadas e estruturas de dados inesperadas
  • Validação de Parâmetros: Códigos de times inválidos, IDs de jogadores e formatos de data
  • Limitação de Taxa: Tratamento gracioso dos limites de taxa da API

Todos os erros são retornados como mensagens descritivas para auxiliar na depuração.

🤝 Contribuindo

Sinta-se à vontade para contribuir:

  • Adicionando novos endpoints da API da NHL à medida que forem disponibilizados
  • Melhorando o tratamento de erros e a validação
  • Adicionando testes mais abrangentes
  • Aprimorando a documentação e os exemplos
  • Reportando bugs ou sugerindo melhorias

📄 Licença

Este projeto é de código aberto. A API da NHL é fornecida pela National Hockey League e está sujeita aos seus termos de serviço.

🖼️ Capturas de Tela

NHL MCP Server em Ação

NHL MCP Server Demo

Captura de tela mostrando o NHL MCP Server fornecendo dados ao vivo da NHL, incluindo classificações atuais, informações de jogadores, placares de jogos e estatísticas. O servidor integra-se com sucesso a clientes MCP para levar dados abrangentes de hóquei a assistentes de IA.

🏒 Pronto para levar dados ao vivo da NHL ao seu assistente de IA!