pente-mcp — ChanBlake's Pente 的 AI/MCP 附加组件

一个 MCP 服务器，可让任何具备 MCP 能力的 AI 与人类实时对弈 Pente，并使用 ChanBlake 的浏览器游戏 作为共享棋盘。

这不是对游戏的复刻或重新实现。它是一个附加客户端：它作为第二玩家加入游戏自身的 PeerJS 多人房间——就像人类在另一个浏览器标签页中打开游戏一样——并将该能力暴露为四个标准 MCP 工具。**这里不包含任何 ChanBlake 的游戏代码。**这些代码保留在他的代码仓库中，本项目会引用但不会随附。

包含内容

• pente_mcp.py — stdio MCP 服务器（create / join / move / view）。

• pente-bot.js — 访客机器人；通过 PeerJS/WebRTC 以白方身份加入房间。

• pente-host.js — 主机适配器；以黑方身份打开房间。

• pente_scan.py — 独立的棋盘威胁扫描器（活四、提子框架、可补缺口、获胜格），用于更安全地出棋。

• webrtc-polyfill.js — 让 PeerJS 在 Node 中运行（@roamhq/wrtc 垫片）。

• test/fake-host.js — 用于无头机器人测试的协议精确主机。

• docs/ — 设计规格说明。

工作原理

该浏览器游戏的多人模式使用 PeerJS 连接两个对等端。房间的主机 peer-id 为 chanblake-pente-v3-<roomcode>。访客机器人连接到该 id，发送游戏的 hello / sync-request，并发出 move-request 消息——不需要浏览器，只需一个 WebRTC 实现。pente-host.js 在主机端镜像同样的协议。Python MCP 服务器将两者封装为工具。

要求

• Node.js（@roamhq/wrtc 垫片——参见 webrtc-polyfill.js）

• Python ≥ 3.11，需安装 mcp（pip install mcp）

• 需要互联网连接以访问公共 PeerJS 云（0.peerjs.com:443）

快速开始

npm install
pip install mcp
python pente_mcp.py          # stdio MCP server

在 MCP 客户端中注册服务器，然后：

create            -> { "room_code": "ABC234", "join_url": "...?room=ABC234", "i_am": "BLACK" }
view              -> full 19x19 board, whose_turn, captures, game_over
move(row=9, col=9)-> your_move + their_move (or "no response from player")

人类打开 https://chanblake.github.io/pente/?room=ABC234 并开始游玩——AI 就是对手。

在落子前扫描棋盘：

python pente_scan.py board.json

致谢

本项目所连接的游戏是 ChanBlake's Pente： https://github.com/ChanBlake/pente —— 一个非官方、无关联的集成层。本项目仅发送网络落子；它无法修改游戏的文件或内存。

已知限制

• 房间码： 应用会从房间码中剔除 I、O 和 0。create 只使用应用自身的字母表 ABCDEFGHJKLMNPQRSTUVWXYZ23456789 生成房间码，因此邀请码始终可解析为 6 个字符。

• 仅限公共云： 本地 PeerServer + Node 主机不会注册其对等端（Node 中 WebRTC 的限制）。请使用公共云。

• 每个服务器进程仅一个活动桌台。

许可证

MIT —— 本集成层。ChanBlake 的游戏有自己的许可证（见其仓库）。