Unofficial WCA MCP Server

Instructions

Implementation Reference

• src/wca_mcp_server/main.py:88-195 (handler)

  The primary handler function for the 'get_person_by_wca_id' tool. Decorated with @mcp.tool() for automatic registration. Fetches person data from WCAAPIClient, applies configurable filtering for results, records, rankings, and medals, and returns a customized response.

  @mcp.tool()
  async def get_person_by_wca_id(
      wca_id: str,
      competition_id: str = None,
      include_competition_results: bool = False,
      include_personal_records: bool = True,
      include_rankings: bool = True,
      include_medals: bool = True,
      max_recent_competitions: int = 5
  ) -> Dict[str, Any]:
      """Get detailed information about a specific WCA competitor by their WCA ID.
      
      Returns information about a speedcuber with configurable detail levels.
      By default, returns basic info, personal records, rankings, and medals without
      the verbose competition results that can make responses extremely long.
      
      Args:
          wca_id: WCA ID of the person (e.g., "2003SEAR02")
          competition_id: Optional competition ID to get results from a specific competition (e.g., "WC2023")
          include_competition_results: Include detailed competition results (default: False)
          include_personal_records: Include personal best records (default: True)
          include_rankings: Include current world/continental/national rankings (default: True)
          include_medals: Include medal counts (default: True)
          max_recent_competitions: If including results, limit to N most recent competitions (default: 5)
          
      Returns:
          Filtered person information based on the specified parameters
      """
      try:
          async with WCAAPIClient() as client:
              person_data = await client.get_person(wca_id)
              
              # Create filtered response
              filtered_data = {
                  "id": person_data.get("id"),
                  "name": person_data.get("name"),
                  "slug": person_data.get("slug"),
                  "country": person_data.get("country"),
                  "numberOfCompetitions": person_data.get("numberOfCompetitions"),
                  "numberOfChampionships": person_data.get("numberOfChampionships"),
              }
              
              # Add competition IDs list (always include as it's lightweight)
              if "competitionIds" in person_data:
                  filtered_data["competitionIds"] = person_data["competitionIds"]
              if "championshipIds" in person_data:
                  filtered_data["championshipIds"] = person_data["championshipIds"]
              
              # Add personal records if requested
              if include_personal_records and "records" in person_data:
                  filtered_data["records"] = person_data["records"]
              
              # Add rankings if requested
              if include_rankings and "rank" in person_data:
                  filtered_data["rank"] = person_data["rank"]
              
              # Add medals if requested
              if include_medals and "medals" in person_data:
                  filtered_data["medals"] = person_data["medals"]
              
              # Handle specific competition results if competition_id is provided
              if competition_id:
                  competition_ids = person_data.get("competitionIds", [])
                  results = person_data.get("results", {})
                  
                  if competition_id in competition_ids:
                      # Person participated in this competition
                      if competition_id in results:
                          # Results data is available
                          filtered_data["results"] = {competition_id: results[competition_id]}
                          filtered_data["_results_note"] = f"Showing results from competition: {competition_id}"
                      else:
                          # Person participated but no results data available
                          filtered_data["results"] = {}
                          filtered_data["_results_note"] = f"Person participated in {competition_id} but no results data available"
                  else:
                      # Person did not participate in this competition
                      filtered_data["results"] = {}
                      filtered_data["_results_note"] = f"Person did not participate in competition: {competition_id}"
              
              # Add competition results if requested (with optional limiting)
              elif include_competition_results and "results" in person_data:
                  results = person_data["results"]
                  if max_recent_competitions and max_recent_competitions > 0:
                      # Get the most recent competitions (competition IDs are typically in chronological order)
                      competition_ids = person_data.get("competitionIds", [])
                      recent_competition_ids = competition_ids[-max_recent_competitions:] if competition_ids else []
                      
                      # Filter results to only include recent competitions
                      filtered_results = {
                          comp_id: results[comp_id] 
                          for comp_id in recent_competition_ids 
                          if comp_id in results
                      }
                      filtered_data["results"] = filtered_results
                      filtered_data["_results_note"] = f"Showing results from {len(filtered_results)} most recent competitions out of {len(results)} total"
                  else:
                      filtered_data["results"] = results
              elif not include_competition_results and not competition_id:
                  # Explicitly exclude results when not requested
                  filtered_data["_results_note"] = f"Competition results excluded (set include_competition_results=True to include). Total competitions: {person_data.get('numberOfCompetitions', 0)}"
              
              return filtered_data
              
      except APIError as e:
          raise Exception(f"Failed to get person {wca_id}: {e}")
      except Exception as e:
          raise Exception(f"Unexpected error getting person {wca_id}: {e}")