mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:535-578 (handler)

  The core handler function for the 'get_mlb_roster' tool, decorated with @mcp.tool() for automatic registration in the MCP server. It resolves the team ID using a helper, constructs parameters, calls mlb.get_team_roster(), and handles errors. The docstring and type hints define the input schema.

  @mcp.tool()
  def get_mlb_roster(
      team: str,
      date: Optional[str] = None,
      rosterType: Optional[str] = None,
      season: Optional[str] = None,
      hydrate: Optional[str] = None,
      fields: Optional[str] = None,
  ) -> dict:
      """
      Get team roster for a specific team (ID or name), with optional filters.
  
      Args:
          team (str): Team ID or team name as a string. Can be numeric string, full name, abbreviation, or location.
          date (Optional[str]): Date in 'YYYY-MM-DD' format. If not provided, defaults to today.
          rosterType (Optional[str]): Filter by roster type (e.g., 40Man, fullSeason, etc.).
          season (Optional[str]): Filter by single season (year).
          hydrate (Optional[str]): Additional data to hydrate in the response.
          fields (Optional[str]): Comma-separated list of fields to include.
  
      Returns:
          dict: Team roster information.
      """
      try:
          if date is None:
              date = datetime.now().strftime("%Y-%m-%d")
          params = {}
          if rosterType is not None:
              params["rosterType"] = rosterType
          if season is not None:
              params["season"] = season
          params["date"] = date
          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}'"}
          roster = mlb.get_team_roster(team_id, **params)
          return roster
      except Exception as e:
          return {"error": str(e)}

• mlb_api.py:152-174 (helper)

  Helper utility function used by get_mlb_roster to resolve a team name (full, partial, or ID string) to a numeric team ID by checking a local CSV file.

  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