iit-mcp-hudu 0.2.3 → 0.3.0

package/.env.example

@@ -57,27 +57,21 @@ MCP_TRANSPORT=stdio
 # caller that can reach the listener is trusted.
 # HUDU_ALLOW_ANY_BASE_HOST=false
 
-# Omit mutation tools entirely by default. Set false before enabling a write policy.
-#
-# Deployment spectrum — the variables below compose it, and every step stays fail-closed:
-#   light read-only : the shipped defaults (HUDU_READ_ONLY=true, HUDU_WRITE_POLICY=deny,
-#                    HUDU_SECRET_READS=deny). Reads only; no mutation tools at all.
-#   scoped writes   : HUDU_READ_ONLY=false, HUDU_WRITE_POLICY=allow_list,
-#                    HUDU_WRITE_ALLOW=<operation keys> (plus HUDU_SECRET_READS=allow if
-#                    plaintext credential reads are wanted).
-#   full read-write : HUDU_READ_ONLY=false, HUDU_WRITE_POLICY=all (plus HUDU_SECRET_READS=allow).
-#                    Every write and destructive operation is permitted; the SDK's per-mode
-#                    client gates (read / write / destructive) still apply underneath.
-HUDU_READ_ONLY=true
-# HUDU_READ_ONLY=false
-
-# Authority over the mutation dispatchers. deny (the default) refuses every write and destructive
-# operation; allow_list permits only the keys in HUDU_WRITE_ALLOW; all is today's behaviour and has
-# to be typed out deliberately. An unset value means deny, so forgetting this gets a read-only
-# server, never an open one. Reads are never affected.
+# Deployment spectrum -- HUDU_WRITE_POLICY is the one switch for mutation, and every step is fail-closed:
+#   read-only       : HUDU_WRITE_POLICY=deny (default). No hudu_write / hudu_delete tool exists.
+#   scoped writes   : HUDU_WRITE_POLICY=allow_list + HUDU_WRITE_ALLOW=<operation keys>. hudu_write is
+#                     registered only if the list has a write op, hudu_delete only if it has a destructive op.
+#   full read-write : HUDU_WRITE_POLICY=all. The SDK's per-mode client gates still apply underneath.
+# Plaintext credential reads are a separate switch: HUDU_SECRET_READS=allow.
+
+# Authority over the mutation dispatchers. deny (the default) registers no mutation tool; allow_list permits only the keys in HUDU_WRITE_ALLOW; all is today's behaviour and has
+# to be typed out deliberately. Unset means deny. Reads are never affected.
 HUDU_WRITE_POLICY=deny
 # HUDU_WRITE_POLICY=allow_list
 # HUDU_WRITE_POLICY=all
+# Hard override: true means no write/delete tool and every mutation refused, whatever the policy and
+# allow-list say. Unset or false leaves HUDU_WRITE_POLICY in charge.
+# HUDU_READ_ONLY=true
 
 # Authority over reads that return a plaintext credential -- independent of HUDU_WRITE_POLICY, which
 # never covers them: asset_passwords.get returns password and otp_secret as an ordinary read. deny
@@ -91,6 +85,7 @@ HUDU_SECRET_READS=deny
 # Only read under HUDU_WRITE_POLICY=allow_list. Comma-separated registry operation keys, e.g.
 # articles.update,assets.create. It must be non-empty and every key must exist in the registry (and
 # be a write) or the container fails at boot with the variable named. Ignored under deny/all.
+# Allowing a write also allows the writes it delegates to (articles.patchSection -> articles.update).
 # The write client is offered the write-effect keys and the delete client the destructive-effect
 # keys from this one list: to reach the same coverage as `all` via an allow list, it must name
 # every write and every destructive operation (the full key set is the node-hudu capability
@@ -101,30 +96,6 @@ HUDU_SECRET_READS=deny
 PORT=8787
 LOG_LEVEL=info
 
