get_rankings

Instructions

Implementation Reference

• src/wca_mcp_server/main.py:198-237 (handler)

  The main MCP tool handler for 'get_rankings' decorated with @mcp.tool(), which invokes the WCAAPIClient to fetch paginated rankings data from the WCA static API.

  @mcp.tool()
  async def get_rankings(
      event_id: str,
      region: str = "world",
      ranking_type: str = "single",
      page: int = 1,
      per_page: int = 25
  ) -> Dict[str, Any]:
      """Get current world rankings and records for a specific event.
      
      Returns the current rankings for any WCA event, which includes world records
      and top performers. Can filter by region (world, continent, or country).
      
      Args:
          event_id: WCA event ID (e.g., "333" for 3x3x3 Cube, "222" for 2x2x2)
          region: Region code - "world" for world rankings, continent codes like "Europe", 
                  or country ISO2 codes like "US", "CN" (default: "world")
          ranking_type: Type of ranking - "single" for single solve records or 
                       "average" for average records (default: "single")
          page: Page number (1-based, default: 1)
          per_page: Items per page (max 100, default: 25)
          
      Returns:
          Paginated ranking data with current records and top performers
      """
      try:
          async with WCAAPIClient() as client:
              rankings_data = await client.get_rankings(
                  event_id=event_id,
                  region=region,
                  type=ranking_type,
                  page=page,
                  per_page=per_page
              )
              return rankings_data
      except APIError as e:
          raise Exception(f"Failed to get rankings for {event_id}: {e}")
      except Exception as e:
          raise Exception(f"Unexpected error getting rankings for {event_id}: {e}")

• src/wca_mcp_server/client.py:189-210 (helper)

  Helper method in WCAAPIClient that performs the HTTP request to the WCA static API endpoint for rankings data.

  async def get_rankings(
      self,
      event_id: str,
      region: str = "world",
      type: str = "single",
      page: int = 1,
      per_page: int = 25
  ) -> Dict[str, Any]:
      """Get rankings for an event.
      
      Args:
          event_id: Event ID (e.g., "333")
          region: Region code ("world", continent code, or country ISO2)
          type: Ranking type ("single" or "average")
          page: Page number (1-based)
          per_page: Items per page (max 100)
          
      Returns:
          Paginated ranking data
      """
      # The static API uses a specific URL format: rank/{region}/{type}/{event}.json
      return await self._make_request(f"rank/{region}/{type}/{event_id}.json")

• src/wca_mcp_server/models/ranking.py:1-30 (schema)

  Pydantic models defining the structure of ranking data (Rank, Ranks) used for input/output validation of the get_rankings tool.

  """Ranking and record models."""
  
  from enum import Enum
  from typing import List
  from pydantic import BaseModel, Field
  
  from .base import PaginatedResponse, RankInfo
  
  
  class RankType(str, Enum):
      """Type of ranking (single or average)."""
      
      SINGLE = "single"
      AVERAGE = "average"
  
  
  class Rank(BaseModel):
      """Individual ranking entry."""
      
      rank_type: RankType = Field(..., alias="rankType", description="Type of ranking")
      person_id: str = Field(..., alias="personId", description="WCA ID of the person")
      event_id: str = Field(..., alias="eventId", description="Event identifier")
      best: int = Field(..., description="Best time/score in centiseconds or points")
      rank: RankInfo = Field(..., description="Ranking positions across regions")
  
  
  # Paginated response types
  class Ranks(PaginatedResponse[Rank]):
      """Paginated list of rankings."""
      pass

• src/wca_mcp_server/main.py:198-198 (registration)

  The @mcp.tool() decorator registers the get_rankings function as an MCP tool.

  @mcp.tool()