ChessPal 国际象棋引擎 - 一个由 Stockfish 驱动的国际象棋引擎，通过 FastMCP 作为 MCP 服务器暴露

一个由 Stockfish 驱动的国际象棋引擎，通过 FastMCP 作为 MCP 服务器暴露。 使用 MCP 客户端库，通过可经由 SSE（默认）或 stdio 传输访问的 MCP 工具计算最佳移动。 是 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：设置 ENGINE_PATH 环境变量以指向您的 Stockfish 二进制文件
   • 选项 2：使用带有以下环境变量的后备配置：

     # 所有变量都有默认值，根据需要覆盖
     export ENGINE_NAME=stockfish     # 默认值：stockfish
     export ENGINE_VERSION=17.1       # 默认值：17.1
     export ENGINE_OS=linux           # 默认值：linux
     export ENGINE_BINARY=stockfish   # 默认值：stockfish（Windows 包括 .exe）
     

用法

启动服务器

该服务器使用 FastMCP，支持服务器发送事件 (SSE) 和 stdio 传输。 您可以使用以下命令启动它：

SSE 模式（默认）

poetry run python -m dylangames_mcp_chess_engine.main

此命令以 SSE 模式启动 MCP 服务器，该服务器侦听配置的主机和端口上的 SSE 连接（默认值：127.0.0.1:8001）。 此模式非常适合需要通过 HTTP 与国际象棋引擎交互的程序客户端和代理。

Stdio 模式

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

此命令以 stdio 模式启动 MCP 服务器，该服务器通过标准输入/输出进行通信。 此模式对于与 Claude Desktop 等工具直接集成或用于测试目的非常有用。

API 端点

该模块通过 FastMCP 暴露以下端点：

• get_best_move_tool：获取给定国际象棋位置的最佳移动

使用 MCP SSE 客户端的示例请求：

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

async def get_best_move():
    # 连接到 SSE 端点
    async with sse_client("http://127.0.0.1:8001/sse", timeout=10.0) as streams:
        # 创建一个 MCP 会话
        async with ClientSession(*streams) as session:
            # 初始化会话
            await session.initialize()

            # 调用工具
            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}")  # 例如，“e2e4”

环境变量

该模块使用以下环境变量进行配置：

# 主要配置
ENGINE_PATH=/path/to/your/engine/binary

# 后备配置（如果未设置/无效 ENGINE_PATH，则使用）
ENGINE_NAME=stockfish       # 默认值：stockfish
ENGINE_VERSION=17.1         # 默认值：17.1
ENGINE_OS=linux            # 默认值：linux
ENGINE_BINARY=stockfish    # 默认值：stockfish（Windows 包括 .exe）

# MCP 服务器配置
MCP_HOST=127.0.0.1        # 默认值：127.0.0.1
MCP_PORT=8001             # 默认值：8001

有关完整的示例配置，请参见 .env.example。

开发

项目结构

dylangames-mcp-chess-engine/
├── src/                    # 源代码
│   └── dylangames_mcp_chess_engine/
│       ├── __init__.py
│       ├── main.py        # FastMCP 服务器
│       └── engine_wrapper.py  # Stockfish 包装器
├── tests/                 # 测试套件
│   └── test_engine_wrapper.py
├── engines/              # 引擎二进制文件目录
├── pyproject.toml       # Poetry 依赖项和配置
├── poetry.lock         # 锁定的依赖项
├── .env.example        # 环境变量示例
└── README.md          # 此文件

开发工作流程

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 检查器：

poetry run mcp dev src/dylangames_mcp_chess_engine/main.py

# 在检查器 UI 中
# STDIO 配置
Command: poetry
Arguments: run python -m dylangames_mcp_chess_engine.main --transport stdio

# SSE
# 在单独的终端中以 SSE 模式运行应用程序
poetry run python -m dylangames_mcp_chess_engine.main
# 在 mcp 检查器 UI 中
Transport Type > SSE

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

添加依赖项

要添加新的依赖项：

# 添加生产依赖项
poetry add package-name

# 添加开发依赖项
poetry add --group dev package-name

代码质量

代码库遵循以下标准：

• 所有函数的类型提示
• 综合错误处理
• 详细的文档字符串（Google 风格）
• 通过 Black、isort 和 flake8 实现 PEP 8 合规性
• 适当的资源管理

贡献

1. Fork 存储库
2. 创建一个功能分支
3. 进行更改
4. 运行测试和 linters：

   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 job)

   • 在 Ubuntu 最新版本上运行
   • 使用 Black 检查代码格式
   • 使用 isort 验证导入排序
   • 使用 flake8 执行代码质量检查

2. Test (test job)

   • 在 Ubuntu 最新版本上运行
   • 安装 Stockfish 引擎
   • 使用 pytest 执行测试套件

3. Package (package job)

   • 在成功的 lint 和测试后运行
   • 使用 Poetry 构建 Python 软件包
   • 上传构建工件以供发布

4. Release (release job)

   • 仅在版本标签上运行（例如，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 问题跟踪器。