download_player_games_pgn

Instructions

Implementation Reference

• src/chess_mcp/server.py:239-267 (handler)

  The main tool handler function that downloads PGN files for all games in a specific month from Chess.com's API. Decorated with @mcp.tool, it constructs the API endpoint, calls make_api_request with accept_json=False to get PGN text, and returns the result.

  @mcp.tool(description="Download PGN files for all games in a specific month from Chess.com")
  async def download_player_games_pgn(
      username: str,
      year: int,
      month: int
  ) -> str:
      """
      Download PGN files for all games in a specific month from Chess.com.
  
      Args:
          username: The Chess.com username
          year: Year (YYYY format)
          month: Month (MM format, 01-12)
  
      Returns:
          Multi-game PGN format text containing all games for the month
      """
      month_str = str(month).zfill(2)
      logger.info(
          "Downloading player games PGN",
          username=username,
          year=year,
          month=month_str
      )
      result = await make_api_request(
          f"player/{username}/games/{year}/{month_str}/pgn",
          accept_json=False
      )
      return result

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

  The @mcp.tool decorator registers the function as an MCP tool with the given description.

  @mcp.tool(description="Download PGN files for all games in a specific month from Chess.com")

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

  The helper function used by download_player_games_pgn to make the actual HTTP GET request to the Chess.com API. When accept_json is False (as called by the PGN tool), it sends 'application/x-chess-pgn' as the Accept header and returns the raw text response.

  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:240-244 (schema)

  The function signature defines the schema/inputs: username (str), year (int), month (int), and returns a string (multi-game PGN text).

  async def download_player_games_pgn(
      username: str,
      year: int,
      month: int
  ) -> str:

• src/chess_mcp/server.py:413-448 (helper)

  An MCP resource that wraps the download_player_games_pgn tool, providing a resource-based access pattern to the same underlying PGN download functionality.

  @mcp.resource("chess://player/{username}/games/{year}/{month}/pgn")
  async def player_games_pgn_resource(username: str, year: str, month: str) -> str:
      """
      Resource that returns a player's games for a specific month in PGN format.
  
      Args:
          username: The Chess.com username
          year: Year (YYYY format)
          month: Month (MM format, 01-12)
  
      Returns:
          PGN-formatted games
      """
      try:
          logger.debug(
              "Fetching player games PGN resource",
              username=username,
              year=year,
              month=month
          )
          pgn_data = await download_player_games_pgn(
              username=username,
              year=int(year),
              month=int(month)
          )
          return pgn_data
      except Exception as e:
          logger.error(
              "Error downloading PGN data",
              username=username,
              year=year,
              month=month,
              error=str(e)
          )
          return f"Error downloading PGN data: {str(e)}"