NBA Player Stats

Fornece estatísticas abrangentes de jogadores da NBA do basketball-reference.com, incluindo estatísticas de carreira, comparações de temporadas e métricas avançadas.

GitHub
3
Experimente este MCPPatrocinado

Documentação

NBA Player Stats MCP Server

Um servidor focado do Model Context Protocol (MCP) que fornece estatísticas abrangentes de jogadores da NBA do basketball-reference.com. Este servidor é especializado em fornecer estatísticas detalhadas de jogadores, incluindo estatísticas de carreira, comparações de temporadas, métricas avançadas, estatísticas de arremessos e mais.

Sumário

Recursos

Este servidor MCP fornece ferramentas especializadas de estatísticas de jogadores da NBA em três níveis de profundidade:

Nível 1: Estatísticas principais (Ferramentas 1-10)

  • Estatísticas de carreira: Estatísticas completas de carreira com detalhamento temporada por temporada
  • Estatísticas por temporada: Estatísticas detalhadas para temporadas específicas, incluindo playoffs
  • Médias por jogo: Estatísticas tradicionais por jogo
  • Estatísticas totais: Totais da temporada e da carreira (não médias)
  • Por 36 minutos: Estatísticas por 36 minutos ajustadas ao ritmo
  • Métricas avançadas: PER, TS%, WS, BPM, VORP e outras métricas de eficiência
  • Comparações de jogadores: Comparações lado a lado entre dois jogadores
  • Divisões de arremessos: Porcentagens de arremesso detalhadas e estatísticas de volume
  • Desempenho nos playoffs: Estatísticas completas de playoffs com comparações com a temporada regular
  • Destaques da carreira: Melhores temporadas, marcos e conquistas

Nível 2: Análise aprofundada (Ferramentas 11-17)

  • Registros de jogos: Estatísticas jogo a jogo para análise detalhada
  • Consultas de estatísticas específicas: Obtenha estatísticas individuais para qualquer temporada (ex.: "3P% de Steph em 2018")
  • Prêmios e votação: Votações para MVP, DPOY e outros prêmios
  • Estatísticas contra times: Desempenho de carreira contra times específicos
  • Divisões mensais: Desempenho dividido por mês
  • Estatísticas de clutch: Desempenho em jogos decididos e situações de pressão
  • Detalhes dos playoffs: Desempenho nos playoffs ano a ano

Nível 3: Análise ultra-aprofundada (Ferramentas 18-23)

  • Tendências de carreira: Progressão ano a ano e análise de declínio
  • Recordes em jogos: Máximos de carreira, jogos de 40+ pontos, triplos-duplos
  • Divisões situacionais: Casa/fora, dias de descanso, situações de vitória/derrota
  • Estatísticas por quarto: Especialização no 4º quarto e desempenho em clutch
  • Acompanhamento de marcos: Progresso em direção a recordes com projeções
  • Rankings de todos os tempos: Onde os jogadores se posicionam na história da NBA

Recursos adicionais

  • Fotos dos jogadores: URLs de fotos dos jogadores do basketball-reference.com
  • Múltiplos tipos de estatísticas: PER_GAME, TOTALS, PER_MINUTE, PER_POSS, ADVANCED
  • Dados históricos: Acesso a temporadas históricas e progressões de carreira
  • 23 Ferramentas totais: Cobertura abrangente de todas as consultas possíveis de estatísticas de jogadores

Início Rápido

Instalar a partir do PyPI

pip install nba-player-stats-mcp

Instalar a partir do código-fonte

  1. Clone o repositório:
git clone https://github.com/ziyadmir/nba-player-stats-mcp
cd nba-player-stats-mcp
  1. Instale as dependências:
pip install -r requirements.txt

Executando o servidor

# If installed from PyPI
nba-player-stats-server

# If running from source
python src/server.py

Configurar o Claude Desktop

{
  "mcpServers": {
    "nba-player-stats": {
      "command": "python",
      "args": ["path/to/basketball/src/server.py"],
      "cwd": "path/to/basketball"
    }
  }
}

Instalação

Pré-requisitos

  • Python 3.8 ou superior
  • Gerenciador de pacotes pip

Instalar a partir do PyPI

A maneira mais fácil de instalar o NBA Player Stats MCP Server:

pip install nba-player-stats-mcp

Instalar a partir do código-fonte

