hoi4-agent-tools 2.1.0 → 2.2.0

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 = '2.1.0';
+export const PACKAGE_VERSION = '2.2.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/README.md

@@ -2,6 +2,7 @@
 
 - [Setup](setup.md): install the server, configure HOI4 paths, and connect an MCP client.
 - [Event chains](events.md): inspect, trace, lint, render, and compare event chains.
+- [Technology trees](technology.md): inspect, trace, lint, render, and compare technologies and doctrines.
 - [Focus trees](focus.md): inspect, create, render, and clean national or continuous focus content.
 - [Scripted GUIs](gui.md): inspect linked UI source, render states, and create or repair GUIs.
 - [Maps](map.md): inspect and edit provinces, states, regions, adjacency, supply, and railways.

package/docs/development.md

@@ -19,7 +19,11 @@ npm run inspector
 
 Keep changes focused and include tests for behavior changes. CI fixtures must be synthetic and project-owned; never commit installed-game or third-party-mod content. Public tool or schema changes require compatibility review and a versioned release.
 
-The event-chain acceptance fixture contains more than 300 project-owned event definitions and exercises routes, options, timing, state flow, scope changes, unresolved dynamic calls, rendering, and comparison. Local opt-in tests can also read an installed game and an external mod without copying their sources:
+The event-chain acceptance fixture contains more than 300 project-owned event definitions and exercises routes, options, timing, state flow, scope changes, unresolved dynamic calls, rendering, and comparison.
+
+The technology acceptance fixture contains 1,040 project-owned technologies across 13 folders and exercises classic and current doctrines, prerequisites, exclusive branches, multiple placements, unlocks, bonuses, grants, assets, unresolved references, rendering, and comparison.
+
+Local opt-in tests can also read an installed game and an external mod without copying their sources:
 
 ```bash
 HOI4_GAME_ROOT="/games/Hearts of Iron IV" \

package/docs/setup.md

@@ -10,7 +10,7 @@ npm install --global hoi4-agent-tools
 
 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.
 
-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.
+When the MCP server starts with its working directory inside a mod, every focus, GUI, map, event, and technology call uses that mod automatically. Configured multi-mod or remote deployments can use explicit workspace selection.
 
 ## Optional persistent configuration
 

package/docs/technology.md

@@ -0,0 +1,90 @@
+# Technology trees
+
+The Technology Tree Viewer reconstructs classic technologies, legacy doctrine technologies, and current doctrine definitions across the active mod, configured dependencies, and vanilla sources. It links prerequisites, folder placements, exclusive choices, categories, tags, unlocks, bonuses, grants, localisation, icons, and AI metadata without launching the game.
+
+Use the three technology tools directly from the target mod.
+
+## Inspect
+
+`hoi4.tech_inspect` provides eight focused modes:
+
+- `scan`: build the complete technology graph and report its inventory, diagnostics, analysis limits, and revision.
+- `folders`: list folder roots and source placements, or inspect one `folderId`.
+- `trace`: follow prerequisites, descendants, or both from a `technologyId` with bounded depth and node limits.
+- `explain`: collect one technology's definition, placements, paths, exclusivity, metadata, effects, unlocks, grants, bonuses, and unresolved references.
+- `unlocks`: filter unlock relationships by technology, target kind, or target ID.
+- `bonus_coverage`: show which technologies or categories are covered by discovered research bonuses.
+- `lint`: filter source-linked findings by classification, diagnostic code, folder, or technology.
+- `impact`: find the definitions, placements, edges, grants, bonuses, unlocks, localisation, sprites, and files affected by a proposed removal or rename.
+
+Example trace:
+
+```json
+{
+  "mode": "trace",
+  "technologyId": "infantry_weapons",
+  "direction": "both",
+  "maxDepth": 12,
+  "maxNodes": 2000
+}
+```
+
+Impact mode takes a subject with `kind` set to `technology`, `category`, `folder`, or `unlock_target`. A rename also requires `replacementId`:
+
+```json
+{
+  "mode": "impact",
+  "impact": {
+    "kind": "technology",
+    "id": "old_technology",
+    "operation": "rename",
+    "replacementId": "new_technology"
+  }
+}
+```
+
+Findings are separated into confirmed errors, probable defects, design warnings, and unresolved analysis. Roots, grant-only technologies, early dates, zero AI weights, repeated effects, and routing nodes are evaluated in context instead of being treated as automatic defects.
+
+## Render
+
+`hoi4.tech_render` returns authoritative JSON with deterministic SVG and PNG resources; set `includeHtml` when a bundled static report is useful. Available views are `summary`, `folder`, `dependencies`, `technology`, `doctrine`, `exclusive`, `memberships`, `bonuses`, `grants`, `unlocks`, `metadata`, `assets`, and `unresolved`.
+
+Folder renders use the actual folder assignments, gridbox geometry, and technology coordinates found in source. Dependency and other semantic views are explicitly labelled as generated analysis layouts. Missing sprites, textures, or localisation remain identifiable from JSON and vector output even when no icon raster is decoded.
+
+Example folder render:
+
+```json
+{
+  "view": "folder",
+  "folderId": "infantry_folder",
+  "maxNodes": 1000,
+  "includeHtml": false
+}
+```
+
+Large dependency requests return a bounded overview plus focused folder resources and a coverage manifest. The graph itself is not truncated: use the manifest and linked `hoi4-agent://` resources to inspect the relevant folder or branch without loading the entire system into the prompt.
+
+## Compare
+
+`hoi4.tech_compare` compares cached revisions, graph resources, current source, or proposed in-memory source overlays. It reports added, removed, renamed, or moved technologies; graph and placement changes; metadata, category, tag, unlock, grant, bonus, localisation, and icon changes; introduced and resolved findings; and newly reachable or disconnected content.
+
+`before` and `after` each accept `{ "revision": "<sha256>" }` or `{ "artifactUri": "hoi4-agent://..." }`. Proposed overlays take `{ relativePath, source, expectedSourceHash? }`; use `source: null` to model deletion. Overlays are analyzed without writing them.
+
+```json
+{
+  "proposedSources": [
+    {
+      "relativePath": "common/technologies/example.txt",
+      "source": "technologies = { example_tech = { start_year = 1936 } }\n"
+    }
+  ],
+  "render": true,
+  "maxRenderNodes": 500
+}
+```
+
+## Agent workflow
+
+For an unfamiliar technology system, an agent can scan it, discover folders, trace or explain the relevant path, render only the needed views, edit Clausewitz source through its normal repository workflow, and compare the result. The same graph and revision back every query and artifact, so folder placement, dependency structure, unlock impact, and cross-file references stay aligned.
+
+This is static analysis. Exact runtime research time, AI choices, balance, arbitrary dynamic grants, and unsupported visibility behavior are not inferred. Dynamic expressions remain in the results with their confidence and blockers, and no destination is invented.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "2.1.0",
-  "description": "Analyze HOI4 event chains; create and clean focus trees, scripted GUIs, and maps with coding agents.",
+  "version": "2.2.0",
+  "description": "Analyze HOI4 events and technology trees; create and clean focus trees, GUIs, and maps.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "HOI4 Agent Tools contributors",
@@ -22,6 +22,8 @@
     "clausewitz",
     "focus-trees",
     "event-chains",
