ChessPal Chess Engine - MCP Server

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

PyPI version

Python Version

License: GPL v3

Poetry

Code style: black

CI/CD

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

Clone the repository:

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

Install dependencies and create virtual environment using Poetry:

poetry install

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)

Stockfish Binary Setup

This package requires the Stockfish chess engine binary to be available. You have two options for setting up the binary:

Option 1: Environment Variable (Recommended)

Download the appropriate Stockfish binary for your system from the official Stockfish website.
Make the binary executable (Unix-like systems):
```
chmod +x path/to/stockfish
```

Set the ENGINE_PATH environment variable to point to your Stockfish binary:

# Unix-like systems
export ENGINE_PATH=/path/to/stockfish

# Windows (PowerShell)
$env:ENGINE_PATH="C:\path\to\stockfish.exe"

Option 2: Default Directory Structure

Place the Stockfish binary in the default directory structure under the package installation:

engines/
└── stockfish/
    └── 17.1/
        ├── linux/
        │   └── stockfish
        ├── macos/
        │   └── stockfish
        └── windows/
            └── stockfish.exe

The package will automatically detect your operating system and use the appropriate binary.

Platform Support

Linux: stockfish binary in the linux directory
macOS: stockfish binary in the macos directory
Windows: stockfish.exe in the windows directory

Troubleshooting

Ensure the binary has executable permissions on Unix-like systems.
For custom binary locations, use the ENGINE_PATH environment variable.
You can override OS detection by setting the ENGINE_OS environment variable to linux, macos, or 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

Install dependencies:

poetry install

Activate the virtual environment:

poetry shell

Run tests:

poetry run pytest
poetry run pytest tests/ -v

Run code quality tools:

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

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

Fork the repository
Create a feature branch
Make your changes

Run tests and linters:

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

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

Lint (lint job)
- Runs on Ubuntu latest
- Checks code formatting with Black
- Verifies import sorting with isort
- Performs code quality checks with flake8
Test (test job)
- Runs on Ubuntu latest
- Installs Stockfish engine
- Executes the test suite with pytest
Package (package job)
- Runs after successful lint and test
- Builds the Python package using Poetry
- Uploads build artifacts for release
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:

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
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:

Set ENABLE_PYPI to true in the workflow file
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.

Running Tests

The test suite includes both unit tests and integration tests. Integration tests require a working Stockfish binary.

# Run all tests
pytest

# Run only unit tests (no Stockfish binary required)
pytest -m "not integration"

# Run only integration tests
pytest -m integration