holonovel
Summary: Holonovel is an MCP server that runs tabletop campaigns as a persistent, rules-enforced world simulation — the server owns the rules, dice, and world state, while the AI narrates outcomes it cannot invent.
Ingest rulebooks: convert PDFs, HTML, and web scrapes into clean, indexed Markdown, then build declarative ruleset packages from them with no hand-written code.
Install and bind rulesets: search an installed ruleset's index, install or remove packages, bind a Novel to a system, and add supplementary Wisdom — or just play the seeded starter Novel with no rulebook.
Move through a spatial world: run parser commands (go north, take the lantern), resolve movement without mutating, and query visibility/audibility.
Author the world: create, update, remove, bulk-convert, or generate rooms, things, and exits with real containment, locks, and switchable/readable/wearable properties.
Run combat and conditions: set encounter turn order, add or remove participants, advance and end fights, and apply timed conditions to entities.
Stage scenes: set scene description, location, atmosphere, and story beat; issue narrative directives, offer choices, consult an oracle, and fast-forward time.
Populate the cast: manage NPCs with GM-only minds and stat-block links, player characters with sheets and voice, factions, directed relationships, vows with milestones, and countdown clocks that fire world effects.
Control what is known: keep durable lore entries with triggers and visibility, gate secrets until revealed, register cold-reference documents with per-entity access, and record beliefs and perceptions per entity.
Track objective causality: propose, admit, or reject state transitions in an audited ledger, with version guards and external-event ingress.
Keep a story journal: record decisions, moments, revelations, bonds, and consequences; promote entries into lore; branch a Novel from any event ordinal.
Resolve mechanics: roll Fate dice/aspects/stress, Ironsworn moves and progress, Forged in the Dark action rolls, and ruleset generation tables — all persisted and audited.
Seat players with badges: switch between Player, Game Master, Observer, and Editor, with server-side enforcement that re-filters available tools immediately and keeps GM-only secrets out of Player view.
Configure the game: adjust autonomy sliders (level, confirmation, safety, creativity), player signals, narrative directives, POV, speaker strategy, briefing order, verbosity, and synthesis refresh.
Deepen play with synthesis: run or revert Ruleset Wisdom and research layers, activate what fits, verify citations, and record rulings — with player-authored items preserved.
Manage the save file: create, resume, rename, archive, clone, checkpoint, roll back, and export/import campaigns as JSON or Markdown.
Reuse content across campaigns: maintain a server-level codex of NPCs, scenes, encounters, lore, rooms, templates, and voice profiles, plus an offline artifact registry for exchanging packs.
Inspect and undo: recover from mistakes with per-badge undo/redo, recap sessions, check health and context budgets, compress the audit log, verify state against hashes, and scan drafts for GM-only disclosure.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@holonovel Help me run my D&D campaign as an interactive story"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Holonovel
The Holodeck for your rulebooks — rules enforced, worlds remembered.
Start with the project wiki — it routes players, Game Masters, and builders by task.
A holonovel is a Star Trek holodeck program — an interactive story where you step inside as a character and the rules govern. Holonovel builds the server (the Holodeck). Your campaign is the program (the Novel). Your rulebooks become the mechanics — D&D 5e, Starfinder, or the game on your shelf. Your books. Your server. Your Holodeck.
Table of contents
Run a server — operators
How it works — evaluators
How it compares — evaluators
License — reference
Related MCP server: rpg-mcp
Run a server
Install
A fresh install is playable without a rulebook. On first start the server seeds
Torre Nosferatu, a tutorial Novel, and open_session resumes it in one call;
set TTRPG_STARTER_NOVEL=off to start with an empty world instead.
The base server runs the Holodeck. Rooms, objects, exits, and containment form a real state graph, while scenes, NPCs, lore, and a story journal layer on top, so narration is grounded in stored facts rather than prior chat turns. Requires Node.js 22+.
npx -y holonovelAdd to your MCP client:
{
"mcpServers": {
"holonovel": {
"command": "npx",
"args": ["-y", "holonovel"]
}
}
}Clients with their own configuration shape (for example a type plus a command
array) take the same command and arguments. From a source checkout, run
cd holonovel && npm install && npm run start, then point the client at
npx tsx src/index.ts in that directory.
Campaign data defaults to the operating system's user-data directory:
~/.local/share/holonovel on Linux, ~/Library/Application Support/holonovel
on macOS, or %LOCALAPPDATA%\holonovel on Windows. Set TTRPG_DATA_DIR to
override it. An existing .holonovel-state/ beside the server is preserved. A
container or hosted deploy keeps that directory inside the container, so point
TTRPG_DATA_DIR at a mounted volume to keep campaigns across restarts.
Setup details and first-run checks: Getting Started guide.
Install a ruleset
A ruleset package is a declarative bundle produced by the Build workflow. Copy it into the server's ruleset install directory and the server registers it. That directory is inside the state directory — by default the per-user data location described above.
Packages load lazily: a ruleset's tools and index are read only when you open a campaign bound to it, so unused packages cost nothing at startup. Install, remove, and list packages from the server's own tools, or move files and restart.
Campaign data and installed packages stay in the state directory, outside the
server tree, so updating Holonovel leaves both intact. After an upgrade,
npx -y holonovel update re-stamps campaigns and rulesets (--dry-run
previews; every rewrite is backed up). The Building a Server
guide covers
packaging a rulebook; Updating a
Server covers
upgrades and rollback.
How it works
Holonovel is one pipeline — Convert, Build, Holodeck, Novel, Synthesis — that turns a rulebook into a running table.
Convert
Convert takes PDFs, HTML, and web scrapes and turns them into clean Markdown. Multi-column pages are read in the right order, and tables split across page breaks are reassembled. Scanned pages fall back to OCR. The output is structurally sound — headings resolve and references trace.
"Convert the files in
ruleset/dnd5e/to Markdown for the D&D 5e ruleset." "Convert the HTML export inruleset/starfinder/for the Starfinder ruleset."
Clean, indexed Markdown ready for the build.
Build
Build reads that Markdown and extracts the mechanics. Dice procedures, combat systems, spell catalogues, equipment tables, condition tracks — modeled elements become tools, resources, or prompts in a declarative ruleset package, while anything that can't be modeled stays searchable. Guidance prose becomes narrative material. The discovery engine reads the source in chunks, measures extraction confidence, and works until the mechanical sections are accounted for. Nothing is fabricated to fill a gap.
"Build the Markdown in
ruleset/dnd5e/into a holonovel." "Packageruleset/starfinder/as a second ruleset alongside D&D 5e."
One spec reads any rulebook, and the build produces zero hand-written code.
Holodeck
The Holodeck is the narrative world model — the core engine that drives the simulation. It turns a saved Novel into a running game. Every part of a campaign is structured state: rooms, objects, exits, and containment in the spatial model; scenes, NPCs, lore, factions, secrets, vows, countdowns, relationships, decisions, and the story journal in the narrative model; mechanics and ruleset voice alongside them. None is decoration. Each has a defined effect on the others.
That effect is what makes Holonovel an engine. A scene sets the place and cast and activates lore whose triggers match its text. An NPC carries identity, disposition, relationships, and a location, so moving them changes who is present and who can speak. A secret stays hidden until knowledge and trigger conditions allow it to surface. A vow creates a decision the Game Master must honor. A countdown advances on schedule and fires its result into the world. A mechanical outcome — damage, a destroyed object, a doused light — mutates the state it touches. The story journal records the consequence, and later scenes can recall it.
The engine evaluates these couplings. The AI narrates the result. Nothing is left to a "remember this" instruction, and nothing drifts between turns. The MCP server is one adapter over the engine; the Novel is the portable program.
Parser commands act on the spatial model with real containment logic. Go north. Take the lantern. The room, the object, and the inventory are stored records, not claims in narration. Exits connect in both directions, containers hold what they hold, and doors stay locked until something unlocks them. The spatial conventions are drawn from Inform, the interactive-fiction language behind decades of text-adventure classics.
"Go north into the flooded ossuary." "Set the scene here — the ossuary reeks of stale incense and old water." "Have Sister Mora follow me into the ossuary." "Ask Sister Mora what she knows about the buried order." "Advance the reliquary countdown by one day."
The Holodeck is the live simulation; the Novel is its save file.
Novel
A Novel is the save file for a Holodeck game, and it stores the configuration that shapes that game. Server settings supply defaults; each Novel overrides them where the setting is campaign-scoped, and every change is saved with the campaign.
Who plays is configurable. A badge sets your seat at the table and what that seat can see: Player is in the story as a character, Game Master sees and controls the world, Observer watches while the AI runs both roles, and Editor steps outside the story to manage the save. The server enforces the boundary, so GM-only secrets do not leak to the Player badge. Each Novel carries its own active badge, and four autonomy sliders decide how much the AI handles alongside it: level (auto-play, prompt on mechanical actions, or manual), confirmation (execute, confirm, or prompt), safety (safe, moderate, or hardcore), and creativity (predictable, standard, or chaotic). The sliders compose with any badge, so a human can hand off one character, all NPCs, or the whole table without changing seats. The Game Mastering guide covers running the world from the opposite side.
How the story behaves is configurable. Player signals set pace, difficulty, tone, focus, and boundaries. A narrative directive tunes pacing, autonomy, world reactivity, and synthesis in plain language; matching keywords take effect mechanically, and anything else becomes guidance for the narrator. Behavioral settings cover whether the world reacts, whether NPCs and factions pursue goals on their own, when synthesis refreshes, how much memory each tier retains, and whether moments record automatically. Point of view can lock to the active character or stay omniscient, and social scenes can use a manual, natural, list, or pooled speaker order.
What content appears is configurable. A Novel binds to one ruleset at creation and can add supplementary rulesets without changing that binding. The categories used to organize available actions can be reassigned per Novel, and briefing order, enabled action patterns, and journal detail decide which guidance surfaces during play.
Export as JSON or Markdown. Import with merge, replace, or dry-run. Clone, checkpoint, and roll back. A clone carries the full configuration.
"Let the AI run all NPCs and player characters, but pause for mechanical decisions." "Make the game faster and darker, with harder fights." "Let the world react and NPCs act independently; use the rulebook's voice patterns." "Run synthesis whenever the scene changes." "Clone this Novel with its settings."
Every Novel-scoped setting is saved with the Novel, so a clone or checkpoint preserves the exact game you configured.
Synthesis
Synthesis deepens the Holodeck beyond mechanics. Ruleset Wisdom comes from the rulebook and any vendor package during Build — voice examples from example-of-play dialogue, lore templates from setting descriptions, action patterns from resolution sequences, and narrative voice profiles from inspirational media citations. It is build output, active by default, and survives every rebuild and synthesis reversion.
The Synthesis run adds two layers on demand. External research collects web-sourced GM advice, actual-play breakdowns, and designer notes, tagged with source URLs, confidence scores, and freshness timestamps. Internal synthesis reads the Novel itself for patterns the table has already produced. Both are inert by default: the Game Master activates what fits and deactivates what does not, and that activation state is saved with the Novel. Re-running synthesis replaces inactive items and preserves active ones. Reverting removes the synthesis layers; Ruleset Wisdom and player-authored items persist.
Synthesis can run on demand, at the start of a session, or after a scene change.
"Research horror one-shot pacing and actual-play examples, tagged with sources." "Enable the horror pacing guidance that fits this campaign." "Run synthesis after every scene change."
Ruleset Wisdom, synthesis layers, and player-authored items coexist in the Novel without replacing one another.
How it compares
Category | What you're used to | How Holonovel differs |
AI storytelling apps | Narrative-first apps with no rule engine — conditions drift, dice are improvised, the world is whatever the model remembers | The server holds the rules, dice, and world state; the AI narrates outcomes it cannot invent. |
Generic LLM chat | General-purpose chat with no durable state — forgets conditions mid-combat, invents spells, drifts toward safe outcomes | Mechanics resolve deterministically, state survives restarts, and the game keeps its consequences. |
Rules MCP servers | Server-side mechanics and durable saves, but a fixed ruleset or a single SRD seed. | Any rulebook, a containment-based world, and badge-enforced roles in one server. |
Rules engines serve one system. Storytellers improvise mechanics. Holonovel does neither: any rulebook becomes enforced mechanics, a spatial world, and a saved campaign. Across the TTRPG MCP servers reviewed in October 2026, no other reviewed server combined rulebook ingestion, spatial containment, and server-side role enforcement — for D&D 5e, Starfinder, or your own book. Questions about a specific table's setup? See the FAQ.
License
Canonical origin: git.gay/flukeatzerocool/Holonovel.
Licenses, upstream links, and modification status for every borrowed source:
docs/licenses/ATTRIBUTION.md.
Holonovel is MIT-licensed. Built from:
D&D 5e SRD v5.2.1 (CC BY 4.0, Wizards of the Coast)
Graham Nelson's Inform (Artistic License 2.0, Graham Nelson)
if-craft-corpus (CC BY 4.0, pvliesdonk)
dmcp (MIT, Shawn Rushefsky)
lonelog (CC BY-SA 4.0, zeruhur)
COF — Character Open File (CC BY 4.0 / CC0 1.0, Yann Souetre)
BitD SRD (CC BY 3.0, John Harper)
Ironsworn: Starforged SRD (CC BY 4.0, Shawn Tomkin)
Sly Flourish Lazy GM Resource Document (CC BY 4.0, Mike Shea)
The Alexandrian (CC BY 4.0, Justin Alexander)
Dungeon World SRD (CC BY 3.0, Sage LaTorra, Adam Koebel)
Fate SRD (CC BY 3.0, Evil Hat Productions)
Ironsworn SRD (CC BY 4.0, Shawn Tomkin)
License texts: CC BY 4.0, CC BY 3.0, CC BY-SA 4.0, CC0 1.0, MIT, Artistic 2.0.
Upstream sources: D&D 5e SRD, Inform, if-craft-corpus, dmcp, lonelog, BitD SRD, Starforged SRD, Lazy GM, The Alexandrian, Dungeon World SRD, Fate SRD, Ironsworn SRD, COF.
RSS. Last updated: 2026-11-08.
Available Tools
37 toolsclose_sessionClose Play SessionADestructive
Close a play session by returning a recap and saving the current context. The close seals the session's recap and saved context but does not archive or export the Novel; resume it later with open_session. Context and recap state persist and are audited; revert with manage_history (action: undo). Use when: ending a session or checkpointing the narrative context. Do NOT use when: archiving or exporting a Novel — use manage_archive.
Inputs: no named parameters. Returns: text, status
manage_adventureAdventure ManagementADestructive
Generate, load, or list adventure content. generate writes a scaffold to target — novel, codex, or both (default novel when one is active, else codex) — using premise; a !force prefix overrides the generation guard. generate_encounter writes one encounter to the Novel using context. Both persist, appear in the audit log, and the most recent write is undoable via manage_history (action: undo). load and list are read-only, and list accepts an optional genre filter. Use when: the GM wants a new adventure scaffold, a single encounter, or to load a prepared module. Do NOT use when: recording a story beat — use manage_story (action: record).
Inputs: action (required), slug, filter, target, +2 more. Returns: text, status
manage_agentAgent Task ManagementADestructive
Manage durable NPC/agent tasks and their action lifecycle. create reads goal and optional source_goal; advance requires task_id and appends description; complete, fail, and cancel require task_id, settle the task without deleting it, and terminal tasks are immutable; autonomy defaults to TTRPG_AGENT_AUTONOMY. Mutating actions persist to the Novel and are audited; list/get are read-only. Use when: creating, starting, advancing, settling, or inspecting tasks. Do NOT use when: surfacing an advisory suggestion — use manage_scene (action: oracle); managing NPC identity — use manage_npc. Revert with manage_history (action: undo).
Inputs: action (required), goal, detail, subject, +4 more. Returns: text, status
manage_archiveNovel Archive ManagementADestructive
Export, import, archive, unarchive, clone, branch, and checkpoint Novel save files. export writes a file in json or markdown; share emits a portable full-scope json bundle with embedded adventure content; import writes Novel state and mode selects dry-run (validate only), merge (keep existing entries), or replace (discard current Novel state), while strict aborts on unresolved references. clone copies the whole Novel unless trim_audit_sessions keeps only recent sessions; branch starts from from_event (default latest); archive is reversible with unarchive; checkpoint_restore replaces the live Novel with the stored checkpoint and is itself undoable; checkpoint subscriptions persist. Use when: exporting or importing a Novel, archiving/unarchiving, cloning/branching, or managing checkpoints. Do NOT use when: creating, resuming, renaming, or ending a Novel — use manage_novel. Revert the most recent mutation with manage_history (action: undo); checkpoint_list is read-only.
Inputs: action (required), data, mode, slug, +10 more. Returns: text, status
manage_artifactLocal Artifact RegistryADestructive
Manage the host registry of shareable artifacts — Novel packs, adventure modules, and ruleset packages — exchanged offline through an inbox. list and verify are read-only. install copies a verified artifact into its kind directory and audits it; ruleset tools become callable after restart. remove is permanent (no undo), rebuilds ruleset prompts, and refuses while a Novel depends on it. install/remove need the GM badge and record a security event, and install refuses a hash/provenance mismatch, a mismatched slug, or an existing slug; slug names remove/verify and must match the artifact's slug on install (a pack without one adopts it). source is an inbox-relative file or package directory; location is GM-only. Use when: exchanging a world pack or ruleset between installations. Do NOT use when: installing a package built in-process — use manage_ruleset (action: install); importing state into the active Novel — use manage_archive (action: import).
Inputs: action (required), kind, slug, source, +1 more. Returns: text, status
manage_beliefBelief ManagementADestructive
Manage per-entity evidence, reconciled belief stances, the perception ledger, and a one-entity knowledge query. list, get, evidence, conflicts, perception_list, and knowledge_query read; admit, retract, reconcile, and perception_record write. admit records a subject/predicate/object proposition with a 0..1 weight and does not change a stance until reconcile recomputes it; retract requires the evidence_id from admit and reconciles; the perception ledger is append-only, so correct a mistaken perception with a new record. Mutating actions persist to the Novel. knowledge_query returns perceptions, beliefs, and known secrets with event provenance, optionally filtered by topic. Use when: inspecting or recording what an entity learned or believes. Do NOT use when: recording objective truth — use manage_causality; recording shared lore — use manage_lore; ranking derived text or traversing the knowledge graph — use manage_knowledge.
Inputs: action (required), topic, detail, object, +19 more. Returns: text, status
manage_causalityCausality ManagementADestructive
Manage objective causal state and transition proposals. causal_propose records a proposal without applying it; causal_admit applies the proposal and causal_reject marks it rejected without deleting the ledger record; causal_expected_version guards optimistic concurrency and causal_from records the expected prior value; causal_ingress admits an external event without a proposal. Proposals persist and are audited, and the ledger is capped by TTRPG_CAUSAL_MAX_LEDGER_ENTRIES; list and state are read-only. Causal changes are not undoable via manage_history. Use when: proposing, admitting, rejecting, listing, or inspecting causal transitions, or ingressing an external event. Do NOT use when: changing rooms, things, or exits — use manage_world.
Inputs: action (required), causal_key, causal_from, causal_scope, +7 more. Returns: text, status
manage_characterPlayer Character ManagementADestructive
Manage player characters: create, import, stage, activate, edit, signal, remove, or list roster characters. stage adds an existing entity to the roster; set_active chooses which Novel entity play acts through and optionally sets pov; import requires roster_id and copies that roster character into the Novel. sheet and roster_list are read-only; Novel mutations persist, are audited, and are undoable via manage_history (action: undo). update merges provided fields (stats shallow-merge; omitted fields preserved), personality{} aliases description/voice/background/goals, and details{} aliases ability_scores/skills/feats/talents/equipment; a top-level value overrides its grouped alias. stage and roster_remove are exact inverses on the roster; remove deletes the Novel entity and is undoable. Use when: creating or importing a PC, staging or activating one for play, editing its sheet or voice, or handling player feedback. Do NOT use when: managing an NPC — use manage_npc.
Inputs: action (required), pov, name, seed, +23 more. Returns: text, status
manage_codexCodex Library ManagementADestructive
Manage the server-level codex library of reusable, cross-Novel content (NPCs, characters, scenes, encounters, lore, factions, rooms, things, templates, voice profiles, adventures). Entries persist to .holonovel-state/codex.json outside every Novel and survive restarts; mutations are audited. Out-of-play and badge-free: requires the Editor or Game Master badge, a Player mid-adventure gets [FORBIDDEN], and reads are not badge-filtered. When no Novel is active, the codex is the default store; import and capture require an active Novel. set needs kind + name (the id derives from them); merge=true shallow-merges content. Revert the most recent mutation with manage_history (action: undo). Use when: storing reusable content for later import, or enumerating/reading/deleting it. Do NOT use when: storing Novel-scoped content — use manage_lore (action: set) or manage_note (action: set).
Inputs: action (required), id, kind, name, +8 more. Returns: text, status
manage_combatCombat Encounter ManagementADestructive
Manage combat encounters in the active Novel — encounter turn order, participants, and lifecycle, not per-entity conditions. Mutating actions persist to the Novel and are audited; read-only actions do not mutate state. Revert the most recent mutation with manage_history (action: undo). init's seed only reorders the danger set; participants keep their given order. Use when: starting, advancing, ending a fight, or changing its participants. Do NOT use when: applying a status effect — use manage_condition (action: apply).
Inputs: action (required), seed, dangers, outcome, +2 more. Returns: text, status
manage_conditionCondition ManagementADestructive
Manage mechanical or narrative conditions on entities. apply attaches a named condition to one entity; rounds is a positive round count, and omitting it (or passing 0) leaves the condition without an expiry. Re-applying an active condition warns instead of duplicating it, and remove deletes the condition and its round counter. apply and remove require the GM or Editor badge, persist to the Novel, and are undoable via manage_history (action: undo); list is read-only. Use when: applying, removing, or listing conditions. Do NOT use when: recording damage or combat state — use manage_combat (action: init/advance).
Inputs: action (required), rounds, condition, entity_id. Returns: text, status
manage_contextContext ControlsADestructive
Manage play-facing context controls: recap, verbosity, briefing_order, and tool discovery, distinct from story content and Novel lifecycle. recap accepts an archived session_id, GM-only gm_notes, and an optional compression tier; gm_notes are never returned to a non-GM badge. discover searches names, descriptions, and titles, and detail schema requires query. verbosity is session-scoped; briefing_order persists to the Novel and requires the GM or Editor badge. recap and discover are read-only; a setting is restored by setting it again (no undo snapshot is taken). Use when: recapping play, tuning output verbosity, reordering the briefing, or finding a tool. Do NOT use when: health, audit compaction, event-log, or category operations — use manage_diagnostics; recording story content — use manage_story (action: record).
Inputs: action (required), mode, tier, query, +8 more. Returns: text, status
manage_corpusKnowledge CorpusADestructive
Manage the cold-reference knowledge corpus. corpus_register indexes a document with optional access_public, access_domains, grants, and denies; route derives its domain from a trusted source profile; grant and deny add per-entity decisions, and an explicit deny overrides public, grant, and domain access; access sets an entity's domain profile; consume records a read. Mutating actions persist access state and are audited; list, get, and acquisitions are read-only. Corpus mutations are not undoable via manage_history. Use when: registering, listing, reading, routing, granting/denying access, consuming, or inspecting acquisitions of corpus documents. Do NOT use when: writing Novel lore entries or secrets — use manage_lore; ranking derived text or traversing the knowledge graph — use manage_knowledge.
Inputs: action (required), corpus_body, corpus_mode, corpus_title, +9 more. Returns: text, status
manage_countdownCountdown ManagerADestructive
Manage countdown timers in the active Novel. set accepts a starting tick count and optional total; advance fires the configured world_effect when the countdown reaches its threshold, and on_scene_transition advances it automatically; direction shifts NPC dispositions only when scope is also set. remove is GM-only and deletes the timer without firing its world_effect. Mutating actions persist to the Novel and are audited; list is read-only. Use when: starting, advancing, removing, or listing clocks. Do NOT use when: tracking a vow's progress — use manage_vow (action: milestone). Revert with manage_history (action: undo).
Inputs: action (required), name, type, scope, +7 more. Returns: text, status
manage_diagnosticsSession DiagnosticsADestructive
Manage session diagnostics and maintenance surfaces separate from play-facing session controls. compress summarizes the audit log while compact prunes it irreversibly; verify compares live state with recorded hashes and replay reads the retained log, and both are read-only; context_report emits a per-section token ledger and accepts budget_tokens to pack it; visibility_check records its decision in the audit log while visibility_audit reads recent decisions; health, subscribe, and category reassignment do not change Novel content. compact is GM-only. Use when: reporting health or context size, summarizing or compacting the audit log, subscribing, reassigning a category, appending/reading the event log, verifying or replaying state, or scanning a draft for GM-only disclosure. Do NOT use when: recapping play, setting verbosity, or reordering the briefing — use manage_context.
Inputs: action (required), mode, text, tier, +21 more. Returns: text, status
manage_factionFaction ManagementADestructive
Manage organizations in the active Novel: create, update, remove, or list factions, each carrying a name, description, goals, resources, and optional territory room names. name is required to create and faction_id targets an existing faction; the progress clock is Novel-internal and not set directly. create, update, and remove require the GM or Editor badge, persist to the Novel, and are undoable via manage_history (action: undo); remove deletes the faction permanently unless undone, and list is read-only. Use when: creating, revising, removing, or listing factions. Do NOT use when: tracking a faction's territory rooms — use manage_world (action: create_room).
Inputs: action (required), name, goals, detail, +4 more. Returns: text, status
manage_historyUndo and Redo HistoryADestructive
Undo or redo the most recent state mutation for the calling badge, restoring the Novel content snapshot captured before it. Append-only logs, checkpoints, and the undo/redo stacks are preserved rather than rolled back, and the response reports success without a diff. Both directions mutate Novel state and persist immediately. The stack is per badge and capped by TTRPG_MAX_SNAPSHOT_DEPTH, and a pending workflow decision blocks both until resolved with respond_decision. Use when: reverting the last mutation (undo) or restoring an undone one (redo). Do NOT use when: an older change is the target — re-run the owning tool (for example manage_story), because only the most recent mutation is stacked.
Inputs: action. Returns: text, status
manage_identityIdentity ManagementADestructive
Manage a roster character's durable identity: staged candidates, accepted facets, and the versioned compiled kernel. stage imports or authors identity material; accept replaces a facet, retains the displaced value in an internal history, and bumps the identity version; reject marks a candidate rejected without touching accepted facets; revert restores the most recently displaced facet. bootstrap seeds from a character card; accept's perspective defaults to the candidate's stored perspective. Mutation persists the roster and is audited; list and snapshot are read-only and report current facets only. Use when: staging, accepting, rejecting, reverting, or reading identity material. Do NOT use when: recording what a character knows or believes — use manage_belief; editing narrative personality — use manage_character (action: personality).
Inputs: action (required), character_id (required), card, facet, +5 more. Returns: text, status
manage_knowledgeDerived KnowledgeADestructive
Manage derived, in-memory knowledge over Novel sources: a semantic index for advisory text ranking and a typed knowledge graph. index_build and graph_build are audited, replace the prior projection in one step, and do not persist a separate copy; both are safe to rebuild from the authoritative Novel file, which is never modified. Search and neighbor reads require the matching build and return one hop of edges or ranked candidates (limit defaults to 5); rebuild after editing or restoring the Novel. The read actions never mutate state. Use when: building or rebuilding the index or graph, checking staleness, ranking indexed items, or reading relations and graph structure. Do NOT use when: searching a bound ruleset's index — use manage_ruleset (action: search); recording knowledge — use manage_corpus; recording beliefs or perceptions — use manage_belief.
Inputs: action (required), limit, query, item_id, +1 more. Returns: text, status
manage_loreLore ManagementADestructive
Manage the active Novel's lore entries — durable facts every caller recalls. set upserts a keyed entry, merging supplied fields into an existing key; update requires an existing key and changes only supplied fields; set_secret, reveal, secret_list, and knowledge control Player-visible facts. import defaults to dry-run; merge overwrites colliding keys and keeps entries not in the import; replace clears first. Triggers fire on scene-text match; sticky counts scenes an entry stays active after its last match. visibility gates Player read access (gm_only default, shared, player_discovered). Mutations require GM/Editor, persist to the Novel, and are undoable; reads are read-only. Use when: creating, revising, removing, toggling, grouping, suggesting, listing, exporting, importing, or controlling knowledge. Do NOT use when: recording one entity's beliefs or perceptions — use manage_belief; handling cold-reference documents — use manage_corpus; storing scratch notes — use manage_note.
Inputs: action (required), key, data, mode, +11 more. Returns: text, status
manage_noteNote ManagementADestructive
Manage Novel-scoped scratch notes, badge-scoped to game_master (default), player, or shared. set replaces the note content; badge_scope defaults to game_master and controls which badge can read it; remove deletes one note, and the Player badge cannot remove a game_master note; list hides game_master notes from non-GM badges. set_server stores a GM-only server-level note with an optional narrative_tag; remove_server deletes it; list_server returns summaries unless detail is set. Mutating note actions persist and are audited, but are not undoable. Use when: storing scratch state the caller will reuse. Do NOT use when: recording durable world facts — use manage_lore (action: set); handling external documents — use manage_corpus; ranking derived text — use manage_knowledge.
Inputs: action (required), key, detail, content, +2 more. Returns: text, status
manage_novelNovel Save ManagementADestructive
Manage a Novel's save-file lifecycle: create, resume, switch, end, rename, describe, set genre, list, save/get play context, and record provenance. list returns one line per Novel unless detail is set, and filter selects active, archived, or all. create, save_context, and provenance persist; list, info, and get_context are read-only. export, import, archive/unarchive, clone/branch, and checkpoint actions remain callable here for compatibility, but manage_archive exposes them with clearer scope — prefer it. Lifecycle changes are not reversible via manage_history, so clone a Novel before a risky change. Use when: handling a campaign's lifecycle or returning to saved context. Do NOT use when: managing content inside the Novel — use the entity tools; use manage_archive for export, import, archiving, cloning, branching, and checkpoints.
Inputs: action (required), data, mode, name, +27 more. Returns: text, status
manage_npcNPC ManagementADestructive
Manage non-player characters in the active Novel. create requires a name; ruleset_reference links a stat block without copying it; mind is GM-only and never returned to the Player badge; remove deletes the NPC permanently. create, update, and remove require the GM or Editor badge, persist to the Novel, are audited, and are undoable via manage_history (action: undo); list and get are read-only. Use when: introducing, revising, removing, listing, or reading NPCs. Do NOT use when: managing player characters — use manage_character (action: create/import/sheet).
Inputs: action (required), card, mind, name, +12 more. Returns: text, status
manage_relationshipRelationship ManagementADestructive
Manage directed relationships between entities, NPCs, or factions. set is keyed by the ordered (entity_a, entity_b) pair and updates type, value, or description in place rather than duplicating; type is one of ally, rival, neutral, mentor, dependent, or suspicious, and value is an optional numeric strength. get returns outgoing and incoming edges separately. set requires the GM or Editor badge, persists to the Novel, and is undoable via manage_history (action: undo); get is read-only. Use when: setting or reading how two parties relate. Do NOT use when: tracking faction standing or progress — use manage_faction (action: update).
Inputs: action (required), type, value, entity_a, +3 more. Returns: text, status
manage_rulesetRuleset Package ManagementADestructive
Manage ruleset packages: search an installed ruleset's index, install or remove a package, list installed packages, bind a Novel to a ruleset, or import/remove supplementary Wisdom. search accepts an optional slug, works with no active Novel, and is read-only; install, remove, import_supplementary, and remove_supplementary mutate state, are audited, and are reversible via the paired action. install of an existing slug conflicts, and remove refuses while a Novel is bound to that slug. binding scopes only Novel-dependent features; import_supplementary uses inline wisdom when present and reads source only when absent. Table rolls are resolve_mechanic (action: roll). Use when: searching rules content, managing packages, binding a Novel, or adding/removing supplementary Wisdom. Do NOT use when: the ruleset name is unknown — use manage_context (action: discover).
Inputs: action (required), seed, slug, index, +10 more. Returns: text, status
manage_sceneScene ManagementADestructive
Manage the active scene and its narrative framing — scene description, directive, choices, and oracle rolls. set overwrites the scene's description and metadata, derives the description from location only when description is omitted, and accepts fast_forward to skip an interval: changes applies NPC moves, conditions, or dispositions and skip_countdowns preserves narrative countdowns. directive replaces the active directive; choices replaces the offered options; oracle resolves a chance question and records the roll, so repeated calls are additive rather than idempotent. set and directive require the GM or Editor badge, persist to the Novel, are audited, and are undoable. Use when: setting scene state, issuing a directive, offering choices, consulting the oracle, or skipping time. Do NOT use when: recording a story beat — use manage_story (action: record); staging presence or autonomy — use manage_staging; changing the spatial model — use manage_world.
Inputs: action (required), beat, seed, prompt, +14 more. Returns: text, status
manage_stagingScene Staging ManagementADestructive
Manage scene presence, autonomy, and social-cast staging. presence replaces the present set; cast sets the multi-NPC speaker strategy with mute/unmute adjusting its pool; next_speaker runs manual, forced, or pooled selection, where force overrides select; autonomy changes apply to the current scene only. Presence, autonomy, and cast state persist to the Novel and are audited. Use when: setting who is present, adjusting scene autonomy, choosing a speaker strategy, or selecting the next speaker. Do NOT use when: setting the scene, issuing a directive, offering choices, or consulting the oracle — use manage_scene. Revert the most recent mutation with manage_history (action: undo).
Inputs: action (required), mute, force, level, +8 more. Returns: text, status
manage_storyStory Journal ManagementADestructive
Manage the story journal — typed narrative memories (decision, moment, revelation, bond, consequence). record appends an entry and consumes the turn_handle minted by take_turn; update edits a mutable entry; decision and consequence entries are immutable and refuse update or promotion; remove deletes an entry by index; promote copies an entry into lore under a derived or supplied key. list filters by type and paginates with offset and limit, returning previews unless detail is set. Mutations require the GM or Editor badge, persist to the Novel, and are undoable via manage_history (action: undo); list is read-only. Use when: recording, editing, removing, listing, or promoting story beats. Do NOT use when: recording a durable world fact — use manage_lore (action: set).
Inputs: action (required), key, type, entry, +5 more. Returns: text, status
manage_synthesisSynthesis ManagementADestructive
Manage synthesis content (voice examples, lore templates, action patterns, and other Ruleset Wisdom). Mutating actions (run, revert, activate, deactivate, toggle, toggle_action, player_add, player_remove, record_ruling, revert_ruling) persist to the Novel and are audited; read-only actions (list, player_list, verify) do not mutate state. verify checks each item's stored citation locally and reports pass/weak/unsupported; it never fetches and never changes state. record_ruling writes a ruling and its verified citations to the GM-only ruling ledger; revert_ruling marks a ledger entry reverted; ruling_list reads the ledger newest-first. Undo the latest mutation with manage_history. activate/deactivate with key omitted act on the whole module. Use when: running, reverting, listing, activating, deactivating, toggling, verifying, recording or reading rulings, or player-authoring items. Do NOT use when: browsing the codex — use manage_codex (action: list).
Inputs: action (required), key, force, query, +10 more. Returns: text, status
manage_vowVow ManagementADestructive
Track narrative vows, quests, and obligations with milestones. set creates a vow and suggests a linked countdown whose ticks follow the difficulty track (troublesome 12, dangerous 8, formidable 4, extreme 2, epic 1; scope defaults to shared); accept the suggestion in the briefing to create it. milestone increments progress and any linked countdown; resolve and forsake close the vow as fulfilled or abandoned and keep the record. set identifies the vow with name; milestone, resolve, and forsake use vow_name. Mutations require the GM or Editor badge, persist to the Novel, and are undoable via manage_history (action: undo); resolve and forsake are terminal in the forward direction. Use when: setting, advancing, resolving, forsaking, or listing vows. Do NOT use when: starting a clock timer — use manage_countdown (action: set).
Inputs: action (required), name, scope, reason, +6 more. Returns: text, status
manage_worldWorld Model ManagementADestructive
Manage the world model — rooms, things, exits, and their spatial properties. create and update mutate in place and persist to the Novel; all mutations are audited; remove is permanent and requires re-creation; convert replaces the described subtree; generate creates rooms from installed table pools bounded by TTRPG_WORLD_GEN_MAX_ROOMS. create_exit links both directions; create_thing honors location_type only when location is set, and kind forces property defaults. There are no read-only actions here; inspect state with run_command (action: execute). Use when: creating, updating, removing, bulk-converting, or generating locations and objects. Do NOT use when: navigating the world — use run_command (action: execute); proposing objective-state transitions — use manage_causality; recording what an entity believes — use manage_belief.
Inputs: action (required), to, key, lit, +29 more. Returns: text, status
open_sessionOpen Play SessionADestructive
Open a play session by resuming a Novel, activating a badge, and returning a recap. novel selects the slug and badge the seat; both are optional and fall back to the active Novel and current badge. With no novel and no active Novel, it resumes the only Novel on the server (on a fresh install, the seeded starter), and refuses naming the available slugs when several exist. resume closes the current session window, switches the active Novel, and increments its session count; a badge change persists, is audited, and re-filters tools/list immediately; neither deletes prior Novel state. Session and badge changes are not undoable via manage_history. Use when: starting or resuming a session, especially after a restart. Do NOT use when: creating a Novel — use manage_novel (action: create); running a turn — use take_turn.
Inputs: badge, novel. Returns: text, status
resolve_mechanicResolve MechanicsADestructive
Resolve uncertain actions across the host's base mechanics: Fate Fudge dice, aspects, Fate points, and stress; Ironsworn momentum, moves, and progress; Forged action rolls, stress, trauma, and downtime; and generic ruleset table rolls. Rolls and state changes persist to the Novel and are audited; a roll with no following write is flagged as an uncommitted roll. Revert the most recent mutation with manage_history (action: undo). fate_roll uses dF, ironsworn_move compares an action die against two challenge dice, and forged_action_roll takes the highest of a d6 pool. Use when: resolving a Fate, Ironsworn, or Forged mechanic, or rolling on a ruleset generation table. Do NOT use when: resolving a ruleset skill check — use the bound ruleset's roll tools; managing vows — use manage_vow (action: set).
Inputs: action (required), op, adds, burn, +19 more. Returns: text, status
respond_decisionRespond to Workflow DecisionADestructive
Answer a pending workflow decision, atomically draining it and persisting the outcome to the Novel. option must match one of the emitted choices; 'cancel' aborts the workflow and restores its pre-workflow snapshot, while any applied outcome is not reversible. The drain is mutating and audited, and a second call with no pending decision returns STATE_CONFLICT. Use when: the server emitted a [NEED_INPUT] prompt and the caller must choose. Do NOT use when: no decision is pending — use set_badge or a state tool instead.
Inputs: option (required), decision (required). Returns: text, status
run_commandParser CommandADestructive
Run the spatial parser: execute a parsed command, resolve a movement outcome, or map an intent to tool calls. execute accepts free-form text, mutates world and entity state, persists, and is audited; a mistaken move is reversed by issuing the inverse command because no undo snapshot is taken. resolve computes the same movement without mutating, and suggest returns recommended calls without executing them; source and target apply only to perception queries. On a ruleset-bound Novel the parser is GM-only for navigation and mutation, while the Player badge keeps read-only perception commands. Use when: a player or narrator takes a physical action, needs a movement outcome without mutating, or wants intent mapped to tools. Do NOT use when: the GM creates or edits the model — use manage_world; durable world facts — use manage_lore.
Inputs: action, intent, source, target, +2 more. Returns: text, status
set_badgeSet Active BadgeADestructive
Switch the active badge to player, game_master, observer, or none (Editor), gating tool access server-side for the active Novel; always callable. The badge is per Novel and switching re-filters tools/list immediately, so a narrower badge can revoke tools mid-task and switching back restores them; badge changes are mutating session state, audited, and reversible by switching back. Use when: entering the story, spectating, or stepping away to edit. Do NOT use when: answering a pending workflow decision — use respond_decision.
Inputs: badge (required). Returns: text, status
take_turnTake Play TurnARead-onlyIdempotent
Resolve a player intent through the parser and mint a turn handle for the story record. intent is free text parsed by the command resolver; entity_id optionally scopes the parse to the acting entity. The turn is read-only and non-persistent: no Novel state is mutated; the handle is session-scoped, single-use, and consumed by manage_story (action: record), though recording without it still works. Repeated calls mint fresh handles rather than resuming the prior one. Use when: taking a turn before recording its outcome. Do NOT use when: resolving a specific combat round — use manage_combat (action: advance); rolling a ruleset check — use resolve_mechanic (action: roll).
Inputs: intent (required), entity_id. Returns: text, status
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 37 tools
The descriptions do a lot of work with explicit 'Use when / Do NOT use when' cross-references, which makes most boundaries traceable. However there are genuinely subtle overlaps across the knowledge cluster (manage_lore vs manage_belief vs manage_corpus vs manage_knowledge vs manage_note) and across session/lifecycle tools (manage_novel still carries export/import/archive actions that manage_archive duplicates). An agent must read carefully rather than rely on names alone to pick correctly.
Names follow a predictable verb_noun scheme throughout: a manage_<resource> family plus single-purpose verbs (set_badge, run_command, take_turn, open_session, close_session, resolve_mechanic, respond_decision). The only weakness is that manage_* names hide heavy action multiplexing, so the name alone doesn't reveal that a tool spans create/update/remove/list/undo.
37 tools is heavy, and several pairs look like they could be one surface (manage_context vs manage_diagnostics, manage_novel vs manage_archive, manage_codex vs manage_synthesis). The domain is genuinely large (world, NPCs, PCs, combat, lore, belief, causality, corpus, sessions, archives, rulesets), so each tool arguably earns its place, but this sits at the upper edge of reasonable.
Coverage is remarkably broad: full CRUD across world, characters, NPCs, factions, conditions, combat, vows, countdowns, story, plus lifecycle, archive, ruleset, and diagnostics surfaces. Minor gaps remain: manage_world has no read-only inspection (delegated to run_command), and several subsystems (causality, corpus, notes) explicitly opt out of undo, creating uneven recovery coverage.
Maintenance
Related MCP Connectors
D&D and TTRPG campaign manager for GMs: your AI reads and writes a live, typed campaign database.
Play and build AI RPG worlds: your agent tells the story, Worldtable keeps HP, items and the map.
A persistent tabletop RPG with an AI dungeon master. Agents and humans share one table.
Your tabletop campaign's journal, wiki, map, character sheets and combat tracker.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables creation and management of structured game worlds for text adventures and RPGs with character creation, world generation, and natural language interaction through AI integration.1MIT
- AlicenseCqualityBmaintenanceRPG game engine that lets AI run tabletop sessions without hallucinating mechanics. SQLite-backed persistence, D\&D 5e-style combat, procedural world generation, and deterministic dice.10022 npm46MIT
- AlicenseNot gradedqualityFmaintenanceEnables AI-powered campaign management for Foundry Virtual Tabletop through natural language, supporting multiple RPG systems with tools for quest creation, character management, combat resolution, and more.MIT
- FlicenseBqualityDmaintenanceAn MCP server that provides 18 tools for dice rolling, luck tests, character management, world state, combat, and save/load, enabling an AI game master to run a solo-play gamebook entirely through deterministic game logic.181-