Fantasy Gamebook Engine · The Grimoire of Claude Code

◆ ◆ ◆ ◆

Game Plugin Phase 1 MVP · 158 Tests Python · MCP · Claude Code

A solo-play Fighting Fantasy–style gamebook engine where Claude acts as the game master and narrator, but every dice roll, stat change, and combat outcome is decided by a local MCP server. The AI improvises the story. The engine arbitrates reality.

3 Skills 4 Commands MCP · 18 Tools 96% Coverage Ignarok Debut Module

§1

The Concept

Classic gamebooks (Fighting Fantasy, Lone Wolf) are books where you make choices, roll dice, and track your own stats. The engine recreates that experience in Claude Code — but with one hard rule that shapes the entire architecture:

The AI never invents a number and never rolls a die in prose. Every random outcome, stat change, and combat result goes through the MCP server. Claude narrates what the engine returns — nothing more.

This separation is the whole point: the AI handles language and story. The engine handles math and state. Swap the AI for a different model tomorrow — the rules stay identical. Swap the adventure module — the engine never changes.

System Architecture — ignarok → Claude harness → MCP server → rules/combat/storage → domain

dashed = pluggable swap point · purple = harness (AI) · teal = deterministic engine · click to zoom ↗

§2

The Harness — Skills

Click any card to see it in action inside Claude Code.

/game-master

The Narrator

Orchestrates every session: opens the character sheet from MCP, narrates turns in second person, offers numbered choices, delegates combat to the sub-agent, and compacts context.

Orchestrator Session loop

/combat-sub-agent

The Combat Arbiter

Runs one fight end-to-end via MCP tools only. The Game Master delegates a fight, passing hero stats and the enemy list. Returns a single FinalResult for the master to narrate.

Sub-agent MCP only

/ignarok

The Grey Mountain Lore

The debut adventure module — a static lore pack. Six zones of the Grey Mountain, a full bestiary, and one archmage to defeat. Swap this file to play a different adventure.

Lore pack Swappable

§3

The Commands — Incantations

Four commands that read or write state directly via MCP — no story impact. Available at any time, even mid-combat. Click any card to see the output.

solid = read-only · dashed = can write state · click to zoom ↗

/hero

Print the full character sheet — skill, stamina, luck, gold, provisions, inventory — straight from MCP state. Never a narrated value.

/backpack

List inventory, gold and provisions. Optionally use or consume an item — the state change goes through MCP, not prose.

/map

Show current location and every visited zone from real world state. Read-only — changes nothing, reflects the engine exactly.

/save

Checkpoint current progress via MCP. Accepts an optional slot name. Confirms with the slot identifier on success.

§4

Claim the Engine

Available Now

Clone the Engine

Full source — run the engine locally. The .mcp.json auto-registers the server when you open the directory in Claude Code.

Step 1 — Clone

git clone https://github.com/rc-ventura/fantasy-gamebook-engine

Step 2 — Install deps

cd fantasy-gamebook-engine && uv sync

Step 3 — Open in Claude Code

claude .

MCP server auto-registers from .mcp.json

Coming Soon — PyPI Release

Install Without Cloning

Once published to PyPI, uvx fetches and runs the engine with no local Python setup.

Step 1 — Install skills

bash install.sh fantasy-gamebook

Step 2 — MCP config (via uvx)

{"mcpServers":{"gamebook":{
  "command":"uvx",
  "args":["gamebook"]
}}}

In Progress

Requires uv publish from the engine repo. Follow the repo for the release.

§5

Begin Your Adventure

Once the engine is cloned and Claude Code is open in the directory, the MCP server is live. Type the first incantation:

▸ /game-master

What happens next

Claude reads the ignarok lore pack and checks MCP for an existing character.

If no hero exists, the engine rolls your attributes via MCP — not in prose.

Claude narrates the opening of the Grey Mountain. The adventure begins at §1.

◆ ◆ ◆

"You stand at the foot of the Grey Mountain. The wind smells of ash and old iron. Turn to §1."

← Return to the Grimoire

Hosted in the dungeons of GitHub Pages