get_player_game_archives

Instructions

Implementation Reference

• src/chess_mcp/server.py:170-182 (handler)

  The tool handler function that makes an API request to Chess.com to get a list of available monthly game archives for a player.

  @mcp.tool(description="Get a list of available monthly game archives for a player on Chess.com")
  async def get_player_game_archives(username: str) -> Dict[str, Any]:
      """
      Get a list of available monthly game archives for a player on Chess.com.
  
      Args:
          username: The Chess.com username
  
      Returns:
          List of available game archives
      """
      logger.info("Fetching player game archives", username=username)
      return await make_api_request(f"player/{username}/games/archives")

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

  The tool is registered as an MCP tool via the @mcp.tool decorator on the handler function.

  @mcp.tool(description="Get a list of available monthly game archives for a player on Chess.com")
  async def get_player_game_archives(username: str) -> Dict[str, Any]:

• src/chess_mcp/server.py:170-182 (schema)

  The function signature defines the input schema: username (str) is required. The return type is Dict[str, Any].

  @mcp.tool(description="Get a list of available monthly game archives for a player on Chess.com")
  async def get_player_game_archives(username: str) -> Dict[str, Any]:
      """
      Get a list of available monthly game archives for a player on Chess.com.
  
      Args:
          username: The Chess.com username
  
      Returns:
          List of available game archives
      """
      logger.info("Fetching player game archives", username=username)
      return await make_api_request(f"player/{username}/games/archives")

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

  The make_api_request helper function is called by the handler to perform the actual HTTP request to the Chess.com API.

  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

• tests/test_server.py:242-248 (helper)

  Test for the get_player_game_archives handler, verifying it calls the correct API endpoint and returns the mock response.

  async def test_get_player_game_archives():
      mock_archives = {"archives": ["https://api.chess.com/pub/player/username/games/2022/01"]}
  
      with patch("chess_mcp.server.make_api_request", new=AsyncMock(return_value=mock_archives)):
          result = await get_player_game_archives("username")
  
      assert result == mock_archives