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

ChessPal Chess Engine - 由 Stockfish 驱动、使用 FastMCP 作为 MCP 服务的国际象棋引擎

这是一个由 Stockfish 驱动、使用 FastMCP 作为 MCP 服务的国际象棋引擎。它通过 MCP 工具计算最佳走法，可通过 MCP 客户端库使用 SSE（默认）或 stdio 传输方式访问。它是 ChessPal 项目的一部分。

功能

• 与 Stockfish 引擎稳健集成，并妥善管理进程
• 使用 FastMCP 通过模型上下文协议（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     # 默认值：stockfish
     export CHESSPAL_ENGINE_VERSION=17.1       # 默认值：17.1
     export CHESSPAL_ENGINE_OS=macos           # 默认值：根据平台自动检测
     export CHESSPAL_ENGINE_BINARY=stockfish   # 默认值：stockfish（Windows 系统请包含 .exe）
     

Stockfish 二进制文件配置

ChessPal Chess Engine 需要 Stockfish 二进制文件来运行服务和集成测试。你可以通过以下三种方式配置二进制文件：

选项 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 releases 下载的文件
• 从源代码手动编译的文件

选项 2：使用 engines/ 目录

如果未设置 CHESSPAL_ENGINE_PATH，服务将在预定义的目录结构中查找二进制文件：

1. 从 Stockfish releases 下载适用于你的操作系统的官方二进制文件
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，同时支持服务器发送事件（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 与国际象棋引擎交互的程序化客户端和 Agent。

您也可以使用入口命令：

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

代码质量

代码库遵循以下标准：

• 所有函数都添加类型提示
• 全面处理错误
• 编写详细的文档字符串（Google 风格）
• 通过 Black、isort 和 flake8 遵循 PEP 8
• 妥善管理资源

贡献

1. Fork 仓库
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（默认禁用）

版本控制与标签

项目采用语义化版本控制，并使用两种类型的标签：

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 二进制文件（请参阅上文的设置选项）
  • 测试真实的引擎初始化和走法计算
  • 如果没有可用的二进制文件，则自动跳过