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

ChessPal チェスエンジン - FastMCP を使用して MCP サーバーとして公開する、Stockfish を基盤としたチェスエンジン

FastMCP を使用して MCP サーバーとして公開する、Stockfish を基盤としたチェスエンジンです。MCP クライアントライブラリを使い、SSE（デフォルト）または stdio トランスポート経由で利用できる MCP ツールから最善手を計算します。ChessPal プロジェクトの一部です。

特長

• 適切なプロセス管理を備えた、堅牢な Stockfish エンジン統合
• FastMCP を使用した Model Context Protocol（MCP）経由でのエンジン機能の公開
• クライアントとのやり取りに SSE と stdio の両方の MCP トランスポートをサポート
• チェスの手を生成する UCI プロトコルの実装
• TDD アプローチによる包括的なテストスイート
• エラー処理および復旧メカニズム
• FEN の局面と棋譜に対応
• 柔軟なエンジンバイナリ設定

前提条件

• Python 3.10 以降
• 依存関係の管理に使用する Poetry（Poetry のドキュメントからインストールしてください）
• Stockfish チェスエンジンのバイナリ（バージョン 17.1 を推奨）

インストール

pip を使用して、公開済みのパッケージを PyPI からインストールします。

pip install chesspal-mcp-engine

開発用インストール

1. リポジトリをクローンします。

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

2. Poetry を使用して依存関係をインストールし、仮想環境を作成します。

poetry install

3. エンジンバイナリを設定します。
   • オプション 1：CHESSPAL_ENGINE_PATH 環境変数に Stockfish バイナリのパスを設定します
   • オプション 2：次の環境変数を使ってフォールバック設定を行います。

     # すべての変数にはデフォルト値があります。必要に応じて上書きしてください
     export CHESSPAL_ENGINE_NAME=stockfish     # Default: stockfish
     export CHESSPAL_ENGINE_VERSION=17.1       # Default: 17.1
     export CHESSPAL_ENGINE_OS=macos           # Default: automatically detected based on platform
     export CHESSPAL_ENGINE_BINARY=stockfish   # Default: stockfish (include .exe for Windows)
     

Stockfish バイナリのセットアップ

ChessPal チェスエンジンでサーバーと統合テストを実行するには、Stockfish バイナリが必要です。バイナリのセットアップには、次の 3 つの方法があります。

オプション 1：CHESSPAL_ENGINE_PATH を設定する（推奨）

システム上の任意の Stockfish 実行ファイルを指定します。

# Unix-like systems (binary from apt/brew or downloaded)
export CHESSPAL_ENGINE_PATH=/usr/local/bin/stockfish

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

バイナリは次のいずれでもかまいません。

• パッケージマネージャーでシステムにインストールしたもの（apt install stockfish、brew install stockfish）
• Stockfish リリースからダウンロードしたもの
• ソースから手動でコンパイルしたもの

オプション 2：engines/ ディレクトリを使用する

CHESSPAL_ENGINE_PATH が設定されていない場合、サーバーはあらかじめ定義されたディレクトリ構成内でバイナリを検索します。

1. Stockfish リリースから、お使いの OS 用の公式バイナリをダウンロードします
2. engines/stockfish/<version>/<os>/<binary_name> に配置します
   • 正確なディレクトリ構成については engines/README.md を参照してください
3. システムに合わせて CHESSPAL_ENGINE_OS 環境変数を設定します。

   export CHESSPAL_ENGINE_OS=macos    # For macOS
   export CHESSPAL_ENGINE_OS=linux    # For Linux
   export CHESSPAL_ENGINE_OS=windows  # For Windows
   

オプション 3：ソースからビルドする（上級者向け）

上級者は、別の dylangames-engine リポジトリを使用して、Stockfish をソースからコンパイルできます。この方法ではビルド設定を最大限に制御できますが、C++ の開発経験が必要です。

使用方法

サーバーの起動

