@chrischall/mcp-utils 0.22.0 → 0.23.1

package/README.md

@@ -144,14 +144,31 @@ from one, and a value that silently aliases to another is a lie in the schema.
 
 `stripMediaUrls(payload)` is the highest-value projection that needs no
 knowledge of the API: it drops `avatar` / `picture` / `cover_photo` /
-`thumbnail` keys and bare image URLs. Measured on a real 187.6 KB
+`thumbnail` keys — including the `…Link` / `…Uri` / `…Url` suffixed forms every
+Google Workspace API uses (`thumbnailLink`, `iconUri`, `photoUrl`), and the
+snake_case and kebab-case forms most other APIs use (`image_url`,
+`primary_photo_url`, `avatar_image_url`) — and bare
+image URLs. The suffix is load-bearing outside consumer-social APIs: without it
+the rule matched none of Google's media fields, and `thumbnailLink` alone is 32%
+of a `gog drive ls` listing. Its key rule stays anchored at the START, so a key
+that merely contains a media noun survives — Drive's `hasThumbnail: false` is a
+fact about the file, and `webViewLink` sits in the same object as
+`thumbnailLink`. Measured on a real 187.6 KB
 `splitwise-mcp` groups response — which does not fit in a tool result at all —
 minifying alone is −25%, minifying **and** stripping media is **−73%**. It
 deliberately keeps `null` (an absent key and a null one are different facts;
 `ofw-mcp`'s `viewedAt: null` means "never opened"), keeps page URLs, and never
 mutates its input. Do **not** apply it to a tool whose product IS the image —
-`alltrails_get_trail_photos`, `sw_get_receipt` — where it empties the response
-rather than shrinking it; `keep` is the escape hatch for a mixed payload.
+`alltrails_get_trail_photos`, `sw_get_receipt`, `redfin`'s photo tools (whose
+records are literally a `photoUrls` bundle) — where it empties the response
+rather than shrinking it.
+
+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
+**without a library release** — which is what Google Workspace's
+`thumbnailLink`/`iconUri`/`photoUrl` cost the first time round. `keep` wins over
+`drop`.
 
 `viewResult` minifies `compact` and `full` and leaves `raw` indented (that rung
 exists to be read by a person); `minifiedResult` is the same rule with no view

package/dist/response/media.d.ts

@@ -38,6 +38,22 @@ export interface StripMediaOptions {
      * decorative avatar with an image the caller actually asked for.
      */
     keep?: readonly string[];
+    /**
+     * Extra keys to drop, for a service whose naming this pattern does not know.
+     *
+     * The symmetric half of `keep`, and the point is that a repo should not need
+     * a LIBRARY RELEASE to strip its own noise. That is exactly what happened
+     * once already: Google Workspace names every picture `thumbnailLink` /
+     * `iconUri` / `photoUrl`, none of which the original pattern matched, and
+     * closing it took a version bump across every consumer. The next service with
+     * an unguessed convention can now fix itself locally and propose the pattern
+     * change at leisure.
+     *
+     * A string matches a key exactly, case-insensitively; a RegExp is tested
+     * against the key as given, whatever flags it carries — see `stripMediaUrls`
+     * for why a `g` or `y` rule needs care.
+     */
+    drop?: readonly (string | RegExp)[];
 }
 /**
  * Return a copy of `value` with media keys and bare image URLs removed.

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;AAyBH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,GAAE,iBAAsB,GAAG,CAAC,CAG3E"}
+{"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"}

package/dist/response/media.js

@@ -32,8 +32,59 @@
  * tool's own name is the test. `keep` is the escape hatch for a payload that
  * mixes both.
  */