-# Pages the search body index walks per resource (SDK default 250 = 25,000 records). Lower it when
-# the tenant's assets are numerous enough to evict article bodies from the 64 MB text budget: the
-# article walk must fit with room to spare or every search answers body-blind. 40 covers ~4,000
-# articles and caps assets at ~4,000.
-HUDU_SEARCH_MAX_INDEX_PAGES=40
-
-# The read-through cache the SDK clients use (SDK 0.12.0). on (the default) selects the SDK's
-# per-entity TTL preset (1 h structural / 5 min mutable / 1 min base): repeated reads of the
-# same record are served from the cache until the TTL expires. off disables it: every read
-# re-dials Hudu.
-# HUDU_CACHE_PRESET=on
-
-# The 429 cooldown gate (SDK 0.12.0). on (the default) arms a local deadline after a vendor
-# 429 whose retries are spent (the profile's 1 retry: the first such call dials twice): calls
-# the gate refuses are answered locally with notSent: true, never re-dialed. off
-# retries a 429 per the agent profile's retry budget instead of arming a local deadline.
-# HUDU_COOLDOWN=on
-
-# The whole-call deadline in milliseconds (SDK 0.12.0). Must be a positive integer. Defaults
-# to 30000 and is always sent to the SDK explicitly, so it stays above the agent profile's
-# 20 s deadline regardless of preset: the default keeps the tolerance a cold tier:'index'
-# body-index walk had before the 0.12.0 adoption.
-# HUDU_TIMEOUT_MS=30000
-
 # The resources hudu_search and hudu_resolve_any may offer and query. Unset means the SDK's full
 # searchable set (articles, asset_passwords, assets, companies, groups, password_folders, users,
 # websites). Set it to the subset THIS deployment's Hudu API key can read, so a tool neither

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.3.0
+
+**Upgrading from 0.2.3: breaking changes.** (1) Article bodies through `hudu_read` / `hudu_write` / `hudu_delete` are Markdown by default. (2) `HUDU_CACHE_PRESET`, `HUDU_COOLDOWN`, `HUDU_TIMEOUT_MS` and `HUDU_SEARCH_MAX_INDEX_PAGES` are removed and a set one now fails boot. (3) `hudu_list_companies` / `_articles` / `_assets` / `_asset_layouts` are replaced by `hudu_list(resource)`. (4) Served tool definitions drop `_meta`. (5) The repository uses pnpm. The SDK is pinned exactly to node-hudu 0.16.0 (plan hash `fba0aa46...`); 0.15.0 was never published. `HUDU_READ_ONLY` is NOT removed: `true` is a hard override (see below). **UPGRADE HAZARD:** on 0.2.3 an UNSET `HUDU_READ_ONLY` meant read-only. Now only `HUDU_WRITE_POLICY` decides when it is unset, so these two configs, with `HUDU_READ_ONLY` unset, now give the model `hudu_write` / `hudu_delete`: (a) `HUDU_WRITE_POLICY=all`; (b) `HUDU_WRITE_POLICY=allow_list` with a non-empty `HUDU_WRITE_ALLOW`. Set `HUDU_READ_ONLY=true` to keep them read-only. The server logs a warning at boot in exactly this case.
+
+
+- Behaviour change: `hudu_read` / `hudu_write` / `hudu_delete` serve and accept article bodies as Markdown (node-hudu `contentFormat: 'markdown'`). Bodies that open with block HTML are still sent as HTML.
+- Tooling: the repository moves from npm to pnpm (`pnpm-lock.yaml`, `pnpm-workspace.yaml`, `packageManager`); the Dockerfile and CI use pnpm, and the runtime image carries no package manager. Contributors run `pnpm install`.
+- The MCP handshake reports the package version (it was hardcoded 0.1.0).
+- CLI: `--version` and `--help` work without configuration. The package no longer ships source maps or `.d.ts` files. The SDK's tracker references ("issues #70/#72") are stripped from served tool descriptions.
+- CI: adds `pnpm audit --prod` and a container job (build, no package manager, fail-fast boot, non-default port, origin guard).
+- Dependency: node-hudu 0.13.2 to 0.14.0 (Hudu Markdown dialect, `articles.getSection`, `articles.patchSection`); catalog plan hash and reachable-operation counts updated for the two new operations.
+- Dependency: node-hudu 0.14.0 -> 0.16.0 (0.15.0 was never published). New discoverable operations: `articles.pin`, `articles.unpin`, `asset_passwords.listShares` / `getShare` / `createShare` / `deleteShare`; no served tool added. `asset_layouts.create` / `update` now send the body nested under `asset_layout` (SDK fix: fields were silently dropped). Plan hash re-stamped to `fba0aa46...`.
+- `hudu_resolve_any` returns `unauthorized` (resources the credential may not read) beside the permitted hits; it errors only when every requested resource refuses. The dispatcher path returns it too.
+- `hudu_get_company_context` accepts `opts.skip` and returns `skipped`.
+- Share operations: refused under the default `HUDU_SECRET_READS=deny`; `createShare` is never runnable (the SDK needs `reveal`, this server never grants it) and is listed unreachable.
+- Fix: the `hudu_search` default-tier sentence rewrite matched stale SDK text, so `auto` and narrowed deployments advertised a false `index` default; it now fails loudly if the anchor drifts.
+- Discovery no longer names tools this server does not serve (`hudu_get_asset_password`, `hudu_get_website`).
+- Served surface: `$schema` and safe-integer `maximum` stripped, SDK dispatcher field text served verbatim, shorter article-format note and `hudu_search` `query` text; an intermediate 46.3 / 40.8 KB. A size-gate test ratchets both.
+- Mermaid is stored in the bare editor-native `<pre class="language-mermaid">` form (SDK 0.16.0); round-trip test added.
+- Breaking: the four `hudu_list_companies` / `hudu_list_articles` / `hudu_list_assets` / `hudu_list_asset_layouts` tools are replaced by one `hudu_list` with a `resource` argument. Filters move inside `filters`; an unaccepted filter is refused, `asset_layouts` refuses `page_size`. A call to an old name answers with a pointer to `hudu_list`. Same bounds and pagination as before. Resync tool catalogs.
+- Breaking (metadata): served tool definitions no longer carry `_meta` (`backingOperation`, `sensitive`, `requiresApproval`, ...).
+- Served surface after these: 19 tools / 39.5 KB write-enabled, 17 tools / 33.9 KB read-only (`tools/list`), down from 22 / 50.1 KB and 20 / 43.7 KB on node-hudu 0.16.0.
+- Markdown article reads (`hudu_read` `articles.get` / `getContext` / `resolve`, `hudu_get_article_context`) that lose content the dialect cannot express (e.g. an inline `<svg>`) now set `markdown_lossy: true` and `markdown_lossy_codes` and add one sentence to the result text; a lossless read is byte-identical to before. Detection uses the SDK's `diffArticleRoundTrip` (content-impact findings only).
+- `allow_list` registers `hudu_write` only when the list holds a write-effect operation and `hudu_delete` only when it holds a destructive-effect one (previously both). `all` registers both; `deny` and `HUDU_READ_ONLY=true` neither. The boot log states which were registered.
+- `HUDU_WRITE_POLICY` (`deny` default | `allow_list` | `all`) is the write switch; `deny` registers no `hudu_write` / `hudu_delete` tool. Allowing a write also allows the writes it delegates to (`articles.patchSection` -> `articles.update`). `HUDU_READ_ONLY=true` stays a HARD OVERRIDE: no write or delete tool and every mutation refused, whatever `HUDU_WRITE_POLICY` / `HUDU_WRITE_ALLOW` say; unset or `false` leaves `HUDU_WRITE_POLICY` in charge. The effective policy is logged once at boot.
+- Behaviour note: on 0.2.3 an UNSET `HUDU_READ_ONLY` defaulted to true (read-only). It is now unset = `HUDU_WRITE_POLICY` decides, so a deployment that sets `HUDU_WRITE_POLICY=allow_list` or `all` without `HUDU_READ_ONLY=true` gets the write tools. Set `HUDU_READ_ONLY=true` to keep a deployment read-only regardless.
+- Breaking: `HUDU_CACHE_PRESET`, `HUDU_COOLDOWN`, `HUDU_TIMEOUT_MS` and `HUDU_SEARCH_MAX_INDEX_PAGES` are removed; the SDK client now uses the fixed agent profile, recommended cache, a 30 s timeout and an armed cooldown. A set one fails boot.
+- `hudu_get_article_context` returns Markdown; `hudu_read`, `hudu_write`, `hudu_list` and `hudu_fetch_many` descriptions state which paths speak Markdown and which carry stored HTML.
+- Tests: Markdown read and write loss-guard coverage through the dispatchers.

