内容
# 游戏大师
**真正与AI一起玩棋盘游戏。** 不是“描述一个棋盘并希望”——一个小型本地游戏服务器保持实际状态，强制执行实际规则，并让你们两个进行真正的行动：你的AI通过[MCP](https://modelcontextprotocol.io)工具，你通过对话或在一个舒适的小网页游戏室。
<img width="618" height="719" alt="Screenshot From 2026-07-19 13-52-46" src="https://github.com/user-attachments/assets/fa0bbe4d-45c9-4e0e-b5e5-6b159bb5e473" />
六款游戏，完整规则，无需信用系统：
| 游戏 | 规则 |
| --- | --- |
| **井字棋** | 快速经典游戏 |
| **四子连珠** | 重力，四颗连珠 |
| **跳棋** | 强制捕获，多跳，升王 |
| **西洋双陆棋** | 斑点，横条，清除棋子，双倍 |
| **国际象棋** | 王车易位，升变，检查，杀死， stalemate,五十步规则，三次重复，不足物质 |
| **战舰** | 两个隐藏的10×10舰队 - 每个侧面只看到自己的船只和自己的射击结果。秘密保留在服务器上。 |
已完成的比赛会自动记录在**游戏账本**中（胜场，连胜，最长游戏），并且你的AI拥有一个工具来为每场比赛添加标题和游戏后备注。网页大厅在游戏架下显示账本，旁边有一个小型奖杯柜。
## 快速开始 — MCP服务器
需要Python 3.10+ 和 `mcp` 包：
```bash
pip install mcp
```
然后使用MCP客户端注册 `game_master.py`。
**Claude 代码：**
```bash
claude mcp add game-master -- python3 /path/to/game-master-mcp/game_master.py
```
**Claude 桌面版** (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"game-master": {
"command": "python3",
"args": ["/path/to/game-master-mcp/game_master.py"]
}
}
}
```
任何其他MCP客户端都以相同的方式工作：它是一个普通的stdio服务器。
现在要求你的AI开始一个游戏（“新的国际象棋游戏 - 你是黑色”）。两个席位始终称为`human`和`agent`；你的AI扮演`agent`。游戏状态存放在`~/.game-master/games/`（使用`GAME_MASTER_HOME`覆盖）。
## 网页游戏室（可选但很好）
```bash
python3 server.py # 或：./ctl.sh start
```
打开 http://127.0.0.1:8777/ - 一个灯光昏暗的房间，里面有六个游戏盒在架子上，下面是游戏账本。点击一个盒子坐下：棋盘在左边，规则卡和（可选）AI聊天席在右边。浏览器在专用桌子上扮演`human`（`room-chess`，`room-battleship`，...），因此你纯粹通过对话玩的游戏永远不会被打扰。
棋盘轮询与MCP工具写入相同的状态文件，因此当你的AI从任何客户端进行回合时，移动出现在你的屏幕上。
### 使其成为你的
复制 `config.example.json` 到 `config.json`（或使用环境变量）：
```json
{
"player_name": "Sam",
"agent_name": "Aria",
"theme": "hearth"
}
```
- **名称** 在所有地方显示：回合笔记，聊天席，账本。
- **主题**：`hearth`（温暖的琥珀色木材），`tide`（深海洋蓝色），`grove`（森林绿色）。大厅中也有一个选择器。
### 聊天席
如果你的AI设置公开了一个本地聊天服务器，支持 Hermes WebUI聊天API（`/api/session/new`，`/api/chat/start`，SSE `/api/chat/stream`），请设置`chat_url`（例如`http://127.0.0.1:8787`），游戏室嵌入一个实时的聊天面板在每个棋盘旁边 - 垃圾话和“你的回合”提示。
没有它，聊天席礼貌地解释它没有连接，其他一切都完全相同：你点击，你的AI通过其工具进行游戏，棋盘更新。
## 诚信如何工作
- **没有任何东西为你进行移动。** 浏览器仅根据你的明确点击进行操作；AI仅通过其工具进行操作；服务器拒绝任何非法，轮流或超出界限的操作。
- **战舰永远不会泄露。** 舰队仅存在于服务器的状态文件中。浏览器视图和AI的`battleship_get_state`工具都返回一个编辑过的视图：你自己的舰队，加上命中/未命中/击沉标记，记录你的射击。
- **账本记录自己。** 当游戏结束时，结果写入`record_id`；AI的`gameroom_annotate_match`工具添加风味。
## 开发
```bash
pip install mcp pytest
python -m pytest tests/
```
`game_master.py` 包含所有六个引擎和MCP工具定义；`server.py` 是一个依赖于stdlib的网页服务器；`web/` 是普通的HTML/CSS/JS，没有构建步骤。
## 许可证
MIT - 请参阅 [LICENSE](LICENSE)。
