@chrischall/mcp-utils 0.23.1 → 0.23.2

package/README.md

@@ -163,9 +163,15 @@ mutates its input. Do **not** apply it to a tool whose product IS the image —
 records are literally a `photoUrls` bundle) — where it empties the response
 rather than shrinking it.
 
+**Arrays of bare image URLs under a non-media key are kept** — `floorplan_urls:
+['a.jpg', 'b.jpg']` comes back whole. That is deliberate: removing a *key* is
+visible, removing *elements* is not, and a caller reading `.length` to report
+"4 floor plans" would be quietly wrong. Use `drop` for those. An array under a
+media-named key (`photos: [...]`) is already removed by the key rule.
+
 Two escape hatches, and they are symmetric: `keep` preserves a key that looks
 like media but is the thing the caller asked for; `drop` adds keys this pattern
-does not know, so a service with an unguessed naming convention can fix itself
+does not know. Both take `string | RegExp`, so a service with an unguessed naming convention can fix itself
 **without a library release** — which is what Google Workspace's
 `thumbnailLink`/`iconUri`/`photoUrl` cost the first time round. `keep` wins over
 `drop`.

package/dist/response/media.d.ts

@@ -25,6 +25,10 @@
  * answered. Three points is not worth a payload that can no longer distinguish
  * "no value" from "not reported".
  *
+ * **Arrays of bare image URLs under a non-media key are KEPT** — see the note
+ * in `walk`. Use `drop` for those; the key rule already covers an array under
+ * a media-named key (`photos: [...]`).
+ *
  * **Never apply this to a tool whose PRODUCT is the image.**
  * `alltrails_get_trail_photos`, `zillow_get_property_photos`,
  * `sw_get_receipt`, `musescore_fetch_svgs` exist to return exactly these URLs,