package/README.md

@@ -3,29 +3,32 @@
 MCP server for Hudu IT documentation, built on the [`node-hudu`](https://www.npmjs.com/package/node-hudu) SDK.
 
 ## Tool surface
-
-20 tools by default: `hudu_list_operations`, `hudu_describe_operation`, `hudu_read`,
-`hudu_fetch_many`, twelve core reads, and four bounded list reads. Setting
-`HUDU_READ_ONLY=false` adds `hudu_write` and `hudu_delete` (22 tools). Each dispatcher uses a
-separate SDK client in its matching mode,
-with names, annotations and operation enums from the SDK's curated metadata. SDK enforcement
-rejects cross-effect calls before requests. The old `hudu_invoke`, `hudu_catalog` and
-`hudu_describe` names are removed; consumers must resync their tool catalog.
-
-The four list tools each wrap exactly ONE fixed registry operation (`companies.list` /
-`articles.list` / `assets.listAcrossCompanies` / `asset_layouts.list`), take exactly one page and
-accept no operation selector or nested invocation, so an ungated Reader can page companies,
-articles, assets or asset layouts without using a registry dispatcher and without exposing the write
-surface. The first three take `page` / `page_size` (capped at 100); `hudu_list_asset_layouts` takes
-`page` only, because `/asset_layouts` ignores `page_size` — a caller bound would truncate a vendor
-page and skip rows as `page` advanced, so the tool returns the vendor page whole and page N is
-always the vendor's Nth page. For the searchable resources (`companies` / `articles` /
-`assets`) a resource excluded by `HUDU_SEARCH_RESOURCES` is refused by the list tool too, before any
-request; `asset_layouts` is not searchable (the SDK declares no vendor text filter for it), so
-`hudu_list_asset_layouts` follows the same reachability as the existing ungated
-`hudu_get_asset_layout` tool.
-
-These tools run on node-hudu 0.13.2; 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.
+17 tools by default: `hudu_list_operations`, `hudu_describe_operation`, `hudu_read`,
+`hudu_fetch_many`, twelve core reads, and `hudu_list`. Setting `HUDU_WRITE_POLICY` `allow_list` or
+`all` adds `hudu_write` and `hudu_delete` (19 tools). Each dispatcher uses a separate SDK client in
+its matching mode; names, annotations and the dispatcher field text are the SDK's curated metadata.
+SDK enforcement rejects cross-effect calls before any request. The old `hudu_invoke`,
+`hudu_catalog` and `hudu_describe` names are removed; consumers must resync their tool catalog.
+
+`hudu_list(resource)` replaces the four `hudu_list_companies` / `hudu_list_articles` /
+`hudu_list_assets` / `hudu_list_asset_layouts` tools of 0.2.x (a call to an old name answers with a
+pointer to `hudu_list`). `resource` selects one of four fixed registry operations (`companies.list` /
+`articles.list` / `assets.listAcrossCompanies` / `asset_layouts.list`); the tool takes exactly one
+page and accepts no operation selector or nested invocation, so an ungated reader can page these
+collections without the registry dispatcher and without exposing the write surface. Filters go in
+`filters`; each resource accepts only its own set, and any other key is refused naming the accepted
+ones (never dropped, which would turn a company-scoped request into an account-wide one). Companies,
+articles and assets take `page` / `page_size` (capped at 100); `asset_layouts` takes `page` only,
+because `/asset_layouts` ignores `page_size`: a caller bound would truncate the vendor page and skip
+rows as `page` advanced, so the tool returns the vendor page whole and page N is always the
+vendor's Nth page. For searchable resources (`companies` / `articles` / `assets`) a resource
+excluded by `HUDU_SEARCH_RESOURCES` is refused by the list tool too, before any request;
+`asset_layouts` is not searchable (the SDK declares no vendor text filter for it), so it follows the
+same reachability as the existing ungated `hudu_get_asset_layout` tool. The tool set is the SDK's
+`CORE_TOOLS` plus `hudu_list`, which is this server's own; a future SDK upgrade must not re-add the
+four old names.
+
+These tools run on node-hudu 0.16.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
@@ -33,7 +36,7 @@ numeric vendor id, and an optional client-side field projection. A shape violati
 the schema layer before any request, and failure is per-item: a miss or a vendor fault lands on
 its own row as a typed error while the rest of the batch is served. The deployment's secret-read
 policy applies to the batch's items exactly as to a single read, so a credential item is
