# xinkouhe Chess MCP

一个可接入 ChatGPT MCP Apps 的国际象棋服务器。用户执白，模型执黑。

## 功能

- `start_game` 创建棋局并显示棋盘
- `new_game` 在当前棋盘内创建新棋局，不额外生成棋盘卡片
- `user_move` 验证并应用用户走子
- `model_move` 验证并应用模型走子
- `show_game` 供棋盘组件读取并恢复当前权威棋局
- `get_game_state` 获取 FEN、PGN、合法走法和历史记录
- `end_game` 认输或放弃
- 只有 `start_game` 创建 MCP App 棋盘；其余工具是数据工具，不会在聊天中重复生成棋盘
- 棋盘在等待黑方时低频调用 `get_game_state`，把黑方已完成的走子同步回同一个组件
- 每次工具调用都返回完整的结构化棋局快照

## 组件恢复与对局隔离

- 每个棋局快照带有递增的 `revision`；组件提交走子时会带上它，旧棋盘不能覆盖新局。
- 新建棋局后，旧棋局只读；旧组件或延迟的模型结果会收到当前权威局面，不能修改新局。
- 非法走法响应仍包含当前权威 FEN、回合和合法走法，组件不会因为错误变成空白。
- 最近一次非法走法会作为 `lastError` 保留在当前快照中；组件轮询发现后会立即停止等待并开放“请求黑方行棋”重试。
- 白方落子后组件会显示等待倒计时；若模型没有继续走黑方，倒计时结束后可点击“请求黑方行棋”。
- “同步棋盘”只读取并重绘当前局面，不会额外触发模型行棋。
- 非法黑方走法不会清空组件；棋盘保留原局面，并可在等待超时后点击“请求黑方行棋”重试。

## 本地运行

```bash
npm install
npm test
npm start
```

MCP endpoint：`http://localhost:3000/mcp`

如果通过 Cloudflare Quick Tunnel 接入 ChatGPT，启动 Node 服务前要把 Tunnel 的 HTTPS 地址设置为 widget 域名：

```powershell
$env:WIDGET_DOMAIN = "https://你的临时域名.trycloudflare.com"
npm start
```

MCP 地址则是这个域名再加上 `/mcp`。每次 Quick Tunnel 重新启动并换了域名，都要用新域名重启 Node 服务；否则 ChatGPT 的 widget 域名校验会失败。

`tools/cloudflared.exe` 是 Windows 本地隧道辅助工具，不随仓库提交。需要 Quick Tunnel 时，请从 Cloudflare 官方发布页下载对应版本并放入 `tools` 目录；正式使用建议改用固定域名或已创建的 Cloudflare Tunnel。

当前模板版本为 `v13`。如果 ChatGPT 仍显示旧版棋盘，请断开并重新连接此 MCP，或在新会话中重新调用 `start_game`。

可以使用 MCP Inspector 连接这个 Streamable HTTP endpoint，依次检查初始化、工具清单、`start_game`、`user_move`、`model_move` 和 `show_game`。

## 许可证

本项目以 MIT 许可证发布。

## 接入 ChatGPT

ChatGPT 开发者模式需要一个公开可访问的 HTTPS MCP endpoint。部署本项目后，在 ChatGPT 的 Apps / Connectors 中创建应用，填写：

```text
https://你的域名/mcp
```

这个版本使用内存保存棋局，适合单进程个人使用和验证。正式公开部署时，建议把 `GameStore` 换成 SQLite、Redis 或其他持久化存储，并为 `gameId` 增加用户隔离。

## Docker 部署

```bash
docker build -t xinkouhe-chess-mcp .
docker run --rm -p 3000:3000 xinkouhe-chess-mcp
```

部署平台需要把外部 HTTPS 请求转发到容器的 `3000` 端口，并把 `/mcp` 作为 MCP endpoint。将 `PUBLIC_URL` 设置为公开站点地址后，根页面会显示完整的 MCP URL。

## 设计说明

服务端是棋局状态的唯一来源。UI 不依赖页面刷新、`localStorage` 或 widget state 保存棋局；每次落子后都从服务端返回的 FEN、PGN、回合和合法走法重绘棋盘。