iit-mcp-hudu 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.9.1
+
+**Upgrading from 0.9.0:** no configuration change. This release sharpens the argument prose a calling
+model reads without asking for help, and refuses arguments `hudu_search` does not implement.
+
+- Change: `hudu_search`'s `company_id` description now states the filter's real semantics — a
+  **numeric** id only (a company name cannot be filtered: the Typesense tier sends the number into
+  `filter_by` and the vendor path compares the number), and omission means all companies **plus
+  global articles**, which is the wide answer rather than a narrow one. `resources` now says what the
+  list means ("only these resource types") and that fewer collections is less work. Funded by trimming
+  redundant prose in `mode` / `updated_since` / `min_score` / `query`, so the served `tools/list`
+  surface is **byte-identical in size** to 0.9.0; the frozen hashes were re-recorded and say why.
+- Fix: the loose `http` argument object accepted and **silently ignored** any argument the tool does
+  not implement. Measured on 0.9.0: `asset_layout_id` (advertised by `mode:"resources"` as an assets
+  filter) returned unfiltered results with no signal — a dropped filter answers a different question
+  than the one asked. Unknown fields are now refused with a named error, and the looseness is kept
+  only for the policy-owned `tier` / `refresh`, where `meta.policyOverride` already discloses the
+  override. `stdio` stays strict.
+- Documentation: the Typesense tier's 8-finding adversarial audit is closed. Seven were fixed in
+  `node-hudu` 0.22.0 (pre-scoring cap in Typesense's ranking order, non-numeric ids miscounted as a
+  page cap, a 401 from one collection masking a healthy sibling, the probe reading only `articles`,
+  the `hydrated` count's meaning, `verifyHits:false` disclosing nothing, and per-hit provenance now
+  carried by the required `source` field); Q8 was clean. Q7 (silent partial LRU body eviction under
+  `maxIndexTextBytes`) remains an unverified live-environment question and is not claimed as fixed.
+
+## 0.9.0
+
+**Upgrading from 0.8.0:** no configuration change. The pinned `node-hudu` moves from 0.21.0 to 0.22.0,
+which closes four MAJOR and three MINOR defects in the Typesense body tier found by an adversarial
+audit. Nothing changes for a deployment that leaves the tier unset.
+
+- Add: `probeBodySearch` results now carry the additive per-collection `results[]` field
+  (`node-hudu` 0.22.0). The probe report maps it when present, so a caller can see WHICH collection
+  answered or failed instead of only the aggregate `reachable`.
+- Change: the pinned SDK's tier is honest about its bounds. Articles are hydrated in full through a
+  bounded pool of reads (so title matches ranked 11+ reach the local scorer), `meta.typesense` splits
+  `capped` / `unreadable` / `unscored`, the circuit breaker is per collection, a 401 from one
+  collection is no longer reported as a bad key when a sibling answered, and `verifyHits:false`
+  discloses that the tier contributed no hit. See `node-hudu` 0.22.0 release notes.
+
 ## 0.8.0
 
 **Upgrading from 0.7.0:** no configuration change for any existing deployment. Six new optional

package/dist/tools/search-prose.js