-refused pre-request under the default `HUDU_SECRET_READS=deny`; `HUDU_READ_ONLY` keeps the tool
+refused pre-request under the default `HUDU_SECRET_READS=deny`; `HUDU_WRITE_POLICY=deny` keeps the tool
 — it is a read. The same batch stays reachable through `hudu_read` with operation
 `operations.fetchMany`, gated the same way.
 
@@ -47,7 +50,7 @@ refused pre-request under the default `HUDU_SECRET_READS=deny`; `HUDU_READ_ONLY`
 ## Local use (stdio)
 
 Needs Node 24+, a Hudu API key and your Hudu origin. `stdio` is the default transport, so no
-`MCP_TRANSPORT` is needed. Mutation tools stay off unless you set `HUDU_READ_ONLY=false`.
+`MCP_TRANSPORT` is needed. Mutation tools stay off unless you set `HUDU_WRITE_POLICY`.
 
 **From npm** (recommended):
 
@@ -74,7 +77,7 @@ or in `.mcp.json` / Claude Desktop config:
 `npx` fetches the package on first run and caches it; use `iit-mcp-hudu@<version>` to pin one.
 
 **From a clone** (for development): see [Development](#development). Point your client at
-`node /absolute/path/to/iit-mcp-hudu/dist/main.js` after `npm run build`.
+`node /absolute/path/to/iit-mcp-hudu/dist/main.js` after `pnpm run build`.
 
 ## Loading credential values (read this before a live session)
 
@@ -121,7 +124,7 @@ whose envelope names a shape anomaly (`credentialShape: "anomalous"`) points bac
 The server enforces the shape itself, so a bad load cannot reach the wire even if `doctor` is
 skipped: a malformed `HUDU_API_KEY` fails boot; a malformed `X-Hudu-Api-Key` header is refused
 before any client is built, with the typed `CREDENTIAL_MALFORMED` envelope (value-free, and
-`retryable: false`). Neither path dials. Since node-hudu 0.13.2 the SDK enforces credential shape
+`retryable: false`). Neither path dials. Since node-hudu 0.14.0 the SDK enforces credential shape
 itself too — refusing a contaminated value at client construction and attaching a value-free shape
 diagnostic to a refused credential — and this server consumes that diagnostic directly on a 401;
 the server's own gate stays as the boundary guard, a superset of the SDK's checks.
