mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:485-517 (handler)

  The core handler implementation for the get_mlb_game_scoring_plays tool. Decorated with @mcp.tool() for automatic registration. Fetches play-by-play data using mlbstatsapi, filters by eventType if provided (e.g., scoring plays), and returns structured plays or error.

  @mcp.tool()
  def get_mlb_game_scoring_plays(
      game_id: int, eventType: Optional[str] = None, timecode: Optional[str] = None, fields: Optional[str] = None
  ) -> dict:
      """
      Get plays for a specific game by game_id, with optional filtering by eventType.
  
      Args:
          game_id (int): The game ID.
          eventType (Optional[str]): Filter plays by this event type (e.g., 'scoring_play', 'home_run').
          timecode (Optional[str]): Specific timecode for the play-by-play snapshot.
          fields (Optional[str]): Comma-separated list of fields to include.
  
      Returns:
          dict: Game plays, optionally filtered by eventType.
      """
      try:
          params = {}
          if timecode is not None:
              params["timecode"] = timecode
          if fields is not None:
              params["fields"] = fields
          plays = mlb.get_game_play_by_play(game_id, **params)
          if eventType:
              filtered_plays = [
                  play for play in plays.allplays if getattr(play.result, "eventType", None) == eventType
              ]
              return {"plays": filtered_plays}
          else:
              return {"plays": plays.allplays}
      except Exception as e:
          return {"error": str(e)}

• main.py:21-23 (registration)

  Registers the MLB tools (including get_mlb_game_scoring_plays) by invoking setup_mlb_tools(mcp), which defines all @mcp.tool() decorated functions.

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

• tests/test_mlb_api.py:28-30 (registration)

  In tests, registers tools via setup_mlb_tools(mcp) for testing the get_mlb_game_scoring_plays tool.

  mcp = MagicMock()
  patch_mcp_tool(mcp)
  mlb_api.setup_mlb_tools(mcp)

• tests/test_mlb_api.py:127-140 (handler)

  Test confirming the handler works, retrieves via get_tool and tests filtering by eventType."

  def test_get_mlb_game_scoring_plays(mcp):
      get_mlb_game_scoring_plays = get_tool(mcp, "get_mlb_game_scoring_plays")
      assert get_mlb_game_scoring_plays is not None
      # Corrected: Each play should be a MagicMock with .result.eventType
      mock_play1 = MagicMock()
      mock_play1.result.eventType = "scoring_play"
      mock_play2 = MagicMock()
      mock_play2.result.eventType = "other"
      mock_plays = MagicMock()
      mock_plays.allplays = [mock_play1, mock_play2]
      with patch("mlb_api.mlb.get_game_play_by_play", return_value=mock_plays):
          result = get_mlb_game_scoring_plays(game_id=1, eventType="scoring_play")
          assert "plays" in result

• mlb_api.py:489-500 (schema)

  Docstring defining input parameters and output format (schema).

  """
  Get plays for a specific game by game_id, with optional filtering by eventType.
  
  Args:
      game_id (int): The game ID.
      eventType (Optional[str]): Filter plays by this event type (e.g., 'scoring_play', 'home_run').
      timecode (Optional[str]): Specific timecode for the play-by-play snapshot.
      fields (Optional[str]): Comma-separated list of fields to include.
  
  Returns:
      dict: Game plays, optionally filtered by eventType.
  """