内容
# chess-coach-mcp
[](https://pypi.org/project/chess-coach-mcp/)
[](https://github.com/parkseokjune/chess-coach-mcp/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](LICENSE)
一款**混合人工智能国际象棋教练**，作为 [MCP](https://modelcontextprotocol.io) 服务器。本地 **Stockfish** 引擎提供有根据的评估、错误分类和战术主题；您的 MCP 主机模型（例如 Claude）将这些事实转化为自然语言的**中文或英文**教学。
> 引擎知道**最佳移动**。模型解释**原因**。
> 该项目将两者结合起来，并添加了两者单独无法实现的功能：**“这是您的常见错误，从您的游戏中总结。”**
```bash
pip install chess-coach-mcp # 或：uvx chess-coach-mcp （需要本地 Stockfish）
```
## 看看它的实际效果
<p align="center">
<img src="https://raw.githubusercontent.com/parkseokjune/chess-coach-mcp/main/docs/demo.gif" alt="演示：一个错误，引擎的首选移动和重复模式" width="420">
</p>
`diagnose_weaknesses` 将您最近的游戏转换为弱点报告 — 重复的战术盲点和您损失最多的地方（按阶段）：
<p align="center">
<img src="https://raw.githubusercontent.com/parkseokjune/chess-coach-mcp/main/docs/weakness_report.png" alt="弱点热图：战术盲点和平均 centipawn 损失按阶段" width="820">
</p>
…然后 `recommend_drills` 返回您错误的 exact 位置 — 您的移动以红色显示，引擎的移动以绿色显示 — 以便您重新解决**您自己的**错误：
<p align="center">
<img src="https://raw.githubusercontent.com/parkseokjune/chess-coach-mcp/main/docs/board_example.png" alt="注释钻石板：您的移动以红色显示，引擎的移动以绿色显示" width="340">
</p>
> 上面的数字是真实的 Stockfish 输出；弱点报告使用示例数据集。可以使用 `uv run --with matplotlib --with pillow python docs/generate_assets.py` 重新生成所有内容。
## 为什么存在
引擎（Stockfish）告诉您最佳的移动，但不是原因。原始 LLMs 流利地解释，但下棋/评估棋局很差，并且会胡乱生成线路。现有的训练器是分散的（一个应用程序用于统计数据，一个用于解释，一个用于课程），并且很少提供**个性化、指导**的路径。`chess-coach-mcp` 是基础层：教练的每个声明都得到 Stockfish 的支持，弱点诊断是根据玩家实际游戏计算的。
## 它能做什么
- **获取** 来自 **Lichess** 或 **Chess.com** （公共 API，无需密钥）的近期游戏。
- **分析游戏**：每步分类（最佳/良好/不准确/错误/失误，附韩文标签），胜率前后， centipawn 损失，引擎的首选移动，战术主题标签和按阶段总结。
- **分析位置** （FEN）：SAN 中的顶级引擎线路，胜率，物质和 fork/pin 标志 — 以便模型可以解释**原因**。
- **诊断弱点** 跨多个游戏：阶段弱点（开局/中局/残局），重复的战术盲点，带有示例位置的易漏开局，时间麻烦代理和排名靠前的弱点列表。
- **推荐训练**：从玩家**自己的错误**中重新解决的位置，按目标弱点排序，并附有 Lichess 每日谜题热身。
## 它的与众不同之处
大多数国际象棋工具都擅长一件事情，因此您最终会将多个工具组合起来。`chess-coach-mcp` 是缺失的**基础 + 个性化层**，直接在您已经使用的地方提供 — 在您的 AI 助手内部。
| | chess-coach-mcp | Stockfish 单独 | DecodeChess | Aimchess | Chessable |
|---|:---:|:---:|:---:|:---:|:---:|
| 最佳移动（**什么**） | ✅ | ✅ | ✅ | ◐ | – |
| 用散文解释 **为什么** | ✅ | ❌ | ✅ | ❌ | – |
| **个人** 弱点诊断跨游戏 | ✅ | ❌ | ❌ | ✅ | ❌ |
| 来自**您自己的**错误的训练 | ✅ | ❌ | ❌ | ◐ | ❌ |
| **韩文** （双语）教学 | ✅ | ❌ | ❌ | ❌ | ❌ |
| **本地/私有** （您的引擎，无帐户） | ✅ | ✅ | ❌ 云 | ❌ 云 | ❌ 云 |
| 生活在**您的 AI 助手** （MCP）中 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 成本 | 免费，OSS | 免费 | 订阅 | 订阅 | 付费课程 |
使它与众不同的五个方面：
1. **混合和有根据的** — Stockfish 是裁判，LLM 是解释者。每个教学声明都得到引擎的支持，因此没有虚构的评估或编造的线路（原始 LLM 在谈论国际象棋时的失败模式）。
2. **个性化，而不是通用** — `diagnose_weaknesses` 将**您的**游戏汇总为阶段弱点，重复的战术盲点和易漏的开局；`recommend_drills` 测验您**自己的**错误位置 — 不是您评级的随机谜题。
3. **双语 EN/KO** — 每个结构化事实都带有韩文标签，因此教学在韩文中读起来很自然（한국어 코칭）。
4. **本地优先和私有** — 您自己的 Stockfish 二进制文件 + 公共只读 API。无需帐户，无需 API 密钥，您的游戏不会上传到任何地方。
5. **在您的助手内** — 它是一个 MCP 服务器，因此教学发生在您已经使用的同一个聊天中，与您的助手可以做的所有其他事情相结合。
## 工具
| 工具 | 目的 |
|---|---|
| `engine_status` | 检查本地 Stockfish 二进制文件是否可用。 |
| `render_board(fen, orientation)` | 以文本棋盘 + Lichess 链接显示位置（无需引擎）。 |
| `fetch_recent_games(username, source, max_games, speed)` | 列出近期游戏（无分析）。 |
| `analyze_position(fen, depth, multipv)` | 评估一个位置；顶级线路 + 标志。 |
| `analyze_game(pgn, depth, user_color, max_plies)` | 完整的每步游戏审查。 |
| `diagnose_weaknesses(username, source, max_games, depth, speed)` | 跨游戏的弱点报告。 |
| `recommend_drills(username, source, max_games, depth, num_drills, include_daily_puzzle)` | 个性化的训练集。 |
`source` 是 `lichess` （默认）或 `chesscom` 。每个数字/分类事实都附带一个 `*_ko` 韩文标签，用于自然的韩文教学。工具输出中的位置还带有 `board_ascii` 文本棋盘和 `lichess_url` ，以便教练可以直接在聊天中绘制棋盘或链接到交互式棋盘。
### 棋盘是否在聊天中显示？
这是一个 MCP 服务器：它返回**数据** （FEN，评估，`board_ascii` 文本棋盘，`lichess_url`），而您的助手将这些数据转换为教学。因此，图形棋盘不会自行弹出 — 但模型可以在任何客户端打印 `board_ascii` 棋盘，您可以点击 `lichess_url` 获取真正的交互式棋盘，并且在 claude.ai 上，模型可以从 FEN 绘制 SVG 棋盘。（上面的演示 GIF 是生成的 README 资产，而不是实时聊天 UI。）
## 要求
- Python ≥ 3.11
- **Stockfish** 在您的 `PATH` 上（或设置 `STOCKFISH_PATH` ）：
- macOS： `brew install stockfish`
- Debian/Ubuntu： `apt install stockfish`
## 安装和运行
从 PyPI：
```bash
pip install chess-coach-mcp
chess-coach-mcp # 在 stdio 上运行 MCP 服务器
# … 或在不安装的情况下运行：
uvx chess-coach-mcp
```
从源代码：
```bash
uv sync # 安装依赖项
uv run chess-coach-mcp # 在 stdio 上运行 MCP 服务器
```
### 注册 Claude 代码
```bash
claude mcp add chess-coach -- uv --directory /ABS/PATH/TO/chess-coach-mcp run chess-coach-mcp
```
或添加到 MCP 客户端配置中：
```json
{
"mcpServers": {
"chess-coach": {
"command": "uv",
"args": ["--directory", "/ABS/PATH/TO/chess-coach-mcp", "run", "chess-coach-mcp"],
"env": { "STOCKFISH_PATH": "/opt/homebrew/bin/stockfish" }
}
}
}
```
## 示例教学流程
> “내 리체스 약점 좀 진단해줘. 아이디 `myname`.”
主机调用 `diagnose_weaknesses("myname")` ，获取每阶段的 ACPL，重复的主题（例如 `hanging_piece` ×4，`missed_tactic` ×3）以及示例 FEN，然后用韩文解释**为什么**这些位置出错，并调用 `recommend_drills("myname")` 来测验用户自己的错误。
## 配置（环境变量）
| 变量 | 默认值 | 含义 |
|---|---|---|
| `STOCKFISH_PATH` | 自动检测 | Stockfish 二进制文件的路径。 |
| `CHESS_COACH_ENGINE_THREADS` | 1 | 引擎线程。 |
| `CHESS_COACH_ENGINE_HASH_MB` | 128 | 引擎哈希大小（MB）。 |
| `CHESS_COACH_POSITION_DEPTH` | 16 | `analyze_position` 的默认深度。 |
| `CHESS_COACH_GAME_DEPTH` | 14 | `analyze_game` 的默认深度。 |
| `CHESS_COACH_DIAGNOSE_DEPTH` | 12 | 诊断的默认深度（越低越快）。 |
## 移动分类的工作原理
移动根据**胜率下降**进行分类，而不是原始的 centipawns，使用 Lichess 的逻辑模型 — 在已经获胜或已经失败的位置中更有意义。一个移动是**失误** 如果它损失 ≥20% 胜率，**错误** 在 ≥10%，**不准确** 在 ≥5%。与棋局相关的评估：一个移动如果放弃强制将杀或走入将杀，则会相应地标记。
战术主题是**启发式**标签（用于悬挂棋子的深度 1 静态交换，用于 fork/pins/back-rank 的几何检测）。它们用于将引擎发现的错误分组为人类主题，而不是取代引擎的判断。
## 开发
```bash
uv run pytest # 单元测试 + 引擎测试（如果没有 Stockfish，则跳过引擎测试）
uv run python examples/mcp_smoke.py # 启动 MCP 服务器并调用工具
uv run python examples/live_check.py <lichess_username> # 实时网络端到端
```
标记为 `engine` 的测试需要 Stockfish 二进制文件；`live` 测试（默认情况下没有）会命中网络，除非您传递 `-m live` ，否则会被取消。
## 许可证
MIT
