象棋游戏服务器

国际象棋MCP服务器

一种模型上下文协议（MCP）服务器，使AI助手能够与用户下棋。服务器提供用于管理国际象棋游戏、移动、评估位置和可视化棋盘的工具。

特性

• 游戏管理：创建新游戏，获取棋盘状态，可视化位置
• 移动验证：在移动之前验证移动
• AI对手：与Stockfish国际象棋引擎对弈
• 岗位评估：获取发动机位置评估
• 移动历史记录：使用撤消功能跟踪移动
• 电路板可视化：ASCII艺术板表示法

需求

• Python 3.11或更高版本
• 紫外线 包管理器
• Stockfish象棋引擎（包含在 server/bin/stockfish/)

安装

1. 克隆存储库：

git clone <repository-url>
cd chess-mcp

2. 安装依赖项和软件包：

uv sync

这将：

• 创建虚拟环境
• 安装所有依赖项（包括 mcp 和 chess)
• 以可编辑模式安装软件包

运行服务器

使用入口点

安装后，您可以使用以下命令运行服务器：

uv run chess-mcp

作为模块运行

或者，您可以将其作为Python模块运行：

uv run -m server.main

服务器运行在 stdio 传输，这意味着它通过标准输入/输出进行通信。这是MCP服务器与客户端交互的标准方式。

MCP客户端的配置

克劳德桌面版

要将此服务器与Claude Desktop一起使用，请将以下内容添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "chess-game": {
      "command": "uv",
      "args": [
        "run",
        "chess-mcp"
      ],
      "cwd": "/path/to/chess-mcp"
    }
  }
}

替换 /path/to/chess-mcp 带有此项目目录的绝对路径。

其他MCP客户端

对于其他MCP客户端，将其配置为运行：

uv run chess-mcp

确保工作目录设置为项目根目录。

可用工具

服务器提供以下MCP工具：

游戏状态

• new_game_tool：创建新的国际象棋游戏
• get_state_tool：以FEN格式返回当前电路板状态
• visualize_board_tool：返回电路板的ASCII艺术可视化

动作

• make_move_tool(move: str)：以UCI格式采取行动（例如“e2e4”）
• ai_make_move_tool：使用AI对手进行移动
• undo_move_tool：撤消上次移动

验证

• validate_move_tool(move: str)：验证移动是否合法

分析

• evaluate_board_tool：返回引擎对位置的评估，单位为厘泊

项目结构

appli/
├── server/
│   ├── main.py              # MCP server entry point
│   ├── config.py            # Configuration (paths, etc.)
│   ├── engine/              # Stockfish engine wrapper
│   ├── storage/             # File I/O and serialization
│   └── tools/               # MCP tool implementations
├── storage/                 # Game state storage
│   ├── current_game.fen     # Current board position
│   └── move_history.json    # Move history for undo
├── tests/                   # Test files for tools
├── pyproject.toml           # Project configuration
└── README.md                # This file

存储

服务器将游戏状态存储在 storage/ 目录：

• current_game.fen：FEN符号中的当前董事会职位
• move_history.json：移动列表（用于撤消功能）

发展

运行测试

安装测试依赖项：

uv sync --extra dev

运行测试：

uv run pytest

运行覆盖率测试：

uv run pytest --cov=server --cov-report=html

添加新工具

1. 在适当的位置创建一个函数 server/tools/ 模块
2. 在中注册 server/tools/registry.py
3. 将其添加到 register_tools() 函数

故障排除

未找到Stockfish

如果你收到一个关于找不到Stockfish的错误：

• 检查一下 server/bin/stockfish/ 包含适合您平台的二进制文件
• 服务器会自动检测您的平台并选择正确的二进制文件
• 支持：macOS（英特尔/苹果硅）、Linux、Windows

导入错误

如果遇到导入错误：

• 确保你已经跑过了 uv sync 安装软件包
• 验证您是否在项目根目录中
• 检查虚拟环境是否已激活

致谢

• 用途 python象棋 国际象棋逻辑
• 用途 长筒鱼 象棋引擎
• 内置于 FastMCP 用于MCP服务器功能