Unofficial WCA MCP Server

Instructions

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 } }