ChatQuest AI

Play a text adventure with an AI, save your progress, and try another choice on a separate timeline.

繁體中文 · Try the story · Connect ChatGPT, Claude or Grok · Playtest transcript · Build a world

Have a coding agent set it up: agent installation guide.

ChatQuest AI keeps the inventory, rolls, story progress and each character's knowledge in local SQLite. The model reads those records through MCP before continuing a scene. That gives it something to check when a conversation gets long and details start drifting.

You can also go back to a saved decision and play a different route without overwriting the first one. JSON world packs let you write your own setting. The server provides 17 tools and has no web UI or model API calls; you bring a chat client, with its own account and hosting requirements.

The bundled demo exercises this flow with scripted prose:

PLAYER  “Read the dispatch alone. Don't tell Jun what I find yet.”
MODEL   prepare_turn → roll_check → commit_turn
ENGINE  Saves the roll and records the finding for the player only.
RETRY   Same request + same key → same receipt, no duplicate cost.
IF      “Take the bridge instead.” → fork an earlier decision, main untouched.

Why an engine behind the chat?

An item you've spent should stay spent. A secret you found alone shouldn't appear in an absent character's memory. ChatQuest AI stores the records for those checks. The model still has to use them correctly when writing the scene.

Related MCP server: Fantasy Gamebook Engine

Try it in five minutes

If you want an agent to install and configure it, give it this prompt:

Install ChatQuest AI for my MCP client using https://raw.githubusercontent.com/KinsonLai/chatquest-ai/main/docs/agent-install.md . Preserve my existing saves and other MCP settings, test the installation with a disposable database, and report any remaining client login or restart step.

Requires Node.js 24+ and npm. Try the story without cloning the repo:

npx --yes --package=https://github.com/KinsonLai/chatquest-ai/releases/download/v0.4.0/chatquest-ai-0.4.0.tgz chatquest --demo

The package downloads from GitHub Releases; it isn't published on the npm registry yet.

The Last Ferry starts at a quay before a flood. The demo plays five scenes, then tries an IF branch. A failed repair uses up supplies; a failed landing causes an injury and sends you to the high bridge. The prose is prewritten, while MCP calls, dice, saves and knowledge checks run against a real server. It doesn't call a model. For a model-run session, see the playtest transcript and findings, including submitted scenes and receipts.

For MCP clients, omit --demo:

npx --yes --package=https://github.com/KinsonLai/chatquest-ai/releases/download/v0.4.0/chatquest-ai-0.4.0.tgz chatquest

This waits for a stdio client. Add --http to serve http://127.0.0.1:3333/mcp, or --help for options. Use an absolute --db path in client settings to resume the same save. Connection instructions for ChatGPT, Claude and Grok →

To work from source:

git clone https://github.com/KinsonLai/chatquest-ai.git
cd chatquest-ai
npm ci
npm run demo

The demo uses a separate in-memory database, so it leaves your campaign save alone. Dice results vary.

Then connect a client using stdio:

{
  "mcpServers": {
    "chatquest": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=https://github.com/KinsonLai/chatquest-ai/releases/download/v0.4.0/chatquest-ai-0.4.0.tgz",
        "chatquest"
      ],
      "env": { "CHATQUEST_DB": "/absolute/path/to/my-adventure.sqlite" }
    }
  }
}

Use an absolute executable path if your client cannot find npx. On Windows, use forward slashes or escaped backslashes in JSON paths. This is a local stdio configuration; ChatGPT and Grok web need the remote/tunnel setup in the client guide.

Ask your client:

Read ChatQuest AI's operating guide and workflows. Create a new campaign using the ferry template, from the beginning. Let me choose Robin's actions, keep each character's knowledge separate, and confirm saves only from committed receipts.

For an existing campaign, list campaigns and branches instead of creating a new one.

Recoverable server errors include a retry instruction for the chat client: check for an existing receipt, then retry the original authorized call once without asking you to repeat your prompt. This is client guidance, not an enforced hook, and it cannot handle a request blocked before it reaches the server.

To reduce waiting between scenes, prepare_turn can include checks and a world preview when their inputs are already known. That lets those scenes use two calls rather than four, with the same commit validation. See examples and local measurements; dependent checks still need separate calls.

