search_championships
Find World Cube Association championship competitions by type, including World, Continental, and National Championships. Filter results using continent codes or country ISO2 codes to locate specific speedcubing events.
Instructions
Search for WCA championships with optional filtering.
Returns championship competitions which are the most prestigious competitions in speedcubing including World Championships, Continental Championships, and National Championships.
Args:
page: Page number for pagination (default: 1)
championship_type: Filter by championship type:
- "world" for World Championships
- continent codes like "Europe", "Asia", "North America" for Continental Championships
- country ISO2 codes like "US", "CN", "DE" for National Championships
- None for all championships (default)
Returns: Paginated championship data with competition details
Example: search_championships(championship_type="world") - World Championships only search_championships(championship_type="US") - US National Championships
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| championship_type | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/wca_mcp_server/main.py:326-369 (handler)The @mcp.tool() decorated handler function that defines and implements the 'search_championships' tool. It handles input parameters, calls the WCAAPIClient for data retrieval with appropriate filters, and manages errors.
@mcp.tool() async def search_championships( page: int = 1, championship_type: str = None ) -> Dict[str, Any]: """Search for WCA championships with optional filtering. Returns championship competitions which are the most prestigious competitions in speedcubing including World Championships, Continental Championships, and National Championships. Args: page: Page number for pagination (default: 1) championship_type: Filter by championship type: - "world" for World Championships - continent codes like "Europe", "Asia", "North America" for Continental Championships - country ISO2 codes like "US", "CN", "DE" for National Championships - None for all championships (default) Returns: Paginated championship data with competition details Example: search_championships(championship_type="world") - World Championships only search_championships(championship_type="US") - US National Championships """ try: async with WCAAPIClient() as client: # Build filters based on championship_type filters = {} if championship_type: # The API expects the type parameter for filtering filters["type"] = championship_type.lower() championships_data = await client.get_championships( page=page, **filters ) return championships_data except APIError as e: raise Exception(f"Failed to search championships: {e}") except Exception as e: raise Exception(f"Unexpected error searching championships: {e}") - src/wca_mcp_server/client.py:242-287 (helper)The WCAAPIClient.get_championships method that fetches championships data from the WCA static API, applies client-side filtering by championship type (world, continent, country), and implements pagination.
async def get_championships( self, page: int = 1, per_page: int = 25, **filters ) -> Dict[str, Any]: """Get championships with optional filtering. Args: page: Page number (1-based) - Note: static API doesn't support pagination per_page: Items per page (max 100) - Note: static API doesn't support pagination **filters: Additional filter parameters - Note: static API has limited filtering Returns: Paginated championship data """ # For the static API, we get all championships and handle filtering/pagination client-side data = await self._make_request("championships.json") # Handle filtering by type if specified items = data.get("items", []) if isinstance(data, dict) else [] if "type" in filters: filter_type = filters["type"].lower() if filter_type == "world": items = [item for item in items if item.get("region") == "world"] else: # Filter by region (continent or country) items = [item for item in items if item.get("region", "").lower() == filter_type] # Simple client-side pagination start_idx = (page - 1) * per_page end_idx = start_idx + per_page paginated_items = items[start_idx:end_idx] return { "items": paginated_items, "total": len(items), "page": page, "per_page": per_page, "pagination": { "page": page, "size": per_page, "total_pages": (len(items) + per_page - 1) // per_page } }