mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:314-352 (handler)

  The core handler function for the 'get_mlb_team_info' tool. It is decorated with @mcp.tool(), which registers the tool and infers the schema from the type hints and docstring. The function resolves the team name/ID using a helper, fetches team information from the MLB stats API, and returns the data or an error.
  @mcp.tool() def get_mlb_team_info( team: str, season: Optional[int] = None, sport_id: Optional[int] = None, hydrate: Optional[str] = None, fields: Optional[str] = None, ) -> dict: """ Get information about a specific team by ID or name. Args: team (str): Team ID or team name as a string. Can be numeric string, full name, abbreviation, or location. season (Optional[int]): Season year. sport_id (Optional[int]): Sport ID. hydrate (Optional[str]): Additional data to hydrate. fields (Optional[str]): Comma-separated list of fields to include. Returns: dict: Team information. """ try: params = {} if season is not None: params["season"] = season if sport_id is not None: params["sportId"] = sport_id if hydrate is not None: params["hydrate"] = hydrate if fields is not None: params["fields"] = fields team_id = get_team_id_from_name(team) if team_id is None: return {"error": f"Could not find team ID for '{team}'"} team_info = mlb.get_team(team_id, **params) return {"team_info": team_info} except Exception as e: return {"error": str(e)}
• main.py:22-22 (registration)

  Invocation of setup_mlb_tools(mcp) in the main server file, which defines and registers the get_mlb_team_info tool (along with other MLB tools) on the MCP server instance.
  setup_mlb_tools(mcp)
• mlb_api.py:152-175 (helper)

  get_team_id_from_name helper function: Maps a team string (name, partial name, or ID) to the numeric team ID by checking a local CSV file, used directly in the handler to resolve the 'team' parameter.
  def get_team_id_from_name(team: str) -> Optional[int]: """Helper to get team ID from team name, partial name, or stringified ID.""" # Accept stringified integer as ID try: return int(team) except (ValueError, TypeError): pass import csv team_lower = team.lower().strip() with open("current_mlb_teams.csv", "r") as f: reader = csv.DictReader(f) # First, try exact match for row in reader: if team_lower == row["team_name"].lower().strip(): return int(row["team_id"]) f.seek(0) next(reader) # skip header # Then, try substring match for row in reader: if team_lower in row["team_name"].lower(): return int(row["team_id"]) return None
• mlb_api.py:177-187 (helper)

  get_team_abbreviation_from_name helper: Gets the 3-letter team abbreviation from name or ID, though not directly used in this tool.
  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:315-352 (schema)

  The function signature and docstring define the input schema (parameters like team: str, season: Optional[int], etc.) and output (dict with team_info or error), used by MCP for validation.
  def get_mlb_team_info( team: str, season: Optional[int] = None, sport_id: Optional[int] = None, hydrate: Optional[str] = None, fields: Optional[str] = None, ) -> dict: """ Get information about a specific team by ID or name. Args: team (str): Team ID or team name as a string. Can be numeric string, full name, abbreviation, or location. season (Optional[int]): Season year. sport_id (Optional[int]): Sport ID. hydrate (Optional[str]): Additional data to hydrate. fields (Optional[str]): Comma-separated list of fields to include. Returns: dict: Team information. """ try: params = {} if season is not None: params["season"] = season if sport_id is not None: params["sportId"] = sport_id if hydrate is not None: params["hydrate"] = hydrate if fields is not None: params["fields"] = fields team_id = get_team_id_from_name(team) if team_id is None: return {"error": f"Could not find team ID for '{team}'"} team_info = mlb.get_team(team_id, **params) return {"team_info": team_info} except Exception as e: return {"error": str(e)}