get_mlb_game_scoring_plays
Retrieve scoring plays and game events from MLB games by game ID, with options to filter by event type, timecode, or specific fields.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| game_id | Yes | ||
| eventType | No | ||
| timecode | No | ||
| fields | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
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. """