RHoiScribe
czxieddan/RHoiScribe
Servidor MCP para modding Hearts of Iron IV com referência local e geração de código
Ver no GitHubServidor MCP local especializado em modding para Hearts of Iron IV. Fornece prompts contextualizados, recursos de referência e ferramentas para gerar arquivos válidos em jogo, eliminando buscas repetidas e erros de sintaxe ao usar agentes de IA.
Instalação
npx convez-ai czxieddan/RHoiScribe1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Desenvolvimento de mods para Hearts of Iron IV com assistência de agentes IA
- Geração de scripts, localização e GUI seguindo padrões válidos do jogo
- Fluxos de trabalho offline com referência local integrada ao Claude Code
Veredito

Ferramenta altamente especializada e bem executada para um nicho específico. Reduz drasticamente erros de sintaxe em geração automática de código HOI4 ao fornecer contexto local estruturado — ideal para modders que usam agentes IA, mas inútil fora desse ecossistema.
README
A tradução para o português deste README ainda está na fila.
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.
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.
- 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.
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.
Agents can read local resources instead of starting from a blank prompt:
rhoiscribe://hoi4/latest-updaterhoiscribe://hoi4/knowledge/catalogrhoiscribe://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, unique identifier checks, 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, game path discovery, debug launch checks, error log triage, and common loading errors.
Agents can call tools for repeatable generation and validation:
generate_localisation_batchgenerate_focus_batchgenerate_event_batchgenerate_decision_batchsearch_hoi4_knowledgescan_unique_identifiersdiscover_hoi4_environmentvalidate_hoi4_debug_runclassify_error_logvalidate_hoi4_pathsformat_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.
Identifier scanning checks batches of proposed new IDs against structured HOI4 definitions and reports duplicates, existing output files, and replace_path risks.
Environment discovery finds the HOI4 install through Steam metadata first, then optional folder scanning, and reads launcher-settings.json for the document data path, hoi4.exe path, logs/error.log path, and game version.
Debug-run validation checks the document map, localisation, and history folders, active launcher mod descriptors, the current playset, dependency descriptors, and the workspace mod path before an optional hoi4.exe -gdpr-compliant -debug_mode launch.
Error-log classification groups error.log lines by likely HOI4 subsystem and links them back to changed paths when the agent has a diff or generated file list.
HOI4 syntax and modding practice change over time. If you find bundled knowledge that is outdated, incomplete, or wrong, please open an Issue with the game version, file type, source reference, and a minimal example when possible.
Pull requests are welcome for expanding the knowledge catalog, improving examples, or building more MCP tools for generation, validation, project scanning, and other agent workflows.
Download a prebuilt binary from GitHub Releases:
- Windows:
rhoiscribe-windows-x86_64.exe - Linux:
rhoiscribe-linux-x86_64 - macOS:
rhoiscribe-macos-universal
For agents that can read a Skill folder, download the matching Skill package:
- Windows:
rhoiscribe-skill-windows-x86_64.zip - Linux:
rhoiscribe-skill-linux-x86_64.zip - macOS:
rhoiscribe-skill-macos-universal.zip
Unzip it into a stable folder. The package contains SKILL.md and the matching executable, so an agent can use RHoiScribe directly even when you do not want to configure an MCP server.
Keep the downloaded file in a stable folder. On Linux and macOS, run chmod +x on the downloaded file if the system asks for executable permission.
Build from source only when you want a local Cargo build:
cargo build --release
Source builds place the executable under <ABSOLUTE_PATH_TO_RHOISCRIBE>/target/release/.
Print the command path to use in your MCP client:
.\rhoiscribe-windows-x86_64.exe --print-command
Linux and macOS users can run the same option on their downloaded file:
./rhoiscribe-linux-x86_64 --print-command
./rhoiscribe-macos-universal --print-command
Run it directly only when you want to start the stdio MCP server by hand:
.\rhoiscribe-windows-x86_64.exe
./rhoiscribe-linux-x86_64
./rhoiscribe-macos-universal
Skill packages can also be called directly for JSON output:
.\rhoiscribe-windows-x86_64.exe --skill list-tools
.\rhoiscribe-windows-x86_64.exe --skill list-resources
.\rhoiscribe-windows-x86_64.exe --skill list-prompts
.\rhoiscribe-windows-x86_64.exe --skill read-resource "rhoiscribe://hoi4/latest-update"
./rhoiscribe-linux-x86_64 --skill call-tool "search_hoi4_knowledge" '{"query":"on_actions ROOT FROM"}'
For Codex, Claude Code, and generic MCP configuration examples, see docs/client-setup.md.
After the client starts RHoiScribe, the agent can use standard MCP methods:
prompts/listprompts/getresources/listresources/readtools/listtools/call
Example resource read:
rhoiscribe://hoi4/knowledge/scripted_gui.dynamic_lists
Example environment discovery call:
{
"scan_fallback": true
}
Example debug preflight call:
{
"game_path": "<HOI4_GAME_PATH>",
"document_path": "<HOI4_DOCUMENT_PATH>",
"workspace_mod_path": "<MOD_OUTPUT_ROOT>",
"launch": false
}
Example error log classification call:
{
"error_log_path": "<HOI4_DOCUMENT_PATH>/logs/error.log",
"changed_paths": ["common/national_focus/CHI.txt"],
"limit": 5
}
Example tools/call arguments for a localisation dry run:
{
"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:
{
"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.
Generation tools return structured file plans:
{
"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.