mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:847-896 (handler)

  The @mcp.tool()-decorated function implementing the core logic of the 'get_statcast_batter' tool. It validates the date range, fetches Statcast batter data using pybaseball's statcast_batter function, converts to JSON-serializable format, checks result size, and returns the data or appropriate error.

  @mcp.tool()
  def get_statcast_batter(
      player_id: int,
      start_date: str,
      end_date: str,
  ) -> dict:
      """
      Retrieve MLB Statcast data for a single batter over a date range.
  
      Parameters
      ----------
      player_id : int
          MLBAM ID of the batter.
      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 batter. 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_batter(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)}

• main.py:21-23 (registration)

  The code block in main.py that calls setup_mlb_tools(mcp), which registers the get_statcast_batter tool (and other MLB tools) with the MCP server instance.

  # Setup all MLB and generic tools
  setup_mlb_tools(mcp)
  setup_generic_tools(mcp)

• mlb_api.py:206-218 (helper)

  Helper function used by get_statcast_batter 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_batter 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