@@ -384,7 +384,7 @@ function serverPolicyTierSentence(ctx) {
 /** The `query` field description, adjusted so it does not promise a body search it cannot run. */
 export function searchQueryDescription(ctx) {
     const { bodySearchable, toolDefaultTier } = ctx;
-    const base = 'REQUIRED for mode="search". Partial words fine; article BODY is searched. Multi-word rules: topic="query" (mode="help").';
+    const base = 'REQUIRED for mode="search". Partial words fine; article BODY is searched. Multi-word: topic="query" (mode="help").';
     if (!bodySearchable) {
         // Fail loudly: a missed anchor would advertise a body search this deployment cannot run.
         if (!base.includes('article BODY is searched.'))

package/dist/tools/search.js

@@ -244,10 +244,12 @@ export function registerSearchTool(server, ctx) {
     // instead of being rejected before the policy path can answer. Under `stdio` every field is
     // served, so the object stays STRICT: an unknown argument is refused, never silently ignored.
     const inputFields = {
+        // The tool title already names the three modes; "help documents fields" is redundant there
+        // and costs 23 B of the measured surface. The help mode's own output documents fields.
         mode: z
             .enum(['search', 'help', 'resources'])
             .default('search')
-            .describe('search|help|resources; help documents fields'),
+            .describe('search|help|resources'),
         query: z
             .string()
             .min(1)
@@ -265,12 +267,21 @@ export function registerSearchTool(server, ctx) {
             .describe('help only; "all" adds syntax'),
         limit: z.number().int().min(1).max(25).optional().describe('1-25, default 8; larger is CONFIG_ERROR'),
         snippetChars: z.number().int().min(0).max(400).optional().describe('0 = no snippet.'),
-        company_id: z.number().int().positive().optional().describe('One company'),
-        updated_since: z.string().optional().describe('ISO timestamp; newer only'),
+        // A name cannot be filtered: the tier sends company_id into Typesense's filter_by and the
+        // vendor path compares the number. Say so where the model reads it, and say what omission
+        // means, because "no company" is the wide answer, not a narrow one. Funded by trimming
+        // min_score/query prose so the served surface stays byte-identical (see the size gate).
+        company_id: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('Numeric company id; omit = all companies + global articles.'),
+        updated_since: z.string().optional().describe('ISO ts; newer only'),
         min_score: z
             .number()
             .optional()
-            .describe('0-100; 0 hits may be floor/filter; meta.scanned/meta.returned; company_id/updated_since; drops uncounted.'),
+            .describe('0-100; floor may empty hits; meta.scanned/meta.returned; company_id/updated_since; uncounted.'),
         exact_only: z.boolean().optional().describe('No fuzzy match.'),
         // Under `http` neither field is served: the tier decides whether a call may wait for a
         // corpus-wide walk, and the calling model can observe neither the index's warmth nor the
@@ -321,6 +332,25 @@ export function registerSearchTool(server, ctx) {
         }
         // A field the mode cannot honour is a CONFIG_ERROR naming the fields it does honour.
         const bag = args;
+        // An argument this tool does not implement is REFUSED, never silently ignored. Under `http`
+        // the input object is loose ONLY so the policy-owned `tier`/`refresh` reach the handler and
+        // are reported as overridden (`meta.policyOverride`); every OTHER unknown key is a caller bug,
+        // and dropping it would answer a different question than the one asked. Measured on 0.9.0:
+        // `asset_layout_id` (advertised by `mode:"resources"` as an assets filter, but not implemented
+        // here) was accepted and ignored, returning unfiltered results with no signal. The invoke path
+        // already validates its bag against the SDK's inputSchema, so this aligns the two paths.
+        const knownFields = new Set([
+            ...Object.keys(inputFields),
+            ...(searchTierIsPolicy ? ['tier', 'refresh'] : []),
+        ]);
+        const unknownFields = Object.keys(bag).filter((k) => bag[k] !== undefined && !knownFields.has(k));
+        if (unknownFields.length) {
+            return errorContent(configError(
+            // Kept under the 200-char model-facing error cap (`MAX_ERROR_MESSAGE_CHARS`): a longer
+            // message is truncated mid-sentence, which is worse than a shorter one that survives
+            // intact. The essential disclosure comes first, the pointer last.
+            `hudu_search: unknown argument(s) ${unknownFields.join(', ')} — a dropped filter answers a different question, so unknown fields are never silently ignored. Call mode:"help" for fields.`));
+        }
         const provided = Object.keys(bag).filter((k) => k !== 'mode' && bag[k] !== undefined);
         const unhonoured = provided.filter((k) => spec.rejects.includes(k));
         if (unhonoured.length) {

package/dist/tools/typesense-probe.js

@@ -51,6 +51,7 @@ export async function probeTypesense(hudu, config) {
             reachable: result.reachable === true,
             collections: Array.isArray(result.collections) && result.collections.length > 0 ? result.collections : collections,
             probeMs: typeof result.probeMs === 'number' ? result.probeMs : Date.now() - started,
+            ...(Array.isArray(result.results) && result.results.length > 0 ? { results: result.results } : {}),
             ...(result.error ? { error: { code: result.error.code, message: result.error.message } } : {}),
         };
     }

package/dist/tools.js

@@ -32,4 +32,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 = '1c5f979de2bc4398d95e860dfa7adc43e00c2f5126233bc6b95d6aaa830b0cbb';
+export const BUILT_AGAINST_PLAN_HASH = 'b46a003d8bef3f781f1bd1e21dc27271a1ad469eaa891560c767ad5b274dfaa1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-hudu",
-  "version": "0.8.0",
+  "version": "0.9.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.21.0",
+    "node-hudu": "0.22.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {