get_player_games_by_month
Retrieve Chess.com player game records for a specific month by providing username, year, and month. Access historical chess data for analysis or reference through the MCP server.
Instructions
Get a player's games for a specific month from Chess.com
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| month | Yes | ||
| username | Yes | ||
| year | Yes |
Input Schema (JSON Schema)
{
"properties": {
"month": {
"title": "Month",
"type": "integer"
},
"username": {
"title": "Username",
"type": "string"
},
"year": {
"title": "Year",
"type": "integer"
}
},
"required": [
"username",
"year",
"month"
],
"title": "get_player_games_by_monthArguments",
"type": "object"
}
Implementation Reference
- src/chess_mcp/server.py:143-168 (handler)The @mcp.tool decorator registers the tool named 'get_player_games_by_month'. The async function implements the core logic: formats the month, logs the request, and fetches the games data from the Chess.com API endpoint using the shared make_api_request helper.@mcp.tool(description="Get a player's games for a specific month from Chess.com") async def get_player_games_by_month( username: str, year: int, month: int ) -> Dict[str, Any]: """ Get a player's games for a specific month from Chess.com. Args: username: The Chess.com username year: Year (YYYY format) month: Month (MM format, 01-12) Returns: Games data for the specified month """ month_str = str(month).zfill(2) logger.info( "Fetching player games by month", username=username, year=year, month=month_str ) return await make_api_request(f"player/{username}/games/{year}/{month_str}")
- src/chess_mcp/server.py:143-143 (registration)The @mcp.tool decorator provides the registration of the tool with its description. FastMCP uses the function name as the tool name.@mcp.tool(description="Get a player's games for a specific month from Chess.com")
- src/chess_mcp/server.py:144-148 (schema)Function signature defines the input schema (username: str, year: int, month: int) and output (Dict[str, Any]), which FastMCP uses for tool schema generation.async def get_player_games_by_month( username: str, year: int, month: int ) -> Dict[str, Any]:
- src/chess_mcp/server.py:26-81 (helper)Shared helper function used by the tool to make HTTP requests to the Chess.com API, handling JSON/PGN responses and errors.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