llmdm

1# llmdm
2 
3A Go MCP server for D&D campaign state management, dice rolling, and session memory.
4 
5## What It Does
6 
7- Serves a Model Context Protocol (MCP) toolset over `stdio` or streamable HTTP.
8- Stores campaign data in per-campaign SQLite databases.
9- Tracks characters, plot events/hooks, world flags, roll history, checkpoints, and session summaries.
10- Generates session briefs and markdown recaps for fast DM context restoration.
11- Compresses end-of-session logs using Anthropic when available, with deterministic local fallback.
12 
13## Tech Stack
14 
15- Go `1.25.6`
16- MCP framework: `github.com/mark3labs/mcp-go`
17- Database: SQLite (`modernc.org/sqlite`)
18- Config loading: `.env` via `github.com/joho/godotenv`
19 
20## Repository Layout
21 
22```text
23cmd/server/main.go         # MCP server bootstrap, transport, tool registration/handlers
24config/config.go           # Environment config parsing and defaults
25internal/db/               # SQLite open/migrations and embedded schema
26internal/dice/             # Dice parser/roller and log models
27internal/memory/           # Data access layer for campaign entities
28internal/session/          # Brief rendering, recap rendering, event compression
29internal/dm/               # DM system prompt generation
30internal/types/            # Shared domain structs
31```
32 
33## Requirements
34 
35- Go `>= 1.25`
36- Optional: Anthropic API key for AI session compression
37 
38## Configuration
39 
40Environment variables (see `.env.example`):
41 
42| Variable | Default | Description |
43|---|---|---|
44| `ANTHROPIC_API_KEY` | _(empty)_ | Optional key for Anthropic summarization in `end_session` |
45| `DB_PATH` | `./data/campaigns` | Base directory for campaign database files |
46| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |
47| `MCP_TRANSPORT` | `stdio` | `stdio`, `http`, or `streamable-http` |
48| `HTTP_ADDR` | `127.0.0.1:8080` | Bind address for HTTP mode (loopback by default) |
49| `MCP_HTTP_ENDPOINT` | `/mcp` | MCP endpoint path in HTTP mode |
50| `READ_TIMEOUT` | `15s` | HTTP read timeout (also used for read header timeout) |
51| `WRITE_TIMEOUT` | `60s` | HTTP write timeout |
52| `IDLE_TIMEOUT` | `60s` | HTTP idle timeout |
53 
54### Example `.env`
55 
56```bash
57cp .env.example .env
58```
59 
60## Build, Test, Run
61 
62```bash
63make build
64make test
65make run
66```
67 
68Additional targets:
69 
70- `make lint` (requires `golangci-lint`)
71- `make build-linux` (cross-compile to `bin/dnd-mcp-linux`)
72- `make clean`
73 
74### Direct Run
75 
76```bash
77go run ./cmd/server serve
78```
79 
80Binary usage:
81 
82```bash
83./bin/dnd-mcp serve
84```
85 
86## Transport Modes
87 
88### 1) `stdio` (default)
89 
90Use when launching the server as a local MCP subprocess from an MCP client.
91 
92```bash
93MCP_TRANSPORT=stdio ./bin/dnd-mcp serve
94```
95 
96### 2) Streamable HTTP
97 
98```bash
99MCP_TRANSPORT=http HTTP_ADDR=127.0.0.1:8080 MCP_HTTP_ENDPOINT=/mcp ./bin/dnd-mcp serve
100```
101 
102Security note: HTTP transport does not provide built-in authentication. Keep `HTTP_ADDR` bound to loopback (for example, `127.0.0.1:8080`) unless you place it behind a trusted authn/authz proxy.
103 
104Health endpoint:
105 
106```bash
107curl http://127.0.0.1:8080/health
108```
109 
110MCP endpoint:
111 
112- `http://127.0.0.1:8080/mcp`
113 
114## MCP Client Examples
115 
116This repo includes `.mcp.json` for a local HTTP MCP server:
117 
118```json
119{
120  "mcpServers": {
121    "dnd-campaign": {
122      "type": "http",
123      "url": "http://127.0.0.1:8080/mcp"
124    }
125  }
126}
127```
128 
129### Claude (`stdio` transport)
130 
131Use this when configuring Claude to launch the MCP server as a local subprocess:
132 
133```json
134{
135  "mcpServers": {
136    "dnd-campaign": {
137      "command": "/absolute/path/to/bin/dnd-mcp",
138      "args": ["serve"],
139      "env": {
140        "MCP_TRANSPORT": "stdio"
141      }
142    }
143  }
144}
145```
146 
147## Available MCP Tools
148 
149### Dice
150 
151- `roll`
152- `roll_contested`
153- `roll_saving_throw`
154- `get_roll_history`
155 
156### Campaign Memory
157 
158- `create_campaign`
159- `save_character`
160- `update_character`
161- `get_character`
162- `list_characters`
163- `save_plot_event`
164- `list_open_hooks`
165- `resolve_hook`
166- `set_world_flag`
167- `get_world_flags`
168 
169### Session Management
170 
171- `start_session`
172- `end_session`
173- `checkpoint`
174- `get_session_brief`
175- `list_sessions`
176- `get_npc_relationships`
177- `export_session_recap`
178 
179## Persistence Model
180 
181Each campaign is persisted in its own SQLite file:
182 
183- `<DB_PATH>/<campaign_id>.db`
184 
185Core tables (auto-migrated on access):
186 
187- `campaigns`
188- `characters`
189- `plot_events`
190- `plot_hooks`
191- `world_flags`
192- `roll_log`
193- `sessions`
194- `checkpoints`
195 
196Schema source: `internal/db/schema.sql`.
197 
198## End-Session Compression Behavior
199 
200`end_session` always returns a summary:
201 
202- If `ANTHROPIC_API_KEY` is set and the API call succeeds, summary is model-generated.
203- If key is missing or API fails, server falls back to deterministic truncation + `OPEN HOOKS` scaffold.
204 
205This keeps workflows resilient in offline or degraded network/API conditions.
206 
207## Development Notes
208 
209- SQLite pragmas are enabled on open: foreign keys, WAL, and busy timeout.
210- Logging is structured JSON via `log/slog`.
211- Migrations are embedded and run automatically when opening campaign DBs.
212- Test suite uses race detector by default via `make test`.
213 
214## Troubleshooting
215 
216- `invalid MCP_TRANSPORT ...`: set to one of `stdio`, `http`, `streamable-http`.
217- `Failed to load config`: verify env values and `.env` formatting.
218- Empty/short summary in `end_session`: confirm `raw_events` is non-empty.
219- HTTP connection issues: verify `HTTP_ADDR`, `MCP_HTTP_ENDPOINT`, and that client URL matches exactly.
220