◉ClassyGitshadowzzh

playchess.py

playchess.py
"""
Chess MCP Server

This module provides MCP server functionality for chess game operations and analysis.
It utilizes the 'python-chess' library to support various chess-related tasks.

Key features:
- Manage chess game states (new game, load FEN, make moves)
- Validate and execute moves in UCI or SAN format
- Get legal moves for the current position
- Check game status (checkmate, stalemate, draw, etc.)
- Basic board visualization (ASCII)
- LLM-optimized output formatting for game states and analysis

Main functions:
- mcp_new_game: Start a new chess game
- mcp_load_fen: Load a game state from FEN notation
- mcp_make_move: Make a move on the current board
- mcp_get_legal_moves: List all legal moves in the current position
- mcp_get_board_state: Get the current board state (FEN, ASCII, status)
- mcp_get_game_status: Check the current game status (e.g., checkmate)
- mcp_get_chess_capabilities: Get service capabilities
"""

import json
import traceback
from datetime import datetime
from typing import Any

import chess
from dotenv import load_dotenv
from pydantic import BaseModel, Field
from pydantic.fields import FieldInfo

from aworld.logs.util import Color
from examples.gaia.mcp_collections.base import ActionArguments, ActionCollection, ActionResponse


class ChessBoardState(BaseModel):
    """Structured representation of the chess board state."""

    fen: str
    turn: str  # 'white' or 'black'
    castling_rights: str
    ep_square: str | None = None  # The target square if an en passant capture is possible *right now*
    halfmove_clock: int
    fullmove_number: int
    is_check: bool
    is_checkmate: bool
    is_stalemate: bool
    is_insufficient_material: bool
    is_seventyfive_moves: bool
    is_fivefold_repetition: bool
    is_game_over: bool
    ascii_board: str
    legal_moves_uci: list[str]
    legal_moves_san: list[str]
    is_en_passant_possible: bool  # True if there is a legal en passant capture
    en_passant_capture_square: str | None = None  # The square a pawn would move TO for en passant


class ChessMoveResult(BaseModel):
    """Result of making a chess move."""

    move_uci: str
    move_san: str
    is_capture: bool
    is_check: bool
    is_kingside_castling: bool
    is_queenside_castling: bool
    board_after_move: ChessBoardState


class ChessMetadata(BaseModel):
    """Metadata for Chess operation results."""

    operation: str
    fen_before: str | None = None
    fen_after: str | None = None
    move_played: str | None = None
    execution_time: float | None = None
    error_type: str | None = None
    engine_analysis_depth: int | None = None


