hoi4-agent-tools 1.2.0 → 2.1.0

package/dist/hoi4_agent_tools/runtime.js

@@ -1,9 +1,11 @@
+import { stat } from 'node:fs/promises';
 import path from 'node:path';
 import { homedir } from 'node:os';
-import { loadConfiguration } from './core/configuration.js';
+import { loadConfiguration, serverConfigurationSchema, } from './core/configuration.js';
 import { CoreEngine } from './core/engine.js';
 import { ServiceError } from './core/result.js';
 import { WorkspaceResolver } from './core/workspace.js';
+import { CONFIG_VERSION } from './version.js';
 export function defaultConfigurationPath() {
     const configRoot = process.env.APPDATA ?? process.env.XDG_CONFIG_HOME ?? path.join(homedir(), '.config');
     return path.join(configRoot, 'hoi4-agent-tools', 'config.json');
@@ -21,8 +23,116 @@ export function configurationPath(arguments_ = process.argv.slice(2)) {
         return path.resolve(process.env.HOI4_AGENT_CONFIG);
     return defaultConfigurationPath();
 }
+async function isDirectory(candidate) {
+    try {
+        return (await stat(candidate)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function isFile(candidate) {
+    try {
+        return (await stat(candidate)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function findCurrentModRoot(start = process.cwd()) {
+    for (let cursor = path.resolve(start);;) {
+        if ((await isFile(path.join(cursor, 'descriptor.mod'))) ||
+            ((await isDirectory(path.join(cursor, 'common'))) &&
+                ((await isDirectory(path.join(cursor, 'history'))) ||
+                    (await isDirectory(path.join(cursor, 'interface'))) ||
+                    (await isDirectory(path.join(cursor, 'map')))))) {
+            return cursor;
+        }
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    throw new ServiceError('AUTO_MOD_ROOT_NOT_FOUND', 'Start the MCP from inside a Hearts of Iron IV mod or configure a server workspace', { currentDirectory: path.resolve(start) });
+}
+async function firstExistingDirectory(candidates) {
+    for (const candidate of candidates) {
+        if (await isDirectory(candidate))
+            return path.resolve(candidate);
+    }
+    return undefined;
+}
+function automaticGameRootCandidates() {
+    const home = homedir();
+    return [
+        ...(process.env.HOI4_GAME_ROOT === undefined ? [] : [process.env.HOI4_GAME_ROOT]),
+        path.join(process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Steam', 'steamapps', 'common', 'Hearts of Iron IV'),
+        path.join(home, '.local', 'share', 'Steam', 'steamapps', 'common', 'Hearts of Iron IV'),
+        path.join(home, '.steam', 'steam', 'steamapps', 'common', 'Hearts of Iron IV'),
+        path.join(home, 'Library', 'Application Support', 'Steam', 'steamapps', 'common', 'Hearts of Iron IV'),
+    ];
+}
+function automaticStorageRoots() {
+    const home = homedir();
+    const dataRoot = process.env.XDG_DATA_HOME ?? process.env.LOCALAPPDATA ?? path.join(home, '.local', 'share');
+    const stateRoot = process.env.XDG_STATE_HOME ?? process.env.LOCALAPPDATA ?? path.join(home, '.local', 'state');
+    return {
+        serverStateRoot: path.join(stateRoot, 'hoi4-agent-tools', 'state'),
+        workspaceStorageRoot: path.join(dataRoot, 'hoi4-agent-tools', 'workspaces'),
+    };
+}
+function automaticWorkspaceId(modRoot) {
+    const slug = path
+        .basename(modRoot)
+        .normalize('NFKD')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '_')
+        .replace(/^_+|_+$/gu, '')
+        .slice(0, 48);
+    return `auto_${slug.length === 0 ? 'mod' : slug}`;
+}
+/** Build an in-memory configuration when a local agent starts inside a mod. */
+export async function automaticConfiguration(start = process.cwd()) {
+    const modRoot = await findCurrentModRoot(start);
+    const gameRoot = await firstExistingDirectory(automaticGameRootCandidates());
+    const storage = automaticStorageRoots();
+    return serverConfigurationSchema.parse({
+        version: CONFIG_VERSION,
+        serverStateRoot: storage.serverStateRoot,
+        workspaceStorageRoot: storage.workspaceStorageRoot,
+        ...(gameRoot === undefined ? {} : { gameRoot }),
+        workspaces: [
+            {
+                id: automaticWorkspaceId(modRoot),
+                name: path.basename(modRoot),
+                root: modRoot,
+            },
+        ],
+    });
+}
+async function configurationExists(configPath) {
+    try {
+        return (await stat(configPath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 export async function createEngine(configPath = configurationPath()) {
-    const configuration = await loadConfiguration(configPath);
+    let configuration;
+    try {
+        configuration = await loadConfiguration(configPath);
+    }
+    catch (error) {
+        const useAutomaticConfiguration = configPath === defaultConfigurationPath() &&
+            process.env.HOI4_AGENT_CONFIG === undefined &&
+            error instanceof ServiceError &&
+            error.code === 'CONFIG_READ_FAILED' &&
+            !(await configurationExists(configPath));
+        if (!useAutomaticConfiguration)
+            throw error;
+        configuration = await automaticConfiguration();
+    }
     const resolver = await WorkspaceResolver.create(configuration);
     const engine = new CoreEngine(resolver);
     await engine.initialize();

package/dist/hoi4_agent_tools/schemas/common.js

@@ -1,5 +1,9 @@
 import { z } from 'zod/v4';
-export const workspaceIdSchema = z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/u);
+/** Optional for local agents: omitted means the mod containing the MCP cwd. */
+export const workspaceIdSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9_-]{0,63}$/u)
+    .default('current');
 const diagnosticCodeSchema = z.string().min(1).max(256);
 const diagnosticMessageSchema = z.string().max(4096);
 const sourceDisplayPathSchema = z.string().min(1).max(4096);

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '1.2.0';
+export const PACKAGE_VERSION = '2.1.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/events.md

@@ -2,7 +2,7 @@
 
 The Event Chain Viewer analyzes event definitions and call sites across the active mod, configured dependencies, and vanilla sources. It is read-only: it does not rewrite event files or simulate the game.
 
-Start with `hoi4.mods` to obtain the workspace ID, then use the three event tools as needed.
+Use the three event tools directly from the target mod.
 
 ## Inspect
 
@@ -16,7 +16,9 @@ Start with `hoi4.mods` to obtain the workspace ID, then use the three event tool
 - `lint`: find missing targets, unreachable events, suspicious cycles, conflicting definitions, invalid timing, and unresolved dynamic calls.
 - `impact`: identify callers, descendants, state dependencies, and files affected by a proposed event change.
 
-Use narrow identifiers, direction, and depth limits when the task concerns one chain. The compact response summarizes the result; complete graphs and diagnostics are returned as linked resources.
+Use narrow identifiers, direction, and depth limits when the task concerns one chain. Broad scans build the structural event graph without expanding every scripted helper into duplicate paths. Focused trace, path, state, impact, and render calls expand helper relationships when needed.
+
+The compact response summarizes the result. Small scan resources contain the complete graph; very large scan resources contain exact totals, grouped inventories, representative diagnostics, and the revision needed for focused follow-up queries. This keeps an agent's prompt and artifact storage bounded without reducing the results of those focused queries.
 
 Selectors use one of these forms:
 
@@ -37,7 +39,6 @@ Example `hoi4.event_inspect` arguments:
 
 ```json
 {
-  "workspaceId": "my-mod",
   "mode": "trace",
   "selector": { "kind": "event", "eventId": "namespace.1" },
   "direction": "downstream",
@@ -61,7 +62,6 @@ Example `hoi4.event_render` arguments:
 
 ```json
 {
-  "workspaceId": "my-mod",
   "view": "neighborhood",
   "selector": { "kind": "event", "eventId": "namespace.1" },
   "direction": "both",
@@ -83,7 +83,6 @@ Example `hoi4.event_compare` arguments:
 
 ```json
 {
-  "workspaceId": "my-mod",
   "proposedSources": [
     {
       "relativePath": "events/example.txt",

package/docs/focus.md

@@ -1,6 +1,6 @@
 # Focus trees
 
-Use `hoi4.focus_inspect`, `hoi4.focus_render`, and `hoi4.focus_rewrite` for national focus trees and continuous focus palettes. Start with `hoi4.mods` when the mod ID is not known.
+Use `hoi4.focus_inspect`, `hoi4.focus_render`, `hoi4.focus_raster`, and `hoi4.focus_rewrite` for national focus trees and continuous focus palettes.
 
 ## Create a tree
 
@@ -14,7 +14,7 @@ A complete plan should include:
 - focus positions, convergence points, and shared support branches;
 - titles, descriptions, icons, filters, and AI behavior.
 
-For a missing target, call `hoi4.focus_rewrite` with `createIfMissing: true`. Review the proposed and final artifacts returned by the rewrite, then inspect and render the result. Do not call a tree complete with placeholder rewards, missing localisation, missing icons, or absent AI choices.
+For a missing target, call `hoi4.focus_rewrite` with `createIfMissing: true`. Review the proposed and final artifacts returned by the rewrite, then inspect and render the result. Call `hoi4.focus_raster` when the review needs decoded source icons and a deterministic PNG. Do not call a tree complete with placeholder rewards, missing localisation, missing icons, or absent AI choices.
 
 ## Clean an existing tree
 
@@ -22,7 +22,6 @@ For a layout-only cleanup of an existing national tree, call `hoi4.focus_rewrite
 
 ```json
 {
-  "workspaceId": "my-mod",
   "relativePath": "common/national_focus/my_tree.txt",
   "treeId": "my_tree",
   "layoutMode": "compact"
@@ -47,4 +46,6 @@ If malformed or unsupported script makes a requested change ambiguous, the rewri
 
 Inspection and rendering can report missing references, invalid prerequisite structure, duplicate or overlapping positions, insufficient spacing, long or crossing connectors, branch asymmetry, route conflicts, missing localisation or sprites, weak terminal branches, repeated rewards, and missing AI metadata. Renders are offline review artifacts, not game screenshots.
 
-National trees with 200 or more focuses render review PNGs at half scale by default so large agent workflows stay responsive. Pass an explicit `reviewScale` from `0.25` through `1` when a different raster size is needed; HTML, SVG, JSON, layout, and diagnostics remain complete.
+`hoi4.focus_render` is the normal structural view and writes complete HTML, SVG, JSON, and source-map artifacts without decoding every icon or creating a PNG. `hoi4.focus_raster` adds decoded icons and the high-fidelity PNG. National trees with 200 or more focuses raster at half scale by default; pass `reviewScale` from `0.25` through `1` when a different PNG size is needed.
+
+The public workflow is regression-tested with 1,024-focus creation, compact rewrites, deterministic repeat runs, inspection, vector rendering, and raster rendering. A separate 1,024-icon test decodes a distinct texture for every focus. Large source diffs use the same deterministic review-artifact path instead of blocking at the quadratic matrix size.

package/docs/gui.md

@@ -1,6 +1,6 @@
 # Scripted GUIs
 
-Use `hoi4.gui_inspect`, `hoi4.gui_render`, and `hoi4.gui_rewrite` for `.gui`, `.gfx`, `common/scripted_guis`, localisation, sprites, fonts, and linked decision entry points. Start with `hoi4.mods` when the mod ID is not known.
+Use `hoi4.gui_inspect`, `hoi4.gui_render`, and `hoi4.gui_rewrite` for `.gui`, `.gfx`, `common/scripted_guis`, localisation, sprites, fonts, and linked decision entry points.
 
 ## Create a GUI
 
@@ -30,8 +30,12 @@ Rewrite once, then inspect and render the result.
 
 Inspection checks missing assets and localisation, invalid sizes, overlap, clipping, overflow, conflicting click regions, invisible blockers, broken parents or contexts, list-row cuts, state conflicts, trigger/effect gaps, and resolution drift.
 
+Broad inspection indexes localisation actually referenced by GUI source and returns a connected workspace projection when the complete source graph is very large. The resource records full and returned node and edge counts, so an agent can identify the relevant window without loading unrelated vanilla UI into its prompt. Rendering remains targeted to the selected root, state, and resolution.
+
 ## Offline preview limits
 
 The renderer does not run the game engine. Each render includes a fidelity report that separates fields it models from fields it approximates, ignores, cannot resolve, or does not support. Treat that report as part of the review.
 
+Unresolved numeric runtime values such as `[?variable|format]` render as `[X]`. Unresolved text-returning scripted or scoped localisation such as `[GetStatusText]`, `[FROM.GetName]`, and `[?leader_scope.GetName]` renders as `[dynamic_loc]`. Provide scenario values when the exact value matters. Supported HOI4 `§` localisation colour controls are applied to preview text and `§!` restores the default colour.
+
 A rewrite stops if malformed or unsupported GUI script makes the requested change ambiguous. Runtime animation, masking, tiling, hardcoded controls, and dynamic values may require exact game precedents even when a useful offline preview is available.

package/docs/map.md

@@ -1,6 +1,6 @@
 # Maps
 
-Use `hoi4.map_inspect`, `hoi4.map_render`, and `hoi4.map_rewrite` for provinces, states, strategic regions, adjacency, supply nodes, railways, positions, ownership, cores, claims, resources, buildings, and localisation. Start with `hoi4.mods` when the mod ID is not known.
+Use `hoi4.map_inspect`, `hoi4.map_render`, and `hoi4.map_rewrite` for provinces, states, strategic regions, adjacency, supply nodes, railways, positions, ownership, cores, claims, resources, buildings, and localisation.
 
 ## Create or reshape map content
 

package/docs/setup.md

@@ -2,18 +2,21 @@
 
 HOI4 Agent Tools requires Node.js 22 or 24.
 
-## Install and initialize
+## Install
 
 ```bash
-npm install --global hoi4-agent-tools@1.2.0
-hoi4-agent-tools-setup --init
+npm install --global hoi4-agent-tools
 ```
 
-The setup command discovers standard HOI4 game and mod locations, creates a separate storage folder for generated workspace data, and writes the default per-user config. Each configured mod root is a parent folder whose immediate child directories are individual mods. Every discovered mod is available through the focus, GUI, map, and read-only event tools without per-mod setup. The game root supplies vanilla references.
+Set the MCP process working directory to the mod being edited. The server creates its local workspace in memory, keeps generated artifacts in the per-user data directory, and starts without a config file. The installed game is detected when available for vanilla references; it is not required for source inspection or offline rendering.
 
-After connecting the MCP server, call `hoi4.mods` to confirm which mods are available.
+When the MCP server starts with its working directory inside a mod, every focus, GUI, map, and event call uses that mod automatically. Configured multi-mod or remote deployments can use explicit workspace selection.
 
-## Override discovered paths
+## Optional persistent configuration
+
+Use `--init` only when you need several mod roots, a fixed game path, or a shared/remote process:
+
+### Configure explicit paths
 
 Use explicit paths when discovery is incomplete or when you want to expose more than one mod root:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "1.2.0",
+  "version": "2.1.0",
   "description": "Analyze HOI4 event chains; create and clean focus trees, scripted GUIs, and maps with coding agents.",
   "type": "module",
   "license": "Apache-2.0",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.klimPaskov/hoi4-agent-tools",
   "title": "HOI4 Agent Tools",
   "description": "Analyze HOI4 event chains; create and clean focus trees, scripted GUIs, and maps with coding agents.",
-  "version": "1.2.0",
+  "version": "2.1.0",
   "repository": {
     "url": "https://github.com/klimPaskov/hoi4-agent-tools",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "hoi4-agent-tools",
-      "version": "1.2.0",
+      "version": "2.1.0",
       "transport": {
         "type": "stdio"
       }

package/dist/hoi4_agent_tools/mcp/tools/mods.js

@@ -1,54 +0,0 @@
-import { z } from 'zod/v4';
-import { compareCodeUnits } from '../../core/canonical.js';
-import { emptyServiceResult } from '../../core/result.js';
-import { nonNegativeIntegerSchema } from '../server/output-schemas.js';
-import { errorResult, strictOperationResultSchema, toolResult } from '../server/result.js';
-const modsOutputSchema = strictOperationResultSchema(z
-    .object({
-    count: nonNegativeIntegerSchema,
-    mods: z
-        .array(z
-        .object({
-        id: z.string().min(1).max(64),
-        name: z.string().min(1).max(256),
-        writable: z.boolean(),
-    })
-        .strict())
-        .max(1_000),
-})
-    .strict());
-export function registerModsTool(server, engine, context) {
-    server.registerTool('hoi4.mods', {
-        title: 'List available HOI4 mods',
-        description: 'List configured HOI4 mod workspaces, optionally selecting one by ID.',
-        inputSchema: z.object({ workspaceId: z.string().min(1).max(64).optional() }).strict(),
-        outputSchema: modsOutputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    }, ({ workspaceId }) => {
-        try {
-            const mods = (workspaceId === undefined
-                ? engine.list(context.principal)
-                : [engine.status(workspaceId, context.principal)])
-                .filter(({ kind }) => kind === 'mod')
-                .sort((left, right) => compareCodeUnits(left.id, right.id));
-            const result = emptyServiceResult(workspaceId ?? '', {
-                count: mods.length,
-                mods: mods.map(({ id, name, writable }) => ({
-                    id,
-                    name,
-                    writable,
-                })),
-            });
-            result.code = 'MODS_LISTED';
-            return toolResult(result);
-        }
-        catch (error) {
-            return errorResult(error, workspaceId ?? '');
-        }
-    });
-}