8000 chore(repo): add handoff packet, remove verified dead code, correct CLAUDE.md by Mnehmos · Pull Request #88 · Mnehmos/mnehmos.rpg.mcp · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -69,3 +69,7 @@ Agents/

# Trace-MCP local config (regenerated by init_project, machine-specific)
.trace-mcp/

# Vendored agent skill packs (installed by `npx skills add`, machine-local)
.agents/
skills-lock.json
28 changes: 18 additions & 10 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,15 @@

## This Repository

The backend game engine for Quest Keeper AI. **34 MCP tools** (30 consolidated action-routed + 4 meta/event) for complete RPG mechanics, including LLM-driven NPCs via `agent_manage` and the Operator's constraint-perception lens via `perception_manage`.
The reference backend game engine. **35 MCP tools** (31 consolidated action-routed + 4 meta/event) for complete RPG mechanics, including LLM-driven NPCs via `agent_manage` and the Operator's constraint-perception lens via `perception_manage`.
**Philosophy:** "LLM describes, engine validates" - Database is source of truth.
**Status:** Alpha - 2214 tests passing, 136 test files, MCP Protocol fully integrated
**Status:** Alpha - 2216 tests passing (7 skipped), 141 test files, MCP Protocol fully integrated

## Who consumes this engine

`rpg-mcp-live` (repo `Mnehmos/rpg-mcp-live`, local checkout `F:\Github\rpg mcp live`) is the hosted web product and the **only** active consumer. It calls this engine **over HTTP** — see its `src/reference-engine-client.ts` and `REFERENCE_ENGINE_URL`. It is not a submodule and does not vendor this code, so the two repos are deployed separately and share no build step. Changing a tool's contract here is a breaking change for that service.

The Tauri desktop app (`mnehmos.quest-keeper.game`, "Lantern") still declares this engine as an `externalBin` sidecar, but it is **deprecated and unused** — do not treat its build or deploy steps as live.

## Bastion subsystems

Expand All @@ -25,7 +31,7 @@ npm run build:binaries # Create standalone executables
```
src/
├── server/
│ ├── consolidated/ # 29 action-routed tool handlers
│ ├── consolidated/ # 31 action-routed tool handlers (index.ts = registry)
│ ├── handlers/ # Extracted handler implementations (combat, spatial)
│ ├── index.ts # MCP server entry + transport setup
│ └── meta-tools.ts # search_tools, load_tool_schema
Expand All @@ -41,11 +47,11 @@ src/
│ ├── runtime/ # invoke + preflight + circuit + auto-on-turn hook
│ └── audit/ # Replay
├── storage/ # SQLite repos & migrations
├── schema/ # Zod validation (30 schemas — added schema/agent.ts)
├── schema/ # Zod validation (29 schemas, incl. schema/agent.ts)
├── utils/ # Action router, fuzzy matching
└── math/ # Dice, algebra, physics

tests/ # Mirror of src/ structure (136 files)
tests/ # Mirror of src/ structure (141 files)
docs/ # White paper, ADRs, LLM spatial guide
```

Expand Down Expand Up @@ -76,10 +82,12 @@ Do NOT ask permission for local commits. Just save the state.
4. Commit
5. Repeat

## Deploy to Frontend
## Shell note

After building binaries:
`bash` in this environment fails on startup (`fnm env` is not evaluated in the shell profile). Use **PowerShell** for git and npm work; the Bash tool errors out before running the command.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep the shell guidance portable

On Linux/macOS environments—including the review environment—Bash starts normally while PowerShell may not be installed, so this unconditional instruction prevents contributors and agents from running the documented commands. Scope this note to the affected Windows setup or document the fnm profile fix instead of requiring PowerShell.

Useful? React with 👍 / 👎.


```powershell
copy dist-bundle\rpg-mcp-win.exe "C:\Users\mnehm\Desktop\Quest Keeper AI attempt 2\src-tauri\binaries\rpg-mcp-server-x86_64-pc-windows-msvc.exe"
```
## Deploy

This engine deploys as its own service and is reached over HTTP by `rpg-mcp-live`. There is no copy-a-binary-into-the-frontend step anymore.

`npm run build:binaries` still produces standalone executables in `dist-bundle/` for local and MCP-client use. The old instruction to copy `rpg-mcp-win.exe` into the Quest Keeper Tauri app's `src-tauri/binaries/` is **obsolete** — that desktop app is deprecated and its target directory no longer exists.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Direct binary users to the actual output directory

When npm run build:binaries succeeds, esbuild.config.mjs writes the intermediate bundle to dist-bundle/server.cjs but invokes pkg with --output bin/rpg-mcp and reports the completed files from bin/. Saying the standalone executables are in dist-bundle/ therefore sends local and MCP-client users to the wrong directory.

Useful? React with 👍 / 👎.

198 changes: 198 additions & 0 deletions docs/hosted-handoff/ADRs.md
< 10BC8 /tr>
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
# Architecture Decision Records

These decisions are proposed for the hosted product handoff. They do not silently ratify or replace existing repository ADRs. A maintainer should mark each record Accepted, Rejected, or Superseded during implementation kickoff.

## ADR-H01: Launch as a text-first single-player web game

**Status:** Proposed
**Date:** 2026-08-06

### Context

The engine contains more simulation surface than a first subscription product needs. A full VTT would introduce map rendering, token state, multiplayer synchronization, and a larger frontend before the core DM loop is validated.

### Decision

Launch with a browser narrative log, freeform action composer, character status panel, and server-side rules resolution. Support one player-owned campaign by default.

