# Game Forge — Educational Game MCP

Builds single-file browser games that teach **one concept** through play.
The design doctrine lives in `prompts/system_prompt.md` — edit it, restart, done.

## Run

```bash
pip install -r requirements.txt
python app.py
```

- **MCP endpoint:** `http://127.0.0.1:8000/mcp`
- **Health:** `http://127.0.0.1:8000/health`
- **Saved games:** `http://127.0.0.1:8000/games/<name>.html`

## MCP surface

| Kind | Name | Purpose |
|---|---|---|
| Tool | `build_game_prompt(topic, audience, session_minutes)` | Full parameterized generation prompt |
| Tool | `save_game(name, html)` | Save generated HTML → playable URL |
| Tool | `list_games()` | All saved games |
| Tool | `review_checklist()` | Self-verification gate before shipping |
| Resource | `game-forge://system-prompt` | The raw design doctrine |
| Prompt | `forge_game(topic, audience)` | One-shot "build a game about X" |

## Generate a game

`game.py` ties the MCP to a local Ollama model (`gemma4:12b`):

```powershell
# Terminal 1: MCP server (still required)
python app.py

# Terminal 2: generate a game
python game.py                              # prompts for topic
python game.py "equivalent fractions"       # one-shot
python game.py --topic gravity --audience "ages 10-12" --session 10
python game.py "photosynthesis" --checklist # + auto self-fix pass
```

Prints the playable URL on success. Requires `app.py` to be running and
Ollama to have `gemma4:12b` pulled.

## Test it

```bash
python test_client.py        # exercises every MCP tool + the web endpoints
```

## MCP Inspector (visual testing)

**Option A — stdio** (Inspector spawns the server itself):
```powershell
npx @modelcontextprotocol/inspector python server.py
```

**Option B — HTTP** (Inspector connects to your running app; preferred here
because it tests the real deployment surface, including /games/ hosting):
```powershell
python app.py                                   # terminal 1
npx @modelcontextprotocol/inspector             # terminal 2, no args
# In the Inspector UI: Transport = "Streamable HTTP", URL = http://127.0.0.1:8000/mcp
```

## Agent workflow (what an LLM client does)

1. `build_game_prompt("photosynthesis")` → system prompt for the game-brief
2. LLM generates the single-file HTML game from that prompt
3. `save_game("photosynthesis", html)` → `/games/photosynthesis.html`
4. `review_checklist()` → self-verify, fix, re-save