Unofficial WCA MCP Server

Instructions

Implementation Reference

• src/wca_mcp_server/main.py:241-271 (handler)

  MCP tool handler: decorated with @mcp.tool(), defines parameters (year, month, day), calls WCAAPIClient.get_competitions_by_date, handles errors, and returns competition data.

  @mcp.tool()
  async def search_competitions_by_date(
      year: int,
      month: int,
      day: int
  ) -> Dict[str, Any]:
      """Search for WCA competitions on a specific date.
      
      Returns a small, focused list of competitions that occurred on the exact date specified.
      This typically returns 1-5 competitions, making it perfect for LLM processing.
      
      Args:
          year: Year (e.g., 2023, 2024)
          month: Month (1-12)
          day: Day (1-31)
          
      Returns:
          Competition data for the specific date (typically 1-5 competitions)
          
      Example:
          search_competitions_by_date(year=2024, month=3, day=15) - Competitions on March 15, 2024
      """
      try:
          async with WCAAPIClient() as client:
              competitions_data = await client.get_competitions_by_date(year, month, day)
              return competitions_data
      except APIError as e:
          raise Exception(f"Failed to search competitions by date: {e}")
      except Exception as e:
          raise Exception(f"Unexpected error searching competitions by date: {e}")

• src/wca_mcp_server/client.py:136-156 (helper)

  Helper method in WCAAPIClient: formats date into YYYY/MM/DD.json endpoint and calls internal _make_request to fetch data from WCA static API.

  async def get_competitions_by_date(
      self,
      year: int,
      month: int,
      day: int
  ) -> Dict[str, Any]:
      """Get competitions on a specific date.
      
      Args:
          year: Year (e.g., 2023, 2024)
          month: Month (1-12)
          day: Day (1-31)
          
      Returns:
          Competition data for the specific date
      """
      month_str = f"{month:02d}"  # Ensure 2-digit format
      day_str = f"{day:02d}"      # Ensure 2-digit format
      endpoint = f"competitions/{year}/{month_str}/{day_str}.json"
      return await self._make_request(endpoint)

• src/wca_mcp_server/main.py:25-25 (registration)

  FastMCP server instance creation where tools are registered via decorators.

  mcp = FastMCP("WCA MCP Server")