サーバーは FastMCP を使用しており、Server-Sent Events（SSE）と stdio の両方のトランスポートに対応しています。次のコマンドで起動できます。

SSE モード（デフォルト）

poetry run python -m chesspal_mcp_engine.main
# Or
poetry run python -m chesspal_mcp_engine.main --transport sse

このコマンドは、SSE モードで MCP サーバーを起動します。設定されたホストとポート（デフォルト：127.0.0.1:9000）で SSE 接続を待ち受けます。このモードは、HTTP 経由でチェスエンジンを操作する必要があるプログラムクライアントやエージェントに最適です。

エントリーポイントコマンドも使用できます。

poetry run chesspal-mcp-engine

Stdio モード

poetry run python -m chesspal_mcp_engine.main --transport stdio
# Or
poetry run chesspal-mcp-engine --transport stdio

このコマンドは、stdio モードで MCP サーバーを起動し、標準入出力を介して通信します。このモードは、Claude Desktop などのツールとの直接統合やテストに便利です。

API エンドポイント

このモジュールは、FastMCP を通じて次のエンドポイントを公開します。

• get_best_move_tool：指定されたチェス局面における最善手を取得します
• validate_move_tool：指定された局面で手が合法かどうかを検証します
• get_legal_moves_tool：指定された局面におけるすべての合法手を取得します
• get_game_status_tool：現在のゲーム状況（進行中、チェックメイトなど）を取得します

