ck3-strategy-advisor: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A local stdio Model Context Protocol server that reads the player's latest Crusader Kings III save and exposes their strategic situation to Claude as curated, read-only tools (realm_overview, military, succession, diplomacy, vassals, titles, factions, expansion, find_character, character, foreign_realm). It never modifies the save or the game. See README.md for install/config/usage.

Commands

npm install
npm run build        # tsc -> dist/  (the registered MCP entry is dist/index.js)
npm run dev          # run the server from source via tsx (no build step)
npm test             # vitest run (whole suite)
npm run test:watch
npx vitest run tests/military.test.ts   # single test file

There is no lint step. The build itself (tsc with strict: true) is the type gate.

Architecture

The data flows in one direction, save file → markdown tool output:

1. source.ts (SaveFileSource) — finds the newest parseable (text) .ck3 in the save dir: sorts candidates by mtime (ignoring last_save.ck3), then reads each one's 256-byte header newest-first and returns the first whose detectFormat is "text". This skips CK3 autosaves (always binary token format, regardless of Ironman) and Ironman saves, which are usually the newest file and would otherwise shadow a readable manual save. Falls back to the newest overall if none are text, so the binary/Ironman message still surfaces.
2. envelope.ts (extractGamestate) — a .ck3 is SAV-header + an embedded PKZIP. Detects Ironman vs text saves, unzips, returns the gamestate entry as a Buffer. Ironman detection is by the plaintext meta_data={ marker in the first 256 bytes, NOT by PK presence — both formats embed a zip. Ironman throws IronmanError (surfaced as a friendly message, not an error).
3. parser.ts (queryGamestate) — wraps a lazily-initialized jomini WASM parser singleton. Gives extractors a Query with .at(jsonPointer).
4. snapshot.ts (buildSnapshot) — parses once and eagerly runs every extractor inside a single queryGamestate pass, producing a Snapshot (overview + military + succession + diplomacy + factions + vassals + expansion). One parse feeds all tools.
5. cache.ts (SnapshotCache) — keyed by path:mtimeMs. Returns the cached Snapshot if the newest save is unchanged; coalesces concurrent builds of the same save into one parse; serves the last good snapshot on a transient/mid-write read failure. Also lazily materializes the gamestate as text once per save (rawGamestateText) for find_character's substring search, and exposes query() for tools that need a fresh jomini pass beyond the snapshot (e.g. character).
6. extract/*.ts — pure functions (q: Query, loc: Localizer, ...) => Info. No I/O, no MCP. This is where save-field knowledge lives.
7. tools/*.ts — each registerXTool(server, cache) registers one MCP tool: pull from cache.get() (or cache.query()), format markdown, return it. tools/index.ts wires them all up via registerAllTools.