mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:796-846 (handler)

  The handler function decorated with @mcp.tool(), implementing the core logic for fetching Statcast pitcher data using pybaseball.statcast_pitcher. Includes input validation and result size checks.
  @mcp.tool() def get_statcast_pitcher( player_id: int, start_date: str, end_date: str, ) -> dict: """ Retrieve MLB Statcast data for a single pitcher over a date range. Parameters ---------- player_id : int MLBAM ID of the pitcher. start_date : str The start date in 'YYYY-MM-DD' format. Required. end_date : str The end date in 'YYYY-MM-DD' format. Required. Returns ------- dict Dictionary with Statcast data for the pitcher. If the result is too large, returns an error message. Notes ----- Data is sourced from MLB Statcast via pybaseball. See the official documentation for more details: https://github.com/jldbc/pybaseball/tree/master/docs """ try: # Validate date range date_error = validate_date_range(start_date, end_date) if date_error: return date_error data = statcast_pitcher(start_date, end_date, player_id) # Convert all columns to string to ensure JSON serializability data = data.astype(str) result = {"statcast_data": data.to_dict(orient="records")} if not result["statcast_data"]: return { "error": ( f"No Statcast data found for the given date range ({start_date} to {end_date}). The date " "range may have resulted in nothing being returned." ) } size_error = check_result_size(result, "player") if size_error: return size_error return result except Exception as e: return {"error": str(e)}
• mlb_api.py:206-218 (helper)

  Helper function used by get_statcast_pitcher to validate the input date range.
  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:189-204 (helper)

  Helper function used by get_statcast_pitcher to check if the result size exceeds limits.
  def check_result_size(result: dict, context: str) -> Optional[dict]: """ Utility to check the size of a result dictionary (by word count). Returns an error dict if too large, else None. """ import json word_count = len(json.dumps(result).split()) if word_count > 100000: return { "error": ( f"Result too large ({word_count} words). Please narrow your query " f"(e.g., shorter date range, specific {context})." ) } return None
• mlb_api.py:796-846 (registration)

  The @mcp.tool() decorator registers the get_statcast_pitcher function as an MCP tool.
  @mcp.tool() def get_statcast_pitcher( player_id: int, start_date: str, end_date: str, ) -> dict: """ Retrieve MLB Statcast data for a single pitcher over a date range. Parameters ---------- player_id : int MLBAM ID of the pitcher. start_date : str The start date in 'YYYY-MM-DD' format. Required. end_date : str The end date in 'YYYY-MM-DD' format. Required. Returns ------- dict Dictionary with Statcast data for the pitcher. If the result is too large, returns an error message. Notes ----- Data is sourced from MLB Statcast via pybaseball. See the official documentation for more details: https://github.com/jldbc/pybaseball/tree/master/docs """ try: # Validate date range date_error = validate_date_range(start_date, end_date) if date_error: return date_error data = statcast_pitcher(start_date, end_date, player_id) # Convert all columns to string to ensure JSON serializability data = data.astype(str) result = {"statcast_data": data.to_dict(orient="records")} if not result["statcast_data"]: return { "error": ( f"No Statcast data found for the given date range ({start_date} to {end_date}). The date " "range may have resulted in nothing being returned." ) } size_error = check_result_size(result, "player") if size_error: return size_error return result except Exception as e: return {"error": str(e)}