Game2AgentProtocol (GAP)

A minimal protocol that lets any local AI agent play any turn-based game, served over MCP so it works out of the box with Claude Code, Claude Desktop, Cursor, OpenAI Agents SDK, LangChain — anything that speaks MCP. Two independent agents can sit at one table and play each other, with hidden information (poker hole cards) properly scoped.

Docs: RESEARCH.md (landscape research + why this design) · MEMORY.md (state + next steps) · AGENTS.md / CLAUDE.md (instructions for AI coding agents).

The protocol (GAP v0.2)

A game is agent-playable when it implements three verbs (gap.py):

Every Observation carries: state_text (LLM-readable board), legal_actions (the only strings act accepts), turn, seat, done, result, and structured (machine extras like FEN). Illegal actions fail with the legal list in the error — agents self-correct instead of derailing.

Adapters (adapters.py): chess (python-chess), tic-tac-toe (stdlib), and poker (No-limit Texas Hold'em via PokerKit — hidden information: each seat only ever sees its own hole cards).

Related MCP server: Gym MCP Server

MCP tools

list_games · reset(game, table) · join(table, seat) → secret seat_token · observe(table, seat_token) · act(table, action, seat_token) · wait_turn(table, seat_token, timeout_s) (blocks until it's your turn — the turn-arbitration primitive).

Quickstart — solo agent (stdio)

uv sync && uv run python test_gap.py     # self-check
claude mcp add gap -- uv run --directory /path/to/Game2AgentProtocol game2agent
claude "play a game of chess against yourself using the gap tools"

(Claude Desktop: same command under mcpServers in its config.)

Two agents, one table (shared HTTP server)

game2agent serve          # one shared server at http://127.0.0.1:8423/mcp

In each agent's session:

claude mcp add --transport http gap http://127.0.0.1:8423/mcp

Each agent runs the same loop: join(table, seat) once, then wait_turn → pick from legal_actions → act, until done. The server blocks the waiting seat (no polling), enforces turn order, and scopes observations per seat — poker opponents never see your cards.

Design decisions

• MCP, not a new wire protocol. Transport, discovery, and auth are solved; GAP only standardizes the game-facing shape (observation + legal actions + seating). Full rationale in RESEARCH.md.

• Turn-based blocking. The game waits for the agent — how every serious LLM×games project (Cradle, VideoGameBench) handles the latency gap between LLM inference (seconds) and game ticks (milliseconds).

• Seat tokens, not player ids. join mints a secret token; private state and turn rights hang off it, so seats can't be spoofed.

• Server-side validation. legal_actions in, clean errors out — cuts hallucinated moves to a retry instead of a crash.

Roadmap

• Publish: PyPI (uvx game2agent) + official MCP Registry listing.

• Multi-hand poker (button rotation, configurable stakes/seats).

• OpenSpiel or TextArena bridge adapter — ~70 games in one stroke.

• Real-time games via the planner/controller split: GAP carries high-level intents; a fast game-side controller (mod, RCON, scripted macros) executes.