Building a Server - flukeatzerocool/holonovel GitHub Wiki

Building a Server

Tutorial. For builders. You have a tabletop RPG rulebook in Markdown (or a PDF you can convert). By the end, you'll have a running MCP server for your game — no hand-coding required.

What building means

Holonovel's specification (holonovel.md) is a build prompt for an AI. Point an AI at the spec, give it your rulebook, and the AI reads the mechanics, extracts the tables, and builds a complete MCP server. The spec is the permanent artifact; the server is disposable and rebuilt on demand.

Building involves these workflows:

Workflow	What it does	When you need it
Convert	Turn PDF/HTML/web scrape into clean Markdown. Validates structure.	Your rulebook isn't Markdown yet.
Build	Read the ruleset, discover mechanics, construct MCP server, verify.	You want a running game server.
Synthesis	Add community GM advice, lore templates, and action patterns — three independently removable tiers.	You want GM aids beyond the rulebook.
Update	Reconcile an existing server with a revised spec. Gap audit, implement, re-verify.	The spec changed and your server needs to follow.

The Build workflow supports a ruleset-free mode (§6.2) — a build that produces a world-model server with the full narrative scaffold, world model, parser commands, and badge gating, but no ruleset-specific mechanics. Use this when you want interactive fiction infrastructure without a rulebook.

Source: spec §6.1 (Workflow overview).

Prerequisites

Node.js 20+. The server runs on Node.
An AI with MCP client access. Opencode, Claude Desktop, Continue.dev, Cursor. Holonovel is built and tested with DeepSeek on Opencode Go.
The specification. Clone the repo or download holonovel.md — one file, the complete specification.
Your rulebooks. Markdown, PDF, HTML, or a URL. The spec can convert non-Markdown sources via the Convert workflow. No books handy? The spec's permissive catalog (Appendix I) lists 10 freely-licensed games the agent can scrape for you.

Source: README.md §1.

How it works

The Build workflow runs in six phases (§6.2–§6.7):

1. Intake (§6.2)

The AI asks you a batch of questions — which workflows to run, where your rulebook is, what to call the server, where to save data, which AI client you use. For ruleset-free builds, the ruleset questions are skipped. Answers go into DECISIONS.md. The AI confirms everything back before starting.

2. Verification Workflows G0a and G0b (§8)

G0a checks your rulebook is readable, well-formed, and structurally sound. Counts headings, tables, links. If the source isn't Markdown, the Convert workflow runs first (Appendix G). A viability pre-check warns if the ruleset has too few mechanical sections to produce a playable server.

G0b verifies MCP conformance — the running server against the Appendix D checklist. Every check must pass. This is a ruleset-facing workflow; ruleset-free builds skip ruleset-specific checks and report "no ruleset — skipped."

3. Discovery (§6.3)

The AI reads your rulebook, chunking dynamically based on structural boundaries (headings, tables, section density). For each chunk, it extracts: concepts (stats, conditions, statuses), entities (character types, monsters, NPCs), actions (resolution mechanics, commands, generation tables), tables (lookup and generation), the core resolution mechanic, player/GM roles, and guidance text.

Discovery produces two artifacts:

RULESET_MODEL.md — the semantic model with citations, confidence labels, and a defect log
ruleset_model.json — machine-readable model for verification and server code

The AI cross-checks 10 random items across both formats for consistency before proceeding.

4. Construction (§6.4)

Six dependency-ordered steps, each with an acceptance check:

MCP skeleton — initialize, tools/list, resources/list, prompts/list
Index — anchor tree, search, manage_ruleset (action: search) tool
Extraction pipeline — content-type detection, entity/model extraction
Tools — dice resolution, combat, character management, narrative tools
Prompts — badge_briefing, intro, session_zero, novel_setup, run_workflow
Client config — writes MCP client configuration, verifies key names against the target client's schema

The spec is copied into the server directory during construction, establishing the spec://build resource (REQ-105).

5. Verification and Convergence (§6.5)

The convergence loop measures quality metrics in two phases:

Phase 1 — extraction quality (confidence, extraction/conversion fidelity)
Phase 2 — construction quality (MUST coverage, mechanics fidelity, process compliance)

If thresholds aren't met, the AI iterates. A second model cross-audits the first when available — catching defects a single model would miss. Convergence results are cached so incremental updates can skip unchanged phases.

6. The Pattern Buffer (§6.6)

The Pattern Buffer runs adversarial sub-workflows — tool surface sweeps, combat endurance, badge boundary enforcement, corrupted state recovery, combat stress testing, and narrative lifecycle scenarios. Blocking sub-workflows must pass. Failures feed back into the convergence loop per REQ-208. After two stalled Pattern Buffer iterations, residual failures are logged as accepted limitations.

For ruleset-free builds, a separate Holonovel Pattern Buffer applies with its own sub-workflow set (§6.6, §8 G5).

What you get

A running MCP server. Plus four handoff artifacts (plus LICENSE.md):

RULESET_MODEL.md — what the AI extracted from your ruleset
DECISIONS.md — every decision the AI made during the build, why, and with what confidence
README.md — how to install and run your server
AGENTS.md — AI maintainer orientation for future updates

Source: spec §9.

After the build

Connect the server to your MCP client. The AI verifies the handshake. Open a fresh conversation. Your AI Game Master answers.

To verify the build independently — with a second AI from a cold checkout — see the Independent Verification workflow (spec §10).