rhombus-node-mcp 0.1.56 → 0.1.58

package/dist/filtering-utils.js

@@ -1,13 +1,17 @@
 import { z } from "zod";
+import { matchesEntityName } from "./utils/entity-name-match.js";
 // ---------------------------------------------------------------------------
 // Shared tool arg schemas
 // ---------------------------------------------------------------------------
+const INCLUDE_FIELDS_DESCRIPTION = `Dot-notation field paths to include in the response (e.g. "vehicleEvents.vehicleLicensePlate").
+Pass null to return all fields. WARNING: some responses can exceed 400k characters — use includeFields
+to request only the data you need. For high-volume tools this may be required to get a complete answer.
+Core device-status fields (connected, connectionStatus, healthStatus, healthStatusDetails, batteryStatus)
+are always retained where present, even if not listed here.`;
 export const INCLUDE_FIELDS_ARG = z
     .array(z.string())
     .nullable()
-    .describe(`Dot-notation field paths to include in the response (e.g. "vehicleEvents.vehicleLicensePlate").
-Pass null to return all fields. WARNING: some responses can exceed 400k characters — use includeFields
-to request only the data you need. For high-volume tools this may be required to get a complete answer.`);
+    .describe(INCLUDE_FIELDS_DESCRIPTION);
 export const FILTER_BY_ARG = z
     .array(z.object({
     field: z
@@ -23,9 +27,70 @@ export const FILTER_BY_ARG = z
     .nullable()
     .describe(`Filter array items in the response by field values. All conditions are ANDed.
 Example: [{field: "vehicleLicensePlate", op: "=", value: "ABC123"}, {field: "confidence", op: ">", value: 0.8}]
+For name, locationName, deviceName, cameraName and doorName fields, 'contains' ignores capitalization, spacing and punctuation (e.g. 'iceblocks' matches 'Ice Blocks - Headquarters'). All matching candidates are returned; use '=' for exact comparisons.
 Use alongside includeFields to get only the specific records and fields you need.`);
-/** These keys will always be included in processed output schemas */
-const INCLUDE_WHITELIST = ["requestType"];
+// nullish, not nullable: pre-existing callers (evals, specs, cached tool-call
+// replays) omit the key entirely and must stay valid.
+export const GROUP_BY_ARG = z
+    .string()
+    .nullish()
+    .describe(`Group array items by a field and return EXACT per-group counts computed server-side, instead of the rows.
+Use this for "how many per X" / "which X has the most Y" questions — never tally rows yourself.
+Example: groupBy "locationUuid" on a camera list returns {camerasGrouped: {by: "locationUuid", total: 63, groups: {"<uuid>": 37, ...}}} (groups sorted by count, descending).
+Applied after filterBy, so e.g. filterBy [{field: "connected", op: "=", value: false}] + groupBy "locationUuid" = offline devices per location.
+Accepts the same dot-notation field paths as filterBy (optionally prefixed with the array key, e.g. "cameras.locationUuid").`);
+// Grouping by a high-cardinality field (e.g. a uuid) must not bloat the
+// response: keep the top N groups and report how many were omitted.
+const GROUP_BY_MAX_GROUPS = 50;
+/**
+ * Cross-cutting keys every tool emits (or may emit), always kept regardless of
+ * what the caller projected. `note` carries tool-emitted diagnostics (e.g.
+ * "this location has no doors, so the empty result is not an absence of
+ * activity") — projecting it away would hide exactly the caveat the model needs.
+ *
+ * Tool-SPECIFIC fields do not belong here. Declare those at the tool's own
+ * `registerTool` call with `protectFields` below, so the protection lives next
+ * to the thing being protected instead of in a list nobody reads.
+ */
+const ALWAYS_PROTECTED_FIELDS = [
+    "requestType",
+    "note",
+    "error",
+    // api2 can succeed *with a caveat* (`warningMsg`), and a mutation that half
+    // applied says so only there. Projecting it away turns a qualified success
+    // into an unqualified one, which is worse than losing the field.
+    "warningMsg",
+    "filterByWarnings",
+    "groupByWarnings",
+];
+/**
+ * Carries a tool's protected field names on its registerTool config. A symbol
+ * so it cannot collide with an SDK config key and never survives into JSON;
+ * the proxy strips it before forwarding the config on regardless.
+ */
+const PROTECTED_FIELDS = Symbol.for("rhombus.protectedFields");
+/**
+ * Marks top-level output fields that must survive an `includeFields`
+ * projection even when the caller didn't ask for them.
+ *
+ * Use it for anything the model needs in order to read the rest of the result
+ * correctly — pre-computed rosters/aggregates it would otherwise have to derive
+ * from a long list, scope/caveat markers, and the like:
+ *
+ * ```ts
+ * server.registerTool(
+ *   TOOL_NAME,
+ *   protectFields({ title: "Faces", ... }, ["faceEventSummary"]),
+ *   TOOL_HANDLER,
+ * );
+ * ```
+ *
+ * Names are matched at the TOP LEVEL of the result only, and a bare name keeps
+ * the field's entire subtree.
+ */
+export function protectFields(config, fields) {
+    return { ...config, [PROTECTED_FIELDS]: fields };
+}
 function buildTrie(paths) {
     const trie = {};
     for (const p of paths) {
@@ -39,6 +104,30 @@ function buildTrie(paths) {
     }
     return trie;
 }
+// Device-status fields the model must never be able to project away: a status
+// query where includeFields omits these returns data with no status in it, and
+// the model then truthfully answers "status not included" (observed in prod,
+// 2026-07-22). Grafted onto every internal trie node — fields a payload
+// doesn't have are simply absent, so this is a no-op outside device lists.
+const PROTECTED_STATUS_FIELDS = [
+    "connected",
+    "connectionStatus",
+    "healthStatus",
+    "healthStatusDetails",
+    "batteryStatus",
+];
+function addProtectedStatusFields(trie) {
+    const children = Object.keys(trie);
+    // An empty node means "include everything below" — already keeps them.
+    if (children.length === 0)
+        return;
+    for (const key of children)
+        addProtectedStatusFields(trie[key]);
+    for (const field of PROTECTED_STATUS_FIELDS) {
+        if (!(field in trie))
+            trie[field] = {};
+    }
+}
 function filterByTrie(obj, trie) {
     // Empty trie at this level means "include everything"
     if (Object.keys(trie).length === 0) {
@@ -48,7 +137,7 @@ function filterByTrie(obj, trie) {
         const mapped = obj
             .map((item) => filterByTrie(item, trie))
             .filter((item) => item !== undefined);
-        return mapped.length > 0 ? mapped : undefined;
+        return obj.length === 0 || mapped.length > 0 ? mapped : undefined;
     }
     if (typeof obj === "object" && obj !== null) {
         const result = {};
@@ -59,6 +148,21 @@ function filterByTrie(obj, trie) {
                     result[key] = child;
             }
         }
+        for (const key of Object.keys(obj)) {
+            if (key.endsWith("Grouped") ||
+                key === "groupByWarnings" ||
+                key === "filterByWarnings" ||
+                key === "error" ||
+                key === "errorMsg" ||
+                key === "warningMsg") {
+                if (obj[key] !== undefined)
+                    result[key] = obj[key];
+                const countKey = `${key.slice(0, -"Grouped".length)}Count`;
+                if (key.endsWith("Grouped") && typeof obj[countKey] === "number") {
+                    result[countKey] = obj[countKey];
+                }
+            }
+        }
         return Object.keys(result).length > 0 ? result : undefined;
     }
     // Primitive reached with a non-empty trie — return as-is (e.g. the trie
@@ -77,7 +181,42 @@ export function filterIncludedFields(obj, fieldsToInclude) {
         return obj;
     }
     const trie = buildTrie(fieldsToInclude);
-    return filterByTrie(obj, trie);
+    addProtectedStatusFields(trie);
+    // When groupBy replaced an array with its summary, no trie path can match
+    // anything — start from an empty object so the re-attach below still runs
+    // (an empty final result falls back to `undefined`, the old behavior).
+    const projected = filterByTrie(obj, trie) ??
+        (obj && typeof obj === "object" && !Array.isArray(obj) ? {} : undefined);
+    // A `<key>Count` sibling is authoritative metadata for its array (post-
+    // filterBy it is the match count) — keep it whenever its array survives the
+    // projection, even if the caller didn't list it explicitly. `<key>Grouped`
+    // summaries (from groupBy) replace their array entirely, so no trie path
+    // can match them — always re-attach, along with their Count sibling.
+    if (projected &&
+        typeof projected === "object" &&
+        !Array.isArray(projected) &&
+        typeof obj === "object" &&
+        !Array.isArray(obj)) {
+        for (const key of Object.keys(projected)) {
+            if (Array.isArray(projected[key]) &&
+                typeof obj[`${key}Count`] === "number" &&
+                !(`${key}Count` in projected)) {
+                projected[`${key}Count`] = obj[`${key}Count`];
+            }
+        }
+        for (const key of Object.keys(obj)) {
+            if (key.endsWith("Grouped")) {
+                projected[key] = obj[key];
+                const countKey = `${key.slice(0, -"Grouped".length)}Count`;
+                if (typeof obj[countKey] === "number" && !(countKey in projected)) {
+                    projected[countKey] = obj[countKey];
+                }
+            }
+        }
+        if (Object.keys(projected).length === 0)
+            return undefined;
+    }
+    return projected;
 }
 // ---------------------------------------------------------------------------
 // applyFilterBy — predicate filtering of array items
@@ -115,6 +254,9 @@ function matchesCondition(item, condition) {
         case "<=":
             return Number(actual) <= Number(value);
         case "contains":
+            if (["name", "locationName", "deviceName", "cameraName", "doorName"].includes(condition.field.split(".").at(-1) ?? "")) {
+                return matchesEntityName(String(actual), String(value));
+            }
             return String(actual).toLowerCase().includes(String(value).toLowerCase());
         default:
             return false;
@@ -155,33 +297,144 @@ export function applyFilterBy(obj, conditions) {
         conditionsByTopKey[topKey].push({ ...cond, field: subField });
     }
     const result = { ...obj };
+    const warnings = [];
+    // A condition whose field is absent from EVERY item of the target array
+    // would silently drop all rows (undefined never matches) — the model then
+    // reads {items: [], count: N} as "0 matches" when really it filtered on a
+    // phantom field. Skip such conditions and warn loudly instead.
+    const partitionConds = (items, conds, arrayKey) => {
+        if (items.length === 0)
+            return conds;
+        const applicable = [];
+        for (const c of conds) {
+            if (items.some((item) => getNestedValue(item, c.field) !== undefined)) {
+                applicable.push(c);
+            }
+            else {
+                const available = [...new Set(items.slice(0, 50).flatMap((item) => item && typeof item === "object" ? Object.keys(item) : []))].sort();
+                warnings.push(`filterBy condition on field "${c.field}" was IGNORED — no item in "${arrayKey}" has that field (it would have matched nothing). Available fields: ${available.join(", ")}`);
+            }
+        }
+        return applicable;
+    };
     for (const [topKey, keyConds] of Object.entries(conditionsByTopKey)) {
         if (topKey === "*") {
             // Apply conditions to every top-level array in the object
             for (const k of Object.keys(result)) {
                 if (Array.isArray(result[k])) {
-                    result[k] = result[k].filter((item) => keyConds.every((c) => matchesCondition(item, c)));
+                    const conds = partitionConds(result[k], keyConds, k);
+                    result[k] = result[k].filter((item) => conds.every((c) => matchesCondition(item, c)));
                 }
             }
         }
         else if (topKey in result && Array.isArray(result[topKey])) {
-            result[topKey] = result[topKey].filter((item) => keyConds.every((c) => matchesCondition(item, c)));
+            const conds = partitionConds(result[topKey], keyConds, topKey);
+            result[topKey] = result[topKey].filter((item) => conds.every((c) => matchesCondition(item, c)));
         }
     }
-    // If the result has a sibling `count: number` and exactly one top-level
-    // array, sync count to the (now-filtered) array length. This makes `count`
+    // Sync sibling counts to the (now-filtered) array lengths so counts always
     // reflect what the model is looking at — pre-filter total when no filterBy
-    // was applied (handler computed it), post-filter total when one was. Any
-    // tool returning {count, items[]} gets this for free.
+    // was applied (handler computed it), post-filter total when one was.
+    // Covers both the bare `{count, items[]}` convention and the
+    // `{<key>Count, <key>[]}` convention (e.g. camerasCount next to cameras).
     if (typeof result.count === "number") {
         const arrayKeys = Object.keys(result).filter((k) => Array.isArray(result[k]));
         if (arrayKeys.length === 1) {
             result.count = result[arrayKeys[0]].length;
         }
     }
+    for (const k of Object.keys(result)) {
+        if (Array.isArray(result[k]) && typeof result[`${k}Count`] === "number") {
+            result[`${k}Count`] = result[k].length;
+        }
+    }
+    if (warnings.length > 0) {
+        result.filterByWarnings = warnings;
+    }
     return result;
 }
 // ---------------------------------------------------------------------------
+// applyGroupBy — server-side per-group counts
+// ---------------------------------------------------------------------------
+/**
+ * Replaces each targeted array with a `<key>Grouped` summary of EXACT counts
+ * per distinct value of `groupByField` — so "how many per location" is
+ * computed in code, never tallied by the model (LLM tallies over long lists
+ * are reliably off by small amounts).
+ *
+ * `groupByField` uses the same addressing as filterBy conditions: a bare
+ * field applies to every top-level array, `arrayKey.field` targets one array.
+ * A field no item has leaves the rows intact and warns via `groupByWarnings`.
+ */
+export function applyGroupBy(obj, groupByField) {
+    if (!groupByField || typeof obj !== "object" || obj === null) {
+        return obj;
+    }
+    const dotIdx = groupByField.indexOf(".");
+    const topKey = dotIdx === -1 ? "*" : groupByField.substring(0, dotIdx);
+    const field = dotIdx === -1 ? groupByField : groupByField.substring(dotIdx + 1);
+    const result = Array.isArray(obj) ? { items: obj } : { ...obj };
+    const warnings = [];
+    const groupArray = (items, arrayKey) => {
+        if (items.length > 0 && !items.some((item) => getNestedValue(item, field) !== undefined)) {
+            const available = [...new Set(items.slice(0, 50).flatMap((item) => item && typeof item === "object" ? Object.keys(item) : []))].sort();
+            warnings.push(`groupBy field "${field}" was IGNORED — no item in "${arrayKey}" has that field; rows returned ungrouped. Available fields: ${available.join(", ")}`);
+            return false;
+        }
+        const tally = new Map();
+        for (const item of items) {
+            const value = getNestedValue(item, field);
+            const key = value === undefined || value === null
+                ? "(none)"
+                : typeof value === "object"
+                    ? "(non-scalar)"
+                    : String(value);
+            tally.set(key, (tally.get(key) ?? 0) + 1);
+        }
+        const sorted = [...tally.entries()].sort((a, b) => b[1] - a[1]);
+        const kept = sorted.slice(0, GROUP_BY_MAX_GROUPS);
+        const grouped = {
+            by: field,
+            total: items.length,
+            groups: Object.fromEntries(kept),
+        };
+        if (sorted.length > kept.length) {
+            grouped.omittedGroups = sorted.length - kept.length;
+            grouped.note = `${sorted.length} distinct values; showing the top ${kept.length} by count.`;
+        }
+        result[`${arrayKey}Grouped`] = grouped;
+        delete result[arrayKey];
+        if (typeof result[`${arrayKey}Count`] === "number") {
+            result[`${arrayKey}Count`] = items.length;
+        }
+        return true;
+    };
+    let groupedAny = false;
+    if (topKey === "*") {
+        for (const k of Object.keys(result)) {
+            if (Array.isArray(result[k])) {
+                groupedAny = groupArray(result[k], k) || groupedAny;
+            }
+        }
+    }
+    else if (topKey in result && Array.isArray(result[topKey])) {
+        groupedAny = groupArray(result[topKey], topKey);
+    }
+    else if (result[topKey] && typeof result[topKey] === "object" && field.includes(".")) {
+        result[topKey] = applyGroupBy(result[topKey], field);
+        groupedAny = true;
+    }
+    else {
+        warnings.push(`groupBy "${groupByField}" was IGNORED — the response has no array at "${topKey}".`);
+    }
+    if (warnings.length > 0) {
+        result.groupByWarnings = [...(result.groupByWarnings ?? []), ...warnings];
+    }
+    return Array.isArray(obj) && !groupedAny && warnings.length === 0
+        ? obj
+        : result;
+}
+// ---------------------------------------------------------------------------
 // zodToDotNotationPaths — derive available field paths from an OUTPUT_SCHEMA
 // ---------------------------------------------------------------------------
 /**
@@ -225,20 +478,135 @@ export function zodToDotNotationPaths(schema, prefix = "") {
     return [];
 }
 // ---------------------------------------------------------------------------
+// deepOptionalizeSchema — relax an outputSchema for post-projection validation
+// ---------------------------------------------------------------------------
+/** Carry a rebuilt schema's description over from the schema it replaces. */
+function withDescription(next, prev) {
+    return prev.description ? next.describe(prev.description) : next;
+}
+/**
+ * Returns a copy of `schema` with every object field made optional, recursively.
+ *
+ * The MCP SDK validates a tool's `structuredContent` against its registered
+ * `outputSchema` AFTER the handler returns — which is after this proxy has
+ * already projected the payload down to the caller's `includeFields`. Any field
+ * the schema marks required but the projection dropped then fails validation,
+ * and a working tool call comes back to the model as
+ * `MCP error -32602: Output validation error`. (Hit in prod by
+ * events-tool/brivo-access-control: includeFields asked for
+ * `brivoDoors.doorName` + `.locationUuid` but not the required
+ * `brivoDoors.brivoDoorId`, so the model reported Brivo data as unreadable.)
+ *
+ * Projection inherently invalidates required-ness, so the schema we register
+ * has to be all-optional. Nothing model-facing changes: `outputSchema` is never
+ * forwarded to the LLM, and the includeFields path catalog is derived from the
+ * ORIGINAL schema before this runs. Descriptions are preserved.
+ */
+export function deepOptionalizeSchema(schema) {
+    // Wrappers: unwrap, recurse, re-wrap so nested objects are relaxed too.
+    if (schema instanceof z.ZodOptional) {
+        return deepOptionalizeSchema(schema.unwrap()).optional();
+    }
+    if (schema instanceof z.ZodNullable) {
+        return deepOptionalizeSchema(schema.unwrap()).nullable();
+    }
+    // The default is dropped: this schema is only ever used for validation, and
+    // a defaulted field is already satisfied by `undefined`.
+    if (schema instanceof z.ZodDefault) {
+        return deepOptionalizeSchema(schema._def.innerType).optional();
+    }
+    if (schema instanceof z.ZodObject) {
+        const relaxed = {
+            filterByWarnings: z.array(z.string()).optional(),
+            groupByWarnings: z.array(z.string()).optional(),
+        };
+        for (const [key, value] of Object.entries(schema.shape)) {
+            relaxed[key] = optionalize(deepOptionalizeSchema(value));
+            let unwrapped = value;
+            while (unwrapped instanceof z.ZodOptional ||
+                unwrapped instanceof z.ZodNullable ||
+                unwrapped instanceof z.ZodDefault) {
+                unwrapped = unwrapped.unwrap();
+            }
+            if (unwrapped instanceof z.ZodArray) {
+                relaxed[`${key}Grouped`] = z.object({
+                    by: z.string(),
+                    total: z.number().int().nonnegative(),
+                    groups: z.record(z.string(), z.number().int().nonnegative()),
+                    omittedGroups: z.number().int().nonnegative().optional(),
+                    note: z.string().optional(),
+                }).optional();
+            }
+        }
+        return withDescription(z.object(relaxed), schema);
+    }
+    if (schema instanceof z.ZodArray) {
+        return withDescription(z.array(deepOptionalizeSchema(schema.element)), schema);
+    }
+    if (schema instanceof z.ZodRecord) {
+        const def = schema._def;
+        return withDescription(z.record(def.keyType, deepOptionalizeSchema(def.valueType)), schema);
+    }
+    // Covers discriminated unions too. Rebuilding one as a plain union is
+    // deliberate — an optional discriminator is not a legal discriminated union.
+    if (schema instanceof z.ZodUnion ||
+        schema instanceof z.ZodDiscriminatedUnion) {
+        const options = schema._def.options;
+        if (Array.isArray(options) && options.length >= 2) {
+            return withDescription(z.union(options.map(deepOptionalizeSchema)), schema);
+        }
+        return schema;
+    }
+    // Scalars and anything we don't model (effects, pipes, lazy) pass through.
+    return schema;
+}
+/** `.optional()` builds a fresh wrapper, which does not inherit the description. */
+function optionalize(schema) {
+    return schema instanceof z.ZodOptional
+        ? schema
+        : withDescription(schema.optional(), schema);
+}
+/**
+ * Applies {@link deepOptionalizeSchema} to either form `registerTool` accepts —
+ * a `ZodObject` or a raw `{ key: ZodType }` shape — returning the same form.
+ * A schema we cannot rewrite is left untouched; strict validation is a better
+ * failure mode than a broken registration.
+ */
+function relaxOutputSchemaForProjection(outputSchema) {
+    try {
+        if (outputSchema instanceof z.ZodType) {
+            return deepOptionalizeSchema(outputSchema);
+        }
+        if (outputSchema && typeof outputSchema === "object") {
+            const relaxed = deepOptionalizeSchema(z.object(outputSchema));
+            return relaxed.shape;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return outputSchema;
+}
+// ---------------------------------------------------------------------------
 // createFilteringProxy — MCP server proxy that adds includeFields + filterBy
 // ---------------------------------------------------------------------------
+// Tool DESCRIPTIONS are always in the model's billed context (even for
+// deferred tools behind hosted tool_search — only parameter schemas are
+// deferred). Keep this suffix to one short line and put the usage docs +
+// per-tool field-path catalog in the includeFields/filterBy PARAMETER
+// descriptions instead, which cost nothing until the tool is loaded.
+// (PERF_MASTER_PLAN P2 #4a — the old suffix + path list was 46% of the
+// entire 131KB description surface.)
 const FILTERING_DESCRIPTION_SUFFIX = `
 
-**Output filtering (all tools):**
-- \`includeFields\` (string[]): Dot-notation paths to keep in the response (e.g. \`"vehicleEvents.vehicleLicensePlate"\`). Omit to return all fields.
-- \`filterBy\` (array): Predicates to filter array items. Each entry: \`{field, op, value}\` where op is one of \`= != > >= < <= contains\`. All conditions are ANDed. Example: \`[{field:"vehicleLicensePlate", op:"=", value:"ABC123"}]\`
-WARNING: some tool responses exceed 400k characters — use these params to request only the data you need.`;
-function applyFilteringToResult(result, includeFields, filterBy) {
-    if (!includeFields?.length && !filterBy?.length)
+Supports \`includeFields\` (field projection) and \`filterBy\` (row predicates) params to shrink large responses — see their parameter descriptions for usage and this tool's available field paths.`;
+function applyFilteringToResult(result, includeFields, filterBy, groupBy, protectedFields = []) {
+    if (!includeFields?.length && !filterBy?.length && !groupBy)
         return result;
-    // Always include whitelisted fields
+    // Re-add the cross-cutting keys plus whatever this tool declared, so a
+    // projection can only ever narrow the rows the caller asked about.
     const effectiveIncludeFields = includeFields?.length
-        ? [...INCLUDE_WHITELIST, ...includeFields]
+        ? [...ALWAYS_PROTECTED_FIELDS, ...protectedFields, ...includeFields]
         : includeFields;
     const filteredContent = result.content.map((item) => {
         if (item.type !== "text")
@@ -248,6 +616,8 @@ function applyFilteringToResult(result, includeFields, filterBy) {
             let parsed = JSON.parse(item.text);
             if (filterBy?.length)
                 parsed = applyFilterBy(parsed, filterBy) ?? parsed;
+            if (groupBy)
+                parsed = applyGroupBy(parsed, groupBy) ?? parsed;
             if (effectiveIncludeFields?.length)
                 parsed = filterIncludedFields(parsed, effectiveIncludeFields) ?? parsed;
             return { ...item, text: JSON.stringify(parsed) };
@@ -262,6 +632,9 @@ function applyFilteringToResult(result, includeFields, filterBy) {
         if (filterBy?.length)
             filteredStructured =
                 applyFilterBy(filteredStructured, filterBy) ?? filteredStructured;
+        if (groupBy)
+            filteredStructured =
+                applyGroupBy(filteredStructured, groupBy) ?? filteredStructured;
         if (effectiveIncludeFields?.length)
             filteredStructured =
                 filterIncludedFields(filteredStructured, effectiveIncludeFields) ??
@@ -278,6 +651,7 @@ function applyFilteringToResult(result, includeFields, filterBy) {
  * 1. Inject `includeFields` and `filterBy` into the tool's inputSchema
  * 2. Append a description suffix explaining the filtering params
  * 3. Wrap the handler to apply filtering to the tool result
+ * 4. Backstop results that would otherwise fail SDK output validation
  *
  * Tools whose names appear in `blacklist` are registered without modification.
  *
@@ -295,7 +669,12 @@ export function createFilteringProxy(server, blacklist = new Set()) {
                 if (blacklist.has(name)) {
                     return target.registerTool(name, config, handler);
                 }
-                let descriptionSuffix = FILTERING_DESCRIPTION_SUFFIX;
+                // Declared via protectFields() at the tool's own registration.
+                const protectedFields = config?.[PROTECTED_FIELDS] ?? [];
+                // Field-path catalog goes on the includeFields PARAM description
+                // (deferred/unbilled until the tool is loaded), not the tool
+                // description.
+                let includeFieldsArg = INCLUDE_FIELDS_ARG;
                 if (config.outputSchema) {
                     try {
                         let schema;
@@ -312,30 +691,43 @@ export function createFilteringProxy(server, blacklist = new Set()) {
                         if (paths.length > 0) {
                             const filteredPaths = [...new Set(paths.filter((p) => p !== "requestType" && p !== "error" && p.trim() !== ""))].sort();
                             if (filteredPaths.length > 0) {
-                                descriptionSuffix += `\n\n**Available output field paths for this tool's \`includeFields\` / \`filterBy\`:**\n` +
-                                    filteredPaths.map((p) => `- \`"${p}"\``).join("\n");
+                                includeFieldsArg = z
+                                    .array(z.string())
+                                    .nullable()
+                                    .describe(`${INCLUDE_FIELDS_DESCRIPTION}\n\nAvailable output field paths for this tool's includeFields / filterBy:\n` +
+                                    filteredPaths.map((p) => `- "${p}"`).join("\n"));
                             }
                         }
                     }
                     catch (error) {
-                        // Fall back to the default description suffix on parsing failure
+                        // Fall back to the base includeFields description on parsing failure
                     }
                 }
                 const augmentedConfig = {
                     ...config,
-                    description: (config.description ?? "") + descriptionSuffix,
+                    // Must come after the spread: the registered schema has to
+                    // tolerate the projection this proxy applies to the result.
+                    ...(config.outputSchema
+                        ? {
+                            outputSchema: relaxOutputSchemaForProjection(config.outputSchema),
+                        }
+                        : {}),
+                    description: (config.description ?? "") + FILTERING_DESCRIPTION_SUFFIX,
                     inputSchema: {
                         ...config.inputSchema,
-                        includeFields: INCLUDE_FIELDS_ARG,
+                        includeFields: includeFieldsArg,
                         filterBy: FILTER_BY_ARG,
+                        groupBy: GROUP_BY_ARG,
                     },
                 };
                 // biome-ignore lint/suspicious/noExplicitAny: proxy intercept
                 const wrappedHandler = async (args, extra) => {
-                    const { includeFields, filterBy, ...restArgs } = args;
+                    const { includeFields, filterBy, groupBy, ...restArgs } = args;
                     const result = await handler(restArgs, extra);
-                    return applyFilteringToResult(result, includeFields, filterBy);
+                    return applyFilteringToResult(result, includeFields, filterBy, groupBy, protectedFields);
                 };
+                // The marker is proxy-internal metadata; don't hand it to the SDK.
+                delete augmentedConfig[PROTECTED_FIELDS];
                 return target.registerTool(name, augmentedConfig, wrappedHandler);
             };
         },

package/dist/index.js

@@ -9,7 +9,7 @@ const TRANSPORT_TYPE = process.env.TRANSPORT_TYPE || "stdio";
 async function main() {
     const serverUrl = process.env.RHOMBUS_API_SERVER || "api2.rhombussystems.com";
     if (RHOMBUS_API_KEY) {
-        logger.info(`🔑 Using API_KEY: ${RHOMBUS_API_KEY}`);
+        logger.info(`🔑 Using API_KEY: <set, ${RHOMBUS_API_KEY.length} chars>`);
     }
     logger.info("🌐 Using server url", serverUrl);
     await serverInit();