pente-mcp — an AI/MCP add-on for ChanBlake's Pente

An MCP server that lets any MCP-capable AI play Pente live against a human, using ChanBlake's browser game as the shared board.

This is not a fork or a reimplementation of the game. It is an add-on client: it joins the game's own PeerJS multiplayer rooms as a second player — exactly like a human opening the game in another browser tab — and exposes that as four standard MCP tools. None of ChanBlake's game code is included here. It stays in his repository, which this project references but does not ship.

What's in here

• pente_mcp.py — the stdio MCP server (create / join / move / view).

• pente-bot.js — guest bot; joins a room as WHITE over PeerJS/WebRTC.

• pente-host.js — host adapter; opens a room as BLACK.

• pente_scan.py — standalone board threat scanner (open fours, capture frames, refillable gaps, winning squares) for safer play.

• webrtc-polyfill.js — makes PeerJS run in Node (@roamhq/wrtc shim).

• test/fake-host.js — protocol-accurate host for headless bot testing.

• docs/ — the design spec.

How it works

The browser game's multiplayer uses PeerJS to connect two peers. A room's host peer-id is chanblake-pente-v3-<roomcode>. The guest bot connects to that id, sends the game's hello / sync-request, and speaks move-request — no browser needed, only a WebRTC implementation. pente-host.js mirrors the same protocol from the host side. The Python MCP server wraps both as tools.

Requirements

• Node.js (@roamhq/wrtc shim — see webrtc-polyfill.js)

• Python ≥ 3.11 with mcp (pip install mcp)

• Internet access to the public PeerJS cloud (0.peerjs.com:443)

Quickstart

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

In an MCP client, register the server, then:

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")

A human opens https://chanblake.github.io/pente/?room=ABC234 and plays — the AI is the opponent.

Scan a board before moving:

python pente_scan.py board.json

Credit

The game this connects to is ChanBlake's Pente: https://github.com/ChanBlake/pente — an unofficial, non-affiliated integration layer. This project only sends network moves; it cannot modify the game's files or memory.

Known limits

• Room codes: the app strips I, O and 0 from codes. create only emits codes from the app's own alphabet ABCDEFGHJKLMNPQRSTUVWXYZ23456789, so invites always parse to 6 chars.

• Public cloud only: a local PeerServer + Node host doesn't register its peer (WebRTC-in-Node limitation). Use the public cloud.

• Single active table per server process.

License

MIT — this integration layer. ChanBlake's game has its own license (see his repo).