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