OpenDota MCP Server

Instructions

Args:
    match_id: ID of the match to retrieve

Returns:
    Detailed match information including players, scores, and stats

Implementation Reference

• src/opendota_server/server.py:496-512 (handler)

  The core handler function for the 'get_match_data' tool. Decorated with @mcp.tool() for automatic registration in the FastMCP server. It fetches match data from the OpenDota API using make_opendota_request and formats it using format_match_data.

  @mcp.tool()
  async def get_match_data(match_id: int) -> str:
      """Get detailed data for a specific match.
  
      Args:
          match_id: ID of the match to retrieve
  
      Returns:
          Detailed match information including players, scores, and stats
      """
      match_data = await make_opendota_request(f"matches/{match_id}")
  
      if "error" in match_data:
          return f"Error retrieving match data: {match_data['error']}"
  
      return format_match_data(match_data)

• src/opendota_server/server.py:270-341 (helper)

  Helper function that formats the raw match dictionary from the API into a detailed, human-readable string including match details, scores, teams, and per-player stats.

  def format_match_data(match: Dict[str, Any]) -> str:
      """Format match data into a readable string."""
      if not match or "match_id" not in match:
          return "Match data not found."
  
      # Basic match info
      match_id = match.get("match_id", "Unknown")
      duration = match.get("duration", 0)
      duration_formatted = format_duration(duration)
      start_time = format_timestamp(match.get("start_time", 0))
  
      game_mode = match.get("game_mode", "Unknown")
      radiant_win = match.get("radiant_win", False)
      winner = "Radiant" if radiant_win else "Dire"
  
      # Scores
      radiant_score = match.get("radiant_score", 0)
      dire_score = match.get("dire_score", 0)
  
      # Teams
      radiant_team_data = match.get("radiant_team", {})
      dire_team_data = match.get("dire_team", {})
  
      # Handle the case where these might be strings instead of dicts
      if isinstance(radiant_team_data, dict):
          radiant_team = radiant_team_data.get("name", "Radiant")
      else:
          radiant_team = "Radiant"
  
      if isinstance(dire_team_data, dict):
          dire_team = dire_team_data.get("name", "Dire")
      else:
          dire_team = "Dire"
  
      # Format players data
      player_data = []
      players = match.get("players", [])
  
      for player in players:
          account_id = player.get("account_id", "Anonymous")
          hero_id = player.get("hero_id", "Unknown")
          hero_name = player.get("hero_name", "Unknown Hero")
          kills = player.get("kills", 0)
          deaths = player.get("deaths", 0)
          assists = player.get("assists", 0)
          gpm = player.get("gold_per_min", 0)
          xpm = player.get("xp_per_min", 0)
          team = "Radiant" if player.get("player_slot", 0) < 128 else "Dire"
  
          player_data.append(
              f"Player ID: {account_id}\n"
              f"- Team: {team}\n"
              f"- Hero: {hero_name} (ID: {hero_id})\n"
              f"- K/D/A: {kills}/{deaths}/{assists}\n"
              f"- GPM/XPM: {gpm}/{xpm}"
          )
      joined_player_data = "\n\n".join(player_data)
      formatted_output = (
          f"Match ID: {match_id}\n"
          f"Date: {start_time}\n"
          f"Duration: {duration_formatted}\n"
          f"Game Mode: {game_mode}\n"
          f"Teams: {radiant_team} vs {dire_team}\n"
          f"Score: {radiant_score} - {dire_score}\n"
          f"Winner: {winner}\n\n"
          f"Player Details:\n"
          f"{'-' * 40}\n"
          f"{joined_player_data}"
      )
  
      return formatted_output

• src/opendota_server/server.py:134-196 (helper)

  Core utility function used by get_match_data to perform API requests to OpenDota. Includes rate limiting, caching (5min TTL), retries, and comprehensive error handling.

  async def make_opendota_request(
      endpoint: str, params: Optional[Dict[str, Any]] = None
  ) -> Dict[str, Any]:
      """Make a request to the OpenDota API with proper error handling and caching."""
      # Apply rate limiting
      await apply_rate_limit()
  
      url = f"{OPENDOTA_API_BASE}/{endpoint}"
      request_params = API_PARAMS.copy()
      if params:
          request_params.update(params)
  
      # Create a cache key manually
      cache_key = endpoint
      if request_params:
          param_str = "&".join(f"{k}={v}" for k, v in sorted(request_params.items()))
          cache_key = f"{endpoint}?{param_str}"
  
      # Check cache
      cache_entry = api_cache.get(cache_key)
      if cache_entry:
          timestamp, data = cache_entry
          if time.time() - timestamp < CACHE_TTL:
              logger.debug(f"Cache hit for {cache_key}")
              return data
  
      logger.info(f"Making request to {endpoint} with params {request_params}")
  
      async with httpx.AsyncClient() as client:
          try:
              response = await client.get(
                  url,
                  params=request_params,
                  headers={"User-Agent": USER_AGENT},
                  timeout=10.0,
              )
              response.raise_for_status()
              data = response.json()
  
              # Cache the response
              api_cache[cache_key] = (time.time(), data)
  
              return data
          except httpx.HTTPStatusError as e:
              if e.response.status_code == 429:
                  logger.error(f"Rate limit exceeded for {endpoint}")
                  return {
                      "error": "Rate limit exceeded. Consider using an API key for more requests."
                  }
              if e.response.status_code == 404:
                  logger.error(f"Resource not found: {endpoint}")
                  return {"error": "Not found. The requested resource doesn't exist."}
              if e.response.status_code >= 500:
                  logger.error(f"OpenDota API server error: {e.response.status_code}")
                  return {"error": "OpenDota API server error. Please try again later."}
              logger.error(
                  f"HTTP error {e.response.status_code} for {endpoint}: {e.response.text}"
              )
              return {"error": f"HTTP error {e.response.status_code}: {e.response.text}"}
          except Exception as e:
              logger.error(f"Unexpected error for {endpoint}: {str(e)}")
              return {"error": f"Unexpected error: {str(e)}"}

• src/opendota_server/server.py:496-496 (registration)

  The @mcp.tool() decorator registers the get_match_data function as an MCP tool in the FastMCP server.

  @mcp.tool()