🚀 mcp-stockfish 🐟
这是一个用于链接人工智能与国际象棋引擎Stockfish的桥梁。借助Model Context Protocol（MCP）协议，它让你的AI能够与强大的Stockfish进行“对话”，让国际象棋分析变得更加便捷。
🧠⚡🖥️ 大语言模型思考，Stockfish计算，你只需假装理解那长达15步的战术序列。
🚀 快速开始
📦 安装指南
git clone https://github.com/sonirico/mcp-stockfish
cd mcp-stockfish
make install
💻 使用示例
基础用法
# 默认模式 (标准输入输出，老派风格)
mcp-stockfish
高级用法
# 指定Stockfish路径
MCP_STOCKFISH_PATH=/your/special/stockfish mcp-stockfish
# HTTP模式 (适用于Web场景)
MCP_STOCKFISH_SERVER_MODE=http mcp-stockfish
✨ 主要特性
- 🔄 并发会话：可同时运行多个Stockfish实例，而不会让你的CPU不堪重负。
- ⚡ 完整UCI支持：提供所需的所有命令，无多余干扰。
- 🎯 稳定运行：具备完善的错误处理机制，与你上次失败的副业项目不同。
- 📊 JSON数据格式：所有数据以JSON格式传输，符合现代开发趋势。
- 🐳 Docker支持：支持容器化部署，避免本地环境配置的烦恼。
📚 详细文档
支持的UCI命令 ♟️
| 命令 | 描述 |
|---|---|
uci |
以UCI模式初始化引擎 |
isready |
检查引擎是否就绪，就绪则返回 readyok |
position startpos |
将棋盘设置为起始位置 |
position fen [FEN] |
使用FEN符号设置棋盘位置 |
go |
启动引擎计算最佳走法 |
go depth [n] |
搜索 n 层深度，例如：go depth 10 |
go movetime [ms] |
在指定的毫秒数内思考，例如：go movetime 1000 |
stop |
停止当前搜索 |
quit |
关闭会话 |
配置 ⚙️
环境变量
| 属性 | 详情 |
|---|---|
| 服务器模式 | MCP_STOCKFISH_SERVER_MODE：可选值为 "stdio" 或 "http"（默认："stdio"） |
| HTTP主机 | MCP_STOCKFISH_HTTP_HOST：HTTP主机地址（默认："localhost"） |
| HTTP端口 | MCP_STOCKFISH_HTTP_PORT：HTTP端口号（默认：8080） |
| Stockfish路径 | MCP_STOCKFISH_PATH：Stockfish二进制文件的路径（默认："stockfish"） |
| 最大并发会话数 | MCP_STOCKFISH_MAX_SESSIONS：最大并发会话数（默认：10） |
| 会话超时时间 | MCP_STOCKFISH_SESSION_TIMEOUT：会话超时时间（默认："30m"） |
| 命令超时时间 | MCP_STOCKFISH_COMMAND_TIMEOUT：命令超时时间（默认："30s"） |
| 日志级别 | MCP_STOCKFISH_LOG_LEVEL：可选值为 debug、info、warn、error、fatal |
| 日志格式 | MCP_STOCKFISH_LOG_FORMAT：可选值为 json、console |
| 日志输出 | MCP_STOCKFISH_LOG_OUTPUT：可选值为 stdout、stderr |
工具参数
command：要执行的UCI命令session_id：会话ID（可选，若未提供则自动生成）
响应格式
{
"status": "success|error",
"session_id": "some-uuid",
"command": "what you asked for",
"response": ["what stockfish said"],
"error": "what went wrong (if anything)"
}
会话管理
会话具备以下功能：
- 根据需求启动Stockfish进程。
- 在命令之间保持UCI状态。
- 在会话结束或超时时自动清理资源。
- 实施限制，防止资源耗尽。
集成
Claude Desktop
{
"mcpServers": {
"chess": {
"command": "mcp-stockfish",
"env": {
"MCP_STOCKFISH_LOG_LEVEL": "info"
}
}
}
}
开发
make deps # 获取依赖
make build # 构建项目
make test # 运行测试（若有）
make fmt # 格式化代码
🔧 技术细节
本项目基于 mark3labs/mcp-go 构建，借助其实现了MCP协议的处理，避免了重复造轮子。
📄 许可证
本项目采用MIT许可证，你可以自由使用，但出现问题时请不要责怪作者。
🐟 鸣谢
本项目由 Stockfish 提供支持，这是一个比我们所有人都强大的国际象棋引擎。感谢以下团队和项目：
- Stockfish团队 开发了优秀的国际象棋引擎。
- MCP SDK for Go 处理协议，让开发更轻松。
- 还有咖啡，给予开发者灵感。