get_titled_players

Instructions

Implementation Reference

• src/chess_mcp/server.py:185-206 (handler)

  The main handler function for the 'get_titled_players' tool. Decorated with @mcp.tool, it validates the title against a list of valid chess titles, raises ValueError if invalid, and calls make_api_request to fetch titled players from the Chess.com API endpoint 'titled/{title}'.

  @mcp.tool(description="Get a list of titled players from Chess.com")
  async def get_titled_players(title: str) -> Dict[str, Any]:
      """
      Get a list of titled players from Chess.com.
  
      Args:
          title: Chess title (GM, WGM, IM, WIM, FM, WFM, NM, WNM, CM, WCM)
  
      Returns:
          List of titled players
  
      Raises:
          ValueError: If the title is not valid
      """
      valid_titles = ["GM", "WGM", "IM", "WIM", "FM", "WFM", "NM", "WNM", "CM", "WCM"]
      if title not in valid_titles:
          error_msg = f"Invalid title. Must be one of: {', '.join(valid_titles)}"
          logger.error("Invalid title provided", title=title, valid_titles=valid_titles)
          raise ValueError(error_msg)
  
      logger.info("Fetching titled players", title=title)
      return await make_api_request(f"titled/{title}")

• src/chess_mcp/server.py:185-185 (registration)

  Registration of the tool via the @mcp.tool decorator with description 'Get a list of titled players from Chess.com'.

  @mcp.tool(description="Get a list of titled players from Chess.com")

• src/chess_mcp/server.py:199-203 (schema)

  Input validation schema: defines valid_titles list (GM, WGM, IM, WIM, FM, WFM, NM, WNM, CM, WCM) and raises ValueError with guidance if an invalid title is provided.

  valid_titles = ["GM", "WGM", "IM", "WIM", "FM", "WFM", "NM", "WNM", "CM", "WCM"]
  if title not in valid_titles:
      error_msg = f"Invalid title. Must be one of: {', '.join(valid_titles)}"
      logger.error("Invalid title provided", title=title, valid_titles=valid_titles)
      raise ValueError(error_msg)

• src/chess_mcp/server.py:26-80 (helper)

  The make_api_request helper function that performs the actual HTTP call to the Chess.com API. Used by get_titled_players to fetch data from 'titled/{title}' endpoint.

  async def make_api_request(
      endpoint: str,
      params: Optional[Dict[str, Any]] = None,
      accept_json: bool = True
  ) -> Union[Dict[str, Any], str]:
      """
      Make a request to the Chess.com API.
  
      Args:
          endpoint: The API endpoint to request
          params: Optional query parameters
          accept_json: Whether to accept JSON response (True) or PGN (False)
  
      Returns:
          JSON response as dict or text response as string
  
      Raises:
          httpx.HTTPError: If the request fails
      """
      url = f"{config.base_url}/{endpoint}"
      headers = {
          "accept": "application/json" if accept_json else "application/x-chess-pgn"
      }
  
      logger.debug(
          "Making API request",
          endpoint=endpoint,
          url=url,
          accept_json=accept_json,
          has_params=params is not None
      )
  
      async with httpx.AsyncClient() as client:
          try:
              response = await client.get(url, headers=headers, params=params or {})
              response.raise_for_status()
  
              if accept_json:
                  result = response.json()
                  logger.debug("API request successful", endpoint=endpoint, response_type="json")
                  return result
              else:
                  result = response.text
                  logger.debug("API request successful", endpoint=endpoint, response_type="text")
                  return result
  
          except httpx.HTTPError as e:
              logger.error(
                  "API request failed",
                  endpoint=endpoint,
                  url=url,
                  error=str(e),
                  error_type=type(e).__name__
              )
              raise

• src/chess_mcp/server.py:371-389 (handler)

  The titled_players_resource function (a @mcp.resource) that wraps get_titled_players to provide it as a resource at 'chess://titled/{title}', returning JSON-formatted results.

  @mcp.resource("chess://titled/{title}")
  async def titled_players_resource(title: str) -> str:
      """
      Resource that returns a list of titled players.
  
      Args:
          title: Chess title (GM, WGM, IM, WIM, FM, WFM, NM, WNM, CM, WCM)
  
      Returns:
          JSON-formatted titled players list
      """
      try:
          import json
          logger.debug("Fetching titled players resource", title=title)
          players = await get_titled_players(title=title)
          return json.dumps(players, indent=2)
      except Exception as e:
          logger.error("Error retrieving titled players", title=title, error=str(e))
          return f"Error retrieving titled players: {str(e)}"