get_statcast_pitcher

Instructions

Implementation Reference

• mlb_api.py:796-846 (handler)

  The primary handler function for the 'get_statcast_pitcher' tool. It is decorated with @mcp.tool() for automatic registration and schema generation. Calls pybaseball.statcast_pitcher to fetch data, handles validation and errors.

  @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 that start_date <= end_date and dates are properly formatted.

  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 dictionary is too large (>100k words) and return error if so.

  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

• tests/test_mlb_api.py:26-32 (registration)

  Test fixture that calls mlb_api.setup_mlb_tools(mcp) to register the tools, including get_statcast_pitcher, confirming the registration mechanism.

  @pytest.fixture
  def mcp():
      mcp = MagicMock()
      patch_mcp_tool(mcp)
      mlb_api.setup_mlb_tools(mcp)
      generic_api.setup_generic_tools(mcp)
      return mcp