### Consequences

- Faster path to a usable paid product.
- The core value proposition is measurable.
- Existing map and spatial code remain available for later work.
- Tactical players may find the first release intentionally lightweight.

### Rejected alternatives

- Full PixiJS/Three.js VTT at launch.
- Multiplayer-first architecture.
- Rebuilding the existing Tauri client as the web frontend.

## ADR-H02: Open5e is research-only

**Status:** Proposed
**Date:** 2026-08-06

### Context

The local Open5e MCP is useful for looking up monsters, classes, spells, equipment, and source documents. It is not the RPG engine and should not become a live gameplay dependency.

### Decision

Use Open5e MCP during development to verify and transcribe a deliberately selected ruleset. Store reviewed, engine-native data in the repository. Do not ship an Open5e adapter, Open5e API client, live cache, or MCP subprocess in the hosted request path.

### Consequences

- Gameplay remains available if Open5e is unavailable.
- Runtime behavior is deterministic and version-controlled.
- Rules updates require an intentional transcription review.
- The project owns the responsibility of recording source and license attribution.

### Rejected alternatives

- Fetching monster and spell definitions on every turn.
- Letting the LLM query Open5e directly during play.
- Mixing Open5e 2014 and 2024 records based on search defaults.

## ADR-H03: Pin the first ruleset to the 2014/SRD-compatible engine behavior

**Status:** Proposed
**Date:** 2026-08-06

### Context

The current engine already models familiar 2014-style concepts such as spell slots and existing class progression. Open5e can return multiple content versions for similar names.

### Decision

The first shipped ruleset is explicitly identified as 2014/SRD-compatible. Every transcribed record carries its source document, slug, and review date. A future 2024 ruleset is a separate compatibility target, not an automatic replacement.

### Consequences

- Fewer hidden rules conflicts.
- Tests can assert precise source fixtures.
- Future rulesets require explicit adapters or separate data namespaces.

## ADR-H04: The server is authoritative for mechanics

**Status:** Proposed
**Date:** 2026-08-06

### Context

The LLM is good at language, interpretation, and narrative, but it is not a reliable state machine. Letting it decide outcomes would undermine player trust and make support/debugging difficult.

### Decision

The server interprets candidate actions, applies rules, rolls dice, persists an event, and passes the result to the LLM for narration.

### Consequences

- Players can inspect outcomes.
- Events can be replayed and audited.
- LLM provider changes do not change mechanical history.
- The action interpreter and rules facade become important test surfaces.

## ADR-H05: Web and MCP are separate adapters over a constrained domain boundary

**Status:** Proposed
**Date:** 2026-08-06

### Context

The existing MCP registry is broad and currently coupled to global storage and module-level state. A browser product needs a smaller authenticated API.

### Decision

Retain MCP as a compatibility adapter. Add a hosted HTTP adapter that calls explicit domain services. Do not expose the entire MCP registry through HTTP.

### Consequences

- Existing MCP users are not needlessly broken.
- Hosted authorization can be designed around player actions.
- Domain facades must be extracted before broad reuse is safe.

## ADR-H06: Hosted state is isolated from legacy global SQLite state

**Status:** Proposed
**Date:** 2026-08-06

### Context

The current database singleton, default session, and direct handler queries are not a safe multi-user foundation. Retrofitting ownership into every existing table is larger than the first product slice.

### Decision

Use a separate hosted database file and hosted tables keyed by verified user ID and campaign ID. Reuse pure rules services where safe; do not reuse global state implicitly.

### Consequences

- The private beta can ship with a clear isolation boundary.
- Existing local MCP behavior remains stable.
- Some data duplication exists until a later domain migration.
- A future Postgres migration can target the hosted schema independently.

## ADR-H07: Clerk is identity; Stripe webhooks are entitlement

**Status:** Proposed
**Date:** 2026-08-06

### Context

Authentication and payment state have different sources of truth. The browser must not be trusted to report either one.

### Decision

Clerk verifies identity and supplies the user ID. Stripe Checkout creates subscriptions. Verified, idempotent Stripe webhooks update the local entitlement record. The browser return URL never grants access by itself.

### Consequences

- Authentication and billing responsibilities are clear.
- Webhook replay and delayed events must be handled.
- Test mode and production mode need separate configuration.

## ADR-H08: Railway first; SQLite volume for private beta

**Status:** Proposed
**Date:** 2026-08-06

### Context

The user already uses Railway. Postgres and Redis would increase operational complexity before demand is known.

### Decision

Deploy one Railway service with a persistent volume and a separate hosted SQLite database for the private beta. Define migration triggers for Postgres rather than pre-building the migration.

### Migration triggers

- More than one application instance is required.
- Database locking becomes visible in user-facing latency.
- Restore testing cannot meet the recovery target.
- Campaign volume or analytics needs exceed the single-volume model.

## ADR-H09: No live Open5e content in production

**Status:** Proposed
**Date:** 2026-08-06

### Context

Live content requests create availability, version drift, attribution, and latency risks. They also make a player's outcome depend on an external service.

### Decision

Production uses only reviewed rules data shipped with the engine. Open5e is not in health checks, gameplay requests, or DM tools.

## ADR-H10: Defer multiplayer and the VTT

**Status:** Proposed
**Date:** 2026-08-06

### Context

Multiplayer and tactical maps change the aggregate, realtime, authorization, and frontend requirements substantially.

### Decision

Treat multiplayer campaigns and tactical visualization as post-MVP epics. Preserve campaign ownership and event boundaries so they can be added later.
Loading
Loading
0