Statcast MCP Server

Instructions

Implementation Reference

• src/statcast_mcp/server.py:584-650 (handler)

  The MCP tool handler function `team_season_batting_stats` is defined and registered using the `@mcp.tool()` decorator. It fetches batting stats using pybaseball or fallback scraping and returns a formatted string.

  @mcp.tool()
  def team_season_batting_stats(
      team: str,
      season: int,
      min_plate_appearances: int = 1,
      player_name: str | None = None,
  ) -> str:
      """Full-season **actual** batting stats for one MLB team (entire roster).
  
      Uses **FanGraphs** when available; if that fails or returns no rows, falls back to
      scraping **Baseball Reference**'s team page (same numbers as the site: PA, HR,
      AVG/OBP/SLG, OPS+, WAR, etc.).
  
      Args:
          team: 3-letter team abbreviation — same as Baseball Reference
              (e.g. ``PHI``, ``NYY``, ``LAD``, ``ARI``).
          season: Calendar year of the season (e.g. 2025).
          min_plate_appearances: Minimum PA to include on the FanGraphs pull (default 1).
              Ignored for the BRef fallback, which lists everyone who appeared.
          player_name: Optional. Restrict to one player (e.g. ``Bryce Harper``).
  
      Use this for “Phillies lineup stats”, “Yankees 2024 hitters”, etc. For **league**
      leaderboards without a team filter, use ``season_batting_stats`` instead.
      """
      from pybaseball import batting_stats
  
      abbr = _normalize_team_abbr(team)
      data: pd.DataFrame | None = None
      fg_note = ""
      try:
          data = batting_stats(
              season, season, team=abbr, qual=min_plate_appearances
          )
          if data is None or getattr(data, "empty", True):
              fg_note = "FanGraphs returned no rows."
              data = None
      except Exception as e:
          fg_note = str(e)
          data = None
  
      source = "FanGraphs"
      if data is None or data.empty:
          try:
              data = _team_batting_from_bref(abbr, season)
              source = "Baseball Reference"
              if fg_note:
                  source += f" — {fg_note}"
          except Exception as e2:
              return (
                  f"Could not load team batting stats for {abbr} {season}. "
                  f"FanGraphs: {fg_note}. Baseball Reference: {e2}"
              )
  
      if player_name:
          try:
              data = _filter_player_rows(data, player_name)
          except ValueError as e:
              return str(e)
          if data.empty:
              return (
                  f"No batting row for {player_name!r} on team {abbr} in {season} "
                  "(check spelling and team)."
              )
  
      header = f"**Source:** {source}\n**Team:** {abbr} | **Season:** {season}\n\n"
      return header + _fmt(data, max_rows=200)