ChessPal Chess Engine - A Stockfish-powered chess engine exposed as an MCP server using FastMCP

A Stockfish-powered chess engine exposed as an MCP server using FastMCP. Calculates best moves via MCP tools accessible over SSE (default) or stdio transports using an MCP client library. Part of the ChessPal project.

Features

• Robust Stockfish engine integration with proper process management
• Exposes engine functionality via the Model Context Protocol (MCP) using FastMCP.
• Supports both SSE and stdio MCP transports for client interaction.
• UCI protocol implementation for chess move generation
• Comprehensive test suite with TDD approach
• Error handling and recovery mechanisms
• Support for FEN positions and move history
• Flexible engine binary configuration

Prerequisites

• Python 3.10 or higher
• Poetry for dependency management (install from Poetry's documentation)
• Stockfish chess engine binary (version 17.1 recommended)

Installation

Install the published package from PyPI using pip:

pip install chesspal-mcp-engine

Installation for development

1. Clone the repository:

git clone https://github.com/wilson-urdaneta/dylangames-mcp-chess-engine.git
cd dylangames-mcp-chess-engine

2. Install dependencies and create virtual environment using Poetry:

poetry install

3. Configure the engine binary:
   • Option 1: Set ENGINE_PATH environment variable to point to your Stockfish binary
   • Option 2: Use the fallback configuration with these environment variables:

     # All variables have defaults, override as needed
     export ENGINE_NAME=stockfish     # Default: stockfish
     export ENGINE_VERSION=17.1       # Default: 17.1
     export ENGINE_OS=linux           # Default: linux
     export ENGINE_BINARY=stockfish   # Default: stockfish (include .exe for Windows)
     

Usage

Starting the Server

The server uses FastMCP with support for both Server-Sent Events (SSE) and stdio transports. You can start it using:

SSE Mode (Default)

poetry run python -m dylangames_mcp_chess_engine.main

This command starts the MCP server in SSE mode, which listens for SSE connections on the configured host and port (default: 127.0.0.1:8001). This mode is ideal for programmatic clients and agents that need to interact with the chess engine over HTTP.

Stdio Mode

poetry run python -m dylangames_mcp_chess_engine.main --transport stdio

This command starts the MCP server in stdio mode, which communicates through standard input/output. This mode is useful for direct integration with tools like Claude Desktop or for testing purposes.

API Endpoints

The module exposes the following endpoint through FastMCP:

• get_best_move_tool: Get the best move for a given chess position

Example request using the MCP SSE client:

from mcp.client.sse import sse_client
from mcp import ClientSession

async def get_best_move():
    # Connect to the SSE endpoint
    async with sse_client("http://127.0.0.1:8001/sse", timeout=10.0) as streams:
        # Create an MCP session
        async with ClientSession(*streams) as session:
            # Initialize the session
            await session.initialize()

            # Call the tool
            result = await session.call_tool('get_best_move_tool', {
                "request": {
                    "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
                    "move_history": []
                }
            })

            print(f"Best move: {result.best_move_uci}")  # e.g., "e2e4"

Environment Variables

The module uses the following environment variables for configuration:

# Primary configuration
ENGINE_PATH=/path/to/your/engine/binary

# Fallback configuration (used if ENGINE_PATH is not set/invalid)
ENGINE_NAME=stockfish       # Default: stockfish
ENGINE_VERSION=17.1         # Default: 17.1
ENGINE_OS=linux            # Default: linux
ENGINE_BINARY=stockfish    # Default: stockfish (include .exe for Windows)

# MCP Server Configuration
MCP_HOST=127.0.0.1        # Default: 127.0.0.1
MCP_PORT=8001             # Default: 8001

See .env.example for a complete example configuration.

Development

Project Structure

dylangames-mcp-chess-engine/
├── src/                    # Source code
│   └── dylangames_mcp_chess_engine/
│       ├── __init__.py
│       ├── main.py        # FastMCP server
│       └── engine_wrapper.py  # Stockfish wrapper
├── tests/                 # Test suite
│   └── test_engine_wrapper.py
├── engines/              # Engine binaries directory
├── pyproject.toml       # Poetry dependencies and configuration
├── poetry.lock         # Locked dependencies
├── .env.example        # Environment variables example
└── README.md          # This file

Development Workflow

1. Install dependencies:

poetry install

2. Activate the virtual environment:

poetry shell

3. Run tests:

poetry run pytest
poetry run pytest tests/ -v

4. Run code quality tools:

poetry run black .
poetry run isort .
poetry run flake8
poetry run pre-commit run --all-files

5. Using the mcp inspector:

poetry run mcp dev src/dylangames_mcp_chess_engine/main.py

# In the inspector UI
# STDIO configuration
Command: poetry
Arguments: run python -m dylangames_mcp_chess_engine.main --transport stdio

# SSE
# In a separate terminal run the app in SSE mode
poetry run python -m dylangames_mcp_chess_engine.main
# In the mcp inspector UI
Transport Type > SSE

{
  "fen": "r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1",
  "move_history": []
}

Adding Dependencies

To add new dependencies:

# Add a production dependency
poetry add package-name

# Add a development dependency
poetry add --group dev package-name

Code Quality

The codebase follows these standards:

• Type hints for all functions
• Comprehensive error handling
• Detailed docstrings (Google style)
• PEP 8 compliance via Black, isort, and flake8
• Proper resource management

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linters:

   poetry run black .
   poetry run isort .
   poetry run flake8
   poetry run pytest
   

5. Submit a pull request

CI/CD Pipeline

The project uses GitHub Actions for continuous integration and deployment. The pipeline is triggered on:

• Push to main branch
• Pull requests to main branch
• Tag pushes starting with v (e.g., v1.0.0)

Pipeline Stages

1. Lint (lint job)

   • Runs on Ubuntu latest
   • Checks code formatting with Black
   • Verifies import sorting with isort
   • Performs code quality checks with flake8

2. Test (test job)

   • Runs on Ubuntu latest
   • Installs Stockfish engine
   • Executes the test suite with pytest

3. Package (package job)

   • Runs after successful lint and test
   • Builds the Python package using Poetry
   • Uploads build artifacts for release

4. Release (release job)

   • Runs only on version tags (e.g., v1.0.0)
   • Creates GitHub releases
   • Optionally publishes to PyPI (disabled by default)

Versioning and Tags

The project uses semantic versioning with two types of tags:

1. External Releases (e.g., v1.0.0)

   • Public releases available to users
   • Triggers full release process
   • Creates GitHub release with release notes
   • Can optionally publish to PyPI

2. Internal Releases (e.g., v1.0.0-internal)

   • Used for internal testing and development
   • Skips the release job
   • Useful for testing release process without affecting public releases

PyPI Publishing

PyPI publishing is disabled by default. To enable:

1. Set ENABLE_PYPI to true in the workflow file
2. Configure PYPI_TOKEN secret in GitHub repository settings

License

GNU General Public License v3.0 - see LICENSE file for details.

Support

For issues and feature requests, please use the GitHub issue tracker.