Rhoiscribe

<div align="center">



<h1 align="center">RHoiScribe</h1>

Local MCP server for Hearts of Iron IV modding agents

简体中文 | Русский | 日本語






If RHoiScribe helps your modding workflow, starring the repository helps other HOI4 mod authors find it.

</div>

RHoiScribe gives Codex, Claude Code, and other MCP-compatible clients a local HOI4 modding reference layer plus tools for generating game-readable files.

The goal is simple: reduce wasted agent work caused by repeated web searches, stale assumptions, unsafe file paths, missing localisation encoding, and Paradox script that looks plausible but does not load in game.

<h2 align="center">Environment</h2>

<table align="center">
<tr>
<th align="center">Area</th>
<th align="center">Value</th>
</tr>
<tr>
<td align="center">Server transport</td>
<td align="center">MCP over stdio</td>
</tr>
<tr>
<td align="center">Implementation</td>
<td align="center">Rust 2024</td>
</tr>
<tr>
<td align="center">Build tool</td>
<td align="center">Cargo</td>
</tr>
<tr>
<td align="center">Primary clients</td>
<td align="center">Codex, Claude Code, MCP-compatible clients</td>
</tr>
<tr>
<td align="center">Runtime network</td>
<td align="center">Not required for bundled prompts, resources, and tools</td>
</tr>
<tr>
<td align="center">Modding target</td>
<td align="center">Hearts of Iron IV local mods</td>
</tr>
</table>

<h2 align="center">Who It Is For</h2>

- Mod authors who want AI agents to generate HOI4 content with better local context.
- Agent workflows that need prompts, resources, and tools available through one MCP server.
- Offline or low-search development sessions where the agent should read bundled HOI4 guidance before writing files.
- Teams that want generated content to follow predictable mod-root paths and reviewable output shapes.

<h2 align="center">What Agents Get</h2>

<h3 align="center">Prompts</h3>

Agents can use built-in prompts for:

- mod feature planning
- HOI4 script writing
- localisation writing
- GUI, GFX, and scripted GUI work
- generated-content review

Prompt names currently include hoi4_mod_planner, hoi4_script_writer, hoi4_localisation_writer, hoi4_gui_assistant, and hoi4_review.

<h3 align="center">Resources</h3>

Agents can read local resources instead of starting from a blank prompt:

- rhoiscribe://hoi4/latest-update
- rhoiscribe://hoi4/knowledge/catalog
- rhoiscribe://hoi4/knowledge/<topic_id>

The knowledge catalog is structured for agent use. Topics contain category, file types, tags, syntax examples, relationships to other HOI4 systems, validation guidance, and source references. Current coverage includes script basics, scopes, triggers, effects, modifiers, variables, MTTH variables, arrays, localisation, scripted localisation, scripted triggers/effects, GUI, scripted GUI, focuses, events, detailed on_action scope families, decisions, missions, ideas, characters, history, map files, technology, equipment, units, AI, diplomacy, game rules, defines, bookmarks, audio, and common loading errors.

<h3 align="center">Tools</h3>

Agents can call tools for repeatable generation and validation:

- generate_localisation_batch
- generate_focus_batch
- generate_event_batch
- generate_decision_batch
- search_hoi4_knowledge
- validate_hoi4_paths
- format_paradox_script

Generation tools support dry-run previews. In write mode they require an output_root and write paths relative to the target mod root.
Knowledge search returns matching topic IDs and MCP resource URIs for queries such as mtth variables, decision mission blocks, or on_actions FROM.FROM.

<h2 align="center">Quick Start</h2>

Build the server:

``powershell
cargo build --release
`

Use the release binary in your MCP client:

`text
<ABSOLUTE_PATH_TO_RHOISCRIBE>\target\release\rhoiscribe.exe
`

Linux and macOS clients should use:

`text
<ABSOLUTE_PATH_TO_RHOISCRIBE>/target/release/rhoiscribe
`

Run it directly only when you want to start the stdio MCP server by hand:

`powershell
.\target\release\rhoiscribe.exe
`

For Codex, Claude Code, and generic MCP configuration examples, see docs/client-setup.md.

<h2 align="center">MCP Surface</h2>

After the client starts RHoiScribe, the agent can use standard MCP methods:

- prompts/list
- prompts/get
- resources/list
- resources/read
- tools/list
- tools/call

Example resource read:

`text
rhoiscribe://hoi4/knowledge/scripted_gui.dynamic_lists
`

Example tools/call arguments for a localisation dry run:

`json
{
"language": "l_simp_chinese",
"file_stem": "common/autonomy/CHI",
"key_prefix": "CHI",
"entries": [
{
"id": "industrial_recovery",
"title": "Industrial Recovery",
"description": "Rebuild the industrial base."
}
],
"dry_run": true
}
`

Write mode adds a mod output root:

`json
{
"language": "l_simp_chinese",
"file_stem": "common/autonomy/CHI",
"entries": [
{
"id": "industrial_recovery",
"title": "Industrial Recovery"
}
],
"dry_run": false,
"output_root": "<MOD_OUTPUT_ROOT>"
}
`

The generated localisation file is written with UTF-8 BOM when write mode is enabled.
Use file_stem values such as common/autonomy/CHI, or complete mod-relative paths such as localisation/simp_chinese/common/autonomy/CHI_l_simp_chinese.yml, when the user's mod already organizes localisation in nested folders.

<h2 align="center">Output Model</h2>

Generation tools return structured file plans:

`json
{
"dry_run": true,
"files": [
{
"path": "localisation/simp_chinese/common/autonomy/CHI_l_simp_chinese.yml",
"encoding": "utf-8-bom",
"summary": "HOI4 localisation file"
}
],
"messages": ["dry-run only; no files were written"]
}
``
Paths are mod-relative and can use nested HOI4-readable folders when they match the user's workspace. Unsafe paths, drive-prefixed paths, and traversal attempts are rejected before writing.