jui-tools-mcp-server 2.11.1 → 2.12.0

package/data/screen_identity.json

@@ -89,12 +89,16 @@
     "declaration": {
       "location": "jui.config.json",
       "key": "test.appOwnedScreens",
-      "shape": "Array of entries. An entry is a screen id, or an object { id, group } when the screen also needs diagram metadata. Both forms are equivalent for classification.",
+      "shape": "Array of entries. An entry is a screen id, or an object { id, group, transitions } when the screen also needs diagram metadata or declares outgoing transitions. All forms are equivalent for classification.",
       "example": [
         "tokushoho",
         {
           "id": "company",
-          "group": "static"
+          "group": "static",
+          "transitions": [
+            "Licenses",
+            "Tokushoho"
+          ]
         },
         {
           "id": "licenses",
@@ -104,6 +108,11 @@
           ]
         }
       ],
+      "transitions": {
+        "value": "An array of raw destinations, in the SAME vocabulary a spec's transitions[].destination uses (classified by classify_destination with the face's aliases).",
+        "readBy": "The flow-diagram generator (document_tools spec_graph) — it draws them and flowTestCheck accepts them. Classification and code generation ignore them.",
+        "rationale": "The diagram is drawn from specs only (2026-09-10), and an app-owned screen has no spec — a spec for a screen with nothing to generate describes nothing. Without this key every flow test that leaves an app-owned screen (a footer link from the company page to the licenses page, measured: 2 on one face) would be an error with no way to comply."
+      },
       "group": {
         "value": "A group name, or an array of them — the same shape a screen test's metadata.group takes.",
         "readBy": "The flow-diagram generator only. Classification and code generation read the id and ignore the rest of the object.",
@@ -296,8 +305,17 @@
     ]
   },
   "diagram": {
-    "description": "The screen-transition diagram is derived from the same ids.",
-    "nodeSource": "TWO sources, both normalized into the same id space: (1) flow test inline step 'screen' values plus file-reference steps; (2) spec 'transitions[].destination' values, through specTransitions below. Naming only one of them here is how an implementation ends up reading a source the canon does not declare.",
+    "description": "The screen-transition diagram is drawn from the screen SPECS — <screen spec>.transitions[].destination, plus test.appOwnedScreens[].transitions for a screen that has no spec — and the flow tests are CHECKED against it. Ruled 2026-09-10.",
+    "nodeSource": "ONE source: spec transitions, normalized through specTransitions below, plus the app-owned declarations (appOwnedScreens.declaration.transitions). Flow tests are NOT a source since 2026-09-10; they are the check (flowTestCheck). History: from 2026-09-09 this key declared TWO sources while document_tools read only the first (flow tests) and had ZERO readers of specTransitions — the diagram answered 'No flow tests found' on a face holding 48 specs. A declaration with no reader is a sentence, not a rule. The reader is now document_tools/.../mermaid/spec_graph.py, and its arms fail when the generator reads a flow test as a source.",
+    "drawingPipeline": [
+      "readSpecs (spec stems are the screen ids)",
+      "classifyDestinations (specTransitions.kinds)",
+      "buildForwardEdges (kind screen)",
+      "deriveReturnEdges (kind back → a dotted edge to every screen with a forward edge into the declarer)",
+      "terminalNodes (kind external)",
+      "groupByScreenTestMetadata"
+    ],
+    "pipelineNote": "`pipeline` is the FLOW-TEST walk (resolve → canonicalize → collapse → build edges). It no longer draws anything; flowTestCheck runs it to obtain what the tests DO and compares that with what the specs declare.",
     "pipeline": [
       "resolve",
       "canonicalize",
@@ -307,8 +325,25 @@
     "rules": [
       "Self-loops are discarded (they are the collapse of a screen onto itself).",
       "An edge caused by a 'back' action is a return edge and is rendered distinctly from a forward transition.",
-      "Node ids are sanitized for the diagram language; a screen id is never emitted raw into a diagram identifier position."
+      "Node ids are sanitized for the diagram language; a screen id is never emitted raw into a diagram identifier position.",
+      "A `back` declaration carries no target: it is drawn as a return edge (dotted) to each screen that has a forward edge into the declaring screen. Derived from the specs, never from a test.",
+      "An `external` destination is drawn as a terminal node; `none` draws nothing (a positive declaration); `unknown` and an unmapped `route` draw nothing and are treated as ABSENT — counted and listed, not errors by themselves (ruled 2026-09-10: 解決できない宣言は「無い」扱い)."
     ],
+    "flowTestCheck": {
+      "rule": "Every FORWARD transition a flow test performs (consecutive distinct screens after resolve/canonicalize/collapse) must be an edge the specs declare: a forward edge, or the return edge derived from a `back` declaration (X returns to each screen that pushes it — a flow that leaves a sheet by tapping save and lands on its opener performs that return as a forward step). One that is neither is an ERROR.",
+      "ruledOn": "2026-09-10 — 'flowdiagram は spec だけ見て書く。flow test で遷移が見つかって、それが spec にない時はエラーを吐く'",
+      "exempt": "Back steps (action `back`). A return through the stack is the inverse of a transition the check already saw — and a spec `back` declaration has no target to compare with.",
+      "unresolvedIsAbsent": "A destination the classifier cannot resolve (kind unknown, or route with no mapping) is NOT in the spec for the purpose of this check. So a flow test that navigates to the screen such a destination was meant to name is an error, and the error names the unresolved destination(s) on that source: that is usually the fix.",
+      "reasons": [
+        "<from> has no spec",
+        "<from>'s spec declares no transition to <to>",
+        "the app-owned screen <from> declares no transition to <to> (jui.config.json test.appOwnedScreens[].transitions)"
+      ],
+      "severity": "error. `jsonui-doc generate html` writes every page (the diagram page lists the errors), prints one `ERROR [doc-diagram]:` line per transition, and exits 1. Not covered by --allow-partial (that accepts missing pages; this is a wrong spec). `generate mermaid` exits 1 likewise.",
+      "reported": "per owner (app), with the flow test's name and file, from, to, and the reason. A count without the list is not a report.",
+      "noSpecDirectory": "A flow group with no spec directory anywhere gets ONE `WARNING [doc-diagram]` naming how many flow test files went unchecked, and no diagram. Absence of the directory is a configuration state, not a spec omission.",
+      "readBy": "document_tools/jsonui_doc_cli/test_doc/mermaid/generator.py build_diagram; the exit code in jsonui_doc_cli/cli.py cmd_generate_html"
+    },
     "specTransitions": {
       "source": "<screen spec>.transitions[].destination",
       "description": "A spec transition's destination is FREE PROSE, not an identifier. The validator requires only that the key exists (condition + destination), so nothing has ever constrained its shape, and the corpus shows at least six different kinds of value in that one column.",
@@ -324,11 +359,11 @@
         "description": "CLOSED vocabulary. It exists so that a destination which is not a screen id stops being reported as a defect. Declaring only 'screen' would make 119 of 271 measured destinations spec errors, when they are other kinds of transition — that turns a reporting gap into a rejection of correct input, which is the worse direction.",
         "values": [
           {"kind": "screen", "meaning": "resolves to a screen id in this face's id space", "drawn": "a node and an edge"},
-          {"kind": "route", "meaning": "a URL path owned by a web router, e.g. '/admin/login'", "drawn": "an edge once the route is mapped to a screen; until then, reported"},
+          {"kind": "route", "meaning": "a URL path owned by a web router, e.g. '/admin/login'", "drawn": "nothing until the route is mapped to a screen; until then it is reported with the unknowns and treated as absent"},
           {"kind": "external", "meaning": "leaves the app entirely (browser, tel:, map app, mailer)", "drawn": "a terminal node, never a screen"},
           {"kind": "none", "meaning": "declares that no screen transition happens (in-page tab switch, SPA state change)", "drawn": "nothing. This is a POSITIVE declaration, not a missing value"},
-          {"kind": "back", "meaning": "returns through the navigation stack (pop, dismiss, previous screen)", "drawn": "a return edge, like a flow test's back action"},
-          {"kind": "unknown", "meaning": "none of the above matched", "drawn": "nothing, and it is COUNTED AND LISTED — see unresolvedReporting"}
+          {"kind": "back", "meaning": "returns through the navigation stack (pop, dismiss, previous screen)", "drawn": "a dotted return edge to each screen that has a forward edge into the declaring screen (derived from the specs)"},
+          {"kind": "unknown", "meaning": "none of the above matched", "drawn": "nothing, and it is COUNTED AND LISTED — see unresolvedReporting. Treated as ABSENT by the diagram and by flowTestCheck (ruled 2026-09-10)"}
         ]
       },
       "normalization": {
@@ -339,9 +374,33 @@
           "strip a trailing parenthetical, full-width or half-width, then split on ' or ', '/', and '、' and try each part",
           "apply the face's declared aliases (below)"
         ],
+        "multipleScreens": "A destination whose split parts (pipeline step 2) resolve to MORE THAN ONE screen — `Chat or Mypage（source依存…）` — declares a transition to each. classify_destination returns the first match; the diagram asks jui_cli.core.screen_identity.destination_parts for the parts and classifies each. One resolving part is the classifier's single answer, unchanged.",
+        "parentSpecs": "A `screen_parent_spec` carries no transitions; its `subSpecs[].file` entries (type `screen_sub_spec`) do. The diagram merges them under the parent's screen id (the parent's stem). Measured 2026-09-10: one face's main screen had 0 transitions in the parent and 15 in the sub spec, and reading the parent alone produced false errors for 42 flow tests.",
+        "flowTestConditions": "For the CHECK: a flow test runs once per context (platform, responsive class), and a step gated by `when.platform` / `when.responsive` — any `when` key with a string or list-of-strings value — runs only in its own. Two sibling steps gated ios / android, or regular / compact, are never consecutive; the sequence is built once per combination of the `when` values the flow uses and the edges are the union (measured 2026-09-10: 3 invented transitions on one face).",
         "aliases": {
           "shape": "each declared alias is (position, affix); position is drawn from the closed set below",
           "positions": ["prefix", "suffix"],
+          "declaration": {
+            "location": "jui.config.json",
+            "key": "spec.transitionAliases",
+            "shape": "Array of { position: 'prefix' | 'suffix', affix: '<text>' }. A wrong position is REFUSED (the run fails naming the entry), never skipped — an alias that silently does not fire looks exactly like a face that declared nothing.",
+            "example": [
+              {
+                "position": "prefix",
+                "affix": "Web"
+              },
+              {
+                "position": "suffix",
+                "affix": "画面"
+              },
+              {
+                "position": "suffix",
+                "affix": "View"
+              }
+            ],
+            "readBy": "jui_cli.core.project_config.declared_transition_aliases → jui_cli.core.screen_identity.parse_transition_aliases; consumed by document_tools spec_graph.build_spec_graph through classify_destination(aliases=…)",
+            "history": "Declared as per-face from 2026-09-09 with the SHAPE only — no key, no reader. Measured 2026-09-10: 0 faces could declare one. Added with the reader."
+          },
           "positionsNote": "THE TWO POSITIONS OBSERVED SO FAR, not all of them. Infix and partial matches are NOT covered, and saying which is which matters: a generalization that names its coverage makes the third example a counterexample that asks for a redesign, while one that says 'all' makes the same example an exception to be pushed in sideways, leaving the mechanism bent.",
           "measured": "prefix 'Web' resolves 50 of one face's 93 destinations; suffix '画面' resolves 10 (9 distinct spellings) of another face's 69. The two sit at different ends, which is why the mechanism carries a position rather than a bare string. A THIRD affix then turned up that does not behave like those two: suffix 'View' resolves 8 on one face and 2 on ANOTHER, so an affix is not necessarily one face's convention. Per-face declaration still expresses it — each face declares it separately — but the earlier reading that 'an affix helps exactly one face' was drawn from a sample of two. Whether to declare it is the FACE's call, not the library's — the mechanism already accepts it — so the numbers a face needs are recorded here rather than argued: declaring suffix 'View' resolves 10 destinations (8 on one face, 2 on another) and leaves 5 occurrences / 4 spellings that contain 'View' still unresolved, because stripping it yields no id — FullscreenImageViewer, LicensesView, and the Privacy/Terms WebView pair, whose kind is a separate question (embedded page or external browser) that no measurement here answers.",
           "scopingIsARiskChoiceNotAMeasuredOne": {
@@ -352,7 +411,8 @@
         }
       },
       "unresolvedReporting": {
-        "rule": "The count of 'unknown' destinations is reported PER FACE, never only as a total, together with the scanned total it was drawn from.",
+        "rule": "The count of 'unknown' destinations is reported PER FACE, never only as a total, together with the scanned total it was drawn from.",        "treatment": "ABSENT (ruled 2026-09-10). Not drawn, not an error by itself, listed per face with the raw value and the reason the classifier gave. It becomes an error only when a flow test performs the transition the unresolved destination was meant to declare.",
+
         "rationale": "Measured unresolved rates were 28% / 61% / 50% / 100%. Summed, the face at 100% disappears into the average — and a face that resolves nothing looks exactly like a face with nothing to resolve. A bare zero, or a bare average, cannot tell an instrument that found nothing from one that never reached the corpus."
       }
     },

package/dist/auto_reload.d.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SpecLoader } from "./spec_loader.js";
+/**
+ * Make every tool registered on `server` refresh the canon before it runs.
+ *
+ * Installed ONCE, before any `register(...)` call, by wrapping `server.tool`:
+ * the last function argument of each registration is the handler, and it is
+ * replaced with one that calls `loader.refreshIfChanged()` first. One wrap,
+ * 41 tools, no per-tool code — which is the point: a per-tool call is the
+ * kind of thing the 42nd tool forgets.
+ *
+ * ⚠️ Groups B–F read `ServerConfig`, not the loader, and are wrapped anyway.
+ * The cost is ~0.2 ms per call; the alternative is a list of "tools that need
+ * it" that drifts from the list of tools that read the canon.
+ */
+export declare function installAutoReload(server: McpServer, loader: SpecLoader): void;

package/dist/auto_reload.js

@@ -0,0 +1,33 @@
+/**
+ * Make every tool registered on `server` refresh the canon before it runs.
+ *
+ * Installed ONCE, before any `register(...)` call, by wrapping `server.tool`:
+ * the last function argument of each registration is the handler, and it is
+ * replaced with one that calls `loader.refreshIfChanged()` first. One wrap,
+ * 41 tools, no per-tool code — which is the point: a per-tool call is the
+ * kind of thing the 42nd tool forgets.
+ *
+ * ⚠️ Groups B–F read `ServerConfig`, not the loader, and are wrapped anyway.
+ * The cost is ~0.2 ms per call; the alternative is a list of "tools that need
+ * it" that drifts from the list of tools that read the canon.
+ */
+export function installAutoReload(server, loader) {
+    const original = server.tool.bind(server);
+    server.tool = (...args) => {
+        let index = -1;
+        for (let i = args.length - 1; i >= 0; i--) {
+            if (typeof args[i] === "function") {
+                index = i;
+                break;
+            }
+        }
+        if (index >= 0) {
+            const handler = args[index];
+            args[index] = async (...handlerArgs) => {
+                loader.refreshIfChanged();
+                return handler(...handlerArgs);
+            };
+        }
+        return original(...args);
+    };
+}

package/dist/index.js

@@ -2,6 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { SpecLoader, mcpRootFromImportMetaUrl } from "./spec_loader.js";
+import { installAutoReload } from "./auto_reload.js";
 import { ServerConfig } from "./config.js";
 // --- Group A: Component Spec Lookup ---
 import { register as registerLookupComponent } from "./tools/spec/lookup_component.js";
@@ -67,6 +68,9 @@ const server = new McpServer({
 // JSONUI_CLI_PATH env > ./.jsonui-cli/ > ~/.jsonui-cli/ > bundled snapshot in data/.
 const mcpRoot = mcpRootFromImportMetaUrl(import.meta.url);
 const loader = new SpecLoader(mcpRoot);
+// Every tool re-reads the canon when its content changed (2.12.0). This
+// replaces "restart the MCP server after each jsonui-cli distribution".
+installAutoReload(server, loader);
 const source = loader.getDataSource();
 log(`attribute_definitions: [${source.attributeDefinitions.layer}] ${source.attributeDefinitions.path} (${source.attributeDefinitions.freshness})`);
 log(`component_metadata:    [${source.componentMetadata.layer}] ${source.componentMetadata.path} (${source.componentMetadata.freshness})`);

package/dist/spec_loader.d.ts

@@ -50,6 +50,14 @@ export interface FileInfo {
      */
     contentHash: string;
 }
+/** One automatic reload attempt. `ok: false` means the previous content is
+ *  still being served — a file did not parse — and `error` says which. */
+export interface ReloadRecord {
+    at: string;
+    changed: string[];
+    ok: boolean;
+    error?: string;
+}
 export interface DataSourceInfo {
     attributeDefinitions: FileInfo;
     componentMetadata: FileInfo;
@@ -89,7 +97,29 @@ export declare class SpecLoader {
     /** When this process read the files. Data is cached in memory from then
      *  on, so a file edited later is not what the server is serving. */
     private loadedAt;
+    /** What the last automatic reload did — see `refreshIfChanged`. */
+    private lastReload;
     constructor(mcpRootDir: string);
+    /**
+     * Re-read the canon when its CONTENT changed since this process loaded it.
+     *
+     * 🚨 WHY THIS EXISTS. Every jsonui-cli distribution replaces `~/.jsonui-cli`
+     * under a running server, and until 2.12.0 the only remedy was "restart the
+     * MCP server" — in every session, on every release. Measured 2026-09-10:
+     * the check costs ~0.2 ms per call (seven sha256s of small files), which is
+     * nothing against a tool call, so every tool handler runs it first
+     * (`installAutoReload`) and a restart is no longer part of a distribution.
+     *
+     * ⚠️ A reload is ALL OR NOTHING. A distribution writes files one by one, so
+     * a call can land on a half-written JSON. The fresh state is built in a
+     * separate instance and swapped in only when every file parsed; on failure
+     * the server keeps serving the last good content and records the error
+     * (`getLastReload`), and the next call tries again.
+     *
+     * Returns the paths whose content differed (empty = nothing to do).
+     */
+    refreshIfChanged(): string[];
+    getLastReload(): ReloadRecord | null;
     getComponent(name: string): ComponentSpec | null;
     getComponentWithCommon(name: string): any;
     getAttribute(name: string): any;

package/dist/spec_loader.js

@@ -64,10 +64,55 @@ export class SpecLoader {
     /** When this process read the files. Data is cached in memory from then
      *  on, so a file edited later is not what the server is serving. */
     loadedAt = new Date().toISOString();
+    /** What the last automatic reload did — see `refreshIfChanged`. */
+    lastReload = null;
     constructor(mcpRootDir) {
         this.mcpRootDir = mcpRootDir;
         this.load();
     }
+    /**
+     * Re-read the canon when its CONTENT changed since this process loaded it.
+     *
+     * 🚨 WHY THIS EXISTS. Every jsonui-cli distribution replaces `~/.jsonui-cli`
+     * under a running server, and until 2.12.0 the only remedy was "restart the
+     * MCP server" — in every session, on every release. Measured 2026-09-10:
+     * the check costs ~0.2 ms per call (seven sha256s of small files), which is
+     * nothing against a tool call, so every tool handler runs it first
+     * (`installAutoReload`) and a restart is no longer part of a distribution.
+     *
+     * ⚠️ A reload is ALL OR NOTHING. A distribution writes files one by one, so
+     * a call can land on a half-written JSON. The fresh state is built in a
+     * separate instance and swapped in only when every file parsed; on failure
+     * the server keeps serving the last good content and records the error
+     * (`getLastReload`), and the next call tries again.
+     *
+     * Returns the paths whose content differed (empty = nothing to do).
+     */
+    refreshIfChanged() {
+        const changed = this.getChangedSinceLoad();
+        if (changed.length === 0)
+            return [];
+        const at = new Date().toISOString();
+        try {
+            const fresh = new SpecLoader(this.mcpRootDir);
+            // Own enumerable fields only — the private state, all of it, in one
+            // step. Nothing observes a half-swapped loader.
+            Object.assign(this, fresh);
+            this.lastReload = { at, changed, ok: true };
+        }
+        catch (error) {
+            this.lastReload = {
+                at,
+                changed,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+        return changed;
+    }
+    getLastReload() {
+        return this.lastReload;
+    }
     // ----- public API ------------------------------------------------------
     getComponent(name) {
         const key = name.toLowerCase();

package/dist/tools/spec/get_data_source.js

@@ -1,5 +1,5 @@
 export function register(server, loader) {
-    server.tool("get_data_source", "Report where the MCP server loaded EVERY canonical data file from — attribute_definitions.json (raw schema), component_metadata.json (presentation metadata), screen_identity.json and binding_semantics.json. Shows layer (env / cwd / home / bundled), the absolute path actually read, file mtime and freshness per file, plus when this server process loaded them. Use it when the CLI and the MCP seem to disagree about the canon: it distinguishes a stale file from a server that simply has not been restarted since the file changed.", {}, async () => {
+    server.tool("get_data_source", "Report where the MCP server loaded EVERY canonical data file from — attribute_definitions.json (raw schema), component_metadata.json (presentation metadata), screen_identity.json and binding_semantics.json. Shows layer (env / cwd / home / bundled), the absolute path actually read, file mtime and freshness per file, plus when this server process loaded them. Use it when the CLI and the MCP seem to disagree about the canon: since 2.12.0 every tool call re-reads a file whose CONTENT changed (sha256, not mtime), so a restart is not needed after a jsonui-cli distribution; `lastReload` says when that last happened and whether it succeeded, and `staleInMemory` is non-empty only when a reload FAILED (a file did not parse) and the server is still serving the previous content.", {}, async () => {
         const info = loader.getDataSource();
         // 🚨 THE SAME SEVEN THE STALENESS CHECK WATCHES. This list held five
         // while `getChangedSinceLoad` tracked seven, so `staleInMemory` could
@@ -22,6 +22,7 @@ export function register(server, loader) {
         // however current the file on disk looks.
         const loadedAt = loader.getLoadedAt();
         const changedSinceLoad = loader.getChangedSinceLoad();
+        const lastReload = loader.getLastReload() ?? undefined;
         return {
             content: [
                 {
@@ -37,6 +38,7 @@ export function register(server, loader) {
                         componentCount: info.componentCount,
                         commonAttributeCount: info.commonAttributeCount,
                         loadedAt,
+                        lastReload,
                         staleInMemory: changedSinceLoad.length > 0 ? changedSinceLoad : undefined,
                         //  `freshness` is a property of the FILE (how old it is);
                         //  `staleInMemory` is a property of THIS SERVER (whether what
@@ -45,7 +47,7 @@ export function register(server, loader) {
                         //  "fresh" on every file while the server serves something
                         //  else. The hint names which one fired.
                         hint: changedSinceLoad.length
-                            ? "The CONTENT of these files differs from what this server loaded (compared by sha256, not by timestamp — a distribution moves every mtime without changing bytes). The server is serving the older content from memory — restart it."
+                            ? "The CONTENT of these files differs from what this server loaded (compared by sha256, not by timestamp — a distribution moves every mtime without changing bytes) AND the automatic reload did not replace it — see lastReload.error. The server keeps serving the last content that parsed; fix the file (or wait for the distribution to finish writing it) and call again."
                             : stale
                                 ? "At least one data file is > 90 days old. Re-fetch via `npm rebuild jui-tools-mcp-server` or point JSONUI_CLI_PATH at a fresher checkout."
                                 : undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jui-tools-mcp-server",
-  "version": "2.11.1",
+  "version": "2.12.0",
   "description": "MCP server for JsonUI project management - wraps jui and jsonui-doc CLIs plus component spec lookup",
   "main": "dist/index.js",
   "scripts": {

package/scripts/fetch-definitions.js

@@ -44,7 +44,7 @@ const DATA_DIR = join(PROJECT_ROOT, "data");
 //   3. `npm run fetch-definitions` and commit the data/ diff together with
 //      this pin in one commit
 // JSONUI_CLI_RAW_BASE still overrides the whole base URL for manual testing.
-const JSONUI_CLI_TAG = "v1.8.65";
+const JSONUI_CLI_TAG = "v1.8.66";
 const BASE_URL =
   process.env.JSONUI_CLI_RAW_BASE ||
   `https://raw.githubusercontent.com/Tai-Kimura/jsonui-cli/${JSONUI_CLI_TAG}`;

package/src/auto_reload.ts

@@ -0,0 +1,38 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SpecLoader } from "./spec_loader.js";
+
+/**
+ * Make every tool registered on `server` refresh the canon before it runs.
+ *
+ * Installed ONCE, before any `register(...)` call, by wrapping `server.tool`:
+ * the last function argument of each registration is the handler, and it is
+ * replaced with one that calls `loader.refreshIfChanged()` first. One wrap,
+ * 41 tools, no per-tool code — which is the point: a per-tool call is the
+ * kind of thing the 42nd tool forgets.
+ *
+ * ⚠️ Groups B–F read `ServerConfig`, not the loader, and are wrapped anyway.
+ * The cost is ~0.2 ms per call; the alternative is a list of "tools that need
+ * it" that drifts from the list of tools that read the canon.
+ */
+export function installAutoReload(server: McpServer, loader: SpecLoader): void {
+  const original = (server.tool as (...args: unknown[]) => unknown).bind(server);
+  (server as unknown as { tool: (...args: unknown[]) => unknown }).tool = (
+    ...args: unknown[]
+  ) => {
+    let index = -1;
+    for (let i = args.length - 1; i >= 0; i--) {
+      if (typeof args[i] === "function") {
+        index = i;
+        break;
+      }
+    }
+    if (index >= 0) {
+      const handler = args[index] as (...handlerArgs: unknown[]) => unknown;
+      args[index] = async (...handlerArgs: unknown[]) => {
+        loader.refreshIfChanged();
+        return handler(...handlerArgs);
+      };
+    }
+    return original(...args);
+  };
+}

package/src/index.ts

@@ -3,6 +3,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { SpecLoader, mcpRootFromImportMetaUrl } from "./spec_loader.js";
+import { installAutoReload } from "./auto_reload.js";
 import { ServerConfig } from "./config.js";
 
 // --- Group A: Component Spec Lookup ---
@@ -78,6 +79,9 @@ const server = new McpServer({
 // JSONUI_CLI_PATH env > ./.jsonui-cli/ > ~/.jsonui-cli/ > bundled snapshot in data/.
 const mcpRoot = mcpRootFromImportMetaUrl(import.meta.url);
 const loader = new SpecLoader(mcpRoot);
+// Every tool re-reads the canon when its content changed (2.12.0). This
+// replaces "restart the MCP server after each jsonui-cli distribution".
+installAutoReload(server, loader);
 const source = loader.getDataSource();
 log(
   `attribute_definitions: [${source.attributeDefinitions.layer}] ${source.attributeDefinitions.path} (${source.attributeDefinitions.freshness})`

package/src/spec_loader.ts

@@ -81,6 +81,15 @@ export interface FileInfo {
   contentHash: string;
 }
 
+/** One automatic reload attempt. `ok: false` means the previous content is
+ *  still being served — a file did not parse — and `error` says which. */
+export interface ReloadRecord {
+  at: string;
+  changed: string[];
+  ok: boolean;
+  error?: string;
+}
+
 export interface DataSourceInfo {
   attributeDefinitions: FileInfo;
   componentMetadata: FileInfo;
@@ -153,11 +162,56 @@ export class SpecLoader {
   /** When this process read the files. Data is cached in memory from then
    *  on, so a file edited later is not what the server is serving. */
   private loadedAt: string = new Date().toISOString();
+  /** What the last automatic reload did — see `refreshIfChanged`. */
+  private lastReload: ReloadRecord | null = null;
 
   constructor(private mcpRootDir: string) {
     this.load();
   }
 
+  /**
+   * Re-read the canon when its CONTENT changed since this process loaded it.
+   *
+   * 🚨 WHY THIS EXISTS. Every jsonui-cli distribution replaces `~/.jsonui-cli`
+   * under a running server, and until 2.12.0 the only remedy was "restart the
+   * MCP server" — in every session, on every release. Measured 2026-09-10:
+   * the check costs ~0.2 ms per call (seven sha256s of small files), which is
+   * nothing against a tool call, so every tool handler runs it first
+   * (`installAutoReload`) and a restart is no longer part of a distribution.
+   *
+   * ⚠️ A reload is ALL OR NOTHING. A distribution writes files one by one, so
+   * a call can land on a half-written JSON. The fresh state is built in a
+   * separate instance and swapped in only when every file parsed; on failure
+   * the server keeps serving the last good content and records the error
+   * (`getLastReload`), and the next call tries again.
+   *
+   * Returns the paths whose content differed (empty = nothing to do).
+   */
+  refreshIfChanged(): string[] {
+    const changed = this.getChangedSinceLoad();
+    if (changed.length === 0) return [];
+    const at = new Date().toISOString();
+    try {
+      const fresh = new SpecLoader(this.mcpRootDir);
+      // Own enumerable fields only — the private state, all of it, in one
+      // step. Nothing observes a half-swapped loader.
+      Object.assign(this, fresh);
+      this.lastReload = { at, changed, ok: true };
+    } catch (error) {
+      this.lastReload = {
+        at,
+        changed,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+    return changed;
+  }
+
+  getLastReload(): ReloadRecord | null {
+    return this.lastReload;
+  }
+
   // ----- public API ------------------------------------------------------
 
   getComponent(name: string): ComponentSpec | null {

package/src/tools/spec/get_data_source.ts

@@ -4,7 +4,7 @@ import { SpecLoader } from "../../spec_loader.js";
 export function register(server: McpServer, loader: SpecLoader) {
   server.tool(
     "get_data_source",
-    "Report where the MCP server loaded EVERY canonical data file from — attribute_definitions.json (raw schema), component_metadata.json (presentation metadata), screen_identity.json and binding_semantics.json. Shows layer (env / cwd / home / bundled), the absolute path actually read, file mtime and freshness per file, plus when this server process loaded them. Use it when the CLI and the MCP seem to disagree about the canon: it distinguishes a stale file from a server that simply has not been restarted since the file changed.",
+    "Report where the MCP server loaded EVERY canonical data file from — attribute_definitions.json (raw schema), component_metadata.json (presentation metadata), screen_identity.json and binding_semantics.json. Shows layer (env / cwd / home / bundled), the absolute path actually read, file mtime and freshness per file, plus when this server process loaded them. Use it when the CLI and the MCP seem to disagree about the canon: since 2.12.0 every tool call re-reads a file whose CONTENT changed (sha256, not mtime), so a restart is not needed after a jsonui-cli distribution; `lastReload` says when that last happened and whether it succeeded, and `staleInMemory` is non-empty only when a reload FAILED (a file did not parse) and the server is still serving the previous content.",
     {},
     async () => {
       const info = loader.getDataSource();
@@ -29,6 +29,7 @@ export function register(server: McpServer, loader: SpecLoader) {
       // however current the file on disk looks.
       const loadedAt = loader.getLoadedAt();
       const changedSinceLoad = loader.getChangedSinceLoad();
+      const lastReload = loader.getLastReload() ?? undefined;
       return {
         content: [
           {
@@ -45,6 +46,7 @@ export function register(server: McpServer, loader: SpecLoader) {
                 componentCount: info.componentCount,
                 commonAttributeCount: info.commonAttributeCount,
                 loadedAt,
+                lastReload,
                 staleInMemory: changedSinceLoad.length > 0 ? changedSinceLoad : undefined,
                 //  `freshness` is a property of the FILE (how old it is);
                 //  `staleInMemory` is a property of THIS SERVER (whether what
@@ -53,7 +55,7 @@ export function register(server: McpServer, loader: SpecLoader) {
                 //  "fresh" on every file while the server serves something
                 //  else. The hint names which one fired.
                 hint: changedSinceLoad.length
-                  ? "The CONTENT of these files differs from what this server loaded (compared by sha256, not by timestamp — a distribution moves every mtime without changing bytes). The server is serving the older content from memory — restart it."
+                  ? "The CONTENT of these files differs from what this server loaded (compared by sha256, not by timestamp — a distribution moves every mtime without changing bytes) AND the automatic reload did not replace it — see lastReload.error. The server keeps serving the last content that parsed; fix the file (or wait for the distribution to finish writing it) and call again."
                   : stale
                     ? "At least one data file is > 90 days old. Re-fetch via `npm rebuild jui-tools-mcp-server` or point JSONUI_CLI_PATH at a fresher checkout."
                     : undefined,

package/tests/a_tool_call_reloads_the_canon_so_no_session_restarts.test.ts

@@ -0,0 +1,176 @@
+/**
+ * A jsonui-cli distribution replaces `~/.jsonui-cli` under every running MCP
+ * server. Until 2.12.0 the remedy was "restart the MCP server" — in EVERY
+ * session, after EVERY release (measured 2026-09-10: three running servers
+ * at 2.10.3 while the distributed copy was 2.11.1). The user's word for it:
+ * 面倒. So every tool call now asks `refreshIfChanged()` first; the check is
+ * seven sha256s of small files, ~0.2 ms.
+ *
+ * The arms below are the three outcomes a call can meet, plus the one
+ * structural claim ("every tool is wrapped") that a per-tool call would not
+ * give: (1) content changed → the call serves the new content; (2) same
+ * bytes, new mtime → nothing happens (a distribution moves every mtime);
+ * (3) a half-written file → the previous content is kept and the failure is
+ * reported, then the next call recovers once the file is whole.
+ */
+import { readFileSync, utimesSync, writeFileSync } from "fs";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { installAutoReload } from "../src/auto_reload.js";
+import { SpecLoader } from "../src/spec_loader.js";
+import { register as registerDataSource } from "../src/tools/spec/get_data_source.js";
+import {
+  cleanupTempDirs,
+  createToolHarness,
+  makeCliDataset,
+  makeTempDir,
+  FIXTURE_ATTRIBUTE_DEFINITIONS,
+  FIXTURE_COVERAGE,
+} from "./helpers.js";
+
+const originalCwd = process.cwd();
+let cliRoot: string;
+let loader: SpecLoader;
+
+function attrPath(): string {
+  return join(cliRoot, "shared", "core", "attribute_definitions.json");
+}
+
+/** One more component on disk than the fixture ships with. */
+function addComponentOnDisk(): void {
+  writeFileSync(
+    attrPath(),
+    JSON.stringify({ ...FIXTURE_ATTRIBUTE_DEFINITIONS, Extra: { foo: { type: "string" } } }, null, 2)
+  );
+}
+
+function harnessWithDataSource() {
+  const harness = createToolHarness();
+  installAutoReload(harness.server, loader);
+  registerDataSource(harness.server, loader);
+  return harness;
+}
+
+beforeEach(() => {
+  cliRoot = makeTempDir("cli");
+  makeCliDataset(cliRoot, { coverage: FIXTURE_COVERAGE });
+  process.env.JSONUI_CLI_PATH = cliRoot;
+  process.chdir(makeTempDir("cwd"));
+  process.env.HOME = makeTempDir("home");
+  process.env.USERPROFILE = process.env.HOME;
+  loader = new SpecLoader(makeTempDir("mcp"));
+});
+
+afterEach(() => {
+  delete process.env.JSONUI_CLI_PATH;
+  process.chdir(originalCwd);
+  cleanupTempDirs();
+});
+
+describe("a tool call after the canon changed serves the new content", () => {
+  it("the component added on disk is counted on the very next call", async () => {
+    const harness = harnessWithDataSource();
+    const before = JSON.parse(await harness.call("get_data_source"));
+    addComponentOnDisk();
+    const after = JSON.parse(await harness.call("get_data_source"));
+
+    expect(after.componentCount).toBe(before.componentCount + 1);
+    expect(loader.listComponents()).toContain("Extra");
+    expect(after.lastReload.ok).toBe(true);
+    expect(after.lastReload.changed).toContain(attrPath());
+    // Nothing left to report: the reload consumed the difference.
+    expect(after.staleInMemory).toBeUndefined();
+    expect(after.loadedAt > before.loadedAt).toBe(true);
+  });
+
+  it("without the wrapper the same call serves the old content (陰性対照 on the mechanism)", async () => {
+    const harness = createToolHarness();
+    registerDataSource(harness.server, loader); // no installAutoReload
+    const before = JSON.parse(await harness.call("get_data_source"));
+    addComponentOnDisk();
+    const after = JSON.parse(await harness.call("get_data_source"));
+    expect(after.componentCount).toBe(before.componentCount);
+    expect(after.staleInMemory).toContain(attrPath());
+  });
+});
+
+describe("same bytes with a new mtime is not a change", () => {
+  it("does not reload when only the timestamp moved", async () => {
+    const harness = harnessWithDataSource();
+    const before = JSON.parse(await harness.call("get_data_source"));
+    const bytes = readFileSync(attrPath());
+    writeFileSync(attrPath(), bytes);
+    const future = new Date(Date.now() + 60_000);
+    utimesSync(attrPath(), future, future);
+    const after = JSON.parse(await harness.call("get_data_source"));
+    expect(after.lastReload).toBeUndefined();
+    expect(after.loadedAt).toBe(before.loadedAt);
+  });
+});
+
+describe("a half-written file does not take the server down", () => {
+  it("keeps the previous content, reports the failure, and recovers on the next whole write", async () => {
+    const harness = harnessWithDataSource();
+    const before = JSON.parse(await harness.call("get_data_source"));
+
+    writeFileSync(attrPath(), '{"Button": {"text": {"ty'); // mid-copy
+    const during = JSON.parse(await harness.call("get_data_source"));
+    expect(during.componentCount).toBe(before.componentCount);
+    expect(during.lastReload.ok).toBe(false);
+    expect(during.lastReload.error).toMatch(/JSON/);
+    expect(during.staleInMemory).toContain(attrPath());
+    expect(during.hint).toMatch(/automatic reload did not replace it/);
+
+    addComponentOnDisk();
+    const after = JSON.parse(await harness.call("get_data_source"));
+    expect(after.componentCount).toBe(before.componentCount + 1);
+    expect(after.lastReload.ok).toBe(true);
+    expect(after.staleInMemory).toBeUndefined();
+  });
+});
+
+describe("every registered tool is wrapped, whatever overload registered it", () => {
+  it("calls refreshIfChanged before each handler registered through the 4-arg form", async () => {
+    const harness = createToolHarness();
+    installAutoReload(harness.server, loader);
+    const spy = vi.spyOn(loader, "refreshIfChanged");
+    harness.server.tool("four", "d", {}, async () => ({ content: [{ type: "text" as const, text: "ok" }] }));
+    expect(await harness.call("four")).toBe("ok");
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it("wraps the LAST function argument whatever the overload, so (name, schema, cb) is covered too", async () => {
+    // The harness stores (name, description, schema, handler) positionally
+    // and cannot represent the SDK's shorter overloads, so the wrapper is
+    // checked here against a recorder: the registration must reach the
+    // original with the handler REPLACED in the position it was given.
+    const recorded: unknown[][] = [];
+    const fake = { tool: (...args: unknown[]) => recorded.push(args) } as unknown as Parameters<typeof installAutoReload>[0];
+    installAutoReload(fake, loader);
+    const spy = vi.spyOn(loader, "refreshIfChanged");
+    const handler = async () => "h";
+    (fake as unknown as { tool: (...a: unknown[]) => unknown }).tool("three", {}, handler);
+    (fake as unknown as { tool: (...a: unknown[]) => unknown }).tool("two", handler);
+
+    expect(recorded[0][0]).toBe("three");
+    expect(recorded[0][2]).not.toBe(handler);
+    expect(recorded[1][1]).not.toBe(handler);
+    await (recorded[0][2] as () => Promise<string>)();
+    await (recorded[1][1] as () => Promise<string>)();
+    expect(spy).toHaveBeenCalledTimes(2);
+    // and the original handler still runs underneath
+    expect(await (recorded[0][2] as () => Promise<string>)()).toBe("h");
+  });
+
+  it("the wrapper runs BEFORE the handler, not after (order is the point)", async () => {
+    const harness = createToolHarness();
+    installAutoReload(harness.server, loader);
+    harness.server.tool("count", "d", {}, async () => ({
+      content: [{ type: "text" as const, text: String(loader.getDataSource().componentCount) }],
+    }));
+    const before = Number(await harness.call("count"));
+    addComponentOnDisk();
+    expect(Number(await harness.call("count"))).toBe(before + 1);
+  });
+});