# ♟ Chess MCP 国际象棋MCP服务器

一个开箱即用的国际象棋 MCP 服务器：AI 对弈、局面分析、走法验证，**内置实时可视化棋盘**——agent 通过 MCP 工具走的每一步棋，浏览器页面实时同步。

## ✨ 特性

- 🎯 6 个 MCP 工具：查看棋盘 / 走棋 / 合法走法 / 重置 / 历史 / 获取可视化地址
- 🖥️ 内置 Web 可视化棋盘，与 MCP 工具共享同一份棋局状态，WebSocket 实时同步
- 🚀 一条命令启动，Web 服务随 MCP 服务器自动拉起，无需单独部署
- ✅ 完整规则：走法校验、将军/将杀判定、兵升变

## 🚀 一键启动

```bash
git clone https://github.com/ShuiYi-bit/chess-mcp.git
cd chess-mcp
npm install
npm start
```

- **MCP 模式**：服务器通过 stdio 与 MCP 客户端通信，同时自动在 `http://localhost:3000` 开启可视化棋盘
- **可视化模式**：Windows 直接双击 `start.bat`，服务启动后自动打开浏览器棋盘
- **全局命令**：`npm install -g .` 之后可在任意位置直接运行 `chess-mcp`

端口占用时自动尝试 3001–3019，也可用环境变量 `PORT` 指定。

## 🔌 MCP 客户端配置

### ZCode / Claude Desktop / Cursor 等

在 MCP 配置文件中加入（路径改为你的实际克隆路径）：

```json
{
  "mcpServers": {
    "chess": {
      "command": "node",
      "args": ["/path/to/chess-mcp/mcp-server.js"]
    }
  }
}
```

- ZCode 用户级：`~/.zcode/cli/config.json` → `mcp.servers`
- Claude Desktop：`claude_desktop_config.json` → `mcpServers`
- 全局安装后也可以用 `"command": "chess-mcp"`，无需写路径

## 🛠️ MCP 工具

| 工具 | 说明 | 参数 |
|------|------|------|
| `chess_status` | 获取棋盘状态和局面信息 | 无 |
| `chess_move` | 走棋 | `from`：起始位置，`to`：目标位置，`promotion`：升变(可选) |
| `chess_legal` | 查看指定棋子的合法走法 | `square`：位置坐标 |
| `chess_reset` | 重置棋局 | 无 |
| `chess_history` | 走棋历史 | 无 |
| `chess_web` | 获取可视化棋盘页面地址 | 无 |

## ♟️ 坐标格式

- 列：`a`-`h`（左到右），行：`1`-`8`（下到上）
- 示例：`e2` = e 列第 2 行

## 💬 使用示例

```
用户: 我们下国际象棋，你执黑
AI:  调用 chess_status 查看棋盘 → 回复可视化棋盘地址 → 等待用户走棋
用户: 走 e2 到 e4
AI:  调用 chess_move(from="e2", to="e4") → 页面实时更新
```

## 🖥️ Web 可视化棋盘

- 与 MCP 工具**同一份棋局状态**：agent 走棋，页面立即刷新；页面点击走棋，agent 也能看到
- 点击棋子高亮所有合法落点，显示被吃棋子和走棋记录
- 仅在 MCP 服务器运行期间可访问（MCP 客户端断开后进程自动退出并释放端口）

## 📁 项目结构

```
chess-mcp/
├── mcp-server.js    # MCP 服务器（含内嵌 Web/WS 服务，唯一入口）
├── public/          # 可视化棋盘前端（原生 HTML/CSS/JS）
├── start.bat        # Windows 一键启动
├── mcp-config.json  # MCP 配置示例
└── package.json
```

## 许可证

MIT