+    "technology-trees",
+    "doctrines",
     "hoi4-events",
     "scripted-gui",
     "hoi4-map"
@@ -34,6 +36,7 @@
     "docs/README.md",
     "docs/setup.md",
     "docs/events.md",
+    "docs/technology.md",
     "docs/focus.md",
     "docs/gui.md",
     "docs/map.md",
@@ -63,11 +66,12 @@
     "test:local": "tsx scripts/run-local-tests.ts",
     "test:coverage": "vitest run --coverage",
     "benchmark": "node --expose-gc --import tsx scripts/benchmark.ts",
-    "fixtures:generate": "npm run fixtures:generate:focus && npm run fixtures:generate:gui && npm run fixtures:generate:map && npm run fixtures:generate:event",
+    "fixtures:generate": "npm run fixtures:generate:focus && npm run fixtures:generate:gui && npm run fixtures:generate:map && npm run fixtures:generate:event && npm run fixtures:generate:technology",
     "fixtures:generate:focus": "tsx scripts/generate-fixtures.ts",
     "fixtures:generate:gui": "tsx scripts/generate-gui-fixture.ts",
     "fixtures:generate:map": "tsx scripts/generate-map-fixture.ts",
     "fixtures:generate:event": "tsx scripts/generate-event-fixture.ts",
+    "fixtures:generate:technology": "tsx scripts/generate-technology-fixture.ts",
     "fixtures:check": "npm run fixtures:generate && tsx scripts/check-generated.ts fixtures",
     "schemas:generate": "tsx scripts/generate-schemas.ts",
     "schemas:check": "tsx scripts/generate-schemas.ts && tsx scripts/check-generated.ts schemas",
@@ -111,6 +115,11 @@
     "typescript-eslint": "8.63.0",
     "vitest": "4.1.10"
   },
+  "overrides": {
+    "@hono/node-server": "2.0.11",
+    "fast-uri": "3.1.4",
+    "shell-quote": "1.10.0"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": true

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "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": "2.1.0",
+  "description": "Analyze HOI4 events and technology trees; create and clean focus trees, GUIs, and maps.",
+  "version": "2.2.0",
   "repository": {
     "url": "https://github.com/klimPaskov/hoi4-agent-tools",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "hoi4-agent-tools",
-      "version": "2.1.0",
+      "version": "2.2.0",
       "transport": {
         "type": "stdio"
       }