mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:314-352 (handler)

  The core handler function for the 'get_mlb_team_info' tool. It is decorated with @mcp.tool(), which registers the tool and infers the schema from the type hints and docstring. The function resolves the team name/ID using a helper, fetches team information from the MLB stats API, and returns the data or an error.

  @mcp.tool()
  def get_mlb_team_info(
      team: str,
      season: Optional[int] = None,
      sport_id: Optional[int] = None,
      hydrate: Optional[str] = None,
      fields: Optional[str] = None,
  ) -> dict:
      """
      Get information about a specific team by ID or name.
  
      Args:
          team (str): Team ID or team name as a string. Can be numeric string, full name, abbreviation, or location.
          season (Optional[int]): Season year.
          sport_id (Optional[int]): Sport ID.
          hydrate (Optional[str]): Additional data to hydrate.
          fields (Optional[str]): Comma-separated list of fields to include.
  
      Returns:
          dict: Team information.
      """
      try:
          params = {}
          if season is not None:
              params["season"] = season
          if sport_id is not None:
              params["sportId"] = sport_id
          if hydrate is not None:
              params["hydrate"] = hydrate
          if fields is not None:
              params["fields"] = fields
          team_id = get_team_id_from_name(team)
          if team_id is None:
              return {"error": f"Could not find team ID for '{team}'"}
          team_info = mlb.get_team(team_id, **params)
          return {"team_info": team_info}
      except Exception as e:
          return {"error": str(e)}

• main.py:22-22 (registration)

  Invocation of setup_mlb_tools(mcp) in the main server file, which defines and registers the get_mlb_team_info tool (along with other MLB tools) on the MCP server instance.

  setup_mlb_tools(mcp)

• mlb_api.py:152-175 (helper)

  get_team_id_from_name helper function: Maps a team string (name, partial name, or ID) to the numeric team ID by checking a local CSV file, used directly in the handler to resolve the 'team' parameter.

  def get_team_id_from_name(team: str) -> Optional[int]:
      """Helper to get team ID from team name, partial name, or stringified ID."""
      # Accept stringified integer as ID
      try:
          return int(team)
      except (ValueError, TypeError):
          pass
      import csv
  
      team_lower = team.lower().strip()
      with open("current_mlb_teams.csv", "r") as f:
          reader = csv.DictReader(f)
          # First, try exact match
          for row in reader:
              if team_lower == row["team_name"].lower().strip():
                  return int(row["team_id"])
          f.seek(0)
          next(reader)  # skip header
          # Then, try substring match
          for row in reader:
              if team_lower in row["team_name"].lower():
                  return int(row["team_id"])
      return None

• mlb_api.py:177-187 (helper)

  get_team_abbreviation_from_name helper: Gets the 3-letter team abbreviation from name or ID, though not directly used in this tool.

  def get_team_abbreviation_from_name(team: str) -> Optional[str]:
      """
      Given a team name, partial name, or ID, return the 3-letter team abbreviation (e.g., 'NYY' for Yankees).
      Returns None if not found.
      """
      team_id = get_team_id_from_name(team)
      if team_id is None:
          return None
      team_info = mlb.get_team(team_id)
      return getattr(team_info, "abbreviation", None)

• mlb_api.py:315-352 (schema)

  The function signature and docstring define the input schema (parameters like team: str, season: Optional[int], etc.) and output (dict with team_info or error), used by MCP for validation.

  def get_mlb_team_info(
      team: str,
      season: Optional[int] = None,
      sport_id: Optional[int] = None,
      hydrate: Optional[str] = None,
      fields: Optional[str] = None,
  ) -> dict:
      """
      Get information about a specific team by ID or name.
  
      Args:
          team (str): Team ID or team name as a string. Can be numeric string, full name, abbreviation, or location.
          season (Optional[int]): Season year.
          sport_id (Optional[int]): Sport ID.
          hydrate (Optional[str]): Additional data to hydrate.
          fields (Optional[str]): Comma-separated list of fields to include.
  
      Returns:
          dict: Team information.
      """
      try:
          params = {}
          if season is not None:
              params["season"] = season
          if sport_id is not None:
              params["sportId"] = sport_id
          if hydrate is not None:
              params["hydrate"] = hydrate
          if fields is not None:
              params["fields"] = fields
          team_id = get_team_id_from_name(team)
          if team_id is None:
              return {"error": f"Could not find team ID for '{team}'"}
          team_info = mlb.get_team(team_id, **params)
          return {"team_info": team_info}
      except Exception as e:
          return {"error": str(e)}