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，把黑方已完成的走子同步回同一个组件

• 每次工具调用都返回完整的结构化棋局快照

Related MCP server: Chess MCP

组件恢复与对局隔离

• 每个棋局快照带有递增的 revision；组件提交走子时会带上它，旧棋盘不能覆盖新局。

• 新建棋局后，旧棋局只读；旧组件或延迟的模型结果会收到当前权威局面，不能修改新局。

• 非法走法响应仍包含当前权威 FEN、回合和合法走法，组件不会因为错误变成空白。

• 最近一次非法走法会作为 lastError 保留在当前快照中；组件轮询发现后会立即停止等待并开放“请求黑方行棋”重试。

• 白方落子后组件会显示等待倒计时；若模型没有继续走黑方，倒计时结束后可点击“请求黑方行棋”。

• “同步棋盘”只读取并重绘当前局面，不会额外触发模型行棋。

• 非法黑方走法不会清空组件；棋盘保留原局面，并可在等待超时后点击“请求黑方行棋”重试。

本地运行

npm install
npm test
npm start

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

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

$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 中创建应用，填写：

https://你的域名/mcp

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

Docker 部署

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、回合和合法走法重绘棋盘。