MCP SSE クライアントを使用したリクエストの例：

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:9000/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 - Note: Arguments MUST be wrapped in a "request" field
            result = await session.call_tool('get_best_move_tool', {
                "request": {  # Required wrapper field
                    "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"

リクエスト形式

get_best_move_tool は、次の形式のリクエストを受け付けます。

{
    "request": {
        "fen": "string",       // Required: FEN string representing the position
        "move_history": []     // Optional: List of previous moves in UCI format
    }
}

注：リクエストを正しく検証するには、外側の「request」ラッパーフィールドが必要です。

タイムアウト

エンジンには次のタイムアウトが設定されています。

• エンジンの計算時間：デフォルトで 1000ms（CHESSPAL_ENGINE_TIMEOUT_MS で設定可能）
• 応答待ちタイムアウト：30s（エンジンの初期化と計算に必要な時間を確保します）
• SSE クライアントの接続タイムアウト：15s（クライアントコードで設定可能）

これらのタイムアウトにより、低速なシステムや複雑な局面の処理にエンジンがより多くの時間を必要とする場合でも、手の計算に十分な時間を確保しながら、安定した動作を実現します。

環境変数

このモジュールでは、設定に次の環境変数を使用します。

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

# Fallback configuration (used if CHESSPAL_ENGINE_PATH is not set/invalid)
CHESSPAL_ENGINE_NAME=stockfish       # Default: stockfish
CHESSPAL_ENGINE_VERSION=17.1         # Default: 17.1
CHESSPAL_ENGINE_OS=macos             # Default: auto-detected based on platform
CHESSPAL_ENGINE_BINARY=stockfish     # Default: stockfish (include .exe for Windows)

# Engine parameters
CHESSPAL_ENGINE_DEPTH=10             # Default: 10
CHESSPAL_ENGINE_TIMEOUT_MS=1000      # Default: 1000

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

# Logging configuration
ENVIRONMENT=development              # Default: development
LOG_LEVEL=INFO                       # Default: INFO for production, DEBUG for development

設定例の全容については、.env.example を参照してください。

開発

プロジェクト構成

dylangames-mcp-chess-engine/
├── src/                    # Source code
│   └── chesspal_mcp_engine/
│       ├── __init__.py
│       ├── main.py        # FastMCP server
│       ├── engine_wrapper.py  # Stockfish wrapper
│       ├── config.py      # Configuration management
│       ├── logging_config.py # Logging setup
│       ├── shutdown.py    # Graceful shutdown handling
│       └── models.py      # Data models
├── 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

開発ワークフロー

1. 依存関係をインストールします。

poetry install

2. 仮想環境を有効にします。

poetry shell

3. テストを実行します。

poetry run pytest
poetry run pytest tests/ -v

4. コード品質ツールを実行します。

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

5. mcp inspector を使用します。

poetry run mcp dev src/chesspal_mcp_engine/main.py

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

# SSE
# In a separate terminal run the app in SSE mode
poetry run python -m chesspal_mcp_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": []
}

依存関係の追加

依存関係を追加するには、次のようにします。

# Add a production dependency
poetry add package-name

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

コード品質

このコードベースでは、次の規約に従います。

• すべての関数に型ヒントを付ける
• 包括的なエラー処理を行う
• 詳細な docstring を記述する（Google スタイル）
• Black、isort、flake8 による PEP 8 準拠
• 適切なリソース管理

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. テストとリンターを実行します。

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

5. プルリクエストを送信します

CI/CD パイプライン

このプロジェクトでは、継続的インテグレーションとデプロイに GitHub Actions を使用しています。パイプラインは次の場合に実行されます。

• main ブランチへのプッシュ
• main ブランチへのプルリクエスト
• v で始まるタグのプッシュ（例：v1.0.0）

パイプラインのステージ

1. Lint（lint ジョブ）

   • 最新の Ubuntu 上で実行
   • Black でコードのフォーマットをチェック
   • isort でインポートの並べ替えを検証
   • flake8 でコード品質をチェック

2. Test（test ジョブ）

   • 最新の Ubuntu 上で実行
   • Stockfish エンジンをインストール
   • pytest でテストスイートを実行

3. Package（package ジョブ）

   • lint と test の成功後に実行
   • Poetry で Python パッケージをビルド
   • リリース用のビルド成果物をアップロード

4. Release（release ジョブ）

   • バージョンタグが付いた場合のみ実行（例：v1.0.0）
   • GitHub リリースを作成
   • 必要に応じて PyPI に公開（デフォルトでは無効）

バージョン管理とタグ

このプロジェクトでは、次の2種類のタグを使用したセマンティックバージョニングを採用しています。

1. 外部リリース（例：v1.0.0）

   • ユーザーが利用できる公開リリースです
   • リリースプロセス全体が実行されます
   • リリースノート付きの GitHub リリースが作成されます
   • 必要に応じて PyPI に公開できます

2. 内部リリース（例：v1.0.0-internal）

   • 内部テストと開発に使用します
   • リリースジョブはスキップされます
   • 公開リリースに影響を与えずにリリースプロセスをテストするのに便利です

PyPI への公開

PyPI への公開はデフォルトで無効になっています。有効にするには、次の手順を実行してください。

1. ワークフローファイルで ENABLE_PYPI を true に設定します
2. GitHub リポジトリの設定で PYPI_TOKEN シークレットを設定します

ライセンス

GNU General Public License v3.0。詳細については LICENSE ファイルを参照してください。

サポート

問題や機能リクエストについては、GitHub のイシュートラッカーをご利用ください。

テストの実行

このプロジェクトには、ユニットテストと統合テストの両方が含まれています。

すべてのテストを実行する

poetry run pytest

これにより、テストスイート全体が実行されます。統合テストには、上記のオプション1または2のいずれかを通じて Stockfish バイナリを利用できる必要があります。

ユニットテストのみを実行する

poetry run pytest -m "not integration"

これにより、Stockfish とのやり取りがモック化され、バイナリが不要なユニットテストのみが実行されます。

テストのカテゴリ

• ユニットテスト：モック化された依存関係を使って、個々のコンポーネントをテストします
• 統合テスト：実際の Stockfish バイナリとのやり取りをテストします
  • Stockfish バイナリが必要です（上記のセットアップオプションを参照）
  • 実際のエンジンの初期化と手の計算をテストします
  • バイナリが利用できない場合は自動的にスキップされます