Para desenvolvimento ou para obter as últimas alterações:

  1. Clone o repositório:
git clone https://github.com/ziyadmir/nba-player-stats-mcp
cd nba-player-stats-mcp
  1. Crie um ambiente virtual (recomendado):
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Instale em modo de desenvolvimento:
pip install -e .
# Or with development dependencies
pip install -e ".[dev]"

Uso

Iniciando o servidor

# If installed from PyPI
nba-player-stats-server

# If running from source
python src/server.py

Exemplos de uso em Python

# Import the fix first
import fix_basketball_reference
from basketball_reference_scraper.players import get_stats

# Get LeBron's career per-game stats
stats = get_stats('LeBron James', stat_type='PER_GAME', ask_matches=False)

# Get specific season
stats_2023 = stats[stats['SEASON'] == '2022-23']

# Get playoff stats
playoff_stats = get_stats('LeBron James', stat_type='PER_GAME', playoffs=True, ask_matches=False)

Veja example_usage.py para exemplos mais abrangentes.

Ferramentas Disponíveis

1. get_player_career_stats

Obtenha estatísticas completas de carreira de um jogador da NBA.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador (ex.: "LeBron James")
  • stat_type (string, opcional): Tipo de estatísticas - "PER_GAME", "TOTALS", "PER_MINUTE", "PER_POSS", "ADVANCED"

2. get_player_season_stats

Obtenha estatísticas para uma temporada específica.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • season (inteiro, obrigatório): Ano da temporada (ex.: 2023 para 2022-23)
  • stat_type (string, opcional): Tipo de estatísticas
  • include_playoffs (booleano, opcional): Incluir estatísticas de playoffs se disponíveis

3. get_player_advanced_stats

Obtenha estatísticas avançadas (PER, TS%, WS, BPM, VORP, etc.).

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • season (inteiro, opcional): Temporada específica, ou None para todas as temporadas

4. get_player_per36_stats

Obtenha estatísticas por 36 minutos (ajustadas ao ritmo).

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • season (inteiro, opcional): Temporada específica, ou None para todas as temporadas

5. compare_players

Compare estatísticas entre dois jogadores da NBA.

Parâmetros:

  • player1_name (string, obrigatório): Nome do primeiro jogador
  • player2_name (string, obrigatório): Nome do segundo jogador
  • stat_type (string, opcional): Tipo de estatísticas para comparar
  • season (inteiro, opcional): Temporada específica, ou None para comparação de carreira

6. get_player_shooting_splits

Obtenha estatísticas detalhadas de arremessos e divisões.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • season (inteiro, opcional): Temporada específica, ou None para estatísticas de carreira

7. get_player_totals

Obtenha estatísticas totais (não médias).

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • season (inteiro, opcional): Temporada específica, ou None para totais de carreira

8. get_player_playoff_stats

Obtenha estatísticas de playoffs com comparação com a temporada regular.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • stat_type (string, opcional): Tipo de estatísticas

9. get_player_headshot_url

Obtenha a URL da foto do jogador no basketball-reference.com.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador

10. get_player_career_highlights

Obtenha destaques e conquistas da carreira.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador

Nível 2: Ferramentas de Análise Aprofundada

11. get_player_game_log

Obtenha estatísticas jogo a jogo para uma temporada específica.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • season (inteiro, obrigatório): Ano da temporada (ex.: 2024)
  • playoffs (booleano, opcional): Se deseja obter registros de jogos dos playoffs
  • date_from (string, opcional): Data de início no formato 'YYYY-MM-DD'
  • date_to (string, opcional): Data de término no formato 'YYYY-MM-DD'

12. get_player_specific_stat

Obtenha uma estatística específica de um jogador em uma determinada temporada. Perfeito para responder perguntas como "Qual foi o 3P% de Steph em 2018?"

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • stat_name (string, obrigatório): A estatística específica (ex.: "PTS", "3P%", "PER")
  • season (inteiro, obrigatório): Ano da temporada

13. get_player_vs_team_stats

Obtenha estatísticas de carreira contra um time específico.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • team_abbreviation (string, obrigatório): Código do time (ex.: "GSW", "LAL")
  • stat_type (string, opcional): Tipo de estatísticas

14. get_player_awards_voting

Obtenha histórico de prêmios e votações.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • award_type (string, opcional): "MVP", "DPOY", "ROY", "SMOY", "MIP"

