mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:271-313 (handler)

  The primary handler function for the 'get_mlb_schedule' MCP tool. It validates input dates, resolves optional team ID, fetches the schedule using mlbstatsapi.Mlb().get_schedule(), and returns the schedule or appropriate error messages.
  @mcp.tool() 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)

  Invocation of setup_mlb_tools(mcp) which defines and registers the get_mlb_schedule tool (along with other MLB tools) using the @mcp.tool() decorator within the setup function.
  setup_mlb_tools(mcp)
• mlb_api.py:278-290 (schema)

  Input schema and documentation for the get_mlb_schedule tool, defining parameters with types, descriptions, and return type. Used by MCP framework for tool schema generation.
  """ 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. """
• mlb_api.py:206-219 (helper)

  Helper function used by get_mlb_schedule to validate that start_date <= end_date and dates are in correct YYYY-MM-DD format.
  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
• mlb_api.py:152-175 (helper)

  Helper function to resolve team parameter (name, partial name, or ID string) to a numeric team ID, used in get_mlb_schedule.
  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