iit-mcp-hudu 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## Unreleased
+
+## 0.5.1
+
+**Upgrading from 0.5.0:** no configuration or client changes needed; behaviour only. A record read (get, getSection, fetch_many, article context) after a `hudu_write` / `hudu_delete` in the same server process now returns the written data instead of the cached pre-write record. A write from another process or deployment can still be served stale for up to the cache TTL (caches are per process). The `hudu_search` body index is a separate store that a write does not refresh: after a write, pass `refresh: true` or wait for the index TTL (SDK default 10 min) before relying on a body search to find new text.
+
+- Fix: record reads (get, getSection, fetch_many, article context) after a write are fresh in the same process: the server now clears the read client's cache after every write or delete attempt (node-hudu 0.19.0 `clearCache()`); previously a read after a write could return the pre-write record for up to the cache TTL (5 min for articles). A dry run and a policy refusal do not clear. The `hudu_search` body index is not refreshed by a write (`refresh: true`, or the 10 min index TTL) (#45, refs #25).
+- Dependency: node-hudu 0.18.0 -> 0.19.0 (exact pin). Plan hash unchanged (`9d110798...`); operation set unchanged (236).
+- Docs: correction to the 0.3.0 line. `articles.resolve`, `articles.getContext` and `hudu_get_article_context` return an article summary with no body by default, so they set no `markdown_lossy` / `markdown_lossy_codes`; only `opts.expand: true` returns a Markdown body that can carry the signal. README and architecture note updated.
+- Docs: Mermaid stored form. Observed live, a ```mermaid fence is stored as `<pre class="language-mermaid"><code class="language-mermaid">...</code></pre>` and round-trips losslessly through `articles.get` and `patchSection`; the read path accepts both that and the bare `<pre>` form. A save made in the Hudu UI editor is not yet verified.
+- Docs: README notes that `HUDU_READ_ONLY=true` makes `hudu_write` / `hudu_delete` a JSON-RPC `-32602` "tool not found", and that `asset_passwords.deleteShare` of a missing share returns 404 `NOT_FOUND` every time; SCOPING notes the live stdio `tools/list` sizes (39,436 / 33,891 B); the per-user-identity decision record gains the 2026-10-25 sandbox data points.
+
+## 0.5.0
+
+**Upgrading from 0.4.0:** clients now see `markdown_lossy` / `markdown_lossy_codes` on `articles.getSection`, with a section-specific note (the signal describes the whole article, so the loss may be in another section). Whole-article read text is unchanged. `hudu_list` compact rows are unchanged. node-hudu 0.17.0 -> 0.18.0, plan hash re-stamped to `9d110798...`, operation set unchanged (236).
+
+- `articles.getSection` lifts the SDK's whole-body `content_loss` into `markdown_lossy` / `markdown_lossy_codes` like the other article reads; `content_loss` is never passed through. This supersedes the 0.4.0 note that section reads carry no signal (#42, #39).
+- `COMPACT_FIELDS` is built from the SDK's `SUMMARY_FIELDS` plus explicit extras (`created_at`, `url`), with a test that derives from the SDK and a literal pin of the final lists, so SDK drift fails CI. Served rows are byte-identical (#42, #39).
+- Dependency: node-hudu 0.17.0 -> 0.18.0 (exact pin). Plan hash re-stamped to `9d110798...`; operation set unchanged (236).
+
 ## 0.4.0
 
 **Upgrading from 0.3.0:** `hudu_list` now returns compact summary rows by default. Callers that read custom `fields`, article `content` or layout `fields` from list rows must pass `expand: true`. Everything else is additive or a fix.

package/README.md

@@ -31,7 +31,7 @@ four old names. Rows are compact summaries by default (id, name, key scalar fiel
 25-row assets page under 20,000 characters instead of ~88,000; pass `expand: true` for the full
 records (`hudu_read` `articles.list` rows are always full). Article rows carry no body unless expanded. Paging is unchanged (`asset_layouts` still takes no `page_size`).
 
-These tools run on node-hudu 0.17.0; the `SDK behaviour (0.12.0)` section below covers the behaviours that shape them: redirect refusal, the closed input contract, the error envelope, and the client opt-ins. Numeric ids must be positive integers on every tool; anything else is refused before a request is made.
+These tools run on node-hudu 0.19.0; the `SDK behaviour (0.12.0)` section below covers the behaviours that shape them: redirect refusal, the closed input contract, the error envelope, and the client opt-ins. Numeric ids must be positive integers on every tool; anything else is refused before a request is made.
 
 `hudu_fetch_many` (node-hudu 0.12.0) fetches up to 20 single records across mixed resources in
 one call: each item is exactly `{ resource, id, fields? }` — one of the 22 bare-id resources, a
@@ -196,6 +196,8 @@ Discovery reports deployment-policy refusals as unreachable.
 `HUDU_READ_ONLY=true` is a hard override of the write policy: no `hudu_write` / `hudu_delete` tool is
 registered and every mutation is refused, whatever `HUDU_WRITE_POLICY` and `HUDU_WRITE_ALLOW` say. Unset or
 `false` leaves `HUDU_WRITE_POLICY` in charge (default `deny`). The effective policy is logged once at boot.
+Because the two tools are not registered, a client that calls them gets the protocol-level JSON-RPC error
+`-32602` (`Tool hudu_write not found`), not a tool error envelope.
 
 `HUDU_WRITE_POLICY` stays a **deployment-wide** decision, not a per-caller one. Per-caller
 credentials make each caller's Hudu role an external authority too, but that authority is not ours
@@ -229,6 +231,9 @@ them. Under `allow`, `listShares` / `getShare` work and the share `url` (a beare
 `createShare` is never runnable here: the SDK refuses it (`POLICY_DENIED`, `reveal_required`, dry-run
 included, no request) without its `reveal` capability, this server never grants `reveal`, and
 `hudu_list_operations` marks the row unreachable. Link-shaped text is scrubbed from share errors.
+Observed live, `deleteShare` of a share that does not exist returns `404 NOT_FOUND` on every attempt, repeats included.
+This server never creates a share (`createShare` is unreachable), but under `HUDU_SECRET_READS=allow` and a permitting
+write policy `deleteShare` will delete any existing share, including one created in the Hudu UI.
 
 `hudu_get_company_context` accepts `opts.skip` (`assets`, `articles`, `websites`, `asset_passwords`); pass
 `["asset_passwords"]` when the key cannot read credentials. The skipped list comes back empty with
@@ -269,9 +274,9 @@ caller-named origins — a security property, not a deployment preference.
 ## Article bodies are Markdown (node-hudu 0.14+)
 
 `hudu_read` and `hudu_write` pass `contentFormat: 'markdown'` to the SDK, and `hudu_get_article_context`
-asks for Markdown, so single-article bodies (`articles.get`, `articles.getContext`, `articles.resolve`,
-`create`, `update`) are returned and accepted as Markdown. Hudu callouts (`> [!INFO]`), accordions, task
-lists and Mermaid fences (stored as the editor-native `<pre class="language-mermaid">` form) round-trip as the dialect documents. Rows from `hudu_fetch_many`, `hudu_read` `articles.list`, `articles.search` and `articles.findBySlug` still carry stored HTML:
+asks for Markdown, so single-article bodies (`articles.get`, `create`, `update`, and
+`articles.resolve` / `articles.getContext` only with `opts.expand: true`) are returned and accepted as Markdown. Hudu callouts (`> [!INFO]`), accordions, task
+lists and Mermaid fences round-trip as the dialect documents. Observed live (Hudu 2.48.1), a ```` ```mermaid ```` fence is stored as `<pre class="language-mermaid"><code class="language-mermaid">...</code></pre>` (entity-escaped, indentation preserved) and reads back as the identical fence, including through `articles.patchSection`. The read path matches the `<pre>` by class and takes its text, so it accepts both that form and the bare `<pre class="language-mermaid">` form. That stored form is what the SDK's `markdownToHtml` emits and Hudu stores it as sent, so it shows what the SDK writes, not what the Hudu editor produces natively. The read rule also accepts the `code-block-mermaid-source` class, which may be what the editor produces (unverified). A save made in the Hudu UI editor itself is not yet verified. Rows from `hudu_fetch_many`, `hudu_read` `articles.list`, `articles.search` and `articles.findBySlug` still carry stored HTML:
 those operations take no format. Rules a caller needs:
 
 - A write's `data.content` is parsed as Markdown unless it opens with block-level HTML (`<p>`, `<div>`,
