<p align="center">
    <img src="extras/images/logo.png" width="360" alt="MCP Game" />
</p>

<h1 align="center">MCP Game</h1>

<p align="center">
    A multiplayer, top-down action game where every character is played by an AI <strong>only</strong>
    through MCP tools — a full worked example of the mcp-gtw library.
</p>

<p align="center">
    <a href="https://github.com/mcp-gtw/demo-game/actions/workflows/ci.yml"><img src="https://github.com/mcp-gtw/demo-game/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
    <a href="LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
</p>

---

You open the page, it hands your agent a private MCP endpoint, and when the agent calls `login` the
page drops straight into the game following your character. From there every tool — move, look, attack,
shoot, chop, speak — acts as that character, since your identity is the session you connected through.
The server is authoritative and reasons only in grid cells. There are no manual controls: the browser
is the view, the agent is the player.

<p align="center">
    <img src="extras/images/screenshot.png" width="300" alt="Gameplay screenshot" />
</p>

It is a single process built as one `AppGateway(Gateway)` subclass — it serves the MCP endpoint, the
authoritative world, the live stream and the self-hosted Phaser client (with a local copy of Phaser,
a vendored Roboto font and curated Tiny Swords art).

## 🚀 Quick start

```bash
make install        # python deps (pulls mcp-gtw) + build the client bundle
make run            # build the client, then serve everything on http://127.0.0.1:8000
```

Open <http://127.0.0.1:8000>, copy the shared MCP URL and token, and point your MCP client at it.
Call `login` with a name (optionally a class — warrior/archer/monk/lancer — and a skin color —
blue/yellow/purple/black; enemies are always red), then play. Open <http://127.0.0.1:8000/?gallery> to see the
component/sprite showcase (one of each UI element and game sprite stacked for a visual check).

```bash
make test           # pytest + vitest
make coverage       # both suites behind their 100% coverage gates
make lint           # ruff check + format check
```

## 🧩 How it is built on the gateway

```python
from mcpgtw.gateway import Gateway


class AppGateway(Gateway):
    async def serve(self):
        # run the authoritative simulation and drive the per-browser session
        # websockets that give each agent a private channel to log in through
        ...

    def register_routes(self, app):
        super().register_routes(app)
        # add /app/info, /app/stream and the self-hosted client
        ...
```

The gateway stays domain agnostic — all game logic lives here. The browser never registers tools:
the game tools run server-side through an in-process provider. See the
[gateway library guide](https://github.com/mcp-gtw/mcp-gtw/blob/main/docs/gateway-library.md).

## 📚 Documentation

| Guide | What it covers |
| --- | --- |
| [The game](docs/app.md) | Architecture, tools, endpoints and the world. |
| [Authoring maps](docs/maps.md) | Editing and creating maps in the Tiled editor. |
| [AGENTS.md](AGENTS.md) | Every game rule and the module that owns it. |

## 🗂️ Layout

```text
.
├── src/app/
│   ├── gateway.py room.py room_manager.py provider.py session.py   # MCP + room session surface
│   ├── game.py world.py fsm.py classes.py colors.py attributes.py items.py weapons.py objects.py catalog.py
│   ├── npcs/             # Behavior, LootDrop, EnemySpec + registry (one class per file)
│   ├── maps/             # SpawnPoint, RenderObject, MapDefinition + loader
│   ├── entities/         # player, enemy, projectile, food, tree, pickup, coin
│   ├── helpers/          # grid geometry and directions
│   └── web/              # game art, Tiled map, fonts and the built client bundle (dist/)
├── client/               # Vite component client (scenes, ui kit, lib) + vitest tests
├── tests/                # unit and integration tests (100% coverage)
├── docs/
└── Dockerfile
```

## ✅ Requirements

- Python 3.12+ — tested on 3.12, 3.13 and 3.14 in CI
- [`uv`](https://docs.astral.sh/uv/)
- Node 22.22.2+ and npm (to build the Vite client)
- A modern browser and any MCP client

## 🎨 Credits

The game art is the **Tiny Swords** pack by **pixelfrog** —
[pixelfrog-assets.itch.io/tiny-swords](https://pixelfrog-assets.itch.io/tiny-swords) — used for the
units, terrain, water foam, decorations, buildings, UI and the login background. Please support the
artist on itch.io.

The background music is by **MaksymMalko** on
[Pixabay](https://pixabay.com/music/search/game%20background/) — say _thanks_ to MaksymMalko! This
helps keep the creative spirit going. By using it you agree to the Pixabay license.

## 💜 Support

If this project saved you time, consider supporting it:
[GitHub Sponsors](https://github.com/sponsors/paulocoutinhox) · [Ko-fi](https://ko-fi.com/paulocoutinho).

Made with care by [Paulo Coutinho](https://github.com/paulocoutinhox).

Licensed under [MIT](LICENSE.md).

## Token and OAuth

Token is the default. Dual mode offers Token and OAuth in the same game. OAuth can use the embedded authorization server on the game domain or a configured external identity provider. The initial menu lets you copy the public OAuth MCP URL before login. With embedded OAuth, the MCP client initiates login/signup and consent, and a later browser login watches the same account's player. See [authentication and deployment](docs/oauth.md).

Embedded OAuth on the game domain uses the published gateway 0.0.12 from PyPI. Sign-in and consent use responsive monochrome dark pages with compact hints and expandable connection details. Docker builds require only this repository. See [authentication and deployment](docs/oauth.md) and `.env.oauth.example`.

Reloading or reopening restores the selected connection and its existing character while the session is active. Multiple tabs share the same identity, and successful MCP tool calls retain the character after the last browser tab closes. See [session resumption](docs/oauth.md#session-resumption-acceptance).

Browser login permits ten minutes by default through `APP_OAUTH_LOGIN_TIMEOUT_SECONDS`. Keep the authorization server login window aligned. Enable embedded account creation explicitly with `APP_OAUTH_ACCOUNT_REGISTRATION_ENABLED=true`. See [login deadlines](docs/oauth.md#browser-flow-and-revocation).