-/** Keys whose value is a picture, whatever it holds. */
-const MEDIA_KEY = /^(avatar|tall_avatar|cover_photo|cover_image|picture|photo|thumbnail|thumb|image|icon|banner|profile_pic(ture)?|logo)s?$/i;
+/**
+ * Keys whose value is a picture, whatever it holds.
+ *
+ * The optional `Link|Uri|Url` suffix is what makes this work outside
+ * consumer-social APIs. Splitwise names a picture `avatar`; every Google
+ * Workspace API names it `thumbnailLink`, `iconUri`, `photoUrl`. Without the
+ * suffix this rule matched NONE of them — measured on a real `gog drive ls`
+ * listing of 25 rows, `thumbnailLink` alone was 4,973 bytes of 15,698 (32% of
+ * the payload) and this helper removed zero of it. Nor does MEDIA_URL cover the
+ * gap: Google's media URLs are extension-less signed URLs. Adding the suffix
+ * takes that listing down 31%, and `drive search` — which supports no field
+ * mask at all, so nothing else can shrink it — down 30%.
+ *
+ * The anchor stays at the START, which is the whole safety property. A key that
+ * merely CONTAINS a media noun is untouched, so Drive's `hasThumbnail: false`
+ * survives: it is a fact about the file, and a caller filtering on it would
+ * otherwise see the key vanish and read that as "not reported". Only the three
+ * reference suffixes are added, so `thumbnailWidth` (a number) and
+ * `imageMediaMetadata` (EXIF) stay too — and so does `webViewLink`, whose noun
+ * is not media and which sits in the same object as `thumbnailLink`.
+ *
+ * The trailing `s?` after the suffix closes a gap the suffix opened: the
+ * pattern matched `imageUrl` and `images`, but not `imageUrls`. Those plurals
+ * are not hypothetical — `imageUrls` appears 5 times in groupon-mcp and
+ * `photoUrls` 17 times in redfin-mcp — and a rule that catches the singular
+ * while missing the plural of the same field is the kind of half-cover that
+ * reads as working. (Counted with `grep -rhoE` over both repos excluding
+ * node_modules. An earlier draft said 33 across the two and named `avatarUrls`
+ * as a third form; neither reproduced.)
+ */
+const MEDIA_NOUN = '(?:avatar|picture|photo|thumbnail|thumb|image|icon|banner|profile_pic(?:ture)?|logo)';
+/**
+ * A bounded set of qualifiers that may precede the noun in a snake_case or
+ * kebab-case key: `primary_photo_url`, `profile_image_url`, `hero-banner`.
+ *
+ * CLOSED on purpose, never `\w+`. That is the whole difference between this
+ * and the two clauses removed in #191 — a bare `\bavatar\b` and an
+ * `/avatars?/` path segment — which were open-ended, stripped genuine page
+ * URLs, and (measured) removed zero bytes. A media noun is also allowed here,
+ * for `avatar_image_url`.
+ *
+ * `cover` and `tall` live here rather than as `cover_photo` / `cover_image` /
+ * `tall_avatar` entries in MEDIA_NOUN. Those three were redundant once this
+ * list existed — `cover` + `photo` already composes — and keeping both spellings
+ * meant the snake_case form matched while the camelCase one silently did not.
+ *
+ * The separator is OPTIONAL for the same reason. With `[_-]` required,
+ * `cover_photo` was stripped and `coverPhoto` was kept: the same field, the
+ * same meaning, a different answer decided by an API's casing convention. That
+ * asymmetry is the exact shape of the bug #197 was about, one level up.
+ */
+const MEDIA_QUALIFIER = '(?:primary|secondary|main|default|cover|hero|profile|master|rendered|small|medium|large|full|original|tall)';
+const MEDIA_KEY = new RegExp(`^(?:(?:${MEDIA_QUALIFIER}|${MEDIA_NOUN})[_-]?)?${MEDIA_NOUN}s?(?:[_-]?(?:link|uri|url|src)s?)?$`, 'i');
 /**
  * A URL that points at an image rather than at a page: a known image extension
  * ending the PATH.
@@ -63,11 +114,42 @@ const MEDIA_URL = /^https?:\/\/[^\s]+?\.(png|jpe?g|gif|webp|svg|avif|bmp|ico)([?
  */
 export function stripMediaUrls(value, opts = {}) {
     const keep = new Set((opts.keep ?? []).map((k) => k.toLowerCase()));
-    return walk(value, 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
+    // one rule object tested across a sequence of keys silently skips the next key
+    // whose length falls inside the advanced index. It fails OPEN — the key
+    // survives — and which key survives depends on the ORDER they are walked in,
+    // so it reads as "the rule did not match" rather than as a bug. Nothing in the
+    // type forbids a `/g`, and `/^blur/gi` is a natural thing to write.
+    //
+    // Copying rather than resetting the caller's own regex keeps the promise this
+    // helper already makes about payloads: it never mutates its input, and a
+    // 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));
+    return walk(value, keep, drop);
+}
+/** Does `key` match one of the caller's extra drop rules? */
+function alsoDrop(key, drop) {
+    const lower = key.toLowerCase();
+    for (const rule of drop) {
+        if (typeof rule === 'string') {
+            if (rule === lower)
+                return true;
+            continue;
+        }
+        // Our own copy, so resetting is free and invisible to the caller.
+        rule.lastIndex = 0;
+        if (rule.test(key))
+            return true;
+    }
+    return false;
 }
-function walk(value, keep) {
+function walk(value, keep, drop) {
     if (Array.isArray(value))
-        return value.map((v) => walk(v, keep));
+        return value.map((v) => walk(v, keep, drop));
     // `null` is data here, not an empty object — see the docblock.
     if (value === null || typeof value !== 'object')
         return value;
@@ -82,11 +164,11 @@ function walk(value, keep) {
             out[key] = v;
             continue;
         }
-        if (MEDIA_KEY.test(key))
+        if (MEDIA_KEY.test(key) || alsoDrop(key, drop))
             continue;
         if (typeof v === 'string' && MEDIA_URL.test(v))
             continue;
-        out[key] = walk(v, keep);
+        out[key] = walk(v, keep, drop);
     }
     return out;
 }

package/dist/response/media.js.map

@@ -1 +1 @@
-{"version":3,"file":"media.js","sourceRoot":"","sources":["../../src/response/media.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,wDAAwD;AACxD,MAAM,SAAS,GACb,2HAA2H,CAAC;AAE9H;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,SAAS,GAAG,qEAAqE,CAAC;AAUxF;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAI,KAAQ,EAAE,OAA0B,EAAE;IACtE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IACpE,OAAO,IAAI,CAAC,KAAK,EAAE,IAAI,CAAM,CAAC;AAChC,CAAC;AAED,SAAS,IAAI,CAAC,KAAc,EAAE,IAAyB;IACrD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACjE,+DAA+D;IAC/D,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,6EAA6E;IAC7E,6EAA6E;IAC7E,sCAAsC;IACtC,IAAI,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC7G,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QACxE,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAChC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACb,SAAS;QACX,CAAC;QACD,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,SAAS;QAClC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,SAAS;QACzD,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"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.22.0",
+  "version": "0.23.1",
   "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",