15. get_player_monthly_splits

Obtenha estatísticas divididas por mês.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • season (inteiro, obrigatório): Ano da temporada
  • month (string, opcional): Mês específico ou None para todos

16. get_player_clutch_stats

Obtenha desempenho em situações de clutch.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • season (inteiro, opcional): Temporada específica ou None para carreira

17. get_player_playoffs_by_year

Obtenha estatísticas detalhadas de playoffs para um ano específico.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • season (inteiro, obrigatório): Ano da temporada

Nível 3: Ferramentas de Análise Ultra-Aprofundada

18. get_player_career_trends

Analise tendências e progressão de carreira, incluindo mudanças ano a ano e padrões de declínio/melhora.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • stat_name (string, opcional): A estatística para analisar tendências (padrão: "PTS")
  • window_size (inteiro, opcional): Anos para média móvel (padrão: 3)

19. get_player_game_highs

Obtenha recordes de carreira e performances marcantes (jogos de 40+ pontos, 50+ pontos, triplos-duplos).

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • threshold_points (inteiro, opcional): Limiar de pontos para jogos de alta pontuação (padrão: 40)
  • include_triple_doubles (booleano, opcional): Se deseja estimar jogos de triplo-duplo

20. get_player_situational_splits

Obtenha divisões de desempenho situacional, incluindo casa/fora, dias de descanso e situações de vitória/derrota.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • season (inteiro, opcional): Temporada específica ou None para carreira
  • split_type (string, opcional): "home_away", "rest_days", "monthly", "win_loss"

21. get_player_quarter_stats

Obtenha desempenho quarto a quarto, especialmente do 4º quarto e prorrogação.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • season (inteiro, opcional): Temporada específica ou None para carreira
  • quarter (string, opcional): "1st", "2nd", "3rd", "4th", "OT" ou "all"

22. get_player_milestone_tracker

Acompanhe o progresso em direção a marcos de carreira com projeções de conquista.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • milestone_type (string, opcional): "points", "assists", "rebounds", "3pm", "games"

23. get_player_rankings

Obtenha rankings de todos os tempos para um jogador em várias categorias.

Parâmetros:

  • player_name (string, obrigatório): O nome do jogador
  • category (string, opcional): "points", "assists", "rebounds", "3pm", "steals", "blocks"

Exemplos

Aqui estão algumas perguntas de exemplo que este servidor MCP pode responder:

Consultas básicas (Nível 1)

  1. Visão geral da carreira: "Quais são as estatísticas de carreira de LeBron James?"
  2. Comparação de temporadas: "Como Stephen Curry se saiu na temporada de 2016?"
  3. Comparação de jogadores: "Compare as estatísticas de carreira de Michael Jordan e LeBron James"
  4. Análise de arremessos: "Quais são as porcentagens de arremesso de carreira de Steph Curry?"
  5. Métricas avançadas: "Qual foi o PER de Nikola Jokić em 2023?"
  6. Desempenho nos playoffs: "Como as estatísticas de Kawhi Leonard nos playoffs se comparam à temporada regular?"
  7. Marcos de carreira: "Quais são os destaques de carreira de Kareem Abdul-Jabbar?"
  8. Estatísticas por 36 minutos: "Quais são as estatísticas por 36 minutos de Giannis Antetokounmpo?"

Consultas de análise aprofundada (Nível 2)

  1. Estatística específica: "Qual foi a porcentagem de 3 pontos de Steph Curry em 2018?"
  2. Consulta de pontos: "Quantos pontos Stephen Curry teve em média em 2024?"
  3. Prêmios: "Onde LeBron James terminou na votação de MVP em 2020?"
  4. Registros de jogos: "Mostre-me o registro de jogos de Damian Lillard nos playoffs de 2021"
  5. Contra times: "Quais são as estatísticas de carreira de Kevin Durant contra os Lakers?"
  6. Mensal: "Como Jayson Tatum se saiu em dezembro de 2023?"
  7. Clutch: "Quais são as estatísticas de clutch de Kyrie Irving na carreira?"
  8. Ano de playoffs: "Como Jimmy Butler se saiu nos playoffs de 2020?"