Four original starting worlds

The four original packs are included under MIT. Pass your own pack through create_campaign.world, or add story text you have permission to use through ingest_canon. See the pack guide.

HTTP without a web app

npm run start:http

This listens at http://127.0.0.1:3333/mcp by default. It serves MCP requests, with no dashboard at /. Set CHATQUEST_TOKEN to require a bearer token, including for local requests.

For a remote server, bind --host 0.0.0.0, set a random token of at least 24 characters and set CHATQUEST_ALLOWED_HOSTS to your public hostname. Put TLS and request limits in front of it. Each HTTP server belongs to one owner: every authenticated connection can access that database. Don't share a token between unrelated users.

docker build -t chatquest-ai .
docker run --rm -p 127.0.0.1:3333:3333 \
  -e CHATQUEST_TOKEN -v branchwright-data:/data chatquest-ai

The Docker entrypoint binds all container interfaces, so a token is mandatory. Export it in the calling environment before running the command. The host port above remains loopback-only.

Tests use the official MCP SDK over stdio and HTTP. The client guide covers Claude's local configuration, ChatGPT's Secure MCP Tunnel route, remote HTTP and authentication requirements. OAuth is not built into this release. Account-level ChatGPT/Claude/Grok integration remains unverified. Deployment and security →

The small game loop

flowchart LR
    A[Player action] --> B[prepare_turn]
    B --> C{Meaningful uncertainty?}
    C -->|Yes| D[roll_check]
    C -->|No| E[Model writes scene]
    D --> E
    E --> F[commit_turn]
    F --> G[SQLite revision + receipt]
    G --> H[Next choice or historical IF]

Use read_guide(section="tools") for the current schemas of all 17 tools. These come from the registered tool definitions, so you can check what the installed server accepts. See workflows and recovery.

Limits

v0.3 is an early release for one owner per database. A model can still pick an unfair difficulty, leak a secret in dialogue or write a character badly. The skill gives it instructions; it doesn't enforce every sentence or override platform safety checks. The playtest report includes both database checks and a prose-review finding.

• Retrieval uses local lexical search. It has no neural embeddings and can miss relevant passages.

• Packs define the difficulty names and DCs. Rolls use d20; other tabletop rulesets aren't implemented.

• World events use a seeded clock, chances and cooldowns. They don't simulate a full society or economy.

• SQLite files contain plaintext story and save data. Back them up and keep them out of Git.

• No branch merge, save import, multiplayer isolation, automatic LLM calls or arbitrary executable plugins in this release.

• Keep imported canon separate from character knowledge. Importing a novel also doesn't grant permission to redistribute it.

Upgrading from Branchwright

The project became ChatQuest AI in v0.3.0. The package is chatquest-ai and the command is chatquest; branchwright still works as an alias. CHATQUEST_DB, CHATQUEST_TOKEN and CHATQUEST_ALLOWED_HOSTS take precedence over the old BRANCHWRIGHT_* variables. If you haven't set the new variables, your old settings still work.

Keep your existing absolute --db path and Docker data volume. The default is still .branchwright/state.sqlite in the working directory, and saves need no migration. Campaign and branch IDs, receipts, tool names and branchwright:// resource URIs are unchanged. We also kept the original operating-skill text and folder: pending turns use that text for validation, so renaming it would invalidate them. Refresh connector metadata to see the new server name. Old release notes and playtest receipts keep their original names.

Develop

npm ci
npm test
npm run format:check
npm run check:release
npm run check:package
npm run demo
npm pack

Tests include complete success and failure story routes, CLI startup, disk reopening, scoped proofs, historical forks, NPC knowledge snapshots, resource rollback, fixed rolls, adjudication recovery, canon immutability and actual MCP transports. CI targets Linux, Windows and macOS on Node 24. See playtest evidence for the model-led session and the remaining client verification gaps.

Make the next world

You can start with an original world pack, a reproducible model failure or a CJK retrieval test case. A new rules adapter should include tests for its invariants. Include sources and permissions for any setting you contribute.

If you find it useful, a star is welcome. See CONTRIBUTING.md for bug reports and contributions.

Other projects in this area include text-adventure-handler-mcp and dmcp. ChatQuest AI was implemented independently and is not affiliated with those projects or any model provider.