RPG Ledger

You can run an RPG campaign ledger powered by AI, exposing campaign state and actions through MCP. This server lets an AI GM or NPCs read and update characters, locations, factions, inventories, logs, and more, enabling rich, interactive sessions with an AI partner.

How to use

Connect your MCP client to the HTTP SSE endpoint at the public or local address your server exposes. You will gain access to tools that let you list campaigns, inspect and modify characters, manage locations and factions, mutate ledger state like gold, HP, XP, and notes, and save or restore campaign snapshots. Use these capabilities to drive AI-driven gameplay, track player progress, and keep a consistent campaign state across sessions.

How to install

Prerequisites: you need Docker and Docker Compose installed. You can also run locally with Python 3.11+ if you prefer a non-Docker setup.

Option A: Run with Docker Compose (recommended)

# Start the MCP server and the ngrok tunnel (if you want a public URL)
dagman
docker compose up --build

Additional setup tips

Local web UI is available at http://localhost:8000/ to browse campaigns, while API endpoints are at http://localhost:8000/api. The MCP endpoint for clients is http://localhost:8000/mcp.

Configuration and operation notes

The server runs on port 8000. MCP is exposed as SSE at /mcp. Use an MCP client configured for HTTP / SSE with endpoint http://localhost:8000/mcp (or a public URL if you expose it externally). The UI and API live under http://localhost:8000/ and http://localhost:8000/api.

Security and access considerations

If you open the MCP endpoint publicly, ensure you implement appropriate access controls and monitoring. Use secure channels (HTTPS) in production and consider restricting access to trusted clients to prevent unintended writes to campaign data.

Examples of usage patterns

• Retrieve a campaign, inspect all characters, and prepare a narrative for your AI GM. - Add a new character or adjust an existing one based on player actions. - Update locations and factions as the story unfolds. - Mutate ledger state to reflect in-world events, quests, or loot. - Create and restore snapshots to experiment with different story trajectories.

Dev tips and debugging

If you run into issues, check the server logs under logs/*.jsonl. You can also use the built-in dev_todo tool to capture feature ideas and track them as you iterate on the campaign system.

Available tools

list_campaigns

Return a list of campaigns available to the MCP client, enabling quick discovery of playable campaigns.

get_campaign

Fetch complete data for a specified campaign, including characters, locations, factions, and logs.

get_character

Retrieve a single character from a campaign by character ID.

list_locations

List all locations within a campaign to support exploration and quest design.

list_factions

List all factions within a campaign to manage reputations and alliances.

create_campaign

Create a new campaign with a given ID and optional base or overwrite behavior.

create_character

Add a new character to a campaign.

update_character

Modify properties of an existing character using patch data.

upsert_location

Add or update a location within a campaign.

delete_location

Remove a location by its ID or name.

faction_rep_add

Change a faction's reputation in a campaign.

upsert_faction

Add or update a faction with its ID, name, reputation, and description.

mutate

Apply ledger-wide mutations such as gold, HP, XP, notes, quests, and equipment.

spawn_npc_group

Generate a group of NPCs from a template for a given campaign.

dev_todo

Record TODO items for MG/AI to implement later in the log.

save_campaign_snapshot

Save a snapshot of the campaign state to a named slot.

restore_campaign_snapshot

Restore a previously saved campaign snapshot from a slot.