Life Lab AI

English | 日本語

A 20×20 implementation of Conway's Game of Life built with Python and Flask. Control the board in a browser, through natural-language instructions, or with an MCP client using stdio or Streamable HTTP. This is a local learning and experimentation project. The interface, operation messages, and validation errors are in English. The local parser accepts English and Japanese instructions.

Features

• Click to edit cells; start, stop, step, randomize, and clear the board

• Place gliders, blinkers, and blocks

• Parse common English and Japanese instructions locally, with optional OpenAI interpretation for other expressions

• Read and modify the board through MCP, with changes reflected in the browser

• Share one board across browsers and MCP clients, using revisions to detect conflicting edits

Cells outside the board are dead; edges do not wrap. The board lives in the Flask process's memory. Reloading the page preserves it; restarting Flask resets it.

Related MCP server: AetherTech MCP Server

Getting started

Requires Python 3.10 or later. Run these commands in the downloaded or cloned project directory:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python app.py

On Windows, activate the environment with .venv\Scripts\activate. Open http://127.0.0.1:5000 in your browser. Press Ctrl+C in the terminal to stop the server.

Natural-language commands

Enter an instruction and click Execute. These examples work without an API key:

Pattern placement, cell edits, and manual stepping stop playback. Rows and columns use coordinates from 1 to 20. Invalid coordinates and unsupported instructions produce an error. Japanese instructions remain supported; see the Japanese README for examples.

Optional OpenAI interpretation

Set OPENAI_API_KEY as an environment variable in the terminal used to start Flask. Keep your key out of source files, documentation, MCP configuration examples, and the browser. In Bash on macOS or Linux, you can enter it without placing the key in shell history:

read -r -s -p 'OpenAI API key: ' OPENAI_API_KEY
printf '\n'
export OPENAI_API_KEY
export OPENAI_MODEL='gpt-4o-mini'  # Optional; this is also the default
python app.py

Only instructions that the local parser cannot interpret are sent to the OpenAI Responses API. For example, 盤面を空にしてから真ん中にグライダーを配置して means “clear the board, then place a glider in the center.” Only the instruction text is sent, not the board. API usage may incur charges. The application does not automatically load .env files.

AI output is validated against an allowlist of operations. Up to 10 operations are applied only if all are valid. The application does not execute generated code, inspect the board with AI, or generate unsupported patterns. Verify live API connectivity and model access in your own environment.

MCP connection

Start Flask before connecting an MCP client. MCP operations do not require an OpenAI API key.

stdio

mcp-config.example.json provides an example for clients using the mcpServers configuration format. Replace /absolute/path/to/life-lab-ai with your local absolute path. Configuration formats vary by client.

{
  "mcpServers": {
    "life-lab": {
      "command": "/absolute/path/to/life-lab-ai/.venv/bin/python",
      "args": ["/absolute/path/to/life-lab-ai/mcp_server.py"],
      "env": { "LIFE_APP_URL": "http://127.0.0.1:5000" }
    }
  }
}

On Windows, use .venv/Scripts/python.exe as the Python executable. The MCP client starts the server process. stdio does not have a connection URL.

Streamable HTTP

In a separate terminal, activate the virtual environment and start the MCP server:

python mcp_server.py --transport streamable-http --port 8000

Set the MCP client's transport to Streamable HTTP and its URL to http://127.0.0.1:8000/mcp. This is a protocol endpoint, not a regular web page. If you change Flask's port, update the LIFE_APP_URL environment variable. Press Ctrl+C to stop the MCP server. Omitting the startup options selects stdio.

Tools

Pass the revision obtained from a read to editing tools to reject changes if another operation has already updated the board. Automatic generations are calculated from elapsed server time when the board is read or modified. Browsers poll every 250 ms; opening additional browsers does not increase the simulation speed.

Security and limitations

• Flask and HTTP MCP listen on 127.0.0.1. This is an unauthenticated local experiment; other processes on the same computer can access it.

• Publishing the source does not deploy the application. Internet hosting and authentication for multiple users are not supported.

• The MCP bridge accepts Flask URLs only on localhost or 127.0.0.1. HTTP MCP uses the SDK's Host/Origin validation.

• AI operations are checked for allowed types, coordinates, and generation counts. Generated code is never executed.

• Do not include secrets in instructions. When OpenAI interpretation is enabled, instructions not recognized locally are sent to an external API.

• .gitignore excludes .env files, key files, local configuration, virtual environments, and caches. Inspect the files being committed before publishing.

• The board belongs to a single Flask process. Database persistence and multiple workers are not supported.

Tests

With the virtual environment activated:

python -m unittest discover -s tests -v

Tests cover Life rules, instruction parsing, mocked AI responses, operation validation, revision conflicts, and real stdio/HTTP MCP connections. MCP tests use an isolated board, temporary localhost ports, and subprocesses that are stopped during cleanup. They do not verify live OpenAI requests or compatibility with every operating system.

Project layout

app.py                    Flask application and board APIs
commands.py               Instruction parsing, validation, and execution
shared_board.py           Shared board and revision management
mcp_server.py             MCP tools and transports
mcp-config.example.json   Example stdio configuration
locales/                  Japanese command compatibility data
static/                   JavaScript and CSS
templates/                HTML
tests/                    Automated tests
docs/screenshot.jpg       Example interface

The compatibility endpoints /api/step and /api/command perform independent calculations. Use /api/board, /api/board/actions, and /api/board/command to interact with the shared board.

License

MIT License