@@ -36,8 +40,20 @@ export interface StripMediaOptions {
     /**
      * Keys to keep even when they look like media — for a payload that mixes a
      * decorative avatar with an image the caller actually asked for.
+     *
+     * Takes the same `string | RegExp` shapes as `drop`. It did not until this
+     * was noticed: `drop` gained RegExp support in #194 and `keep` was left on
+     * strings, so a repo preserving several CONSTRUCTED media fields that share a
+     * prefix — redfin-mcp's `image_url` + `thumbnail_url`, compass-mcp's
+     * `primary_photo_url` + `primary_thumbnail_url` — had to enumerate each one
+     * while the opposite intent could be a pattern.
+     *
+     * That was an oversight in the API rather than a judgement, and if either
+     * side deserved the expressiveness first it was this one: a missed `drop`
+     * entry leaves bytes in the response, while a missed `keep` entry silently
+     * deletes a field the caller asked for.
      */
-    keep?: readonly string[];
+    keep?: readonly (string | RegExp)[];
     /**
      * Extra keys to drop, for a service whose naming this pattern does not know.
      *

package/dist/response/media.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../src/response/media.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAiFH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,GAAE,iBAAsB,GAAG,CAAC,CAmB3E"}
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../src/response/media.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAiFH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IACpC;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,GAAE,iBAAsB,GAAG,CAAC,CAoB3E"}

package/dist/response/media.js

@@ -25,6 +25,10 @@
  * answered. Three points is not worth a payload that can no longer distinguish
  * "no value" from "not reported".
  *
+ * **Arrays of bare image URLs under a non-media key are KEPT** — see the note
+ * in `walk`. Use `drop` for those; the key rule already covers an array under
+ * a media-named key (`photos: [...]`).
+ *
  * **Never apply this to a tool whose PRODUCT is the image.**
  * `alltrails_get_trail_photos`, `zillow_get_property_photos`,
  * `sw_get_receipt`, `musescore_fetch_svgs` exist to return exactly these URLs,
@@ -113,7 +117,9 @@ const MEDIA_URL = /^https?:\/\/[^\s]+?\.(png|jpe?g|gif|webp|svg|avif|bmp|ico)([?
  * The input is never mutated: several repos hand these helpers live cache rows.
  */
 export function stripMediaUrls(value, opts = {}) {
-    const keep = new Set((opts.keep ?? []).map((k) => k.toLowerCase()));
+    // `keep` is normalised exactly like `drop` below — same copy-the-regex
+    // reasoning, same once-per-call lowercasing.
+    const keep = normalizeRules(opts.keep ?? []);
     // Every RegExp rule is COPIED, once per call, for two reasons.
     //
     // `test()` on a `g`- or `y`-flagged regex advances `lastIndex` on a match, so
@@ -128,13 +134,17 @@ export function stripMediaUrls(value, opts = {}) {
     // caller's RegExp is input too. The docs invite hoisting `drop` as a shared
     // constant, which is exactly when someone else's `lastIndex` would be ours to
     // corrupt. Strings are lowercased here for the same once-per-call reason.
-    const drop = (opts.drop ?? []).map((rule) => typeof rule === 'string' ? rule.toLowerCase() : new RegExp(rule.source, rule.flags));
+    const drop = normalizeRules(opts.drop ?? []);
     return walk(value, keep, drop);
 }
-/** Does `key` match one of the caller's extra drop rules? */
-function alsoDrop(key, drop) {
+/** Lowercase the strings and copy the regexes, once per call. See above. */
+function normalizeRules(rules) {
+    return rules.map((rule) => (typeof rule === 'string' ? rule.toLowerCase() : new RegExp(rule.source, rule.flags)));
+}
+/** Does `key` match one of the caller's rules? Used for both `keep` and `drop`. */
+function matchesRule(key, rules) {
     const lower = key.toLowerCase();
-    for (const rule of drop) {
+    for (const rule of rules) {
         if (typeof rule === 'string') {
             if (rule === lower)
                 return true;
@@ -148,6 +158,20 @@ function alsoDrop(key, drop) {
     return false;
 }
 function walk(value, keep, drop) {
+    // Array ELEMENTS are walked but never value-tested, so an array of bare image
+    // URLs under a non-media key — homes-mcp's `floorplan_urls` — comes back
+    // whole. That is deliberate, and it is the one place this helper knowingly
+    // leaves bytes on the table.
+    //
+    // Removing a KEY is visible: the field is gone and a reader can see that it
+    // is. Removing ELEMENTS is invisible — the array is merely shorter, and a
+    // caller reading `floorplan_urls.length` to say "this listing has 4 floor
+    // plans" would be quietly wrong. That is the same class of harm as the
+    // dropped-nulls rule this helper also refuses (see the docblock above):
+    // a silently altered count reads as fact.
+    //
+    // The fix for such a field is `drop: ['floorplan_urls']` at the call site,
+    // which removes the key outright and stays legible in the response.
     if (Array.isArray(value))
         return value.map((v) => walk(v, keep, drop));
     // `null` is data here, not an empty object — see the docblock.
@@ -160,11 +184,11 @@ function walk(value, keep, drop) {
         return value;
     const out = {};
     for (const [key, v] of Object.entries(value)) {
-        if (keep.has(key.toLowerCase())) {
+        if (matchesRule(key, keep)) {
             out[key] = v;
             continue;
         }
-        if (MEDIA_KEY.test(key) || alsoDrop(key, drop))
+        if (MEDIA_KEY.test(key) || matchesRule(key, drop))
             continue;
         if (typeof v === 'string' && MEDIA_URL.test(v))
             continue;

package/dist/response/media.js.map

@@ -1 +1 @@
-{"version":3,"file":"media.js","sourceRoot":"","sources":["../../src/response/media.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"media.js","sourceRoot":"","sources":["../../src/response/media.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/mcp-utils",
-  "version": "0.23.1",
+  "version": "0.23.2",
   "description": "Shared scaffolding for the chrischall MCP fleet — server bootstrap, tool-result formatting, helpful errors, hardened env/config, a bearer API-client kit, zod atoms, session registries, a fetchproxy transport adapter, auth resolver skeletons, an in-memory test harness, and opt-in HTML helpers. The generic MCP glue hoisted out of ~19 sibling servers.",
   "type": "module",
   "license": "MIT",