mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:272-313 (handler)

  The handler function implementing the core logic for the 'get_mlb_schedule' tool. It validates dates, resolves team IDs, fetches the schedule from the MLB API, and handles errors.

  def get_mlb_schedule(
      start_date: str,
      end_date: str,
      sport_id: int = 1,
      team: Optional[str] = None,
  ) -> dict:
      """
      Get MLB schedule for a specific date range, sport ID, or team (ID or name).
  
      Args:
          sport_id (int): Sport ID (default: 1 for MLB).
          start_date (str): Start date in 'YYYY-MM-DD' format. Required.
          end_date (str): End date in 'YYYY-MM-DD' format. Required.
          team (Optional[str]): Team ID or team name as a string. Can be numeric string, full name, abbreviation, or
            location. If not provided, defaults to all teams.
  
      Returns:
          dict: Schedule data for the specified parameters.
      """
      try:
          # Validate date range
          date_error = validate_date_range(start_date, end_date)
          if date_error:
              return date_error
          team_id = get_team_id_from_name(team) if team is not None else None
          schedule = mlb.get_schedule(
              start_date=start_date,
              end_date=end_date,
              sport_id=sport_id,
              team_id=team_id,
          )
          if not schedule:
              return {
                  "error": (
                      f"No games found for the given date range ({start_date} to {end_date}). The date range may "
                      "have resulted in nothing being returned."
                  )
              }
          return {"schedule": schedule}
      except Exception as e:
          return {"error": str(e)}

• main.py:22-22 (registration)

  The call to setup_mlb_tools(mcp) which defines and registers all MLB tools, including 'get_mlb_schedule', with the MCP server instance.

  setup_mlb_tools(mcp)

• mlb_api.py:152-174 (helper)

  Helper function to resolve team ID from team name, partial name, or ID string. Used in get_mlb_schedule to filter by team.

  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:206-218 (helper)

  Helper function for date range validation. Called at the start of get_mlb_schedule to ensure valid input dates.

  def validate_date_range(start_date: str, end_date: str) -> Optional[dict]:
      """
      Utility to check that start_date is before or equal to end_date.
      Returns an error dict if invalid, else None.
      """
      try:
          start = datetime.strptime(start_date, "%Y-%m-%d")
          end = datetime.strptime(end_date, "%Y-%m-%d")
          if start > end:
              return {"error": f"start_date ({start_date}) must be before or equal to end_date ({end_date})"}
      except Exception as e:
          return {"error": f"Invalid date format: {e}"}
      return None