clausewitz-mcp

An MCP server for Paradox Clausewitz/Jomini modding — EU5, EU4, Victoria 3, HOI4, CK3, Stellaris.

It gives an AI assistant the two things it needs to write Paradox script that actually loads: the game's own generated documentation for the exact patch you're modding, and a parsed index of the vanilla script tree to copy working patterns from.

No running game required. No DLL injection, no mod to install, nothing to attach to. It reads files, so it works on any OS regardless of what the game itself supports.

Why

Ask a model to write a Paradox event and you get script that looks right and silently does nothing. has_country_flagg instead of has_country_flag. An effect used in a trigger block. A localisation key that renders as raw text in game. A mod file that shadows a vanilla file nobody noticed. None of it errors — Paradox games fail quietly, which is the worst possible failure mode for a generated-then-forgotten mod.

The fix isn't a better prompt, it's grounding. Paradox games dump their entire scripting surface — every trigger, effect, scope, event target and modifier, with supported scopes — straight out of the binary via the script_docs console command. That output is exact and it's correct for your patch. This server parses it and puts it behind tool calls, so the model looks up add_prestige instead of remembering it.

CWTools already does excellent rules-based validation for Paradox script, and if you're hand-writing mods in VS Code you should use it. But it's a language server — an agent can't call it. This is the agent-facing equivalent, grounded in the game's dumps rather than hand-maintained rules, which is also why it works on a game as new as EU5 that has no rule definitions yet.

Install

uv sync

Register it with Claude Code:

claude mcp add clausewitz -- uv --directory /path/to/clausewitz-mcp run clausewitz-mcp

Setup

Point it at a vanilla game tree and your mod:

set_workspace(
  game_root = "/path/to/Europa Universalis IV",
  mod_roots = ["/path/to/mod/my_mod"],
  docs_dir  = "/path/to/Documents/Paradox Interactive/<game>/docs"
)

game_root and mod_roots are enough to start. docs_dir is what unlocks the good part.

Generating the docs dump

This is the step worth doing. In Steam, add -debug_mode to the game's launch options. Start the game, press ` to open the console, then run:

script_docs
dump_data_types

Output lands in Documents/Paradox Interactive/<game>/docs and .../logs/data_types. Point docs_dir at it.

Everything is copied from there, so you only need access to a machine that can run the game once — the server itself never launches it. If you mod EU5 from a Mac, generate the dump on a Windows box and copy the folder across.

Tools

Grounding

• lookup_script(name, kind) — a trigger/effect/scope/modifier from the game's own docs, verbatim, with supported scopes. Returns did_you_mean on a miss.
• search_script_docs(query, kind) — find the real name when you only know roughly what you want.
• docs_report() — what was ingested, so you can sanity-check the parse.

The script tree

• find_definition(name, category) — where a religion/building/event/scripted effect is defined, across vanilla and mods.
• search_definitions(query, category) — substring search over every defined name.
• find_usages(name) — real working examples of a pattern before you write your own.
• read_block(file, key_path) — one block out of a file instead of ten thousand lines.
• list_categories() — map of what lives where.
• lookup_localisation(key) — resolve a loc key to its text, file and line.

Authoring

• parse_script(text) — syntax-check a snippet before writing it, with exact line/column.
• validate_mod(checks) — run the checks below over your mod.

Validation

Every check is chosen to be low-noise — a reported problem should be a real one.

Check	Finds
syntax	Unclosed braces, dangling operators, malformed blocks, with line/column
unknown_script	Triggers/effects the game doesn't define, with did_you_mean
localisation	Referenced loc keys that resolve nowhere and will render raw in game
encoding	Localisation files missing the UTF-8 BOM the game silently requires
duplicates	The same object defined twice inside your own mod
shadowing	Mod files overriding vanilla files — usually intended, occasionally the bug

unknown_script requires a loaded script_docs dump. Without one it is skipped, not guessed at — inferring trigger validity without the game's signature list produces exactly the confident-but-wrong output this server exists to prevent.

Supported games

Auto-detected from the game root: EU5, EU4, Victoria 3, HOI4, CK3, Stellaris. The game/ subdirectory layout used by the newer Jomini titles is handled, as are both the localization and localisation spellings.

Anything else falls back to a generic adapter and still indexes common/ and events/, so an unrecognised or brand-new title works out of the box. Pass game= to override detection.

Status

v0.1. The parser, indexer and validation passes are tested against a fixture tree (tests/fixtures). The script_docs ingester is deliberately tolerant: entries keep their raw text verbatim and that is what tool calls return, with structured fields layered on best-effort, because the dump format drifts between games and versions. Run docs_report() after loading a real dump — if a large file reports one entry, the split heuristics missed and it's worth an issue with a sample.

License

MIT