Unofficial WCA MCP Server

Instructions

Implementation Reference

• src/wca_mcp_server/main.py:273-300 (handler)

  MCP tool handler decorated with @mcp.tool() that executes the search_competitions_by_event logic by delegating to WCAAPIClient.get_competitions_by_event

  @mcp.tool()
  async def search_competitions_by_event(
      event_id: str,
      page: int = 1
  ) -> Dict[str, Any]:
      """Search for WCA competitions that include a specific event.
      
      Returns competitions that feature the specified WCA event. Results are paginated
      to manage the response size.
      
      Args:
          event_id: WCA event ID (e.g., "333" for 3x3x3 Cube, "222" for 2x2x2, "333bf" for 3x3x3 Blindfolded)
          page: Page number for pagination (default: 1)
          
      Returns:
          Paginated competition data for competitions featuring the specified event
          
      Example:
          search_competitions_by_event(event_id="333bf") - Competitions with 3x3x3 Blindfolded
      """
      try:
          async with WCAAPIClient() as client:
              competitions_data = await client.get_competitions_by_event(event_id, page)
              return competitions_data
      except APIError as e:
          raise Exception(f"Failed to search competitions by event: {e}")
      except Exception as e:
          raise Exception(f"Unexpected error searching competitions by event: {e}")

• src/wca_mcp_server/client.py:157-176 (helper)

  Helper method in WCAAPIClient that constructs the WCA API endpoint for competitions by event and performs the HTTP request via _make_request

  async def get_competitions_by_event(
      self,
      event_id: str,
      page: int = 1
  ) -> Dict[str, Any]:
      """Get competitions that feature a specific event.
      
      Args:
          event_id: Event ID (e.g., "333", "222", "333bf")
          page: Page number (1-based)
          
      Returns:
          Paginated competition data for the event
      """
      if page == 1:
          endpoint = f"competitions/{event_id}.json"
      else:
          endpoint = f"competitions/{event_id}-page-{page}.json"
      return await self._make_request(endpoint)