mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:898-980 (handler)

  The primary handler for the 'get_statcast_team' MCP tool. It uses @mcp.tool() decorator for automatic registration and schema definition via type hints. Fetches Statcast data for a team using pybaseball, filters by fields, handles validation and size limits.

  @mcp.tool()
  def get_statcast_team(
      team: str,
      start_date: str,
      end_date: str,
      fields: List[str],
  ) -> dict:
      """
      Retrieve MLB Statcast data for all players on a team over a date range.
  
      Parameters
      ----------
      team : str
          Team ID or team name (see MLB team list for valid values).
      start_date : str
          The start date in 'YYYY-MM-DD' format. Required.
      end_date : str
          The end date in 'YYYY-MM-DD' format. Required.
      fields: List[str]
          The field to return. If not provided, defaults to all fields. Available fields:
               pitch_type, game_date, release_speed, release_pos_x, release_pos_z, player_name, batter, pitcher,
               events, description, spin_dir, spin_rate_deprecated, break_angle_deprecated, break_length_deprecated,
               zone, des, game_type, stand, p_throws, home_team, away_team, type, hit_location, bb_type, balls,
               strikes, game_year, pfx_x, pfx_z, plate_x, plate_z, on_3b, on_2b, on_1b, outs_when_up, inning,
               inning_topbot, hc_x, hc_y, tfs_deprecated, tfs_zulu_deprecated, umpire, sv_id, vx0, vy0, vz0, ax, ay,
               az, sz_top, sz_bot, hit_distance_sc, launch_speed, launch_angle, effective_speed, release_spin_rate,
               release_extension, game_pk, fielder_2, fielder_3, fielder_4, fielder_5, fielder_6, fielder_7,
               fielder_8, fielder_9, release_pos_y, estimated_ba_using_speedangle,
               estimated_woba_using_speedangle, woba_value, woba_denom, babip_value, iso_value, launch_speed_angle,
               at_bat_number, pitch_number, pitch_name, home_score, away_score, bat_score, fld_score,
               post_away_score, post_home_score, post_bat_score, post_fld_score, if_fielding_alignment,
               of_fielding_alignment, spin_axis, delta_home_win_exp, delta_run_exp, bat_speed, swing_length,
               estimated_slg_using_speedangle, delta_pitcher_run_exp, hyper_speed, home_score_diff, bat_score_diff,
               home_win_exp, bat_win_exp, age_pit_legacy, age_bat_legacy, age_pit, age_bat, n_thruorder_pitcher,
               n_priorpa_thisgame_player_at_bat, pitcher_days_since_prev_game, batter_days_since_prev_game,
               pitcher_days_until_next_game, batter_days_until_next_game, api_break_z_with_gravity,
               api_break_x_arm, api_break_x_batter_in, arm_angle, attack_angle, attack_direction, swing_path_tilt,
               intercept_ball_minus_batter_pos_x_inches, intercept_ball_minus_batter_pos_y_inches
      Returns
      -------
      dict
          Dictionary with Statcast data for all players on the team. If the result is too large, returns an error
          message.
      Notes
      -----
      This uses the pybaseball `statcast` function, which returns all Statcast events for the specified team and date
      range. 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
          abbreviation = get_team_abbreviation_from_name(team)
          if not abbreviation:
              return {"error": f"Could not find 3-letter abbreviation for team '{team}'"}
          data = statcast(start_date, end_date, team=abbreviation)
          # Convert all columns to string to ensure JSON serializability
          data = data.astype(str)
          records = data.to_dict(orient="records")
          # Always include batter and pitcher, plus all requested fields
          filtered_records = []
          for row in records:
              filtered_row = {}
              for key in ["batter", "pitcher", *list(fields)]:
                  if key in row:
                      filtered_row[key] = row[key]
              filtered_records.append(filtered_row)
          result = {"statcast_data": filtered_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, "team")
          if size_error:
              return size_error
          return result
      except Exception as e:
          return {"error": str(e)}

• mlb_api.py:177-187 (helper)

  Helper utility to resolve team name to MLB 3-letter abbreviation, used in get_statcast_team for querying Statcast data.

  def get_team_abbreviation_from_name(team: str) -> Optional[str]:
      """
      Given a team name, partial name, or ID, return the 3-letter team abbreviation (e.g., 'NYY' for Yankees).
      Returns None if not found.
      """
      team_id = get_team_id_from_name(team)
      if team_id is None:
          return None
      team_info = mlb.get_team(team_id)
      return getattr(team_info, "abbreviation", None)

• mlb_api.py:189-203 (helper)

  Helper to check if result size exceeds limit (100k words), returns error if too large; used for get_statcast_team.

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

  Helper to validate date range (format and start <= end), returns error dict if invalid; used in get_statcast_team.

  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