Unofficial WCA MCP Server

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()