@@ -176,16 +179,21 @@ every tool call, with the error naming the missing header. A
 credential header sent twice (which Node would otherwise join with `", "`) is treated as absent
 for the same reason.
 
-`HUDU_READ_ONLY=true` is the default and omits both mutation tools entirely, regardless of
-write policy. To enable mutations, explicitly set it to `false` and configure
-`HUDU_WRITE_POLICY`: `deny` rejects all mutations, `allow_list` permits only the canonical
-keys in `HUDU_WRITE_ALLOW`, and `all` permits the SDK's mutation surface. An empty or invalid
-allow-list fails startup. The SDK clients receive the same allow-list plus reads needed by
-helper dependencies; client mode and effect dispatch remain independent restrictions.
+`HUDU_WRITE_POLICY` is the write switch. `deny` (the default) omits `hudu_write` and
+`hudu_delete` entirely; `allow_list` permits only the canonical keys in `HUDU_WRITE_ALLOW` and
+registers `hudu_write` only if the list holds at least one write-effect operation, and `hudu_delete`
+only if it holds at least one destructive-effect one (per the SDK registry's effect) (a write allowed here also allows the writes it delegates to: allowing
+`articles.patchSection` allows `articles.update`); `all` permits the SDK's whole mutation surface.
+An empty or invalid allow-list fails startup. The SDK clients receive the same allow-list plus
+reads needed by helper dependencies.
 Writes default to dry-run previews; execution requires `dry_run:false`, and destructive
 operations additionally require exact `confirm`. A confirmation string is not human consent.
 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.
+
 `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
 to trust and cannot be allowed to widen this server's surface: the server-side policy is the floor,
@@ -211,6 +219,19 @@ without `expand`. It is independent of `HUDU_WRITE_POLICY`: `all` does not imply
 `allow` does not open writes. `hudu_search` is unaffected — it already redacts hits on those two
 resources. Refusals are `POLICY_DENIED` and appear as unreachable rows in `hudu_list_operations`.
 
+Password share links (node-hudu 0.16.0): `asset_passwords.listShares`, `getShare`, `createShare` and
+`deleteShare` are credential-resource operations, so they are refused under the default
+`HUDU_SECRET_READS=deny`; the two writes also need `HUDU_WRITE_POLICY` (or `HUDU_WRITE_ALLOW`) to permit
+them. Under `allow`, `listShares` / `getShare` work and the share `url` (a bearer link) is masked.
+`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.
+
+`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
+`skipped` set, and no request is made for it. `hudu_resolve_any` returns `unauthorized` (the resources the
+credential may not read) beside the permitted hits; it errors only when every requested resource refuses.
+
 All SDK clients keep default redaction enabled, including when `HUDU_SECRET_READS=allow`.
 That flag permits credential-resource operations; it never enables plaintext results. The
 SDK masks credential fields and confidential or unclassified custom fields as `[REDACTED]`.
@@ -238,17 +259,35 @@ background, so a caller's later search is body-aware without the first one await
 walk (some clients enforce a 60s call timeout). Under `stdio` the one long-lived index stays warm and the
 default is `"index"`. Pass `tier:"index"` explicitly for a complete first answer.
 
-Three 0.12.0 preset knobs are env-tunable, each defaulting to the adopted behaviour.
-`HUDU_CACHE_PRESET` (`on` | `off`) toggles the read-through cache: the default `on` selects
-the SDK's `recommended` per-entity TTL preset, and `off` disables it, so repeated reads
-re-dial Hudu instead of being served from the cache.
-`HUDU_COOLDOWN` (`on` | `off`) is the 429 cooldown gate: `off` means a 429 retries per the
-agent profile instead of arming a local deadline whose refusals answer with `notSent: true`.
-`HUDU_TIMEOUT_MS` (positive integer milliseconds) is the whole-call deadline, default `30000`;
-it is always sent to the SDK explicitly, so it stays above the profile's 20 s.
+The read-through cache (SDK `recommended` preset), the 429 cooldown gate and the 30 s whole-call deadline are fixed, not env-tunable.
 `blockPrivateHosts` deliberately gets no override: it is the literal-IP SSRF floor for
 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_list` (articles),
+`hudu_fetch_many`, `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>`,
+  `<h1>`-`<h6>`, `<table>`, lists, `<pre>`, `<blockquote>`, `<hr>`, Hudu's `mce-accordion`), in which case
+  it is sent as HTML. Re-read an article through `articles.get` before editing it.
+- A Markdown write is refused when the stored article holds something the dialect cannot express
+  (for example an inline `<svg>`); 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.
+- A Markdown read can be incomplete: anything the dialect cannot express (an inline `<svg>`, say) comes
+  back as plain text. `hudu_read` (`articles.get` / `getContext` / `resolve`) and
+  `hudu_get_article_context` 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 with HTML forced and converted locally (so there is no second request); a caller's own
+  `opts.format: "html"` returns the stored HTML untouched with no flag. Callouts, accordions, task
+  lists and Mermaid round-trip cleanly and are never flagged; a lossless read is unchanged.
+
 ## SDK behaviour (0.12.0)
 
 Three SDK behaviours changed in the 0.12.0 line and shape a deployment:
