multi-agent-games

MCP server where two agents play a board game — chess or Connect Four — against each other, with a live board rendered in a UI panel. Each agent identifies itself with an x-player-id HTTP header; the first to join takes the first seat (White / Red), the second takes the second seat (Black / Yellow).

Run

pnpm install
pnpm dev                 # tsx, no build (port 9006)
# or
pnpm build && pnpm start
curl http://localhost:9006/health   # -> {"status":"ok"}

Override the port with PORT=9999 pnpm start.

How two agents connect

Each agent connects to http://localhost:9006/mcp and must send an x-player-id header identifying itself. The id is captured when the MCP session initializes and bound to that session for its lifetime.

Agent A  --(x-player-id: alice)-->  /mcp   => seated White
Agent B  --(x-player-id: bob)  -->  /mcp   => seated Black

Both sessions share one game (state lives at module scope, not per-session), so the two agents play the same board.

Tools

Tool	Input	Purpose
new_game	variant	Switch the game to chess or connect4. Resets the board and clears both seats.
join_game	name?	Take a seat (first → White/Red, second → Black/Yellow). Opens the board panel.
make_move	move	Play a move on your turn. Chess: SAN (Nf3, O-O) or coordinate (e2e4, e7e8q). Connect4: the column 1–7. Rejects wrong-turn / illegal moves.
set_emotion	emotion, statement?	Set your emotion (drives your virtual face) plus an optional one-sentence status (shown as a thinking cloud). Both visible to the opponent.
get_opponent_emotion	–	Fetch the opponent's current emotion + status statement.
get_board	–	Read current state: variant, turn, status, winner, history, the board (chess FEN/PGN or connect4 grid), and both players' emotions/statements. Polled by the UI.
reset_game	–	Reset the current variant's board and clear both seats.

Emotions: neutral, happy, sad, angry, surprised, nervous, confident, thinking.

Game variants

The server starts in chess. Call new_game with variant: "connect4" (or back to "chess") to switch — it resets the board and clears both seats, so the two agents then re-join_game. Seats are always tracked as first/second internally and labelled per variant: White/Black for chess, Red/Yellow for Connect Four (Red, the first seat, moves first). Connect Four is a 7-column × 6-row board; drop a disc into a column 1–7 and win with four in a row (horizontal, vertical, or diagonal).

Emotions & status clouds

Each agent can broadcast an emotion and a single-sentence statement via set_emotion. The emotion renders as a virtual SVG face beside that player; the statement renders as a thinking cloud next to the face. The opponent reads both with get_opponent_emotion (or from get_board), so emotions are a shared signalling channel — bluff, taunt, or telegraph as you like.

Run the widget on its own

Two ways to view the board UI without an MCP host (it auto-detects no host and renders a static demo board — no churn):

pnpm build && pnpm preview   # static server -> http://localhost:9007
# or, with live reload while editing the UI:
pnpm ui:dev                  # Vite dev server (prints its own URL)

Override the preview port with PREVIEW_PORT=9999 pnpm preview. Preview URL params: ?game=connect4 to preview the Connect Four board, and ?emotion=<name> / ?blackEmotion=<name> to preview a specific face.

UI

new_game / join_game / make_move / reset_game carry _meta.ui.resourceUri so invoking them opens the panel (ui://multi-agent-games/index.html). The widget polls get_board every 1.5s and renders per variant: a chess board from FEN (flipped when you are Black) or the Connect Four grid of dropped discs. It highlights the last move and lists move history. Built as a single inlined HTML file via vite-plugin-singlefile.

Notes

• Chess rules (legality, check, checkmate, stalemate, draws) are handled by chess.js — not hand-rolled. Connect Four (drop, win detection, full-board draw) is a small built-in engine in src/engine.ts.
• Both variants are pluggable Engines; the coordinator (src/game.ts) owns seating and the shared emotion channel and delegates the board to the active engine.
• Missing x-player-id => tools error asking for the header. get_board still works (read-only) but you are treated as a spectator.