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.

Related MCP server: Chess MCP

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

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.