NHL MCP Server

""" NHL MCP Server A Model Context Protocol server for the NHL API using FastMCP. Provides access to all NHL API endpoints through MCP tools. """ from fastmcp import FastMCP from typing import Dict, Any, Optional, List import json from nhl_api_client import NHLAPIClient # Create the MCP server mcp = FastMCP( name="NHL-API-Server", instructions=""" This server provides comprehensive access to the NHL API endpoints. Available functionality includes: - Player information and statistics - Team standings, stats, rosters, and schedules - Game information including scores, play-by-play, and boxscores - League schedules and TV information - Playoff brackets and information - Draft and season information Use the appropriate tools to access specific NHL data. All data is returned in JSON format from the official NHL API. """ ) # Initialize the NHL API client nhl_client = NHLAPIClient() # Player Information Tools @mcp.tool def get_player_game_log(player_id: int, season: int, game_type: int) -> Dict[str, Any]: """ Get game log for a specific player, season, and game type. Args: player_id: Player ID (e.g., 8478402) season: Season in YYYYYYYY format (e.g., 20232024) game_type: Game type (2 for regular season, 3 for playoffs) """ return nhl_client.get_player_game_log(player_id, season, game_type) @mcp.tool def get_player_info(player_id: int) -> Dict[str, Any]: """ Get detailed information for a specific player. Args: player_id: Player ID (e.g., 8478402) """ return nhl_client.get_player_info(player_id) @mcp.tool def get_player_game_log_now(player_id: int) -> Dict[str, Any]: """ Get current season game log for a specific player. Args: player_id: Player ID (e.g., 8478402) """ return nhl_client.get_player_game_log_now(player_id) @mcp.tool def get_player_spotlight() -> Dict[str, Any]: """Get players currently in the spotlight.""" return nhl_client.get_player_spotlight() # Skater Stats Tools @mcp.tool def get_current_skater_stats_leaders(categories: Optional[str] = None, limit: Optional[int] = None) -> Dict[str, Any]: """ Get current skater stats leaders. Args: categories: Optional categories filter (e.g., 'goals', 'assists', 'points') limit: Optional limit (-1 for all results, default varies) """ return nhl_client.get_current_skater_stats_leaders(categories, limit) @mcp.tool def get_skater_stats_leaders(season: int, game_type: int, categories: Optional[str] = None, limit: Optional[int] = None) -> Dict[str, Any]: """ Get skater stats leaders for a specific season and game type. Args: season: Season in YYYYYYYY format (e.g., 20232024) game_type: Game type (2 for regular season, 3 for playoffs) categories: Optional categories filter (e.g., 'goals', 'assists', 'points') limit: Optional limit (-1 for all results) """ return nhl_client.get_skater_stats_leaders(season, game_type, categories, limit) # Goalie Stats Tools @mcp.tool def get_current_goalie_stats_leaders(categories: Optional[str] = None, limit: Optional[int] = None) -> Dict[str, Any]: """ Get current goalie stats leaders. Args: categories: Optional categories filter (e.g., 'wins', 'saves', 'shutouts') limit: Optional limit (-1 for all results) """ return nhl_client.get_current_goalie_stats_leaders(categories, limit) @mcp.tool def get_goalie_stats_leaders(season: int, game_type: int, categories: Optional[str] = None, limit: Optional[int] = None) -> Dict[str, Any]: """ Get goalie stats leaders for a specific season and game type. Args: season: Season in YYYYYYYY format (e.g., 20232024) game_type: Game type (2 for regular season, 3 for playoffs) categories: Optional categories filter (e.g., 'wins', 'saves', 'shutouts') limit: Optional limit (-1 for all results) """ return nhl_client.get_goalie_stats_leaders(season, game_type, categories, limit) # Standings Tools @mcp.tool def get_standings_now() -> Dict[str, Any]: """Get current NHL standings.""" return nhl_client.get_standings_now() @mcp.tool def get_standings_by_date(date: str) -> Dict[str, Any]: """ Get standings for a specific date. Args: date: Date in YYYY-MM-DD format (e.g., '2023-11-10') """ return nhl_client.get_standings_by_date(date) @mcp.tool def get_standings_season() -> Dict[str, Any]: """Get standings information for each season.""" return nhl_client.get_standings_season() # Team Stats Tools @mcp.tool def get_club_stats_now(team: str) -> Dict[str, Any]: """ Get current statistics for a specific team. Args: team: Three-letter team code (e.g., 'TOR', 'MTL', 'NYR') """ return nhl_client.get_club_stats_now(team) @mcp.tool def get_club_stats_season(team: str) -> Dict[str, Any]: """ Get stats overview for each season for a specific team. Args: team: Three-letter team code (e.g., 'TOR', 'MTL', 'NYR') """ return nhl_client.get_club_stats_season(team) @mcp.tool def get_club_stats(team: str, season: int, game_type: int) -> Dict[str, Any]: """ Get stats for a specific team, season, and game type. Args: team: Three-letter team code (e.g., 'TOR', 'MTL', 'NYR') season: Season in YYYYYYYY format (e.g., 20232024) game_type: Game type (2 for regular season, 3 for playoffs) """ return nhl_client.get_club_stats(team, season, game_type) @mcp.tool def get_team_scoreboard(team: str) -> Dict[str, Any]: """ Get current scoreboard for a specific team. Args: team: Three-letter team code (e.g., 'TOR', 'MTL', 'NYR') """ return nhl_client.get_team_scoreboard(team) @mcp.tool def get_team_roster(team: str, season: Optional[str] = None) -> Dict[str, Any]: """ Get roster for a specific team. Args: team: Three-letter team code (e.g., 'TOR', 'MTL', 'NYR') season: Optional season parameter (defaults to current) """ return nhl_client.get_team_roster(team, season) @mcp.tool def get_team_schedule(team: str, season: Optional[str] = None) -> Dict[str, Any]: """ Get schedule for a specific team. Args: team: Three-letter team code (e.g., 'TOR', 'MTL', 'NYR') season: Optional season parameter (defaults to current) """ return nhl_client.get_team_schedule(team, season) # League Schedule Tools @mcp.tool def get_schedule_now() -> Dict[str, Any]: """Get current NHL schedule.""" return nhl_client.get_schedule_now() @mcp.tool def get_schedule_by_date(date: str) -> Dict[str, Any]: """ Get schedule for a specific date. Args: date: Date in YYYY-MM-DD format (e.g., '2023-11-10') """ return nhl_client.get_schedule_by_date(date) @mcp.tool def get_schedule_calendar_now() -> Dict[str, Any]: """Get current schedule calendar.""" return nhl_client.get_schedule_calendar_now() @mcp.tool def get_schedule_calendar_by_date(date: str) -> Dict[str, Any]: """ Get schedule calendar for a specific date. Args: date: Date in YYYY-MM-DD format (e.g., '2023-11-10') """ return nhl_client.get_schedule_calendar_by_date(date) # Game Information Tools @mcp.tool def get_daily_scores_now() -> Dict[str, Any]: """Get current daily scores.""" return nhl_client.get_daily_scores_now() @mcp.tool def get_daily_scores_by_date(date: str) -> Dict[str, Any]: """ Get daily scores for a specific date. Args: date: Date in YYYY-MM-DD format (e.g., '2023-11-10') """ return nhl_client.get_daily_scores_by_date(date) @mcp.tool def get_scoreboard_now() -> Dict[str, Any]: """Get current overall NHL scoreboard.""" return nhl_client.get_scoreboard_now() @mcp.tool def get_where_to_watch(include: Optional[str] = None) -> Dict[str, Any]: """ Get streaming and broadcast information. Args: include: Optional include parameter for filtering """ return nhl_client.get_where_to_watch(include) # Game Events Tools @mcp.tool def get_play_by_play(game_id: int) -> Dict[str, Any]: """ Get play-by-play information for a specific game. Args: game_id: Game ID (e.g., 2023020204) """ return nhl_client.get_play_by_play(game_id) @mcp.tool def get_game_landing(game_id: int) -> Dict[str, Any]: """ Get landing page information for a specific game. Args: game_id: Game ID (e.g., 2023020204) """ return nhl_client.get_game_landing(game_id) @mcp.tool def get_game_boxscore(game_id: int) -> Dict[str, Any]: """ Get boxscore information for a specific game. Args: game_id: Game ID (e.g., 2023020204) """ return nhl_client.get_game_boxscore(game_id) @mcp.tool def get_game_story(game_id: int) -> Dict[str, Any]: """ Get game story information for a specific game. Args: game_id: Game ID (e.g., 2023020204) """ return nhl_client.get_game_story(game_id) # Network/TV Schedule Tools @mcp.tool def get_tv_schedule_by_date(date: str) -> Dict[str, Any]: """ Get TV schedule for a specific date. Args: date: Date in YYYY-MM-DD format (e.g., '2023-11-10') """ return nhl_client.get_tv_schedule_by_date(date) @mcp.tool def get_tv_schedule_now() -> Dict[str, Any]: """Get current TV schedule.""" return nhl_client.get_tv_schedule_now() # Playoff Tools @mcp.tool def get_playoff_overview() -> Dict[str, Any]: """Get playoff overview information.""" return nhl_client.get_playoff_overview() @mcp.tool def get_playoff_schedule(season: Optional[int] = None) -> Dict[str, Any]: """ Get playoff schedule. Args: season: Optional season in YYYYYYYY format (defaults to current) """ return nhl_client.get_playoff_schedule(season) @mcp.tool def get_playoff_bracket(season: Optional[int] = None) -> Dict[str, Any]: """ Get playoff bracket. Args: season: Optional season in YYYYYYYY format (defaults to current) """ return nhl_client.get_playoff_bracket(season) # Season and Draft Tools @mcp.tool def get_season_info() -> Dict[str, Any]: """Get current season information.""" return nhl_client.get_season_info() @mcp.tool def get_draft_info(year: Optional[int] = None) -> Dict[str, Any]: """ Get draft information. Args: year: Optional draft year (defaults to most recent) """ return nhl_client.get_draft_info(year) # Miscellaneous Tools @mcp.tool def get_meta_info() -> Dict[str, Any]: """Get NHL API meta information.""" return nhl_client.get_meta_info() @mcp.tool def get_postal_lookup(postal_code: str) -> Dict[str, Any]: """ Get information for a postal code (likely for regional content). Args: postal_code: Postal code to lookup """ return nhl_client.get_postal_lookup(postal_code) @mcp.tool def get_game_replays(date: Optional[str] = None) -> Dict[str, Any]: """ Get game replay information. Args: date: Optional date in YYYY-MM-DD format (defaults to current) """ return nhl_client.get_game_replays(date) # Utility Tools @mcp.tool def get_team_codes() -> List[str]: """Get a list of common NHL team codes for reference.""" return [ "ANA", "ARI", "BOS", "BUF", "CGY", "CAR", "CHI", "COL", "CBJ", "DAL", "DET", "EDM", "FLA", "LAK", "MIN", "MTL", "NSH", "NJD", "NYI", "NYR", "OTT", "PHI", "PIT", "SJS", "SEA", "STL", "TBL", "TOR", "UTA", "VAN", "VGK", "WSH", "WPG" ] @mcp.tool def get_season_format_help() -> Dict[str, str]: """Get help information about season format and game types.""" return { "season_format": "Seasons are in YYYYYYYY format where first 4 digits are start year, last 4 are end year (e.g., 20232024 for 2023-24 season)", "game_types": { "2": "Regular season games", "3": "Playoff games" }, "date_format": "Dates should be in YYYY-MM-DD format (e.g., 2023-11-10)", "example_player_ids": { "Connor McDavid": 8478402, "Sidney Crosby": 8471675, "Alexander Ovechkin": 8471214 } } # Run the server if __name__ == "__main__": mcp.run()