@@ -284,13 +323,13 @@ Every client the server builds — the parent, the fail-closed placeholders and
   (1 retry, 240/min rate limit, concurrency 3, bounded resolution scans). The rate-limit bucket
   is per client, i.e. per scope. The preset stays a deployment-wide constant with no env
   override; the one deadline it would otherwise govern is pinned explicitly instead
-  (`HUDU_TIMEOUT_MS`, below), and the 429 now arms the cooldown gate instead of retrying
+  (a fixed 30 s, below), and the 429 now arms the cooldown gate instead of retrying
   blindly.
-- `cache: 'recommended'` — env-toggled as `HUDU_CACHE_PRESET` (default `on`): the
+- `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. `off` disables the read-through cache: repeated reads re-dial Hudu.
+  unbounded.
 - `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
@@ -299,20 +338,17 @@ Every client the server builds — the parent, the fail-closed placeholders and
   env boundary and is never floor-checked, so an on-prem install whose Hudu sits on a literal
   private IP is unaffected by the upgrade. Deliberately no env override: it is a security
   property, not a deployment preference.
-- `cooldown: { enabled: true }` — env-tunable as `HUDU_COOLDOWN` (default `on`): the 429
+- `cooldown: { enabled: true }` — fixed on: the 429
   cooldown gate; a call refused locally by the gate answers with `notSent: true` in the error
   envelope, so a model does not read a local refusal as a vendor rejection of a sent call.
-  `off` retries a 429 per the profile instead of arming a local deadline.
 
-The whole-call deadline is `HUDU_TIMEOUT_MS` (positive integer milliseconds, default `30000`):
+The whole-call deadline is a fixed `30000` ms:
 it is always passed to the SDK explicitly, so it stays above the agent profile's 20 s
 regardless of preset — the preset's 20 s would shorten a cold `tier:'index'` body-index walk
 that the 0.9.2 deployment tolerated at the SDK's 30 s, and a cold-scope search must not start
 timing out because of an upgrade.
 
-These are deployment-wide, not per-caller: `HUDU_CACHE_PRESET`, `HUDU_COOLDOWN` and
-`HUDU_TIMEOUT_MS` are env-tunable with the defaults above, while `profile` and
-`blockPrivateHosts` stay constants.
+These are deployment-wide constants, not per-caller and not env-tunable.
 
 
 ## Development
@@ -320,16 +356,16 @@ These are deployment-wide, not per-caller: `HUDU_CACHE_PRESET`, `HUDU_COOLDOWN`
 ```
 git clone https://github.com/msoukhomlinov/iit-mcp-hudu.git
 cd iit-mcp-hudu
-npm install
-npm run build
-npm test
-npm run dev
+pnpm install
+pnpm run build
+pnpm test
+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.13.2`. The catalog hash test detects metadata drift; upgrades require
-review of the client authority, operation enums and redaction regressions. Docker uses `npm ci`.
+`node-hudu` is pinned to `0.16.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/auth.js

@@ -81,4 +81,3 @@ export function headerRecord(headers) {
     });
     return out;
 }
-//# sourceMappingURL=auth.js.map

package/dist/base-hosts.js

@@ -36,4 +36,3 @@ export function originOf(url) {
         return undefined;
     }
 }
-//# sourceMappingURL=base-hosts.js.map

package/dist/config.js

@@ -135,18 +135,6 @@ const schema = z
      */
     HUDU_ALLOW_ANY_BASE_HOST: z.enum(['true', 'false']).default('false').transform((value) => value === 'true'),
     MCP_TRANSPORT: z.enum(TRANSPORTS).default('stdio'),
-    /**
-     * Pages the body index walks per resource per build (SDK default 250 = 25,000 records).
-     *
-     * Tenant-shaped, so it is a knob rather than a constant. The walk runs articles first and assets
-     * second, and both compete for one 64 MB text budget that evicts least-recently-read text: on a
-     * tenant with tens of thousands of assets the asset text arrives last, so the ARTICLE BODIES are
-     * the first thing evicted — and article bodies are the only reason this index exists (assets
-     * carry no body, and Hudu's own ?search= already covers their titles and fields). Sizing this so
-     * the article walk completes with budget left over is what keeps searches from going body-blind.
-     * A tenant with 3,000+ articles needs about 32 pages.
-     */
-    HUDU_SEARCH_MAX_INDEX_PAGES: z.coerce.number().int().min(1).max(1000).optional(),
     /**
      * The resources `hudu_search` may offer and query — the read-edge counterpart to
      * `HUDU_WRITE_POLICY`.
@@ -156,15 +144,21 @@ const schema = z
      * resources THIS credential can read so the tool never advertises a guaranteed-empty search and
      * a model never spends a turn on a resource the key is not allowed to read. Every name is
      * validated against the SDK's searchable set at boot, so a typo fails the container instead of a
-     * call weeks later. Applies to `hudu_search` only; the dedicated resolve tools are unaffected.
+     * call weeks later. Applies to `hudu_search`, `hudu_resolve_any` and the same operations through `hudu_read`; the dedicated per-resource resolve tools are unaffected.
      */
     HUDU_SEARCH_RESOURCES: z.string().optional().transform(parseSearchResources),
     /**
-     * Whether `hudu_read / hudu_write / hudu_delete` may reach a `write` or `destructive` operation at all. Read/`null`
-     * effects are never touched by this policy. Defaults to `deny` — see {@link WRITE_POLICIES}.
+     * The single switch for mutation. `deny` (the default) registers no `hudu_write` / `hudu_delete`
+     * tool at all; `allow_list` and `all` register them and gate every call. Read effects are never
+     * touched. See {@link WRITE_POLICIES}.
      */
-    HUDU_READ_ONLY: z.enum(['true', 'false']).default('true').transform((value) => value === 'true'),
     HUDU_WRITE_POLICY: z.enum(WRITE_POLICIES).default('deny'),
+    /**
+     * Hard override. `true` means no `hudu_write` / `hudu_delete` tool and no write or destructive
+     * operation, whatever `HUDU_WRITE_POLICY` / `HUDU_WRITE_ALLOW` say (see {@link applyReadOnly}).
+     * Unset or `false` leaves `HUDU_WRITE_POLICY` in charge (its default is `deny`).
+     */
+    HUDU_READ_ONLY: z.enum(['true', 'false']).optional().transform((value) => value === 'true'),
     /**
      * The operation keys `HUDU_WRITE_POLICY=allow_list` permits. Read only under `allow_list`;
      * ignored under `deny`/`all`. Exposed as the parsed array so no consumer re-splits the string.
@@ -183,33 +177,6 @@ const schema = z
     HUDU_SECRET_READS: z.enum(SECRET_READ_POLICIES).default('deny'),
     PORT: z.coerce.number().int().positive().max(65535).default(8787),
     LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
-    /**
-     * The read-through cache preset every client this server builds gets (SDK 0.12.0).
-     *
-     * The operator-facing toggle for the read-through cache. `on` (the default) selects the
-     * SDK's `recommended` per-entity TTL preset (1 h structural / 5 min mutable / 1 min base);
-     * `off` disables the read-through cache, so a repeated read re-dials Hudu instead of
-     * being served from the cache.
-     */
-    HUDU_CACHE_PRESET: z.enum(['on', 'off']).default('on'),
-    /**
-     * The 429 cooldown gate (SDK 0.12.0).
-     *
-     * `on` (the default) arms a local deadline after a vendor 429 whose retries are SPENT (the
-     * agent profile's 1 retry, so the first such call makes two wire attempts): calls the gate
-     * then refuses locally, and the error envelope marks them `notSent: true` so a local
-     * refusal stays distinguishable from a vendor rejection of a sent call. `off`
-     * retries a 429 per the profile's retry budget instead of arming a local deadline.
-     */
-    HUDU_COOLDOWN: z.enum(['on', 'off']).default('on'),
-    /**
-     * The whole-call deadline in milliseconds (SDK 0.12.0). Positive integer.
-     *
-     * Defaults to 30000 and is always passed to the SDK explicitly, so it wins over the
-     * agent profile's 20 s deadline regardless of preset; the default keeps the tolerance
-     * a cold `tier:'index'` body-index walk had before the 0.12.0 adoption.
-     */
-    HUDU_TIMEOUT_MS: z.coerce.number().int().positive().default(30000),
 })
     .superRefine((c, ctx) => {
     // Pre-dial integrity check (2026-10-07 Autotask incident class): a credential whose bytes were
@@ -371,15 +338,28 @@ function checkCredentialShape(value, ctx, path) {
  * @throws {ConfigError} when any variable is missing or malformed. The message lists every problem
  *   at once — a boot loop that surfaces one missing variable per restart wastes real minutes.
  */
+/** Variables removed in 0.3.0. A stale one must fail boot rather than be ignored silently. */
+const REMOVED_VARS = ['HUDU_CACHE_PRESET', 'HUDU_COOLDOWN', 'HUDU_TIMEOUT_MS', 'HUDU_SEARCH_MAX_INDEX_PAGES'];
 export function loadConfig(env = process.env) {
+    const stale = REMOVED_VARS.filter((name) => env[name] !== undefined);
+    if (stale.length > 0) {
+        throw new ConfigError(`Invalid configuration:\n  ${stale.join(', ')}: removed in 0.3.0; delete it. HUDU_WRITE_POLICY (deny | allow_list | all) governs writes, with HUDU_READ_ONLY=true as a hard override.`);
+    }
     const parsed = schema.safeParse(env);
     if (parsed.success)
         return parsed.data;
     const problems = parsed.error.issues.map((i) => `  ${i.path.join('.') || '(config)'}: ${i.message}`);
     throw new ConfigError(`Invalid configuration:\n${problems.join('\n')}`);
 }
+/**
+ * The configuration the server actually runs with: `HUDU_READ_ONLY=true` forces the policy to
+ * `deny` (no write or delete tool is registered and every write is refused), whatever
+ * `HUDU_WRITE_POLICY` / `HUDU_WRITE_ALLOW` say. Otherwise the config is returned unchanged.
+ */
+export function applyReadOnly(config) {
+    return config.HUDU_READ_ONLY ? { ...config, HUDU_WRITE_POLICY: 'deny', HUDU_WRITE_ALLOW: [] } : config;
+}
 /** Thrown only by {@link loadConfig}. Never carries a credential value — only variable names. */
 export class ConfigError extends Error {
     name = 'ConfigError';
 }
-//# sourceMappingURL=config.js.map

package/dist/credential.js

@@ -112,4 +112,3 @@ export function reportCredential(env, name) {
         return { present: false };
     return { present: true, shape: describeCredential(raw) };
 }
-//# sourceMappingURL=credential.js.map

package/dist/doctor.js

@@ -76,4 +76,3 @@ export function runDoctor(config) {
         notes,
     };
 }
-//# sourceMappingURL=doctor.js.map

package/dist/http.js

@@ -146,4 +146,3 @@ export function startHttpServer(config, mcp, log, exit = process.exit) {
     server.listen(config.PORT, () => log.info('listening', { port: config.PORT, transport: 'http' }));
     return server;
 }
-//# sourceMappingURL=http.js.map

package/dist/lifecycle.js

@@ -49,4 +49,3 @@ export function installHttpLifecycle(server, log, exit = process.exit) {
 function describe(value) {
     return value instanceof Error ? (value.stack ?? value.message) : String(value);
 }
-//# sourceMappingURL=lifecycle.js.map

package/dist/logger.js

@@ -23,4 +23,3 @@ export function createLogger(minLevel = 'info', write = (l) => process.stderr.wr
     };
     return { debug: at('debug'), info: at('info'), warn: at('warn'), error: at('error') };
 }
-//# sourceMappingURL=logger.js.map

package/dist/main.js

@@ -5,8 +5,10 @@
  * Nothing else lives here. Both transports register the same tool surface from the same factory
  * (`createMcpServerFactory`), so "which transport" is the only decision this file makes.
  */
+import { createRequire } from 'node:module';
 import { createMcpHandler } from '@modelcontextprotocol/server';
 import { ConfigError, loadConfig } from './config.js';
+import { logEffectiveWritePolicy } from './policy.js';
 import { runDoctor } from './doctor.js';
 import { createLogger } from './logger.js';
 import { installHttpLifecycle } from './lifecycle.js';
@@ -43,7 +45,27 @@ function runDoctorCommand() {
     // the dial the report just said not to make.
     process.exit(report.ok ? 0 : 1);
 }
+const USAGE = `iit-mcp-hudu: MCP server for Hudu IT documentation
+
+Usage:
+  iit-mcp-hudu            serve (MCP_TRANSPORT=stdio|http, configured by environment)
+  iit-mcp-hudu doctor     zero-wire credential preflight
+  iit-mcp-hudu --version  print the version
+  iit-mcp-hudu --help     print this help
+
+Configuration is environment-only; see .env.example in the package.
+`;
 function main() {
+    // Answered before config is loaded, so they work with no credentials.
+    const flag = process.argv[2];
+    if (flag === '--version' || flag === '-v') {
+        process.stdout.write(`${createRequire(import.meta.url)('../package.json').version}\n`);
+        return;
+    }
+    if (flag === '--help' || flag === '-h') {
+        process.stdout.write(USAGE);
+        return;
+    }
     // `doctor` is matched before anything else, so it never builds a logger, a transport or a client.
     if (process.argv[2] === 'doctor') {
         runDoctorCommand();
@@ -64,6 +86,7 @@ function main() {
         throw err;
     }
     const log = createLogger(config.LOG_LEVEL);
+    logEffectiveWritePolicy(config, log, process.env);
     if (config.MCP_TRANSPORT === 'http'
         && config.HUDU_BASE_URL === undefined
         && config.HUDU_ALLOWED_BASE_HOSTS === undefined) {
@@ -89,4 +112,3 @@ function main() {
     installHttpLifecycle(server, log);
 }
 main();
-//# sourceMappingURL=main.js.map