Game of Life · MCP

A shared Conway's Game of Life world that an AI agent controls through MCP tools while you watch it evolve live in your browser. One Python process serves everything:

Surface	URL
Browser viewer	http://localhost:8000
Live state WebSocket	ws://localhost:8000/ws
MCP endpoint (Streamable HTTP)	http://localhost:8000/mcp

The server owns the authoritative board (NumPy). Every MCP tool call mutates it and immediately broadcasts the new state to all connected browser tabs.

Codex / Claude Code ──MCP──▶ ┌───────────────────┐
                             │  Python server    │──▶ shared GoL world
Browser UI ◀──WebSocket────  │ (FastAPI+FastMCP) │
                             └───────────────────┘

Quickstart

.\run.ps1

(First run creates the venv and installs dependencies. If PowerShell blocks the script, run it as powershell -ExecutionPolicy Bypass -File run.ps1.)

…or manually:

py -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe -m uvicorn gol_server:app --host 127.0.0.1 --port 8000

Open http://localhost:8000. The server binds to localhost only and has no auth — it's a local toy, don't expose it.

Connect an agent

Claude Code (run in any terminal; the server must be running when the agent starts):

claude mcp add --transport http gol http://localhost:8000/mcp

Codex CLI — add to ~/.codex/config.toml (exact key names vary by Codex version; check its MCP docs):

[mcp_servers.gol]
url = "http://localhost:8000/mcp"

MCP tools

Tool	What it does
get_world_status()	Dimensions, generation, population, live-cell bounding box, dynamics, autorun state
observe_world(x, y, width, height)	ASCII view of a region (# alive, . dead) with coordinate rulers; defaults to the full board, capped at 20 000 cells
create_world(width, height, edge, random_fill)	New board, 8–1024 per side; edge="wrap" (toroidal, default) or "dead"; optional random soup
clear_world()	Kill everything, reset generation to 0
set_cells(alive, dead)	Set individual cells from lists of [x, y] pairs
place_pattern(rle, x, y, clear_rect)	Stamp a standard RLE pattern (e.g. glider bob$2bo$3o!) at a position
advance(generations)	Step the simulation, 1–100 per call, animated in the browser
advance_generations(count, sample_every)	Efficiently commit up to thousands of generations in one call, returning compact per-sample stats (not the full board) plus a run summary
preview_generations(count, sample_every)	Same as advance_generations but doesn't touch the world — test what would happen before committing
set_autorun(enabled, fps)	Continuous simulation on the server, 1–1000 gen/s

Coordinates everywhere: (x, y), 0-indexed, (0,0) top-left, x → right, y ↓ down.

advance_generations / preview_generations

Both return {"samples": [...], "summary": {...}} as a JSON string — never the full board, so responses stay small even over thousands of generations. sample_every controls how often a sample is recorded (always including the final generation); each sample has generation, population, births and deaths (since the previous sample), bbox, a state_hash (matches only a bit-for-bit identical board) and a shape_hash (translation-independent — stays the same while a pattern like a glider moves). The summary reports start/end generation, min/max population, and whether the run went extinct, settled into a static state, or fell into a short repeating cycle.

Two caps apply, both surfaced as a {"error": ...} object in the response (not a thrown error) when exceeded:

• At most 500 samples per call. Raise sample_every if you hit this — the error tells you the minimum value that fits.
• count is capped by board size, not a flat number. The real cost of a run is width × height × count, so a 1024×1024 board allows far fewer generations per call than the default 160×100 board — the error reports the exact ceiling for the current board. Call the tool repeatedly for more.

advance_generations commits each sample to the live world as it goes (so the browser animates progress at the sample_every cadence); preview_generations never touches the world or the browser. Both walk the identical simulation code, so a preview and a subsequent advance with the same arguments always agree exactly.

Browser viewer

• Play / Pause / Step / speed — drives the same server-side simulation the agent uses.
• Draw / Erase / Pan — left-drag paints (right-drag always erases), wheel zooms, middle-drag pans, Fit re-centers.
• Activity panel — live feed of every MCP tool call, so you can watch the agent think.

Challenge ideas

• "Place a Gosper glider gun and report the population after 200 generations."
• "I've drawn a mess in the middle — stabilize the board into only still lifes."
• "Make two gliders collide head-on and tell me what survives."
• "create_world(300, 200, random_fill=0.2), run it until it settles, then find and report the coordinates of every oscillator."
• "Write my initials using still lifes."

Files

• gol_server.py — FastAPI app: WebSocket hub, MCP tools, autorun loop
• gol_world.py — pure simulation: NumPy stepping, RLE parser, ASCII renderer
• static/ — the browser viewer (vanilla JS + canvas)