@@ -281,11 +286,10 @@ those operations take no format. Rules a caller needs:
   (for example a `<video>`); send HTML to keep it. The SDK's loss guard runs on every write.
 - Prefer Markdown (or editor-native HTML): Hudu reshapes API-written HTML on the next UI save (h5/h6 flattened, `small`/`abbr`/`q`/`section`/`aside` unwrapped, `thead` removed, an unknown callout type becomes info).
 - `articles.getSection` / `articles.patchSection` read or edit one section as Markdown, with dry-run.
-  `articles.getSection` carries no `markdown_lossy` signal (the SDK drops `content_loss` inside it, and a
-  section is not the whole body); read the whole article with `articles.get` to learn whether it is lossy.
+  `articles.getSection` carries the same `markdown_lossy` / `markdown_lossy_codes` signal as `articles.get`;
+  it describes the whole article, so the loss may be in another section.
 - A Markdown read can be incomplete: anything the dialect cannot express is dropped or reduced
-  (`<video>` and `<script>` are dropped entirely). `hudu_read` (`articles.get` / `getContext` / `resolve`) and
-  `hudu_get_article_context` then set `markdown_lossy: true` (with `markdown_lossy_codes`, the SDK's
+  (`<video>` and `<script>` are dropped entirely). `hudu_read` (`articles.get` / `getSection`, and `resolve` / `getContext` with `opts.expand: true`) and `hudu_get_article_context` with `opts.expand: true` then set `markdown_lossy: true` (with `markdown_lossy_codes`, the SDK's
   `diffArticleRoundTrip` content-loss codes) and add one sentence to the result text; fetch the stored
   HTML with `hudu_fetch_many` (`{items:[{resource:"articles", id}]}`) to see the full body. The read is one
   fetch: the SDK converts the body and reports the loss on the record (no second request); a caller's own
@@ -294,6 +298,10 @@ those operations take no format. Rules a caller needs:
   A body that converts to nothing (only `<video>`, `<input>`, `<p></p>`) reads as `content: ""` with
   `markdown_lossy_codes` containing `ROUNDTRIP_BODY_EMPTY` (it used to fail with `CONVERSION_EMPTY_OUTPUT`).
   The SDK fails a Markdown read with `CONFIG_ERROR` when the Markdown form exceeds 256 KiB.
+- `articles.resolve`, `articles.getContext` and `hudu_get_article_context` carry no lossy signal in the default mode: the result
+  holds an article summary (no body), so there is nothing to convert. Only with `opts.expand: true` is the full record
+  returned (for getContext, as `article`) with a Markdown body, and then the same `markdown_lossy` /
+  `markdown_lossy_codes` signal applies.
 
 ## SDK behaviour (0.12.0)
 
@@ -334,9 +342,11 @@ Every client the server builds — the parent, the fail-closed placeholders and
   blindly.
 - `cache: 'recommended'` — fixed on: the
   per-entity read-through TTL preset (1 h structural / 5 min mutable / 1 min base). Caches are
-  per client, so per scope. A write through the write or delete client does not clear the read
-  client's cache (separate instances), so a read after a mutation is TTL-bounded stale, never
-  unbounded.
+  per client, so per scope. The write and delete clients have their own caches, so after every `hudu_write` /
+  `hudu_delete` attempt that is not a dry run (including a failed or timed-out one, which may have
+  applied) the server clears the read client's cache for the same scope: a record read (get, getSection, fetch_many, article context) after a write in
+  the same server process is fresh. A write made by another process or deployment can still be served
+  stale for up to the TTL, because caches are per process. The `hudu_search` body index is a separate store that a write does not refresh: after a write, pass `refresh: true` or wait for the index TTL (SDK default 10 min) before relying on a body search to find new text.
 - `blockPrivateHosts` on the per-scope clients: the literal-IP SSRF floor for CALLER-named
   origins, fail-closed at client construction. It complements the `HUDU_ALLOWED_BASE_HOSTS`
   hostname matcher (which alone can express wildcard suffixes) and holds even in
@@ -371,7 +381,7 @@ pnpm run dev
 
 CI (`.github/workflows/ci.yml`) runs `typecheck`, `lint` and `test` on every push and pull request.
 
-`node-hudu` is pinned to `0.17.0`. The catalog hash test detects metadata drift; upgrades require
+`node-hudu` is pinned to `0.19.0`. The catalog hash test detects metadata drift; upgrades require
 review of the client authority, operation enums and redaction regressions. Docker uses `pnpm install --frozen-lockfile`.
 
 ## Deployment

package/dist/tools/article-loss.js

@@ -14,6 +14,8 @@ const RECORD_PATHS = {
     // resolve answers the record itself; the `{ value }` envelope is the helper form of the same read.
     'articles.resolve': [[], ['value']],
     'articles.getContext': [['article']],
+    // The SDK reports getSection loss for the WHOLE body (the loss may sit in another section).
+    'articles.getSection': [[]],
 };
 const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 const take = (node, path, codes) => {
@@ -43,4 +45,4 @@ export function takeContentLoss(operation, result) {
     return { result: stripped, codes: [...codes].sort() };
 }
 /** The one short sentence appended to the result text when a read lost content. */
-export const lossyNote = (codes) => ` markdown_lossy: true (${codes.join(', ')}): the Markdown body is incomplete; fetch the stored HTML with hudu_fetch_many {items:[{resource:"articles", id}]} to see all of it.`;
+export const lossyNote = (codes, operation) => ` markdown_lossy: true (${codes.join(', ')}): ${operation === 'articles.getSection' ? 'the Markdown read of this article is incomplete (the loss may be in another section)' : 'the Markdown body is incomplete'}; fetch the stored HTML with hudu_fetch_many {items:[{resource:"articles", id}]} to see all of it.`;

package/dist/tools/dispatch.js

@@ -37,6 +37,10 @@ export function registerDispatchTools(server, ctx) {
             annotations: spec.annotations,
         }, async (args) => {
             const { operation, input, dry_run, confirm } = args;
+            // True once control reaches the SDK dispatcher: every policy gate above it refuses before any
+            // request, so those refusals never clear. Past this point a validation refusal also clears;
+            // that is a cheap no-op, and telling it apart from a write that dialed is not worth the code.
+            let dispatched = false;
             try {
                 // Deployment policy narrows the SDK mode and effect gate.
                 assertWritePermitted(operation, getCapability(operation), config, log);
@@ -72,6 +76,7 @@ export function registerDispatchTools(server, ctx) {
                     opts.dryRun = dry_run;
                 if (typeof confirm === 'string')
                     opts.confirm = confirm;
+                dispatched = true;
                 let result = await dispatchOperation(client, effect, operation, bag, opts);
                 // After the SDK's own input validation, so bad input stays CONFIG_ERROR. The refusing
                 // placeholder never dials, so nothing reached Hudu; the engine swallows its error into a
@@ -120,7 +125,7 @@ export function registerDispatchTools(server, ctx) {
                 }
                 const simulated = result !== null && typeof result === 'object' && result.simulated === true;
                 // A Markdown article read that lost content says so; a lossless read is byte-identical to before.
-                return ok((simulated ? `Dry run: nothing was written (${operation}).` : `${operation} completed.`) + (lossy.length ? lossyNote(lossy) : ''), {
+                return ok((simulated ? `Dry run: nothing was written (${operation}).` : `${operation} completed.`) + (lossy.length ? lossyNote(lossy, operation) : ''), {
                     simulated,
                     operation,
                     result: result ?? null,
@@ -136,6 +141,21 @@ export function registerDispatchTools(server, ctx) {
                     return searchErrorContent(err);
                 return operation === RESOLVE_ANY_OPERATION ? resolveErrorContent(err) : errorContent(err);
             }
+            finally {
+                // Each effect has its own cached client, so a write never clears the read client's cache
+                // (node-hudu clears only the client it mutates through). Clear the read client of this scope
+                // after every real write or delete ATTEMPT, in `finally`: a timeout or 5xx may still have
+                // applied. A dry run (`dry_run` absent is forced to one by the SDK) sends no write, so it
+                // does not clear. clearCache never throws; the guard makes sure it cannot alter the result.
+                if (mode !== 'read' && dispatched && dry_run === false) {
+                    try {
+                        ctx.hudu.clearCache();
+                    }
+                    catch (e) {
+                        log.warn('read cache clear failed after write', { operation, error: e instanceof Error ? e.message : String(e) });
+                    }
+                }
+            }
         });
     }
 }

package/dist/tools/lists.js

@@ -1,4 +1,5 @@
 import * as z from 'zod/v4';
+import { SUMMARY_FIELDS } from 'node-hudu';
 import { getCapability } from 'node-hudu/capabilities';
 import { configError } from 'node-hudu/mcp';
 import { assertSecretReadPermitted, assertWritePermitted } from '../policy.js';
@@ -96,14 +97,28 @@ function assertNonSearchableListReadPermitted(operation, ctx) {
     assertSecretReadPermitted(operation, config, log);
 }
 /**
- * Compact row fields per resource: the node-hudu `*Summary` shapes plus `created_at`. The SDK exports no
- * runtime projection, so `test/tools/lists-compact.test.ts` only pins these lists to a literal copy: it forces a reviewer to revisit them on a node-hudu bump, it does not detect SDK drift itself. `hudu_list` projects each row onto these unless `expand: true`.
+ * Extras beyond the SDK's `SUMMARY_FIELDS` (the keys of the node-hudu `*Summary` shapes). Timestamps go last
+ * in the served row, so `updated_at` (an SDK key where present) is moved after these extras.
+ */
+const COMPACT_EXTRAS = {
+    companies: ['created_at'],
+    articles: ['url', 'created_at'],
+    assets: ['created_at'],
+    asset_layouts: ['url', 'created_at', 'updated_at'],
+};
+const compactFields = (r) => {
+    const base = SUMMARY_FIELDS[r];
+    return [...base.filter((k) => k !== 'updated_at'), ...COMPACT_EXTRAS[r], ...(base.includes('updated_at') ? ['updated_at'] : [])];
+};
+/**
+ * Compact row fields per resource: `SUMMARY_FIELDS` plus `COMPACT_EXTRAS`. `test/tools/lists-compact.test.ts`
+ * derives them from the SDK and also pins the final lists literally. `hudu_list` projects each row onto these unless `expand: true`.
  */
 export const COMPACT_FIELDS = {
-    companies: ['id', 'name', 'nickname', 'slug', 'website', 'phone_number', 'city', 'state', 'id_number', 'archived', 'url', 'created_at', 'updated_at'],
-    articles: ['id', 'name', 'slug', 'company_id', 'folder_id', 'draft', 'enable_sharing', 'url', 'created_at', 'updated_at'],
-    assets: ['id', 'name', 'company_id', 'company_name', 'asset_layout_id', 'primary_serial', 'asset_type', 'archived', 'url', 'created_at', 'updated_at'],
-    asset_layouts: ['id', 'name', 'slug', 'active', 'icon', 'color', 'url', 'created_at', 'updated_at'],
+    companies: compactFields('companies'),
+    articles: compactFields('articles'),
+    assets: compactFields('assets'),
+    asset_layouts: compactFields('asset_layouts'),
 };
 /** Project rows onto the compact fields; a field the row lacks is omitted, not nulled. */
 export function compactRows(resource, rows) {

package/dist/tools/server.js

@@ -384,8 +384,9 @@ export function createMcpServerFactory(requested, log) {
         // `cache` is the SDK's `recommended` per-entity read-through TTL preset (1 h structural / 5 min mutable / 1 min
         // base). Caches are per
         // client, hence per scope — a write through the write or delete client does NOT clear the
-        // read client's cache (separate instances), so a read after a mutation is TTL-bounded stale,
-        // never unbounded.
+        // read client's cache (separate instances), so the dispatchers call the read client's
+        // `clearCache()` after every write or delete attempt (src/tools/dispatch.ts). A write from
+        // another process is still TTL-bounded stale.
         // `cooldown` is the 429 cooldown gate, always on; a
         // locally refused call answers with RateLimitError.notSent, which the error envelope
         // surfaces so a local refusal stays distinguishable from a vendor rejection.

package/dist/tools.js

@@ -30,4 +30,4 @@ export { MAX_SCOPED_CLIENTS, ScopedClientCache, createMcpServerFactory } from '.
  * it against the installed `CATALOG_PLAN_HASH`, so the upgrade fails CI instead of quietly shipping
  * a tool surface that no longer describes the SDK behind it.
  */
-export const BUILT_AGAINST_PLAN_HASH = '1ad5e23b9c140e8f9cf60ac710dd508fc1109e86b9a0620b2d0925f16b11d7b8';
+export const BUILT_AGAINST_PLAN_HASH = '9d11079847a9e2a8d73f4a075a4004b49f59624be5ffc8253636fc41cf677702';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-hudu",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "MCP server for Hudu IT documentation, built on the node-hudu SDK",
   "license": "MIT",
   "author": "Max Soukhomlinov",
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.3.1",
-    "node-hudu": "0.17.0",
+    "node-hudu": "0.19.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {