get_competition_event_results

Instructions

Implementation Reference

• src/wca_mcp_server/main.py:432-520 (handler)

  MCP tool handler for get_competition_event_results. Fetches raw results using WCAAPIClient, filters by round and limit, optionally includes solves, cleans data, and returns paginated response.

  @mcp.tool()
  async def get_competition_event_results(
      competition_id: str,
      event_id: str,
      round: str = "Final",
      limit: int = None,
      include_solves: bool = False
  ) -> Dict[str, Any]:
      """Get results for a specific event within a WCA competition.
      
      Returns focused results data for a single event in a competition.
      By default, returns only Final round results for better LLM processing.
      
      Args:
          competition_id: WCA competition ID (e.g., "WC2025", "CubingUSANationals2024")
          event_id: WCA event ID (e.g., "333" for 3x3x3 Cube, "222" for 2x2x2, 
                   "333bf" for 3x3x3 Blindfolded, "444" for 4x4x4)
          round: Specific round to filter by (default: "Final"). 
                 Use "all" for all rounds, or specify: "Final", "Semi Final", 
                 "Second round", "First round"
          limit: Maximum number of results to return (optional)
          include_solves: Whether to include detailed solve times (default: False)
          
      Returns:
          Filtered results data including:
          - Competitor performances for the specified round
          - Position, best single, and average times
          - Optionally detailed solve breakdowns
          
      Example:
          get_competition_event_results("WC2025", "333") - Final round only (16 results)
          get_competition_event_results("WC2025", "333", round="all") - All rounds (2490 results)
          get_competition_event_results("WC2025", "333", limit=10) - Top 10 from Final
      """
      try:
          async with WCAAPIClient() as client:
              # Get all results first
              all_results = await client.get_competition_event_results(competition_id, event_id)
              
              if not all_results or 'items' not in all_results:
                  return all_results
              
              items = all_results['items']
              
              # Filter by round if specified
              if round != "all":
                  items = [item for item in items if item.get('round') == round]
              
              # Apply limit if specified
              if limit:
                  items = items[:limit]
              
              # Clean up data for LLM consumption
              cleaned_items = []
              for item in items:
                  cleaned_item = {
                      'personId': item.get('personId'),
                      'round': item.get('round'),
                      'position': item.get('position'),
                      'best': item.get('best'),
                      'average': item.get('average')
                  }
                  
                  # Include solves only if requested
                  if include_solves:
                      cleaned_item['solves'] = item.get('solves', [])
                  
                  cleaned_items.append(cleaned_item)
              
              # Return filtered and cleaned results
              return {
                  'pagination': {
                      'page': 1,
                      'size': len(cleaned_items)
                  },
                  'total': len(cleaned_items),
                  'filter': {
                      'round': round,
                      'limit': limit,
                      'include_solves': include_solves
                  },
                  'items': cleaned_items
              }
              
      except APIError as e:
          raise Exception(f"Failed to get {event_id} results for competition {competition_id}: {e}")
      except Exception as e:
          raise Exception(f"Unexpected error getting {event_id} results for competition {competition_id}: {e}")

• src/wca_mcp_server/client.py:226-240 (helper)

  WCAAPIClient helper method that performs the HTTP GET request to the WCA static API endpoint for specific competition event results.

  async def get_competition_event_results(
      self,
      competition_id: str,
      event_id: str
  ) -> Dict[str, Any]:
      """Get results for a specific event in a competition.
      
      Args:
          competition_id: Competition ID
          event_id: Event ID (e.g., "333", "222")
          
      Returns:
          Result data for the specific event in the competition
      """
      return await self._make_request(f"results/{competition_id}/{event_id}.json")