Consultas de Análise Ultra-Profunda (Camada 3)

  1. Tendências de Carreira: "O LeBron James está em declínio com a idade?"
  2. Jogos Marcantes: "Quantos jogos de 40 pontos Kevin Durant tem?"
  3. Casa/Fora: "Como Joel Embiid se sai em casa vs fora?"
  4. 4º Quarto: "Qual é a média de pontos de Luka Dončić nos 4ºs quartos?"
  5. Acompanhamento de Marcos: "Quando LeBron vai passar dos 40.000 pontos?"
  6. Rankings de Todos os Tempos: "Onde Steph Curry está no ranking de todos os tempos em cestas de 3 pontos?"
  7. Situacional: "Como Giannis se sai em jogos consecutivos (back-to-backs)?"
  8. Detalhamento por Quarto: "Qual porcentagem dos pontos de Dame vem no 4º quarto?"

Explicações dos Tipos de Estatística

  • PER_GAME: Médias tradicionais por jogo (pontos, rebotes, assistências, etc.)
  • TOTALS: Estatísticas totais para uma temporada ou carreira
  • PER_MINUTE: Estatísticas por 36 minutos (normalizadas pelo tempo de jogo)
  • PER_POSS: Estatísticas por 100 posses de bola (normalizadas pelo ritmo)
  • ADVANCED: Métricas avançadas (PER, TS%, WS, BPM, VORP, etc.)

Glossário de Estatísticas Principais

  • PER: Player Efficiency Rating (Avaliação de Eficiência do Jogador)
  • TS%: True Shooting Percentage (Porcentagem de Arremesso Real)
  • WS: Win Shares (Participações em Vitórias)
  • BPM: Box Plus/Minus (Box Mais/Menos)
  • VORP: Value Over Replacement Player (Valor sobre o Jogador Substituto)
  • eFG%: Effective Field Goal Percentage (Porcentagem Efetiva de Arremessos de Quadra)
  • USG%: Usage Rate (Taxa de Uso)
  • ORtg: Offensive Rating (Avaliação Ofensiva - pontos por 100 posses)
  • DRtg: Defensive Rating (Avaliação Defensiva - pontos permitidos por 100 posses)
  • 3P%: Porcentagem de Cestas de Três Pontos
  • FT%: Porcentagem de Lances Livres
  • AST%: Porcentagem de Assistências
  • REB%: Porcentagem de Rebotes

Correções do Scraper do Basketball Reference

Importante: A biblioteca basketball_reference_scraper tem problemas de compatibilidade com a estrutura atual do site basketball-reference.com. Este servidor inclui correções automáticas para esses problemas.

Problemas Corrigidos

  1. Mudanças nos IDs das Tabelas: O Basketball Reference atualizou os IDs das tabelas HTML

    • per_game → per_game_stats
    • totals → totals_stats
    • per_minute → per_minute_stats

  2. Compatibilidade com Pandas: Corrigidos avisos de depreciação com pd.read_html()

  3. Tratamento de Erros: Melhor tratamento de dados ausentes e casos extremos

As correções são aplicadas automaticamente quando o servidor inicia via o módulo fix_basketball_reference.py.

Detalhes Completos da Correção

A correção envolve a atualização do arquivo basketball_reference_scraper/players.py:

  1. Adicionar importação de StringIO (após a importação do BeautifulSoup):

    from io import StringIO

  2. Atualizar o mapeamento de IDs de tabela (na função get_stats):

    # Map old table IDs to new ones
table_id_map = {
    'per_game': 'per_game_stats',
    'totals': 'totals_stats',
    'per_minute': 'per_minute_stats',
    'per_poss': 'per_poss_stats',
    'advanced': 'advanced'
}

  3. Corrigir a depreciação do pandas read_html:

    # Replace: df = pd.read_html(table)[0]
df = pd.read_html(StringIO(table))[0]

  4. Tratar a linha de Carreira ausente:

    career_rows = df[df['SEASON']=='Career'].index
if len(career_rows) > 0:
    career_index = career_rows[0]
    # ... rest of logic

Para contribuir com essas correções de volta à biblioteca original, veja a seção Contribuindo.

Guia de Desenvolvimento

Configurando o Ambiente de Desenvolvimento

  1. Criar ambiente virtual:

    python -m venv venv
source venv/bin/activate

  2. Instalar dependências:

    pip install -r requirements.txt

Testes

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test
pytest tests/test_integration.py -v

Testes Manuais

Teste o módulo de correção:

python example_usage.py

