Battle Arena MCP Server

<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

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).

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

from mcp_gtw.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.

📚 Documentation

Guide	What it covers
The game	Architecture, tools, endpoints and the world.
Authoring maps	Editing and creating maps in the Tiled editor.
CLAUDE.md	Every game rule and the module that owns it.

🗂️ Layout

.
├── 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
• Node 22+ 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 — 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 — 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 · Ko-fi.

Made with care by Paulo Coutinho.

Licensed under MIT.