Gamebook

A minimal choose-your-own-adventure system with a FastAPI book backend and a Python MCP server that exposes the story to an LLM.

Run it

Play the adventure directly in a terminal. This starts the backend automatically if it is not already running:

uv run gamebook-play

Select a story with --story; the current observatory adventure is the default:

uv run gamebook-play --story observatory
uv run gamebook --story observatory
uv run gamebook-backend --story observatory

Each built-in story is defined in its own module under src/gamebook/stories and registered in gamebook.story.STORY_MODULES.

Enter a choice number to move through the story. Other commands include use <item>, examine <item>, take <item>, drop <item>, inventory, look, hint, hint direct, restart, and quit.

Start the book backend and Streamable HTTP MCP server together:

uv run gamebook

The MCP endpoint is http://localhost:8000/mcp. It listens on all WSL network interfaces so applications running on Windows can connect to it. The backend listens internally at http://127.0.0.1:8001; its interactive API docs are at http://127.0.0.1:8001/docs.

Configure LM Studio's mcp.json to connect to the already-running server:

{
	"mcpServers": {
		"gamebook": {
			"url": "http://localhost:8000/mcp"
		}
	}
}

VS Code is configured separately to launch gamebook-mcp over stdio from .vscode/mcp.json. Open the MCP Servers view or run MCP: List Servers, then start gamebook to use or debug it. The HTTP backend must also be running for tools launched this way.

For development, the components can also run separately:

uv run gamebook-backend
uv run gamebook-mcp

Point the MCP bridge at another backend by setting GAMEBOOK_BACKEND_URL.

Related MCP server: Integration Quest

MCP tools

• begin_adventure starts a session and returns the opening scene.

• choose_action sends one of the offered choice IDs to the backend.

• use uses an inventory item or a stateful item in the current scene.

• examine describes an inventory item or an item in the current scene.

• look_around returns the current scene and items present there.

• request_hint asks the backend for a subtle or direct clue.

• check_player_status returns the player's health and inventory.

• take_item moves an item from the current place into the player's inventory.

• drop_item moves an inventory item into the player's current place.

Run the tests with uv run pytest.