iit-mcp-hudu 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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.
+
+- Docs: `articles.getSection` carries no `markdown_lossy` signal (node-hudu drops `content_loss` inside `readSection`); the README now says so and a test pins it. Read the whole article with `articles.get` to learn whether a body is lossy.
+- Behaviour change: `hudu_list` serves compact summary rows by default (the node-hudu `*Summary` field sets, plus `url` / `created_at` / `updated_at`) instead of full records, cutting a default page from ~49-88k to under 20k characters. `expand: true` returns the full records as before. Envelope, `page_size` default 25 and `asset_layouts` paging (no `page_size`) are unchanged. Callers that read custom `fields`, article `content` or layout `fields` from list rows must pass `expand: true` (issue #22).
+- Fix: the 401 shape annotation is bound to the call (AsyncLocalStorage) instead of module-level state written per request, so under http a 401 never carries another concurrent request's credential anomalies (#16).
+- Fix: a 401 is annotated only with the anomalies of the credential actually presented on that call (the request key wins over the server-held `HUDU_API_KEY`; the env key's anomalies join only when it is the one dialed), and `hudu_search`'s fully-refused branch now carries the same annotation as every other tool (#16).
+- Fix: `hudu_search` and `hudu_read` `operations.searchKnowledge` / `operations.searchAcrossResources` now refuse a malformed `x-hudu-api-key` (`CREDENTIAL_MALFORMED`) and an origin outside the allow-list (the `AUTH_ERROR` envelope other tools return) before any request, instead of returning a successful 0-hit result (#32).
+- Fix: the same search paths now refuse every other refusing client state (key with no origin, invalid base URL, keyless request) with the `AUTH_ERROR` envelope, and `hudu_fetch_many` / `hudu_read` `operations.fetchMany` return that top-level refusal for a whole-batch credential or origin refusal instead of `ok: 0, failed: 1` with per-item errors; a genuine per-item vendor failure still lands on its row. A keyless `hudu_search` is no longer a soft 0-hit result (#35).
+- Dependency: node-hudu 0.16.0 -> 0.17.0. Plan hash re-stamped to `1ad5e23b...`; operation set unchanged (236).
+- Markdown article reads take their loss signal from the SDK: node-hudu now attaches `content_loss` to the record on a Markdown read, so the server no longer forces HTML and converts and diffs the body itself. `markdown_lossy` / `markdown_lossy_codes` are unchanged; the per-record `content_loss` is lifted into them and not passed through.
+- Behaviour change: inline `<svg>` and `<iframe>` now survive Markdown reads and writes (they were flagged lossy and writes over them were refused). A body that converts to nothing reads as an empty body flagged `ROUNDTRIP_BODY_EMPTY` instead of failing.
+- Docs: decision record for per-user identity (`docs/decisions/per-user-identity.md`): do not build the Hudu account link now; Entra sign-in plus server-side per-user policy and audit instead.
+
 ## 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.

package/README.md

@@ -26,9 +26,12 @@ excluded by `HUDU_SEARCH_RESOURCES` is refused by the list tool too, before any
 `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.
+four old names. Rows are compact summaries by default (id, name, key scalar fields, `url`,
+`created_at`, `updated_at`; no custom-field values, article bodies or layout field definitions), which keeps a
+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.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.
+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.
 
 `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
@@ -268,25 +271,29 @@ caller-named origins — a security property, not a deployment preference.
 `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:
+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:
 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.
+  (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.
-- 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
+  `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.
+- 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
   `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
+  fetch: the SDK converts the body and reports the loss on the record (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.
+  lists, Mermaid, inline `<svg>` and `<iframe>` round-trip cleanly and are never flagged; a lossless read is unchanged.
+  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.
 
 ## SDK behaviour (0.12.0)
 
@@ -364,7 +371,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.16.0`. The catalog hash test detects metadata drift; upgrades require
+`node-hudu` is pinned to `0.17.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

@@ -1,61 +1,46 @@
 /**
- * article-loss.ts — Markdown article reads, and the signal that one is incomplete.
+ * article-loss.ts — the signal that a Markdown article read is incomplete.
  *
- * Reads return article bodies as Markdown (node-hudu 0.14 dialect); anything Markdown cannot
- * express (an inline <svg>, say) would come back as plain text with no signal, because the SDK keeps
- * loss reporting out of the converter and documents `diffArticleRoundTrip` as the one vocabulary.
- *
- * So the read is made ONCE with `format: 'html'` forced, and the conversion the SDK's own
- * `projectContent` would have done (`htmlToMarkdown`) is done here instead, next to the diff of the
- * stored HTML against `markdownToHtml(htmlToMarkdown(html))`. Always one wire request: no second
- * dispatch, no cache or TTL dependence, no extra 429/cooldown exposure, no read-twice race. Only
- * `impact: 'content'` findings count (presentation-only changes are not loss); the constructs the
- * dialect models (callouts, accordions, task lists, Mermaid) round-trip clean. A caller's own
- * `opts.format: 'html'` is honoured untouched. A conversion failure (empty output, over the size
- * cap) throws the same error the SDK's conversion threw.
+ * Since node-hudu 0.17 a Markdown read reports its own loss: the SDK attaches `content_loss` (the
+ * `ROUNDTRIP_*` findings with `impact: 'content'`) to the article record when the stored body does
+ * not survive HTML -> Markdown -> HTML, and returns an empty body plus `ROUNDTRIP_BODY_EMPTY`
+ * instead of throwing when nothing converts. This lifts those codes out of the result into the
+ * tool's `markdown_lossy` fields and drops the per-record findings, so the result shape is the
+ * same as before. A caller's own `opts.format: 'html'` gets no `content_loss`, hence no flag.
  */
-import { diffArticleRoundTrip } from 'node-hudu';
-import { htmlToMarkdown, markdownToHtml } from 'node-hudu/content';
-/** The reads whose article body is converted, and where `content` sits in the SDK result. */
-const CONTENT_PATHS = {
-    'articles.get': [['content']],
+/** The reads whose article body is converted, and where the article record sits in the SDK result. */
+const RECORD_PATHS = {
+    'articles.get': [[]],
     // resolve answers the record itself; the `{ value }` envelope is the helper form of the same read.
-    'articles.resolve': [['content'], ['value', 'content']],
-    'articles.getContext': [['article', 'content']],
+    'articles.resolve': [[], ['value']],
+    'articles.getContext': [['article']],
 };
-export const MARKDOWN_READ_OPERATIONS = new Set(Object.keys(CONTENT_PATHS));
 const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
-/** Whether the caller asked for HTML itself (then the read is returned as is, with no flag). */
-export const callerWantsHtml = (input) => isObject(input) && isObject(input.opts) && input.opts.format === 'html';
-/** `input` with `opts.format` forced to 'html', merged over the caller's own opts. */
-export function forceHtml(input) {
-    return { ...input, opts: { ...(isObject(input.opts) ? input.opts : {}), format: 'html' } };
-}
-const convert = (node, path, codes) => {
+const take = (node, path, codes) => {
     if (!isObject(node))
         return node;
     const [key, ...rest] = path;
-    const value = node[key];
-    if (rest.length === 0) {
-        if (typeof value !== 'string')
+    if (key === undefined) {
+        if (!Array.isArray(node.content_loss))
             return node;
-        const markdown = htmlToMarkdown(value);
-        for (const f of diffArticleRoundTrip(value, markdownToHtml(markdown)))
-            if (f.impact === 'content')
+        for (const f of node.content_loss)
+            if (typeof f?.code === 'string')
                 codes.add(f.code);
-        return { ...node, [key]: markdown };
+        const record = { ...node };
+        delete record.content_loss;
+        return record;
     }
-    const inner = convert(value, rest, codes);
-    return inner === value ? node : { ...node, [key]: inner };
+    const inner = take(node[key], rest, codes);
+    return inner === node[key] ? node : { ...node, [key]: inner };
 };
-/** The Markdown result for `operation` from its stored-HTML result, plus the content-loss codes (empty when lossless). */
-export function projectMarkdown(operation, htmlResult) {
-    const paths = CONTENT_PATHS[operation];
+/** `result` without the SDK's `content_loss`, plus its codes (empty when the read lost nothing). */
+export function takeContentLoss(operation, result) {
+    const paths = RECORD_PATHS[operation];
     if (paths === undefined)
-        return { result: htmlResult, codes: [] };
+        return { result, codes: [] };
     const codes = new Set();
-    const result = paths.reduce((node, path) => convert(node, path, codes), htmlResult);
-    return { result, codes: [...codes].sort() };
+    const stripped = paths.reduce((node, path) => take(node, path, codes), 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.`;

package/dist/tools/dedicated.js

@@ -56,7 +56,7 @@ export const DEDICATED_READ_TOOLS = {
     hudu_list: {
         // The registry operations `hudu_list(resource)` serves, keyed to the resource it takes.
         covers: ['companies.list', 'articles.list', 'assets.listAcrossCompanies', 'asset_layouts.list'],
-        toolArguments: ['resource', 'page', 'page_size', 'filters'],
+        toolArguments: ['resource', 'page', 'page_size', 'expand', 'filters'],
     },
     hudu_fetch_many: {
         covers: ['operations.fetchMany'],
@@ -213,6 +213,7 @@ function listInputSchema(operation) {
         field('resource', 'string', true, { enum: [resource] }),
         field('page', 'integer', false),
         ...(LIST_RESOURCES[resource].pageSize ? [field('page_size', 'integer', false)] : []),
+        field('expand', 'boolean', false),
         field('filters', 'object', false, { description: `Accepted keys: ${listFilterNames(resource).join(', ')}.` }),
     ]);
 }

package/dist/tools/dispatch.js

@@ -3,8 +3,8 @@ import { getCapability } from 'node-hudu/capabilities';
 import { dispatchOperation, META_TOOLS } from 'node-hudu/mcp';
 import { writeToolRegistered, assertNeverReachablePermitted, assertSecretReadPermitted, assertWritePermitted } from '../policy.js';
 import { redactCompanyContextCredentials } from './company-context-policy.js';
-import { MARKDOWN_READ_OPERATIONS, callerWantsHtml, forceHtml, lossyNote, projectMarkdown } from './article-loss.js';
-import { ARTICLE_FORMAT_NOTE, contextErrorContent, errorContent, createResultBuilders, resolveErrorContent, searchErrorContent, unauthorizedContent } from './results.js';
+import { lossyNote, takeContentLoss } from './article-loss.js';
+import { ARTICLE_FORMAT_NOTE, contextErrorContent, errorContent, createResultBuilders, resolveErrorContent, searchErrorContent, unauthorizedContent, upfrontRefusal } from './results.js';
 import { INVOKE_OUTPUT } from './schemas.js';
 import { FETCH_MANY_OPERATION, applyFetchManyPolicyToInvoke, SEARCH_ACROSS_OPERATION, applyAcrossPolicyToInvoke, credentialRefused, RESOLVE_ANY_OPERATION, SEARCH_KNOWLEDGE_OPERATION, applyResolvePolicyToInvoke, applySearchPolicyToInvoke, sanitizeIndexMeta, sanitizeSearchFailures } from './search-policy.js';
 /** The SDK's curated text cites its own tracker ("(issues #70/#72)"); that is noise to a model and an internal reference. */
@@ -72,12 +72,22 @@ export function registerDispatchTools(server, ctx) {
                     opts.dryRun = dry_run;
                 if (typeof confirm === 'string')
                     opts.confirm = confirm;
-                // Markdown article reads: ONE fetch with HTML forced, converted (and loss-checked) locally.
-                const markdownRead = mode === 'read' && MARKDOWN_READ_OPERATIONS.has(operation) && !callerWantsHtml(bag);
-                let result = await dispatchOperation(client, effect, operation, markdownRead ? forceHtml(bag) : bag, opts);
+                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
+                // 0-hit result (searchKnowledge, an isolating searchAcrossResources) or per-item rows
+                // (fetchMany), so only those answer the typed refusal (a throwing call already carries the SDK's own envelope).
+                const isolating = operation === SEARCH_ACROSS_OPERATION && bag.opts?.isolateErrors === true;
+                // fetchMany folds a whole-batch refusal into per-item rows; a refused client is a top-level error.
+                if (operation === SEARCH_KNOWLEDGE_OPERATION || operation === FETCH_MANY_OPERATION || isolating) {
+                    const refused = upfrontRefusal();
+                    if (refused !== undefined)
+                        return refused;
+                }
+                // A Markdown article read that lost content carries the SDK's content_loss (see article-loss.ts).
                 let lossy = [];
-                if (markdownRead)
-                    ({ result, codes: lossy } = projectMarkdown(operation, result));
+                if (mode === 'read')
+                    ({ result, codes: lossy } = takeContentLoss(operation, result));
                 if (operation === 'companies.getContext') {
                     result = redactCompanyContextCredentials(result, operation, config, log);
                 }

package/dist/tools/fetch-many.js

@@ -1,5 +1,5 @@
 import * as z from 'zod/v4';
-import { ARTICLE_FORMAT_NOTE, errorContent, metaSpec, createResultBuilders } from './results.js';
+import { ARTICLE_FORMAT_NOTE, errorContent, metaSpec, createResultBuilders, upfrontRefusal } from './results.js';
 import { applyFetchManyPolicyToInvoke } from './search-policy.js';
 /**
  * The 22 bare-id resources the batch read serves — the closed `items.resource` enum.
@@ -52,6 +52,10 @@ export function registerFetchManyTool(server, ctx) {
             // The deployment's authority, asserted per item BEFORE any request — the same wrapper the
             // hudu_read dispatch of operations.fetchMany applies, so both paths gate identically.
             applyFetchManyPolicyToInvoke(ctx, { items: args.items });
+            // A refusing client fails every item alike: answer once, as every other tool does.
+            const refused = upfrontRefusal();
+            if (refused !== undefined)
+                return refused;
             const result = await ctx.ops.fetchMany(args.items);
             return ok(`${result.ok} of ${args.items.length} item(s) fetched${result.failed > 0 ? `; ${result.failed} failed — the typed per-item error is on each row` : ''}.`, { ok: result.ok, failed: result.failed, results: result.results });
         }

package/dist/tools/lists.js

@@ -2,8 +2,8 @@ import * as z from 'zod/v4';
 import { getCapability } from 'node-hudu/capabilities';
 import { configError } from 'node-hudu/mcp';
 import { assertSecretReadPermitted, assertWritePermitted } from '../policy.js';
-import { ARTICLE_FORMAT_NOTE, errorContent, createResultBuilders } from './results.js';
-import { LIST_OUTPUT, LIST_PAGE, MAX_LIMIT, DEFAULT_LIMIT } from './schemas.js';
+import { errorContent, createResultBuilders } from './results.js';
+import { EXPAND, LIST_OUTPUT, LIST_PAGE, MAX_LIMIT, DEFAULT_LIMIT } from './schemas.js';
 /** The one dedicated list tool this module registers (exported so tests derive the served set). */
 export const LIST_TOOLS = ['hudu_list'];
 /** The tool names `hudu_list` replaced; a call to one gets a clear pointer instead of "not found". */
@@ -95,6 +95,24 @@ function assertNonSearchableListReadPermitted(operation, ctx) {
     assertWritePermitted(operation, getCapability(operation), config, log);
     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`.
+ */
+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'],
+};
+/** Project rows onto the compact fields; a field the row lacks is omitted, not nulled. */
+export function compactRows(resource, rows) {
+    const keep = COMPACT_FIELDS[resource];
+    return rows.map((row) => {
+        const r = row;
+        return Object.fromEntries(keep.filter((k) => k in r).map((k) => [k, r[k]]));
+    });
+}
 const S = z.string();
 const D = (t, d) => t.optional().describe(d);
 const ID = z.number().int().positive();
@@ -171,20 +189,22 @@ export function registerListTools(server, ctx) {
         description: 'List ONE bounded page of companies, articles, assets (across all companies) or asset_layouts, backed by the fixed operations companies.list / articles.list / assets.listAcrossCompanies / asset_layouts.list. Returns at most page_size rows plus whether more exist; it never pages through the tenant. This tool takes no operation argument and cannot be redirected to a write. ' +
             'Filters go in `filters`; each resource accepts only its own: ' +
             LIST_RESOURCE_NAMES.map((r) => `${r}: ${listFilterNames(r).join(', ')}`).join('; ') +
-            '. A filter the resource does not accept is refused naming the accepted ones. asset_layouts takes no page_size (the vendor ignores it): a page is the vendor’s own size, returned whole, has_more is conservative (true for any non-empty page), stop when a page comes back empty. ' +
+            '. Rows are compact summaries (id, name, scalars, url, created_at, updated_at; no custom fields/bodies); expand: true: full records. A filter the resource does not accept is refused naming the accepted ones. asset_layouts takes no page_size (the vendor ignores it): a page is the vendor’s own size, returned whole, has_more is conservative (true for any non-empty page), stop when a page comes back empty. ' +
             'Prefer hudu_search or hudu_resolve_any to identify one record, and the *_context / hudu_get_asset_layout reads to read one in full. This is the ungated path for these reads; use it rather than the approval-gated hudu_read / hudu_write / hudu_delete.' +
-            ARTICLE_FORMAT_NOTE,
+            ' Article bodies: compact article rows carry none; expand: true returns stored HTML (hudu_get_article_context reads Markdown).',
         // strict: a stray top-level filter (the 0.2.x flat shape) must be refused, never stripped into an account-wide read.
         inputSchema: z.strictObject({
             resource: z.enum(LIST_RESOURCE_NAMES).describe('Which collection to list.'),
             page: LIST_PAGE,
             page_size: z.number().int().min(1).max(MAX_LIMIT).optional().describe(`Rows per page (1-${MAX_LIMIT}, default ${DEFAULT_LIMIT}); refused for asset_layouts, never clamped.`),
+            expand: EXPAND,
             filters: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional().describe('Resource-specific filters (see the tool description).'),
         }),
         outputSchema: LIST_OUTPUT,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {
-        const { resource, page, page_size, filters } = args;
+        const { resource, page, page_size, filters, expand } = args;
+        const shape = (rows) => (expand ? rows : compactRows(resource, rows));
         try {
             const spec = LIST_RESOURCES[resource];
             const operation = spec.operation;
@@ -206,14 +226,14 @@ export function registerListTools(server, ctx) {
                 const answered = await firstPage(pages(resource, { ...parsed.data, page }));
                 if (answered === null)
                     return ok('No asset layouts matched.', { rows: [], page, page_size: 0, has_more: false, count: 0 });
-                return ok(`${answered.items.length} asset layout row(s) on page ${page}; ${answered.hasMore ? 'more pages may exist' : 'no more pages'}.`, { rows: answered.items, page, page_size: answered.page_size, has_more: answered.hasMore, count: answered.items.length });
+                return ok(`${answered.items.length} asset layout row(s) on page ${page}; ${answered.hasMore ? 'more pages may exist' : 'no more pages'}.`, { rows: shape(answered.items), page, page_size: answered.page_size, has_more: answered.hasMore, count: answered.items.length });
             }
             const size = page_size ?? DEFAULT_LIMIT;
             const answered = await firstPage(pages(resource, { ...parsed.data, page, page_size: size }));
             if (answered === null)
                 return ok(`No ${resource} matched.`, { rows: [], page, page_size: size, has_more: false, count: 0 });
             const bounded = boundPage(answered, size, page, isNonPaginated(operation));
-            return ok(`${bounded.rows.length} ${spec.label} row(s) on page ${page} (page_size ${size}); ${bounded.hasMore ? 'more pages exist' : 'no more pages'}${bounded.note}.`, { rows: bounded.rows, page, page_size: answered.page_size, has_more: bounded.hasMore, count: bounded.rows.length });
+            return ok(`${bounded.rows.length} ${spec.label} row(s) on page ${page} (page_size ${size}); ${bounded.hasMore ? 'more pages exist' : 'no more pages'}${bounded.note}.`, { rows: shape(bounded.rows), page, page_size: answered.page_size, has_more: bounded.hasMore, count: bounded.rows.length });
         }
         catch (err) {
             return errorContent(err);

package/dist/tools/reads.js

@@ -2,7 +2,7 @@ import * as z from 'zod/v4';
 import { TOOL_DESCRIPTIONS } from 'node-hudu/mcp';
 import { assertSecretReadPermitted } from '../policy.js';
 import { redactCompanyContextCredentials } from './company-context-policy.js';
-import { lossyNote, projectMarkdown } from './article-loss.js';
+import { lossyNote, takeContentLoss } from './article-loss.js';
 import { contextErrorContent, errorContent, createResultBuilders, resolveErrorContent } from './results.js';
 import { ASSET_IDENTIFIER, CONTEXT_OUTPUT, DEFAULT_LIMIT, EXPAND, HITS_OUTPUT, IDENTIFIER, LIMIT, ONE_OUTPUT, resourceEnum } from './schemas.js';
 /** Register the eleven CORE read tools after `hudu_search`, in `CORE_TOOLS` order. */
@@ -110,11 +110,11 @@ export function registerReadTools(server, ctx) {
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {
         try {
-            // ONE fetch with HTML forced; converted and loss-checked locally (see article-loss.ts).
+            // The SDK converts and reports loss on the record (see article-loss.ts).
             const stored = args.opts?.expand
-                ? await hudu.articles.getContext(args.id, { expand: true, format: 'html' })
-                : await hudu.articles.getContext(args.id, { format: 'html' });
-            const { result: context, codes: lossy } = projectMarkdown('articles.getContext', stored);
+                ? await hudu.articles.getContext(args.id, { expand: true, format: 'markdown' })
+                : await hudu.articles.getContext(args.id, { format: 'markdown' });
+            const { result: context, codes: lossy } = takeContentLoss('articles.getContext', stored);
             return ok('Article context returned.' + (lossy.length ? lossyNote(lossy) : ''), {
                 context,
                 ...(lossy.length ? { markdown_lossy: true, markdown_lossy_codes: lossy } : {}),

package/dist/tools/results.js

@@ -1,20 +1,31 @@
 /**
  * tools/results.ts — the `ToolReturn` shape every handler answers with, and its builders.
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { redact } from 'node-hudu';
 import { META_TOOLS } from 'node-hudu/mcp';
 import { normalizeResultUrls } from './result-urls.js';
 import { AUTH_FAILURE_CODES } from './search-policy.js';
 import { CREDENTIAL_LOAD_HINT } from '../credential.js';
-let credentialShapeView = {};
-/** Publish (or clear) this serving unit's view of the credentials it dials with. */
-export function setCredentialShapeView(view) {
-    credentialShapeView = view;
+const viewScope = new AsyncLocalStorage();
+/** Run `fn` (and everything it awaits) with `view` as the credential view `errorContent` reads. */
+export function runWithCredentialShapeView(view, fn) {
+    return viewScope.run(view, fn);
+}
+/**
+ * The refusal envelope for a unit whose client is a refusing placeholder, else undefined. The
+ * search and fetchMany paths fold a refusal into a 0-hit result or per-item rows, so they ask this
+ * first and answer exactly as every other tool does, before any request.
+ */
+export function upfrontRefusal() {
+    const refusal = viewScope.getStore()?.refusal;
+    return refusal === undefined ? undefined : errorContent(refusal);
 }
 /** The anomalies from the credentials the CURRENT serving unit presented, if any were seen. */
 function observedCredentialAnomalies() {
-    const env = credentialShapeView.env ?? [];
-    const request = credentialShapeView.request ?? [];
+    const view = viewScope.getStore() ?? {};
+    const env = view.env ?? [];
+    const request = view.request ?? [];
     const both = [...env, ...request];
     return [...new Set(both)];
 }
@@ -252,8 +263,12 @@ export function credentialMalformedContent(anomalies) {
  * (node-hudu 0.13.2), so its view is the first evidence the auth branch consults; the SDK's own
  * 401 diagnostic is consulted next ({@link unauthorizedShapeDiagnosticContent}). With no anomalies
  * and no SDK artifact diagnostic the envelope is exactly the legacy shape every existing test pins.
+ *
+ * Omitted, `anomalies` defaults to the current serving unit's view, so a caller that answers a
+ * credential refusal without an error to hand (the search branches, where the engine isolates the
+ * 401s into `meta.failed`) is annotated exactly like the thrown path.
  */
-export function unauthorizedContent(anomalies = []) {
+export function unauthorizedContent(anomalies = observedCredentialAnomalies()) {
     if (anomalies.length > 0) {
         return {
             content: [

package/dist/tools/search.js

@@ -1,6 +1,6 @@
 import * as z from 'zod/v4';
 import { SEARCH_HELP, SEARCH_MODES, SEARCH_RESOURCES, configError } from 'node-hudu/mcp';
-import { errorContent, createResultBuilders, searchErrorContent, unauthorizedContent } from './results.js';
+import { errorContent, createResultBuilders, searchErrorContent, unauthorizedContent, upfrontRefusal } from './results.js';
 import { HELP_TOPICS, SEARCH_OUTPUT, resourceEnum } from './schemas.js';
 import { credentialRefused, sanitizeIndexMeta, sanitizeSearchFailures } from './search-policy.js';
 import { adjustHelpText, adjustedSearchModes, searchQueryDescription, searchToolDescription } from './search-prose.js';
@@ -129,6 +129,9 @@ export function registerSearchTool(server, ctx) {
             return errorContent(configError('hudu_search: the body index is unavailable because HUDU_SEARCH_RESOURCES excludes articles or assets; its walk is corpus-wide. Use tier:"vendor" without refresh, or restore the corpus resources.'));
         }
         try {
+            const refused = upfrontRefusal();
+            if (refused !== undefined)
+                return refused;
             const result = await ops.searchKnowledge(args.query, {
                 // An omitted `resources` resolves to the deployment's default scope, never to the SDK's
                 // articles+assets default when those are outside `searchableResources`.

package/dist/tools/server.js

@@ -12,7 +12,7 @@ import { applyReadOnly } from '../config.js';
 import { headerRecord, readHuduBase, readHuduKey } from '../auth.js';
 import { baseHostAllowed, originOf } from '../base-hosts.js';
 import { CREDENTIAL_LOAD_HINT, detectCredentialShape } from '../credential.js';
-import { setCredentialShapeView } from './results.js';
+import { runWithCredentialShapeView } from './results.js';
 import { registerTools } from './register.js';
 import { answerRenamedTools } from './renamed.js';
 import { slimToolSchemas } from './slim.js';
@@ -107,14 +107,22 @@ function malformedCredentialStrategy(anomalies) {
         // parsing.
         name: 'x-hudu-api-key malformed',
         async headers() {
-            const refusal = new AuthError('this request presented a credential whose shape is malformed; nothing was dialed', {
-                suggestedAction: CREDENTIAL_LOAD_HINT,
-            });
-            refusal.anomalies = anomalies;
-            throw refusal;
+            throw malformedCredentialRefusal(anomalies);
         },
     };
 }
+/** The typed refusal a malformed credential answers with; `errorContent` maps it to CREDENTIAL_MALFORMED. */
+function malformedCredentialRefusal(anomalies) {
+    const refusal = new AuthError('this request presented a credential whose shape is malformed; nothing was dialed', {
+        suggestedAction: CREDENTIAL_LOAD_HINT,
+    });
+    refusal.anomalies = anomalies;
+    return refusal;
+}
+/** The error a refusing placeholder client's strategy surfaces, as `errorContent` renders it for every other tool. */
+function placeholderRefusal(strategy) {
+    return new AuthError(`Auth strategy "${strategy.name}" did not produce usable credential headers; no request was sent`);
+}
 /**
  * A per-(origin, credential) client built from the request's own `x-hudu-base-url` and
  * `x-hudu-api-key`, cached by the pair's hash.
@@ -169,6 +177,40 @@ export class ScopedClientCache {
         return scoped;
     }
 }
+/** A header value that is present and non-blank; anything else is treated as not sent. */
+const usable = (v) => (v === undefined || v.trim().length === 0 ? undefined : v);
+/**
+ * Which credential an http request presents: the usable header key and base, and whether the
+ * origin is caller-named. The request key wins; the server-held `HUDU_API_KEY` is dialed only when
+ * no header key came and the origin is not caller-named. One rule, shared by the dispatcher
+ * ({@link resolveHuduClient}) and the 401 shape view ({@link buildCredentialShapeView}).
+ */
+function presentedCredential(config, headers) {
+    const headerKey = usable(headers === undefined ? undefined : readHuduKey(headers));
+    const headerBase = usable(headers === undefined ? undefined : readHuduBase(headers));
+    const defaultOrigin = config.HUDU_BASE_URL === undefined ? undefined : originOf(config.HUDU_BASE_URL);
+    const headerOrigin = headerBase === undefined ? undefined : originOf(headerBase);
+    // An unparsable header value is caller-named even when there is no default to differ from: two
+    // `undefined` origins must not read as "the default", or the default key would be paired with it.
+    const callerNamed = headerBase !== undefined && (headerOrigin === undefined || headerOrigin !== defaultOrigin);
+    return { headerKey, headerBase, callerNamed, envKeyPresented: headerKey === undefined && !callerNamed };
+}
+/**
+ * The credential anomalies a 401 on this serving unit may be annotated with: ONLY those of the
+ * credential actually presented. Under stdio that is the env key; under http the request key wins,
+ * and the env key's anomalies join only when it is the one that would be dialed. (A malformed key
+ * from either source is refused pre-dial, so a real 401 is almost always clean-shape.)
+ */
+export function buildCredentialShapeView(config, headers) {
+    const anomaliesOf = (k) => {
+        const a = k === undefined ? [] : detectCredentialShape(k);
+        return a.length > 0 ? a : undefined;
+    };
+    if (config.MCP_TRANSPORT === 'stdio')
+        return { env: anomaliesOf(config.HUDU_API_KEY) };
+    const { headerKey, envKeyPresented } = presentedCredential(config, headers);
+    return { env: envKeyPresented ? anomaliesOf(config.HUDU_API_KEY) : undefined, request: anomaliesOf(headerKey) };
+}
 /**
  * The client a request's tools should use.
  *
@@ -194,31 +236,25 @@ export class ScopedClientCache {
  * Under `stdio` the process boundary is the trust boundary and the parent already carries the
  * environment's credential and origin; the headers are never read on this path.
  */
-function resolveHuduClient(entry, config, ctx, log) {
+export function resolveHuduClient(entry, config, ctx, log) {
     if (config.MCP_TRANSPORT === 'stdio')
         return { client: entry.parent, origin: new URL(config.HUDU_BASE_URL).origin };
     const headers = ctx.requestInfo === undefined ? undefined : headerRecord(ctx.requestInfo.headers);
-    const usable = (v) => (v === undefined || v.trim().length === 0 ? undefined : v);
-    const headerKey = usable(headers === undefined ? undefined : readHuduKey(headers));
-    const headerBase = usable(headers === undefined ? undefined : readHuduBase(headers));
+    const { headerKey, headerBase, callerNamed } = presentedCredential(config, headers);
     const defaultBase = config.HUDU_BASE_URL;
     const base = headerBase ?? defaultBase;
     // Only a caller-named origin is subject to the allow-list, and naming the default one is free.
-    const defaultOrigin = defaultBase === undefined ? undefined : originOf(defaultBase);
-    const headerOrigin = headerBase === undefined ? undefined : originOf(headerBase);
-    // An unparsable header value is caller-named even when there is no default to differ from: two
-    // `undefined` origins must not read as "the default", or the default key would be paired with it.
-    const callerNamed = headerBase !== undefined && (headerOrigin === undefined || headerOrigin !== defaultOrigin);
     // Keep `undefined` distinct from an explicit list in config: with a configured default, an
     // omitted list means default-only; without one it preserves documented BYO-origin mode.
     const callerOriginAllowed = config.HUDU_ALLOWED_BASE_HOSTS === undefined
         ? defaultBase === undefined
         : baseHostAllowed(headerBase, config.HUDU_ALLOWED_BASE_HOSTS);
-    if (callerNamed && !callerOriginAllowed)
-        return { client: entry.baseRefused };
+    if (callerNamed && !callerOriginAllowed) {
+        return { client: entry.baseRefused, refusal: placeholderRefusal(BASE_URL_NOT_ALLOWED) };
+    }
     const key = headerKey ?? (callerNamed ? undefined : config.HUDU_API_KEY);
     if (key === undefined)
-        return { client: entry.parent };
+        return { client: entry.parent, refusal: placeholderRefusal(NO_SERVER_CREDENTIAL) };
     // Pre-dispatch shape gate, on the value this request will actually present: a credential whose
     // bytes were mangled by the load is refused HERE, before a client is constructed and so before
     // the first dial. The check is on whichever value won above, so it covers the per-request header
@@ -239,10 +275,10 @@ function resolveHuduClient(entry, config, ctx, log) {
             client = entry.buildPlaceholder(malformedCredentialStrategy(anomalies));
             entry.malformed.set(id, client);
         }
-        return { client };
+        return { client, refusal: malformedCredentialRefusal(anomalies) };
     }
     if (base === undefined)
-        return { client: entry.noBase };
+        return { client: entry.noBase, refusal: placeholderRefusal(NO_REQUEST_BASE_URL) };
     try {
         const client = entry.scopes.for(base, key);
         // Only publish an origin after the dispatched client has passed SDK validation.
@@ -263,9 +299,9 @@ function resolveHuduClient(entry, config, ctx, log) {
                     client = entry.buildPlaceholder(malformedCredentialStrategy([]));
                     entry.malformed.set(id, client);
                 }
-                return { client };
+                return { client, refusal: malformedCredentialRefusal([]) };
             }
-            return { client: entry.badBase };
+            return { client: entry.badBase, refusal: placeholderRefusal(INVALID_REQUEST_BASE_URL) };
         }
         throw err;
     }
@@ -413,29 +449,19 @@ export function createMcpServerFactory(requested, log) {
     };
     const read = build('read');
     const mutations = config.HUDU_WRITE_POLICY === 'deny' ? undefined : { write: build('write'), delete: build('delete') };
-    // The server-held credential's anomalies, computed once: the auth-failure envelope annotates a
-    // refusal with them so a 401 on a value this server already knows is malformed is diagnosable
-    // without another dial. `undefined` when the value is clean, so nothing is added to the envelope.
-    const envAnomalies = config.HUDU_API_KEY === undefined ? undefined : detectCredentialShape(config.HUDU_API_KEY);
-    const envView = envAnomalies !== undefined && envAnomalies.length > 0 ? envAnomalies : undefined;
     return (ctx) => {
         const resolve = (entry) => resolveHuduClient(entry, config, ctx, log);
-        // Per serving unit (one stdio connection, or one HTTP request): which of the credentials this
-        // unit is about to present look malformed. Published before the first tool can fail, so the
-        // auth-failure branch can answer with it. A clean value contributes nothing.
-        const headerKey = config.MCP_TRANSPORT === 'stdio' || ctx.requestInfo === undefined
-            ? undefined
-            : readHuduKey(headerRecord(ctx.requestInfo.headers));
-        const requestAnomalies = headerKey === undefined ? undefined : detectCredentialShape(headerKey);
-        setCredentialShapeView({
-            env: envView,
-            request: requestAnomalies !== undefined && requestAnomalies.length > 0 ? requestAnomalies : undefined,
-        });
-        const { client: hudu, origin: huduOrigin } = resolve(read);
+        // Per serving unit (one stdio connection, or one HTTP request): the anomalies of the credential
+        // this unit presents, published before the first tool can fail (see buildCredentialShapeView).
+        const shapeView = buildCredentialShapeView(config, ctx.requestInfo === undefined ? undefined : headerRecord(ctx.requestInfo.headers));
+        const { client: hudu, origin: huduOrigin, refusal } = resolve(read);
         const mutationClients = mutations ? { write: resolve(mutations.write).client, delete: resolve(mutations.delete).client } : undefined;
         const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION, title: 'Hudu MCP Server' });
         answerRenamedTools(server);
         slimToolSchemas(server);
+        // Every handler registered below runs inside this request's view scope (see results.ts).
+        const register = server.registerTool.bind(server);
+        server.registerTool = (name, config, cb) => register(name, config, (...a) => runWithCredentialShapeView(refusal === undefined ? shapeView : { ...shapeView, refusal }, () => cb(...a)));
         registerTools(server, { hudu, huduOrigin, config, log, ...(mutationClients ? { mutationClients } : {}) });
         return server;
     };

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 = 'fba0aa4600d095e3a68e3cb25b55e78a9b9023be1f3b4e6f78fb8644e847ed2d';
+export const BUILT_AGAINST_PLAN_HASH = '1ad5e23b9c140e8f9cf60ac710dd508fc1109e86b9a0620b2d0925f16b11d7b8';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-hudu",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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.16.0",
+    "node-hudu": "0.17.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {