hoi4-agent-tools 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -1,9 +1,16 @@
 # Changelog
 
+## 2.0.0 - 2026-07-15
+
+- Removed the workspace inventory tool and made the current mod implicit for local MCP calls.
+- Starting the server inside any mod now works without a config file or per-mod setup command.
+- Updated the published client examples, Registry metadata, and installation verification for the twelve-tool surface.
+- Rendered unresolved scripted localisation values as `[X]` and applied supported HOI4 `§` text colours in offline GUI previews.
+
 ## 1.2.0 - 2026-07-13
 
 - Added a read-only Event Chain Viewer for scanning, tracing, explaining, linting, rendering, and comparing large HOI4 event chains.
-- Kept the event surface to three tools with seven inspect modes and linked authoritative graph artifacts, bringing the public surface to thirteen tools within the fixed discovery budget.
+- Kept the event surface to three tools with seven inspect modes and linked authoritative graph artifacts, keeping the public surface to twelve tools within the fixed discovery budget. Local calls now resolve the mod containing the MCP working directory.
 - Added event workflow documentation, package and Registry metadata, and project-owned acceptance coverage for more than 300 event definitions.
 - Reconfirmed MCP protocol `2025-11-25`, TypeScript SDK 1.29.0, Registry schema `2025-12-11`, and Registry publisher 1.7.9 for this release.
 

package/README.md

@@ -1,6 +1,6 @@
 # HOI4 Agent Tools
 
-HOI4 Agent Tools is an MCP server for coding agents to analyze Hearts of Iron IV event chains and inspect, create, or clean up focus trees, scripted GUIs, and maps. It works directly with configured mod folders and produces offline renders for review.
+HOI4 Agent Tools is an MCP server for coding agents to analyze Hearts of Iron IV event chains and inspect, create, or clean up focus trees, scripted GUIs, and maps. Start it in a mod folder and it works there immediately, with offline renders for review.
 
 ## What it does
 
@@ -14,11 +14,10 @@ HOI4 Agent Tools is an MCP server for coding agents to analyze Hearts of Iron IV
 Requires Node.js 22 or 24.
 
 ```bash
-npm install --global hoi4-agent-tools@1.2.0
-hoi4-agent-tools-setup --init
+npm install --global hoi4-agent-tools@2.0.0
 ```
 
-`--init` discovers the usual HOI4 game and mod locations and writes the default per-user configuration. No `HOI4_AGENT_CONFIG` environment variable is needed. For custom paths, multiple mod roots, or a custom config location, see [Setup](docs/setup.md).
+Start the MCP with its working directory set to the mod you are editing. No config or per-mod registration is required: the server finds that mod automatically. Run `hoi4-agent-tools-setup --init` only when you want persistent discovery for several mod roots, a custom game path, or a remote deployment; see [Setup](docs/setup.md).
 
 ## Connect your agent
 
@@ -32,7 +31,6 @@ Paste the printed Codex or generic global-install entry into your MCP client, th
 
 | Tool                 | Purpose                                                                                 |
 | -------------------- | --------------------------------------------------------------------------------------- |
-| `hoi4.mods`          | List the writable mods available to the coding agent.                                   |
 | `hoi4.focus_inspect` | Read focus trees and report structural or reference problems.                           |
 | `hoi4.focus_render`  | Render an existing focus tree or continuous palette.                                    |
 | `hoi4.focus_rewrite` | Create or update a focus tree.                                                          |

package/dist/hoi4_agent_tools/core/workspace.js

@@ -4,6 +4,8 @@ import { WORKSPACE_MAX_REGISTRATIONS, workspaceRegistrationSchema, } from './con
 import { compareCodeUnits, hashCanonical, sha256Bytes } from './canonical.js';
 import { ServiceError } from './result.js';
 import { ServerState } from './server-state.js';
+/** Omitted MCP workspace arguments resolve to the mod containing the server cwd. */
+export const CURRENT_WORKSPACE_ID = 'current';
 async function exists(value, signal) {
     signal?.throwIfAborted();
     try {
@@ -185,6 +187,9 @@ export class WorkspaceResolver {
             }
         }
         for (const configured of configuration.workspaces) {
+            if (configured.id === CURRENT_WORKSPACE_ID) {
+                throw new ServiceError('WORKSPACE_ID_RESERVED', `Workspace ID is reserved for the current working mod: ${CURRENT_WORKSPACE_ID}`);
+            }
             const registration = resolver.withGlobalWorkspaceDefaults(configured);
             const workspace = await resolver.resolveRegistration(registration);
             if (resolver.#byId.has(workspace.id)) {
@@ -203,6 +208,28 @@ export class WorkspaceResolver {
     config() {
         return this.configuration;
     }
+    /** Resolve the implicit workspace used by local coding-agent calls. */
+    resolveCurrentWorkspaceId(principal) {
+        const workspaces = this.list(principal).filter(({ registration }) => registration.kind === 'mod');
+        if (workspaces.length === 0) {
+            throw new ServiceError('WORKSPACE_CONTEXT_NOT_FOUND', 'No writable mod workspace is configured for the MCP server');
+        }
+        const currentDirectory = path.normalize(process.cwd());
+        const containing = workspaces.filter((workspace) => isWithin(workspace.modRoot, currentDirectory));
+        if (containing.length === 1)
+            return containing[0].id;
+        if (containing.length > 1) {
+            throw new ServiceError('WORKSPACE_CONTEXT_AMBIGUOUS', 'The MCP working directory is inside more than one writable mod workspace', { currentDirectory });
+        }
+        if (workspaces.length === 1)
+            return workspaces[0].id;
+        throw new ServiceError('WORKSPACE_CONTEXT_REQUIRED', 'The MCP working directory does not identify one writable mod workspace', { currentDirectory, workspaceIds: workspaces.map(({ id }) => id) });
+    }
+    resolveWorkspaceId(workspaceId, principal) {
+        return workspaceId === CURRENT_WORKSPACE_ID
+            ? this.resolveCurrentWorkspaceId(principal)
+            : workspaceId;
+    }
     serverState() {
         return this.#serverState;
     }
@@ -276,15 +303,16 @@ export class WorkspaceResolver {
             .sort((a, b) => compareCodeUnits(a.id, b.id));
     }
     get(workspaceId, principal) {
-        if (principal !== undefined && !this.allowedWorkspaceIds(principal).has(workspaceId)) {
+        const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId, principal);
+        if (principal !== undefined && !this.allowedWorkspaceIds(principal).has(resolvedWorkspaceId)) {
             throw new ServiceError('WORKSPACE_INACCESSIBLE', 'Workspace is unavailable to the authenticated principal');
         }
-        const workspace = this.#byId.get(workspaceId);
+        const workspace = this.#byId.get(resolvedWorkspaceId);
         if (workspace === undefined) {
             if (principal !== undefined) {
                 throw new ServiceError('WORKSPACE_INACCESSIBLE', 'Workspace is unavailable to the authenticated principal');
             }
-            throw new ServiceError('WORKSPACE_NOT_REGISTERED', `Workspace is not registered: ${workspaceId}`);
+            throw new ServiceError('WORKSPACE_NOT_REGISTERED', `Workspace is not registered: ${resolvedWorkspaceId}`);
         }
         return workspace;
     }

package/dist/hoi4_agent_tools/gui/layout.js

@@ -40,8 +40,55 @@ function scalarString(value) {
         return String(value);
     return undefined;
 }
+const defaultTextColour = '#f5f2e8';
+const hoi4TextColours = {
+    B: '#4aa3df',
+    C: '#55d6d6',
+    G: '#56b870',
+    H: '#e7b454',
+    L: '#9aa7b3',
+    M: '#d16bd4',
+    O: '#e58b3c',
+    R: '#e05a5a',
+    T: '#4bc6b9',
+    W: defaultTextColour,
+    Y: '#f1c75b',
+    b: '#4aa3df',
+    g: '#87939e',
+};
 function visibleHoiText(value) {
-    return value.replace(/\u00a7[A-Za-z0-9!]/gu, '').replace(/\u00a3[^\u00a3\s]+/gu, '\u25c6');
+    const characters = [];
+    const colours = [];
+    let colour;
+    let hasColourMarkup = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index] ?? '';
+        const next = value[index + 1];
+        if (character === '\u00a7' && next !== undefined && /^[A-Za-z0-9!]$/u.test(next)) {
+            hasColourMarkup = true;
+            colour = next === '!' ? undefined : hoi4TextColours[next];
+            index += 1;
+            continue;
+        }
+        if (character === '\u00a3') {
+            let cursor = index + 1;
+            while (cursor < value.length && !/[\s\u00a3]/u.test(value[cursor] ?? ''))
+                cursor += 1;
+            characters.push('\u25c6');
+            colours.push(colour);
+            index = cursor - 1;
+            continue;
+        }
+        if (character === '\\' && next === 'n') {
+            characters.push('\n');
+            colours.push(colour);
+            index += 1;
+            continue;
+        }
+        characters.push(character);
+        colours.push(colour);
+    }
+    return { text: characters.join(''), colours, hasColourMarkup };
 }
 function scalarNumber(value, reference) {
     if (typeof value === 'number')
@@ -167,13 +214,15 @@ function resolveTokenText(value, scenario, localisation, rowValues) {
         const key = match[1] ?? '';
         const replacement = rowValues?.[key] ?? scenario.variables[key] ?? scenario.scriptedGui[key];
         if (replacement === undefined) {
-            unresolved.push(`[?${key}]`);
-            return `[?${key}]`;
+            unresolved.push(match[0]);
+            return '[X]';
         }
         return String(replacement);
     }, 'GUI variable substitution');
     text = replaceTextBounded(text, /\[([A-Za-z0-9_.:-]+)\]/gu, (match) => {
         const key = match[1] ?? '';
+        if (key === 'X')
+            return match[0];
         const countryKey = key.replace(/^(?:ROOT|This)\./u, '');
         const replacement = rowValues?.[countryKey] ??
             scenario.country?.[countryKey] ??
@@ -181,16 +230,16 @@ function resolveTokenText(value, scenario, localisation, rowValues) {
             scenario.scriptedGui[key];
         if (replacement === undefined) {
             unresolved.push(match[0]);
-            return match[0];
+            return '[X]';
         }
         return String(replacement);
     }, 'GUI scope substitution');
     return { text, unresolved: [...new Set(unresolved)].sort(), missingLocalisation };
 }
-function wrapText(catalog, fontName, text, fontSize, maximumWidth, work) {
-    const paragraphs = text.replaceAll('\\n', '\n').split('\n');
+function wrapText(catalog, fontName, text, colours, fontSize, maximumWidth, work) {
     const lines = [];
     const widths = [];
+    const colourLines = [];
     const missingGlyphs = new Set();
     const retainMissingGlyphs = (values) => {
         for (const value of values) {
@@ -201,12 +250,44 @@ function wrapText(catalog, fontName, text, fontSize, maximumWidth, work) {
     };
     let lineHeight = fontSize * 1.2;
     let metricSource = 'approximation';
-    for (const paragraph of paragraphs) {
+    const commitLine = (words) => {
+        const characters = [];
+        const lineColours = [];
+        for (const [index, word] of words.entries()) {
+            if (index > 0) {
+                characters.push(' ');
+                lineColours.push(lineColours.at(-1) ?? word.colours[0]);
+            }
+            characters.push(word.text);
+            lineColours.push(...word.colours);
+        }
+        const committedText = characters.join('');
+        work.spendTextLayout('committed text line measurement');
+        const committed = catalog.measureText(fontName, committedText, fontSize);
+        lines.push(committedText);
+        widths.push(committed.width);
+        colourLines.push(lineColours);
+        retainMissingGlyphs(committed.missingGlyphs);
+        lineHeight = committed.lineHeight;
+        metricSource = committed.source;
+    };
+    let paragraphStart = 0;
+    for (let paragraphEnd = 0; paragraphEnd <= text.length; paragraphEnd += 1) {
+        if (paragraphEnd < text.length && text[paragraphEnd] !== '\n')
+            continue;
         work.spendTextLayout('text paragraph layout');
-        const words = paragraph.split(/\s+/u).filter((word) => word.length > 0);
+        const paragraph = text.slice(paragraphStart, paragraphEnd);
+        const paragraphColours = colours.slice(paragraphStart, paragraphEnd);
+        const words = [...paragraph.matchAll(/\S+/gu)].map((match) => {
+            const start = match.index;
+            const word = match[0];
+            return { text: word, colours: paragraphColours.slice(start, start + word.length) };
+        });
+        paragraphStart = paragraphEnd + 1;
         if (words.length === 0) {
             lines.push('');
             widths.push(0);
+            colourLines.push([]);
             continue;
         }
         let currentWords = [];
@@ -215,22 +296,17 @@ function wrapText(catalog, fontName, text, fontSize, maximumWidth, work) {
         let previousWordWidth = 0;
         for (const word of words) {
             work.spendTextLayout('text word measurement');
-            const measuredWord = catalog.measureText(fontName, word, fontSize);
+            const measuredWord = catalog.measureText(fontName, word.text, fontSize);
             retainMissingGlyphs(measuredWord.missingGlyphs);
             let candidateWidth = measuredWord.width;
             if (previousWord !== undefined) {
                 work.spendTextLayout('text word-boundary measurement');
-                const boundary = catalog.measureText(fontName, `${previousWord} ${word}`, fontSize);
+                const boundary = catalog.measureText(fontName, `${previousWord} ${word.text}`, fontSize);
                 retainMissingGlyphs(boundary.missingGlyphs);
                 candidateWidth = currentWidth + boundary.width - previousWordWidth;
             }
             if (maximumWidth > 0 && candidateWidth > maximumWidth && currentWords.length > 0) {
-                const committedText = currentWords.join(' ');
-                work.spendTextLayout('committed text line measurement');
-                const committed = catalog.measureText(fontName, committedText, fontSize);
-                lines.push(committedText);
-                widths.push(committed.width);
-                retainMissingGlyphs(committed.missingGlyphs);
+                commitLine(currentWords);
                 currentWords = [word];
                 currentWidth = measuredWord.width;
             }
@@ -238,26 +314,40 @@ function wrapText(catalog, fontName, text, fontSize, maximumWidth, work) {
                 currentWords.push(word);
                 currentWidth = candidateWidth;
             }
-            previousWord = word;
+            previousWord = word.text;
             previousWordWidth = measuredWord.width;
         }
-        const committedText = currentWords.join(' ');
-        work.spendTextLayout('committed text line measurement');
-        const committed = catalog.measureText(fontName, committedText, fontSize);
-        lines.push(committedText);
-        widths.push(committed.width);
-        retainMissingGlyphs(committed.missingGlyphs);
-        lineHeight = committed.lineHeight;
-        metricSource = committed.source;
+        commitLine(currentWords);
     }
     return {
         lines,
         widths,
+        colourLines,
         lineHeight,
         metricSource,
         missingGlyphs: [...missingGlyphs].sort((a, b) => a - b),
     };
 }
+function colourRunsForLine(catalog, fontName, line, colours, fontSize, work) {
+    if (!colours.some((colour) => colour !== undefined) || line.length === 0)
+        return [];
+    const runs = [];
+    let start = 0;
+    let offsetX = 0;
+    while (start < line.length) {
+        const colour = colours[start] ?? defaultTextColour;
+        let end = start + 1;
+        while (end < line.length && (colours[end] ?? defaultTextColour) === colour)
+            end += 1;
+        const text = line.slice(start, end);
+        work.spendTextLayout('localisation colour-run measurement');
+        const width = catalog.measureText(fontName, text, fontSize).width;
+        runs.push({ text, colour, offsetX, width });
+        offsetX += width;
+        start = end;
+    }
+    return runs;
+}
 function frameFor(element, sprite, scenario) {
     const frameCount = Math.max(1, sprite.frameCount);
     const selected = scenario.selectedFrames[element.name] ?? scenario.selectedFrames[sprite.name];
@@ -439,7 +529,8 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             displayText = `${displayText} — ${displayText} — ${displayText}`;
         if (state === 'missing-localisation')
             displayText = `\u00a7R${rawText}_MISSING\u00a7!`;
-        displayText = visibleHoiText(displayText);
+        const visibleText = visibleHoiText(displayText);
+        displayText = visibleText.text;
         context.work.admitText(displayText, `GUI text for ${definition.name}`);
         const fontName = scalarString(property(definition.attributes, 'font', 'buttonFont'));
         const resolvedFontMetrics = catalog.resolvedFontMetrics(fontName);
@@ -450,10 +541,13 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             16;
         const maxWidth = (scalarNumber(property(definition.attributes, 'maxWidth'), width / scale) ?? width / scale) *
             scale;
-        const wrapped = wrapText(catalog, fontName, displayText, fontSize * scale, maxWidth, context.work);
+        const wrapped = wrapText(catalog, fontName, displayText, visibleText.colours, fontSize * scale, maxWidth, context.work);
         const glyphLines = [];
         for (const line of wrapped.lines)
             glyphLines.push(await catalog.shapeText(fontName, line, fontSize * scale));
+        const colourRuns = visibleText.hasColourMarkup
+            ? wrapped.lines.map((line, index) => colourRunsForLine(catalog, fontName, line, wrapped.colourLines[index] ?? [], fontSize * scale, context.work))
+            : undefined;
         const maximumLineWidth = wrapped.widths.reduce((maximum, value) => Math.max(maximum, value), 0);
         if (width === 0)
             width = maximumLineWidth;
@@ -476,6 +570,7 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             overflowX: width > 0 && measuredWidth > width + 0.01,
             overflowY: height > 0 && measuredHeight > height + 0.01,
             unresolvedTokens: resolved.unresolved,
+            ...(colourRuns === undefined ? {} : { colourRuns }),
         };
         if (wrapped.metricSource === 'approximation')
             addFidelity(fidelity, 'approximated', 'font_metrics', `No supplied font metrics for ${fontName ?? '<default>'}.`, definition);

package/dist/hoi4_agent_tools/gui/renderer.js

@@ -86,6 +86,22 @@ function renderText(element, toolText) {
             (glyphLine === undefined || glyphLine.source === 'deterministic-fallback'
                 ? text.lineHeight * 0.8
                 : glyphLine.baseline);
+        const colourRuns = text.colourRuns?.[index] ?? [];
+        if (colourRuns.length > 0) {
+            const runWidth = colourRuns.reduce((maximum, run) => Math.max(maximum, run.offsetX + run.width), 0);
+            const horizontalScale = runWidth > 0 && width > 0 ? width / runWidth : 1;
+            return `<g data-hoi4-colour-runs="true">${colourRuns
+                .map((run) => toolText.render(run.text, {
+                x: originX + run.offsetX * horizontalScale,
+                y: baseline,
+                fontSize: text.fontSize,
+                fill: run.colour,
+                stroke: '#12151a',
+                strokeWidth: 0.6,
+                ...(run.width > 0 ? { targetWidth: run.width * horizontalScale } : {}),
+            }))
+                .join('')}</g>`;
+        }
         if (glyphLine?.source === 'fontkit-path') {
             const horizontalScale = glyphLine.width > 0 && width > 0 ? width / glyphLine.width : 1;
             return `<g data-font-sha256="${glyphLine.sourceHash}">${glyphLine.glyphs

package/dist/hoi4_agent_tools/mcp/server/create.js

@@ -1,12 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { PACKAGE_NAME, PACKAGE_VERSION } from '../../version.js';
-import { registerModsTool } from '../tools/mods.js';
 import { registerFocusTools } from '../tools/focus.js';
 import { registerGuiTools } from '../tools/gui.js';
 import { registerMapTools } from '../tools/map.js';
 import { registerEventTools } from '../tools/event.js';
 import { registerMcpResources } from '../resources/register.js';
-export const SERVER_INSTRUCTIONS = 'Use hoi4.mods to select a workspace. Use hoi4.event_inspect for scan, roots, trace, explain_path, state_flow, lint, and impact; hoi4.event_render and hoi4.event_compare return linked evidence. JSON resources are authoritative. Event tools are read-only. Only focus, GUI, and map rewrite tools edit configured mods.';
+export const SERVER_INSTRUCTIONS = 'The workspace defaults to the mod containing the MCP working directory; pass workspaceId only when selecting another configured mod. Use hoi4.event_inspect for scan, roots, trace, explain_path, state_flow, lint, and impact; hoi4.event_render and hoi4.event_compare return linked evidence. JSON resources are authoritative. Event tools are read-only. Only focus, GUI, and map rewrite tools edit configured mods.';
 export function createMcpServer(engine, context = {}) {
     const server = new McpServer({
         name: PACKAGE_NAME,
@@ -16,7 +15,6 @@ export function createMcpServer(engine, context = {}) {
         capabilities: { logging: {} },
         instructions: SERVER_INSTRUCTIONS,
     });
-    registerModsTool(server, engine, context);
     registerFocusTools(server, engine, context);
     registerGuiTools(server, engine, context);
     registerMapTools(server, engine, context);

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

@@ -306,11 +306,11 @@ export function registerEventTools(server, engine, context) {
         outputSchema: eventInspectOutputSchema,
         annotations: readOnlyEventTool,
     }, async (input, extra) => {
-        const { workspaceId } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Analyzing event chain');
-            const inspected = await viewer.inspect(inspectRequest(input, context, progress.signal));
+            const inspected = await viewer.inspect(inspectRequest({ ...input, workspaceId }, context, progress.signal));
             await progress.report(2, 3, 'Linking complete event analysis');
             const result = emptyServiceResult(workspaceId, {
                 mode: inspected.mode,
@@ -344,11 +344,11 @@ export function registerEventTools(server, engine, context) {
         outputSchema: eventRenderOutputSchema,
         annotations: readOnlyEventTool,
     }, async (input, extra) => {
-        const { workspaceId } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Rendering event-chain view');
-            const rendered = await viewer.renderAndStore(renderRequest(input, context, progress.signal));
+            const rendered = await viewer.renderAndStore(renderRequest({ ...input, workspaceId }, context, progress.signal));
             await progress.report(2, 3, 'Linking complete event renders');
             const result = emptyServiceResult(workspaceId, {
                 view: rendered.render.view,
@@ -389,11 +389,11 @@ export function registerEventTools(server, engine, context) {
         outputSchema: eventCompareOutputSchema,
         annotations: readOnlyEventTool,
     }, async (input, extra) => {
-        const { workspaceId } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Comparing event-chain graphs');
-            const compared = await viewer.compareAndStore(compareRequest(input, context, progress.signal));
+            const compared = await viewer.compareAndStore(compareRequest({ ...input, workspaceId }, context, progress.signal));
             await progress.report(2, 3, 'Linking complete event comparison');
             const { comparison } = compared;
             const result = emptyServiceResult(workspaceId, {

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

@@ -451,7 +451,8 @@ export function registerFocusTools(server, engine, context) {
         outputSchema: focusInspectOutputSchema,
         annotations: artifactProducing,
     }, async (input, extra) => {
-        const { workspaceId, relativePath } = input;
+        const { workspaceId: requestedWorkspaceId, relativePath } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Building shared workspace index');
@@ -667,7 +668,8 @@ export function registerFocusTools(server, engine, context) {
         outputSchema: focusRenderOutputSchema,
         annotations: artifactProducing,
     }, async (input, extra) => {
-        const { workspaceId, relativePath } = input;
+        const { workspaceId: requestedWorkspaceId, relativePath } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Importing and indexing focus source');
@@ -790,7 +792,8 @@ export function registerFocusTools(server, engine, context) {
             openWorldHint: false,
         },
     }, async (input, extra) => {
-        const { workspaceId, relativePath, createIfMissing, horizontalSpacing, verticalSpacing, padding, reviewScale, } = input;
+        const { workspaceId: requestedWorkspaceId, relativePath, createIfMissing, horizontalSpacing, verticalSpacing, padding, reviewScale, } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             requireServerScope(context, 'hoi4:write');
             const progress = progressReporter(extra);

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

@@ -149,7 +149,8 @@ export function registerGuiTools(server, engine, context) {
         inputSchema: guiInspectInput,
         outputSchema: guiScanOutputSchema,
         annotations: artifactProducing,
-    }, async ({ workspaceId, windowName, scenario, relatedScenarios }, extra) => {
+    }, async ({ workspaceId: requestedWorkspaceId, windowName, scenario, relatedScenarios }, extra) => {
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Building shared index and GUI inspection');
@@ -253,7 +254,8 @@ export function registerGuiTools(server, engine, context) {
         }
     });
     const render = async (input, extra, code) => {
-        const { workspaceId, windowName } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
+        const { windowName } = input;
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 4, 'Building shared index and GUI source graph');
@@ -444,7 +446,8 @@ export function registerGuiTools(server, engine, context) {
             openWorldHint: false,
         },
     }, async (input, extra) => {
-        const { workspaceId, relativePath, windowName, scenario } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
+        const { relativePath, windowName, scenario } = input;
         try {
             requireServerScope(context, 'hoi4:write');
             const progress = progressReporter(extra);

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

@@ -364,7 +364,8 @@ export function registerMapTools(server, engine, context) {
             .strict(),
         outputSchema: mapWorkspaceInspectOutputSchema,
         annotations: artifactProducing,
-    }, async ({ workspaceId, provinceIds, stateIds, regionIds, allocationRequests }, extra) => {
+    }, async ({ workspaceId: requestedWorkspaceId, provinceIds, stateIds, regionIds, allocationRequests }, extra) => {
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Inspecting and validating the map');
@@ -512,7 +513,8 @@ export function registerMapTools(server, engine, context) {
             .strict(),
         outputSchema: mapRenderOutputSchema,
         annotations: artifactProducing,
-    }, async ({ workspaceId, layer, overlays, scale }, extra) => {
+    }, async ({ workspaceId: requestedWorkspaceId, layer, overlays, scale }, extra) => {
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Rendering offline map layer');
@@ -557,7 +559,8 @@ export function registerMapTools(server, engine, context) {
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ workspaceId, operations, diffScale }, extra) => {
+    }, async ({ workspaceId: requestedWorkspaceId, operations, diffScale }, extra) => {
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             requireServerScope(context, 'hoi4:write');
             const progress = progressReporter(extra);

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.0.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; omit `workspaceId` when the MCP working directory is inside the target mod.
 
 ## Inspect
 

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`, and `hoi4.focus_rewrite` for national focus trees and continuous focus palettes. Omit `workspaceId` when the MCP working directory is inside the target mod.
 
 ## Create a tree
 

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. Omit `workspaceId` when the MCP working directory is inside the target mod.
 
 ## Create a GUI
 
@@ -34,4 +34,6 @@ Inspection checks missing assets and localisation, invalid sizes, overlap, clipp
 
 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 runtime localisation expressions such as `[GetValue]` and `[?variable|format]` render as the compact placeholder `[X]`; provide scenario values when the exact text 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. Omit `workspaceId` when the MCP working directory is inside the target mod.
 
 ## 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. Omit `workspaceId`. Explicit `workspaceId` values remain available for configured multi-mod or remote deployments.
 
-## 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.0.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.0.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.0.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 ?? '');
-        }
-    });
-}