mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:394-425 (handler)

  The core handler function for the 'get_multiple_mlb_player_stats' tool. It parses input parameters, determines stats and groups, calls the helper function to fetch data from MLB API, and returns the player stats or an error.

  @mcp.tool()
  def get_multiple_mlb_player_stats(
      player_ids: str,
      group: Optional[str] = None,
      type: Optional[str] = None,
      season: Optional[int] = None,
      eventType: Optional[str] = None,
  ) -> dict:
      """
      Get player stats by comma separated player_ids, group, type, season, and optional eventType.
  
      Args:
          player_ids (str): Comma-separated list of player IDs.
          group (Optional[str]): Stat group (e.g., hitting, pitching).
          type (Optional[str]): Stat type (e.g., season, career).
          season (Optional[int]): Season year.
          eventType (Optional[str]): Event type filter.
  
      Returns:
          dict: Player statistics.
      """
      try:
          player_ids_list = [pid.strip() for pid in player_ids.split(",")]
  
          # Use the helper function from the original code
          stats = ["season", "seasonAdvanced"] if type == "season" else ["career"]
          groups = [group] if group else ["hitting"]
  
          splits = get_multiple_player_stats(mlb, player_ids_list, stats, groups, season)
          return {"player_stats": splits}
      except Exception as e:
          return {"error": str(e)}

• mlb_api.py:10-76 (helper)

  Key helper function that makes the actual API call to MLB stats API (/people endpoint with hydrate=stats) to retrieve stats for multiple players and processes the response into splits.

  def get_multiple_player_stats(
      mlb, person_ids: list, stats: list, groups: list, season: Optional[int] = None, **params
  ) -> dict:
      """
      returns stat data for a team
  
      Parameters
      ----------
      mlb : mlbstatsapi.Mlb
          The MLB stats API instance
      person_ids : list
          the person ids
      stats : list
          list of stat types. List of statTypes can be found at https://statsapi.mlb.com/api/v1/statTypes
      groups : list
          list of stat grous. List of statGroups can be found at https://statsapi.mlb.com/api/v1/statGroups
      season : str, optional
          Insert year to return team stats for a particular season, season=2018
      eventType : str, optional
          Notes for individual events for playLog, playlog can be filered by individual events.
          List of eventTypes can be found at https://statsapi.mlb.com/api/v1/eventTypes
  
      Returns
      -------
      dict
          returns a dict of stats
  
      See Also
      --------
      Mlb.get_stats : Get stats
      Mlb.get_team_stats : Get team stats
      Mlb.get_players_stats_for_game : Get player stats for a game
  
      Examples
      --------
      >>> mlb = Mlb()
      >>> stats = ['season', 'seasonAdvanced']
      >>> groups = ['hitting']
      >>> mlb.get_player_stats(647351, stats, groups)
      {'hitting': {'season': [HittingSeason], 'seasonadvanced': [HittingSeasonAdvanced] }}
      """
      from mlbstatsapi import mlb_module
  
      params["stats"] = stats
      params["group"] = groups
  
      hydrate_arr = []
      if groups:
          hydrate_arr.append(f"group=[{','.join(groups)}]")
      if stats:
          hydrate_arr.append(f"type=[{','.join(stats)}]")
      if season:
          hydrate_arr.append(f"season={season}")
  
      mlb_data = mlb._mlb_adapter_v1.get(
          endpoint=f"people?personIds={','.join(person_ids)}&hydrate=stats({','.join(hydrate_arr)})"
      )
      if 400 <= mlb_data.status_code <= 499:
          return {}
  
      splits = []
  
      for person in mlb_data.data["people"]:
          if person.get("stats"):
              splits.append(mlb_module.create_split_data(person["stats"]))
  
      return splits

• main.py:21-23 (registration)

  The point where MLB tools, including 'get_multiple_mlb_player_stats', are registered to the MCP server instance by calling setup_mlb_tools(mcp). This setup function defines all @mcp.tool() decorated functions.

  # Setup all MLB and generic tools
  setup_mlb_tools(mcp)
  setup_generic_tools(mcp)