Unofficial WCA MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

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

  The MCP tool handler function that implements the core logic for retrieving and filtering person data by WCA ID. It uses WCAAPIClient to fetch raw data and applies configurable filtering for results, records, rankings, and medals.
  @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}")
• src/wca_mcp_server/client.py:178-187 (helper)

  The WCAAPIClient helper method that makes the HTTP GET request to the WCA API endpoint `/persons/{wca_id}.json` to retrieve the raw person data used by the handler.
  async def get_person(self, wca_id: str) -> Dict[str, Any]: """Get a specific person by WCA ID. Args: wca_id: WCA ID (e.g., "2003SEAR02") Returns: Person data """ return await self._make_request(f"persons/{wca_id}.json")
• src/wca_mcp_server/models/person.py:58-76 (schema)

  Pydantic BaseModel defining the expected structure of WCA person data, including fields like id, name, rankings, medals, records, and results, which matches the data processed by the tool handler.
  class Person(BaseModel): """WCA person/competitor information.""" id: str = Field(..., description="WCA ID") name: str = Field(..., description="Full name") slug: str = Field(..., description="URL slug") country: str = Field(..., description="Country code") number_of_competitions: int = Field(..., alias="numberOfCompetitions", description="Total competitions attended") competition_ids: List[str] = Field(..., alias="competitionIds", description="List of competition IDs") number_of_championships: int = Field(..., alias="numberOfChampionships", description="Total championships attended") championship_ids: List[str] = Field(..., alias="championshipIds", description="List of championship IDs") rank: PersonRanks = Field(..., description="Ranking information") medals: MedalCount = Field(..., description="Medal counts") records: Records = Field(..., description="Record counts") results: Dict[str, Dict[str, List[CompetitionResult]]] = Field( ..., description="Competition results organized by competition ID and event ID" )