klimpaskov-hoi4-toolsCAUTION
HOI4 modding tools for agents: local references, visual previews, focus trees, interfaces and maps.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
Give your coding agent one MCP server for Hearts of Iron IV modding. It can find local documentation and vanilla examples, inspect a mod, render its trees and interfaces, compare source behavior, and make focused edits to focus trees, GUIs and maps. The pictures below use real Chaos Redux or installed HOI4 files; click any image for the full-size version.
Get started
Install Node.js 22.19+ in the Node 22 line, or Node.js 24, then run:
npm install --global hoi4-agent-tools hoi4-agent-tools-setup --print-client-config
Add the printed configuration to your MCP client and open your mod as its workspace. The install is about 280 MiB, because npm fetches the image library's binaries for every platform to keep each install identical. Keep an installed copy of HOI4 available for vanilla examples, artwork and fonts. The setup guide covers connecting your agent and choosing game or mod paths.
Ask your agent to find a focus tree and render it, locate the installed documentation for a script command, or preview a scripted GUI at different UI scales. The examples below show the results.
Examples
Focus trees · Technology folders · Interfaces · Maps and events · Local rules and AI · All tools
Focus trees and alternative prerequisites
8ebcf0b2174eOBSERVED · 2026-10-11Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add hoi4-agent-tools -- npx -y [email protected]
Exposed tools (43)
37 read · 6 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
chaosx.focus_country_assets | read | Private ChaosX Discord integration endpoint. Returns country flags and leader portraits to accompany a focus-tree raster; it is not intended for coding-agent workflows. |
chaosx.visual_revision | read | Private ChaosX cache-coherency endpoint. Computes exact scripted-GUI source revisions without rendering PNG artifacts. |
fixture.long | read | |
fixture.stream | read | |
fixture.wait | read | |
hoi4.decision_inspect | read | Inventory decisions or evaluate declared actor and target scenarios for gates, payment, lifecycle, and proposed-source differences. Full evidence is linked. |
hoi4.event_compare | read | Compare cached, artifact-backed, current, or in-memory proposed event graphs, optionally selecting one downstream chain. Full changes and explicit selection coverage are resources. |
hoi4.event_inspect | read | Scan, find roots, trace, explain paths, inspect state flow, lint, or assess impact. Full source-linked reports are resources. |
hoi4.event_render | read | Render deterministic JSON, SVG, PNG, and optional HTML for an event-chain view. Complete artifacts retain source links. |
hoi4.focus_inspect | read | Inspect focus trees and continuous palettes, including source references, diagnostics, and layout. |
hoi4.focus_raster | read | Render focus PNG with decoded source icons; also returns HTML, SVG, and JSON. |
hoi4.focus_render | read | Render focus HTML, SVG, JSON, and source maps. Use hoi4.focus_raster for decoded icons and PNG. |
hoi4.focus_rewrite | write | Create or compact a focus tree or palette from a complete plan. Use treeId for existing trees and createIfMissing for new files. |
hoi4.gui_inspect | read | Inspect GUI sources and scenarios. |
hoi4.gui_render | read | Render GUI states, resolutions, scenarios, hierarchy, comparisons, and diagnostics. |
hoi4.gui_rewrite | write | Apply one validated source, helper, or exact-patch GUI package. Text dependencies use additionalFiles; binary art stays workspace-referenced. |
hoi4.impact_inspect | read | Trace definitions and consumers of symbols or changed source across HOI4 systems. Proposed sources are analyzed in memory; full revision-bound evidence is linked. |
hoi4.job_cancel | read | Durably request cancellation of an authorized background operation. Completed results remain completed. |
hoi4.job_inspect | read | Inspect a durable background operation. A completed job returns the original tool result; active and terminal non-result states return bounded status evidence. |
hoi4.map_inspect | read | Validate and inspect the complete map, or use lookupOnly for bounded coordinate and entity lookups. |
hoi4.map_render | read | Render searchable full-map PNG, JSON, and HTML, or a reusable source-coordinate tile. |
hoi4.map_rewrite | write | Apply map creation, edits, and ID swaps with visual and semantic evidence. |
hoi4.mechanic_test | read | Interpret bounded, source-backed effect steps on isolated declared state and check typed invariants. Unsupported effects remain unresolved; no game or mod source is changed. |
hoi4.package_check | read | Check a declarative package manifest against active definitions, references, registrations, localisation, assets, and required suite cases. |
hoi4.probability_analysis | read | Plan one source-linked AI, MTTH, random, or declared-pool analysis and return to the owning modding workflow. |
hoi4.probability_compare | read | Compare sources or declared pools under identical scenarios. |
hoi4.probability_evaluate | read | Evaluate weights and probabilities under explicit scenarios. |
hoi4.probability_inspect | read | Discover weighted adapters, candidates, provenance, and required inputs. |
hoi4.probability_render | read | Render retained probability analysis as deterministic resources. |
hoi4.probability_sequence | read | Analyze a manifest-declared dynamic weighted sequence. |
hoi4.probability_simulate | write | Run seeded simulations with distributions and confidence intervals. |
hoi4.probability_sweep | read | Evaluate declared ranges, breakpoints, and rank reversals. |
hoi4.reference_context | read | Return a compact bundle of offline wiki and installed game documentation citations for a modding surface. |
hoi4.reference_read | read | Read at most 80 lines from one revision-bound local documentation section. |
hoi4.reference_search | read | Search bounded, cited sections of the configured offline wiki and installed game documentation. |
hoi4.scenario_test | write | Run named inline or workspace-relative cases through bounded typed read-only domain services. Large suites return an authenticated continuation. |
hoi4.script_validate | write | Check an effect or trigger snippet (source, kind, scope) or a whole mod file (path) for syntax, native command kinds and scopes against cited installed documentation. Unknown helpers and native argument blocks remain explicit. |
hoi4.source_lookup | read | Find exact Clausewitz definitions and usages; navigate nested keyPath blocks or list bounded child structure with view=structure. Or pass path and line to get the definitions and keyPath containing that line. |
hoi4.tech_compare | read | Compare cached, resource-backed, current, or proposed source graphs without writes. |
hoi4.tech_inspect | read | Scan, discover folders, trace, explain, inspect unlocks or bonuses, lint, and assess impact. |
hoi4.tech_render | read | Render source-linked JSON, SVG, PNG, and optional HTML technology views. |
server-status | read | Live server processes sharing this server state, with memory, last client activity and execution limits. |
test.inspect_auth_context | read |
Trust audit
CAUTIONgrade C · trust 73/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (5 observation(s))
- Network
- declared (5 observation(s))
- Shell
- none-observed
- Dependencies
- pinned
- Secrets in source
- found
Findings (25)
const token = 'limit-test-secret-that-is-at-least-thirty-two-characters';
const secret = 'test-secret-that-is-at-least-thirty-two-characters';
const token = 'stream-test-secret-that-is-at-least-thirty-two-characters';
const token = 'concurrency-test-token-at-least-thirty-two-characters';
provinces.bmp
.prettierignore
.prettierrc.json
import { artifactResourceDefinition, readArtifactResource } from '../../core/artifact-resource.js';import type { CoreEngine } from '../../core/engine.js';import { readServerStatus, serverStatusResource } from '../../core/server-status-resource.js';import type { OperationContext } from '../../core/operation-context.js';import { ServiceError } from '../../core/result.js';const publicResource = 'http://127.0.0.1/mcp';
const metadataUrl = 'http://127.0.0.1/.well-known/oauth-protected-resource/mcp';
issuer = `http://127.0.0.1:${jwksAddress.port}/`;localUrl = `http://127.0.0.1:${address.port}/mcp`;localUrl = `http://127.0.0.1:${address.port}/mcp`;l_english:
l_english:
l_english:
l_english:
l_english:
- Streamable HTTP uses one `/mcp` POST/GET endpoint plus DELETE for session termination. It is stateful to support progress, cancellation, server notifications, SSE resumption, and secure random sessi
docs/images/comparisons/chemical-historical-mcp.png
docs/images/comparisons/chemical-recent-ingame.png
Gates applied: no_behavioural_pass.
8ebcf0b2174efull audit observations/trust-audit/mcp-server/klimpaskov__hoi4-agent-tools.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-11 | 8ebcf0b2174e | CAUTION | C | 73 | first audit |
Questions
What is the klimpaskov-hoi4-tools MCP server?
HOI4 modding tools for agents: local references, visual previews, focus trees, interfaces and maps.
What tools does klimpaskov-hoi4-tools expose?
43 in total: 37 read-only, 6 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is klimpaskov-hoi4-tools safe to connect to an agent?
With care. The audit graded it C (73/100) and found 25 things worth knowing before you trust this server, listed below with the exact line each was found on.
What credentials does klimpaskov-hoi4-tools need?
It reads GH_TOKEN, GITHUB_TOKEN, HOI4_AGENT_ALPHA_TOKEN, HOI4_AGENT_BETA_TOKEN, HOI4_AGENT_LIMIT_TOKEN, HOI4_AGENT_SECOND_LIMIT_TOKEN, HOI4_AGENT_STREAM_TOKEN, HOI4_AGENT_TEST_TOKEN, HOI4_CONCURRENCY_TOKEN, HOI4_NATIVE_TASK_ALPHA_TOKEN, HOI4_NATIVE_TASK_BETA_TOKEN and HOI4_TOKEN_DIFFERENT_LENGTH from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does klimpaskov-hoi4-tools run?
It speaks stdio and streamable-http, so it runs as a local process your client starts. It is published on npm as hoi4-agent-tools at 3.10.0.
How current is this page?
The grade is for one exact copy of the source (8ebcf0b2174e), read on 2026-10-11. The repository is watched and re-audited when it changes.