zekel-mcp

An MCP server for turn-based board games, with no games built in.

It keeps track of sessions, seats and moves. It runs AI turns, lets a second player join from another device, saves sessions (MongoDB, SQLite or memory), and offers numbered move menus, rules teaching and a web debug page. It knows no game rules: you register games, and every rule lives in them.

The two packages

A game imports only @zekel/game-kit. A program that serves games depends on @zekel/mcp, registers its games and starts the server:

import { registerGame, runServer, SERVER_INSTRUCTIONS } from '@zekel/mcp';

await runServer({
  serverInfo: { name: 'my-games', version: '1.0.0' },
  instructions: SERVER_INSTRUCTIONS,
  registerGames: () => registerGame(myGame),
});

examples/race-to-ten.mjs is a complete, tiny game (two players take turns adding 1 or 2; whoever reaches exactly 10 wins), written so it can be read in one sitting.

Related MCP server: gpt-game-arena

Running it

Needs Node 22.13 or later and pnpm.

pnpm install
pnpm build      # builds both packages
pnpm test       # the unit tests
pnpm smoke      # plays a whole game of the example through the real MCP tools

Settings come from environment variables: SESSION_STORE (mongodb, the default; sqlite; or memory), MONGODB_URI, SESSION_DB_PATH, MCP_TRANSPORT (stdio, the default, or http), PORT and MCP_BEARER_TOKEN.

Tests

The server's tests play a made-up game, Lucky Tic-Tac-Toe (packages/mcp/src/mcp/__tests__/luckyTicTacToe.ts): tic-tac-toe where players choose X or O at setup and each holds a secret lucky-square card, which is enough to exercise setup choices, secret information, private answers, reports from a physical table and on-screen play. It exists only for tests.

clientMode.test.ts replays fixed conversations and compares them with a recording (__fixtures__/llmDrivenBaseline.json), so any change to the text a model reads is made on purpose. After such a change, re-record with UPDATE_BASELINE=1 pnpm test and review the diff before committing it.

What a game can add

Beyond the required methods, a game can add its own MCP tools and resources (getExtraTools, getExtraResources), a board drawing for the web debug page (webAssetsDir), a rules-teaching outline, setup checklists, a move-menu layout and more. These are the optional fields of Game in packages/game-kit/src/game.ts.

Not done yet

• The instructions text was reworded to take its examples from the author's own games (Sweetlands Imperium, Cybernoir 2127, Neither Guts nor Gears). It has not yet been re-checked against weak models, which read it in every game.

• Saved sessions carry one version number for the whole server. When a game changes the shape of its saved state, that number has to change for everyone. Each game should version its own state.

• Only one copy of @zekel/game-kit may be installed: the server recognises a game's errors by their type. Game packages should list it as a peer dependency.

Licence

Licensed under Apache 2.0. See LICENSE.