Casos de Teste Comuns

  1. Variações de Nome do Jogador:

    • Correspondência exata: "LeBron James" ✓
    • Sensibilidade a maiúsculas: "lebron james" ✗
    • Nomes parciais: "LeBron" ✗

  2. Casos Extremos:

    • Jogadores aposentados
    • Jogadores sem experiência em playoffs
    • Jogadores históricos (pré-1973 para estatísticas avançadas)

Diretrizes de Estilo de Código

  1. Estilo Python: Siga o PEP 8
  2. Tratamento de Erros: Sempre capture exceções específicas
  3. Processamento de Dados: Verifique se há resultados vazios antes de acessar

Estendendo o Servidor

Para adicionar novas ferramentas:

  1. Crie a função em server.py:

    @mcp.tool()
async def get_player_new_stat(
    player_name: str,
    **kwargs
) -> Dict[str, Any]:
    """Tool description"""
    try:
        # Implementation
        pass
    except Exception as e:
        logger.error(f"Error: {e}")
        return {"error": str(e)}

  2. Teste completamente com vários jogadores

  3. Atualize este README com a documentação da nova ferramenta

Problemas Conhecidos

Funcionalidades em Funcionamento ✅

  • Todas as ferramentas de estatísticas de jogadores funcionam corretamente com as correções aplicadas
  • URLs de fotos dos jogadores funcionam de forma confiável

Limitações ⚠️

  1. Nomes de Jogadores: Devem corresponder exatamente ao formato do basketball-reference.com

    • ✓ "LeBron James"
    • ✗ "Lebron" ou "lebron james"

  2. Dados Históricos: Alguns recursos podem ter dados limitados para temporadas mais antigas

    • Estatísticas avançadas não disponíveis antes de 1973-74
    • Algumas estatísticas de arremessos ausentes para carreiras iniciais

  3. Limitações da Biblioteca: A basketball_reference_scraper subjacente tem:

    • Sem manutenção ativa
    • Tratamento de erros inconsistente
    • Documentação limitada

Solução de Problemas

Erro "Nenhuma tabela encontrada"

  • Causa: Estrutura do site mudou
  • Correção: Aplicada automaticamente pelo fix_basketball_reference.py

Jogador Não Encontrado

  • Causa: Formato de nome incorreto
  • Solução: Use nomes exatos do basketball-reference.com

Resultados Vazios

  • Causa: O jogador não tem estatísticas para o tipo/temporada solicitado
  • Solução: Verifique o período de carreira do jogador e a disponibilidade de estatísticas

Testes

Execute a suíte de testes:

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

Contribuindo

  1. Faça um fork do repositório
  2. Crie sua branch de funcionalidade (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
  4. Envie para a branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

Contribuindo com Correções para o basketball_reference_scraper

Para contribuir com nossas correções de volta à biblioteca original:

  1. Faça um fork: https://github.com/vishaalagartha/basketball_reference_scraper
  2. Aplique as alterações de fix_basketball_reference.py
  3. Teste completamente com vários jogadores
  4. Envie o PR: "Corrigir análise de tabelas para a estrutura atualizada do basketball-reference.com"

Changelog

Versão 0.3.0 (Mais Recente)

  • Adicionadas ferramentas de análise ultra-profunda da Camada 3 (6 novas ferramentas)
  • Análise de tendências de carreira com progressão ano a ano
  • Recordes de jogos e acompanhamento de marcos (jogos de 40+ pontos, triplos-duplos)
  • Divisões situacionais (casa/fora, dias de descanso, vitórias/derrotas)
  • Análise de desempenho por quarto
  • Projeções de marcos e rankings de todos os tempos
  • Agora inclui 23 ferramentas no total em 3 camadas

Versão 0.2.0

  • Adicionadas ferramentas de análise profunda da Camada 2 (7 novas ferramentas)
  • Logs de jogos e consultas de estatísticas específicas
  • Suporte a prêmios e histórico de votação
  • Estatísticas de confrontos entre equipes
  • Divisões mensais e temporais
  • Métricas de desempenho em momentos decisivos
  • Análise aprimorada de playoffs ano a ano

Versão 0.1.0

  • Lançamento inicial com 10 ferramentas principais de estatísticas de jogadores
  • Correções de compatibilidade com basketball-reference.com
  • Estatísticas de carreira, temporada e avançadas

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Agradecimentos

Suporte

Para problemas e solicitações de recursos, use o rastreador de problemas do GitHub.