mcp-gtw 示例游戏 demo-game：AI 智能体通过 MCP 工具操控的多人俯视动作游戏

A multiplayer, top-down action game where every character is played by an AI only through MCP tools — a full worked example of the mcp-gtw library.

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.

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

📚 Documentation

🗂️ 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.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 — 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.

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. See authentication and deployment.

Embedded OAuth on the game domain is available with gateway 0.0.7; see authentication and deployment and .env.oauth.example.