class ChessCollection(ActionCollection):
    """MCP service for chess game operations and analysis.

    Provides capabilities to manage chess games, make moves, analyze positions,
    and get game status, all formatted for LLM interaction.
    """

    def __init__(self, arguments: ActionArguments) -> None:
        super().__init__(arguments)
        self.board = chess.Board()
        # For more advanced analysis, you might initialize a chess engine here
        # Example: self.engine = chess.engine.SimpleEngine.popen_uci("/path/to/stockfish")
        # Ensure Stockfish or another UCI engine is installed and path is correct.
        self._color_log("Chess service initialized", Color.green, "debug")
        self._color_log(f"Initial board FEN: {self.board.fen()}", Color.blue, "debug")

    def _get_current_board_state(self) -> ChessBoardState:
        """Helper to get the current board state in a structured format."""
        legal_moves_uci = [move.uci() for move in self.board.legal_moves]
        legal_moves_san = []
        # Generating SAN for all moves can be slow, do it carefully or on demand
        # for move in self.board.legal_moves:
        #     try:
        #         legal_moves_san.append(self.board.san(move))
        #     except Exception:
        #         legal_moves_san.append(move.uci()) # Fallback to UCI if SAN fails

        has_legal_ep = self.board.has_legal_en_passant()
        ep_sq_name = chess.square_name(self.board.ep_square) if self.board.ep_square else None

        return ChessBoardState(
            fen=self.board.fen(),
            turn="white" if self.board.turn == chess.WHITE else "black",
            castling_rights=self.board.castling_xfen(),
            ep_square=ep_sq_name,  # This is the target square from FEN, might not be a legal capture
            halfmove_clock=self.board.halfmove_clock,
            fullmove_number=self.board.fullmove_number,
            is_check=self.board.is_check(),
            is_checkmate=self.board.is_checkmate(),
            is_stalemate=self.board.is_stalemate(),
            is_insufficient_material=self.board.is_insufficient_material(),
            is_seventyfive_moves=self.board.is_seventyfive_moves(),
            is_fivefold_repetition=self.board.is_fivefold_repetition(),
            is_game_over=self.board.is_game_over(),
            ascii_board=str(self.board),
            legal_moves_uci=legal_moves_uci,
            legal_moves_san=legal_moves_san,  # Populate if SAN generation is enabled
            is_en_passant_possible=has_legal_ep,
            en_passant_capture_square=ep_sq_name if has_legal_ep else None,
        )

    def _format_board_state_output(self, state: ChessBoardState, output_format: str = "markdown") -> str:
        """Format board state for LLM consumption."""
        if output_format == "json":
            return json.dumps(state.model_dump(), indent=2)

        status_parts = []
        if state.is_checkmate:
            status_parts.append("Checkmate!")
        elif state.is_stalemate:
            status_parts.append("Stalemate!")
        elif state.is_insufficient_material:
            status_parts.append("Draw by insufficient material.")
        elif state.is_seventyfive_moves:
            status_parts.append("Draw by 75-move rule.")
        elif state.is_fivefold_repetition:
            status_parts.append("Draw by fivefold repetition.")
        elif state.is_check:
            status_parts.append("Check!")
        game_status = " ".join(status_parts) if status_parts else "Game in progress."

        en_passant_info = "N/A"
        if state.is_en_passant_possible and state.en_passant_capture_square:
            en_passant_info = f"Yes, capture on {state.en_passant_capture_square}"
        elif state.ep_square:  # FEN might list an ep_square even if no legal ep move
            en_passant_info = f"Target square {state.ep_square} (no legal en passant capture)"

        if output_format == "text":
            return (
                f"Board FEN: {state.fen}\n"
                f"Turn: {state.turn.capitalize()}\n"
                f"Status: {game_status}\n"
                f"Castling: {state.castling_rights}\n"
                f"En Passant Possible: {en_passant_info}\n"  # Updated line
                f"Halfmove Clock: {state.halfmove_clock}\n"
                f"Fullmove Number: {state.fullmove_number}\n"
                f"Game Over: {'Yes' if state.is_game_over else 'No'}\n"
                f"Legal Moves (UCI): {', '.join(state.legal_moves_uci[:10])}... ({len(state.legal_moves_uci)} total)\n"
                f"Board:\n{state.ascii_board}"
            )
        else:  # markdown (default)
            return (
                f"### Chess Board State\n"
                f"**FEN:** `{state.fen}`\n"
                f"**Turn:** {state.turn.capitalize()}\n"
                f"**Status:** {game_status}\n"
                f"**Castling Rights:** {state.castling_rights}\n"
                f"**En Passant Possible:** {en_passant_info}\n"  # Updated line
                f"**Game Over:** {'Yes' if state.is_game_over else 'No'}\n"
                f"**Legal Moves (UCI, sample):** `{', '.join(state.legal_moves_uci[:5])}`... ({len(state.legal_moves_uci)} total)\n"
                f"```\n{state.ascii_board}\n```"
            )

    async def mcp_new_game(self) -> ActionResponse:
        """Starts a new standard chess game, resetting the board.

        Returns:
            ActionResponse with the initial board state.
        """
        start_time = datetime.now()
        self.board.reset()
        self._color_log("🚀 New chess game started", Color.green)

        current_state = self._get_current_board_state()
        formatted_output = self._format_board_state_output(current_state)
        execution_time = (datetime.now() - start_time).total_seconds()

        metadata = ChessMetadata(
            operation="new_game", fen_after=self.board.fen(), execution_time=execution_time
        ).model_dump()

        return ActionResponse(success=True, message=formatted_output, metadata=metadata)

    async def mcp_load_fen(
        self, fen_string: str = Field(description="FEN string representing the board state.")
    ) -> ActionResponse:
        """Loads a chess game from a FEN (Forsyth-Edwards Notation) string.

        Args:
            fen_string: The FEN string to load.

        Returns:
            ActionResponse with the board state after loading the FEN.
        """
        # Handle FieldInfo
        if isinstance(fen_string, FieldInfo):
            fen_string = fen_string.default

        start_time = datetime.now()
        try:
            self.board.set_fen(fen_string)
            self._color_log(f"🔄 Board loaded from FEN: {fen_string}", Color.blue)
            current_state = self._get_current_board_state()
            formatted_output = self._format_board_state_output(current_state)
            execution_time = (datetime.now() - start_time).total_seconds()
            metadata = ChessMetadata(
                operation="load_fen", fen_after=self.board.fen(), execution_time=execution_time
            ).model_dump()
            return ActionResponse(success=True, message=formatted_output, metadata=metadata)
        except ValueError as e:
            error_msg = f"Invalid FEN string: {str(e)}"
            self.logger.error(f"FEN loading error: {traceback.format_exc()}")
            execution_time = (datetime.now() - start_time).total_seconds()
            metadata = ChessMetadata(
                operation="load_fen", error_type="invalid_fen", execution_time=execution_time
            ).model_dump()
            return ActionResponse(success=False, message=error_msg, metadata=metadata)

    async def mcp_make_move(
        self, move_str: str = Field(description="Move in UCI (e.g., 'e2e4') or SAN (e.g., 'Nf3') format.")
    ) -> ActionResponse:
        """Makes a move on the current chess board.

        The move can be in UCI (Universal Chess Interface) format (e.g., 'g1f3')
        or SAN (Standard Algebraic Notation) format (e.g., 'Nf3').

        Args:
            move_str: The move to make.

        Returns:
            ActionResponse with the result of the move and new board state.
        """
        # Handle FieldInfo
        if isinstance(move_str, FieldInfo):
            move_str = move_str.default

        start_time = datetime.now()
        fen_before = self.board.fen()
        try:
            move = None
            # Try parsing as UCI first, then SAN
            try:
                move = self.board.parse_uci(move_str)
            except ValueError:
                try:
                    move = self.board.parse_san(move_str)
                except ValueError as e_san:
                    raise ValueError(f"Invalid move format. UCI error: N/A, SAN error: {e_san}") from e_san

            if move not in self.board.legal_moves:
                raise ValueError(f"Illegal move: {move_str}")

            move_san = self.board.san(move)
            is_capture = self.board.is_capture(move)
            is_kingside_castling = self.board.is_kingside_castling(move)
            is_queenside_castling = self.board.is_queenside_castling(move)

            self.board.push(move)
            is_check_after_move = self.board.is_check()

            self._color_log(f"♟️ Move made: {move_str} (UCI: {move.uci()}, SAN: {move_san})", Color.cyan)

            current_state = self._get_current_board_state()
            move_result = ChessMoveResult(
                move_uci=move.uci(),
                move_san=move_san,
                is_capture=is_capture,
                is_check=is_check_after_move,  # Check status *after* the move
                is_kingside_castling=is_kingside_castling,
                is_queenside_castling=is_queenside_castling,
                board_after_move=current_state,
            )

            # Format output (can be customized)
            formatted_output = f"Move {move_result.move_san} (UCI: {move_result.move_uci}) played.\n"
            formatted_output += self._format_board_state_output(current_state)

            execution_time = (datetime.now() - start_time).total_seconds()
            metadata = ChessMetadata(
                operation="make_move",
                fen_before=fen_before,
                fen_after=self.board.fen(),
                move_played=move.uci(),
                execution_time=execution_time,
            ).model_dump()

            return ActionResponse(success=True, message=formatted_output, metadata=metadata)

        except ValueError as e:
            error_msg = f"Failed to make move '{move_str}': {str(e)}"
            self.logger.error(f"Move error: {traceback.format_exc()}")
            execution_time = (datetime.now() - start_time).total_seconds()
            metadata = ChessMetadata(
                operation="make_move",
                fen_before=fen_before,
                move_played=move_str,
                error_type="invalid_or_illegal_move",
                execution_time=execution_time,
            ).model_dump()
            return ActionResponse(success=False, message=error_msg, metadata=metadata)

    async def mcp_get_legal_moves(
        self,
        output_format: str = Field(
            default="markdown", description="Output format: 'uci_list', 'san_list', 'markdown', 'json'"
        ),
    ) -> ActionResponse:
        """Gets all legal moves for the current board position.

        Args:
            output_format: 'uci_list' (simple list of UCI moves),
                           'san_list' (simple list of SAN moves),
                           'markdown' (formatted list),
                           'json' (structured list).

        Returns:
            ActionResponse with the list of legal moves.
        """
        # Handle FieldInfo
        if isinstance(output_format, FieldInfo):
            output_format = output_format.default

        start_time = datetime.now()
        legal_moves_uci = [move.uci() for move in self.board.legal_moves]

        message_content: Any
        if output_format == "uci_list":
            message_content = legal_moves_uci
        elif output_format == "san_list":
            try:
                message_content = [self.board.san(move) for move in self.board.legal_moves]
            except Exception as e:
                self.logger.warning(
                    f"Could not generate all SAN moves: {e}. Falling back to UCI for problematic moves."
                )
                san_moves = []
                for move in self.board.legal_moves:
                    try:
                        san_moves.append(self.board.san(move))
                    except Exception:
                        san_moves.append(move.uci() + " (SAN failed)")
                message_content = san_moves
        elif output_format == "json":
            moves_data = []
            for move in self.board.legal_moves:
                try:
                    san = self.board.san(move)
                except Exception:
                    san = move.uci() + " (SAN failed)"
                moves_data.append({"uci": move.uci(), "san": san})
            message_content = json.dumps(moves_data, indent=2)
        else:  # markdown
            if not legal_moves_uci:
                message_content = "No legal moves available (game might be over)."
            else:
                san_formatted_moves = []
                for move_uci in legal_moves_uci[:20]:  # Display sample for markdown
                    try:
                        move_obj = self.board.parse_uci(move_uci)
                        san_formatted_moves.append(f"`{self.board.san(move_obj)}` ({move_uci})")
                    except Exception:
                        san_formatted_moves.append(f"`{move_uci}` (SAN failed)")

                header = f"### Legal Moves ({len(legal_moves_uci)} total)\n"
                moves_list_md = "\n".join([f"- {m}" for m in san_formatted_moves])
                if len(legal_moves_uci) > 20:
                    moves_list_md += "\n- ... (and more)"
                message_content = header + moves_list_md

        execution_time = (datetime.now() - start_time).total_seconds()
        metadata = ChessMetadata(
            operation="get_legal_moves", fen_before=self.board.fen(), execution_time=execution_time
        ).model_dump()

        return ActionResponse(success=True, message=message_content, metadata=metadata)

    async def mcp_get_board_state(
        self, output_format: str = Field(default="markdown", description="Output format: 'markdown', 'json', or 'text'")
    ) -> ActionResponse:
        """Gets the current state of the chess board.

        Includes FEN, turn, game status, ASCII board, and legal moves.

        Args:
            output_format: Desired format for the board state.

        Returns:
            ActionResponse with the current board state.
        """
        # Handle FieldInfo
        if isinstance(output_format, FieldInfo):
            output_format = output_format.default

        start_time = datetime.now()
        current_state = self._get_current_board_state()
        formatted_output = self._format_board_state_output(current_state, output_format)
        execution_time = (datetime.now() - start_time).total_seconds()

        metadata = ChessMetadata(
            operation="get_board_state",
            fen_before=self.board.fen(),  # FEN is part of the state, so 'before' and 'after' are same here
            execution_time=execution_time,
        ).model_dump()

        return ActionResponse(success=True, message=formatted_output, metadata=metadata)

    async def mcp_get_game_status(self) -> ActionResponse:
        """Checks and returns the current game status (e.g., checkmate, stalemate).

        Returns:
            ActionResponse with a human-readable game status and structured data.
        """
        start_time = datetime.now()
        state = self._get_current_board_state()

        status_message = "Game in progress."
        if state.is_checkmate:
            status_message = f"Checkmate! {state.turn.capitalize()} is mated."
        elif state.is_stalemate:
            status_message = "Stalemate! The game is a draw."
        elif state.is_insufficient_material:
            status_message = "Draw by insufficient material."
        elif state.is_seventyfive_moves:
            status_message = "Draw by 75-move rule."
        elif state.is_fivefold_repetition:
            status_message = "Draw by fivefold repetition."
        elif state.is_check:
            status_message = f"{state.turn.capitalize()} is in check."

        status_data = {
            "status_message": status_message,
            "is_game_over": state.is_game_over,
            "is_check": state.is_check,
            "is_checkmate": state.is_checkmate,
            "is_stalemate": state.is_stalemate,
            "is_draw": state.is_stalemate
            or state.is_insufficient_material
            or state.is_seventyfive_moves
            or state.is_fivefold_repetition,
            "winner": None,  # Could be determined if checkmate
        }
        if state.is_checkmate:
            status_data["winner"] = "black" if self.board.turn == chess.WHITE else "white"

        execution_time = (datetime.now() - start_time).total_seconds()
        metadata = ChessMetadata(
            operation="get_game_status", fen_before=self.board.fen(), execution_time=execution_time
        ).model_dump()
        metadata.update(status_data)  # Add specific status flags to metadata

        return ActionResponse(success=True, message=status_message, metadata=metadata)

    def mcp_get_chess_capabilities(self) -> ActionResponse:
        """Get information about the Chess service capabilities.

        Returns:
            ActionResponse with service capabilities.
        """
        capabilities_info = {
            "service_name": "Chess MCP Service",
            "library_used": "python-chess",
            "supported_operations": [
                "new_game: Start a new chess game.",
                "load_fen: Load game state from FEN string.",
                "make_move: Make a move (UCI or SAN).",
                "get_legal_moves: List legal moves.",
                "get_board_state: Get current board FEN, ASCII, status, etc.",
                "get_game_status: Check for checkmate, stalemate, draw conditions.",
            ],
            "output_formats": ["markdown", "json", "text"],
            "move_input_formats": ["UCI (e.g., e2e4)", "SAN (e.g., Nf3)"],
            "fen_support": "Full FEN loading and generation.",
            "engine_integration": "Basic structure for UCI engine integration (not fully implemented by default).",
        }

        formatted_message = "# Chess Service Capabilities\n\n"
        formatted_message += f"**Service Name:** {capabilities_info['service_name']}\n"
        formatted_message += f"**Core Library:** {capabilities_info['library_used']}\n\n"
        formatted_message += "**Supported Operations:**\n"
        for op in capabilities_info["supported_operations"]:
            formatted_message += f"- {op}\n"
        formatted_message += "\n**Supported Output Formats:** " + ", ".join(capabilities_info["output_formats"]) + "\n"
        formatted_message += "**Move Input Formats:** " + ", ".join(capabilities_info["move_input_formats"]) + "\n"

        return ActionResponse(success=True, message=formatted_message, metadata=capabilities_info)

    # Optional: Method to close engine if it was initialized
    # def __del__(self):
    #     if hasattr(self, 'engine') and self.engine:
    #         self.engine.quit()
    #         self._color_log("Chess engine quit.", Color.yellow)


# Default arguments for testing
if __name__ == "__main__":
    import os

    load_dotenv()

    arguments = ActionArguments(
        name="chess_service",
        transport="stdio",
        workspace=os.getenv("AWORLD_WORKSPACE", "~"),
    )

    try:
        service = ChessCollection(arguments)
        service.run()
    except Exception as e:
        print(f"An error occurred: {e}: {traceback.format_exc()}")