@chrischall/mcp-utils 0.7.0 → 0.9.0

package/README.md

@@ -28,7 +28,7 @@ import light:
 | Import | Contents |
 | --- | --- |
 | `@chrischall/mcp-utils` | core barrel: `server` + `response` + `errors` + `config` + `fs` + `http` + `zod` + `auth` |
-| `@chrischall/mcp-utils/session` | session registry, session store, token manager |
+| `@chrischall/mcp-utils/session` | session registry, session store, token manager, cookie-session manager |
 | `@chrischall/mcp-utils/fetchproxy` | fetchproxy transport adapter, bot-wall / retry / concurrency helpers |
 | `@chrischall/mcp-utils/html` | opt-in HTML scraping helpers (needs `node-html-parser`) |
 | `@chrischall/mcp-utils/test` | in-memory test harness for tool registration |
@@ -109,19 +109,46 @@ tool surface can show the user.
 
 ### `config` — hardened env/config
 
-`readEnvVar`, `requireEnvVar`, `parseBoolEnv`, `expandPath`, `loadDotenvSafely`.
+`readEnvVar`, `requireEnvVar`, `parseBoolEnv`, `readPortEnv`, `expandPath`,
+`loadDotenvSafely`, `createCachedJsonArrayLoader`.
 
 ```ts
-import { requireEnvVar, parseBoolEnv, expandPath } from '@chrischall/mcp-utils';
+import { requireEnvVar, parseBoolEnv, readPortEnv, expandPath } from '@chrischall/mcp-utils';
 
 const apiKey = requireEnvVar('MY_API_KEY');
 const debug = parseBoolEnv('MY_DEBUG', { default: false });
+const port = readPortEnv('MY_WS_PORT', 37149);  // placeholder/NaN/out-of-range → fallback
 const home = expandPath('~/.config/my-mcp');
 ```
 
+`readPortEnv` parses a TCP port with the same placeholder hardening as
+`readEnvVar`, plus integer + `1..65535` range validation — so an unexpanded
+`${MY_WS_PORT}` or junk falls back to the default instead of handing `NaN` to
+the server.
+
 `loadDotenvSafely` is a no-throw `.env` loader (returns `false` instead of
 failing when the file is absent).
 
+`createCachedJsonArrayLoader` builds a cached, negative-cached loader for an
+env-named JSON string-array file — the `loadCommunities`/`DEFAULT_COMMUNITIES`
+pattern shared across the realty servers:
+
+```ts
+import { createCachedJsonArrayLoader } from '@chrischall/mcp-utils';
+
+const loadCommunities = createCachedJsonArrayLoader({
+  envVar: 'REDFIN_COMMUNITIES_FILE',  // path to a JSON string-array file
+  defaults: DEFAULT_COMMUNITIES,      // returned when unset/missing/invalid
+  label: 'redfin-mcp',
+});
+
+const communities = loadCommunities();  // parses + caches; re-reads only on path change
+```
+
+A successful parse is cached; a missing/unreadable file, invalid JSON, or a
+non-string-array logs one stderr warning and negative-caches (returns defaults
+without re-reading). Pass `readFile` to inject a reader in tests.
+
 ### `fs` — streaming file helpers (uploads)
 
 `fileBlob`, `readFileHead`.
@@ -145,10 +172,15 @@ constant memory instead of a 20 MB Buffer.
 ### `http` — bearer API-client kit
 
 `createApiClient` plus building blocks: `buildQueryString`, `buildOptionalBody`,
-`formatApiError`, `parseLinkHeader`, `parseCookieJar`, JWT helpers
-(`decodeJwtExp`, `decodeJwtSessionId`, `validateJwtExpiry`), and the
+`formatApiError`, `parseLinkHeader`, `parseCookieJar`, `parseCookieHeader`,
+`runBoundedBatch`, JWT helpers (`decodeJwtExp`, `decodeJwtSessionId`,
+`decodeJwtClaim`, `validateJwtExpiry`), and the `ApiError` / `UpstreamHttpError` /
 `UnauthorizedError` / `RateLimitedError` / `RequestTimeoutError` classes.
 
+`decodeJwtClaim(token, claim)` is the generic single-claim reader — returns the
+raw claim value (`unknown`) or `undefined` for an undecodable token / absent
+claim, so a repo doesn't hand-roll its own `extractXFromJwt`.
+
 ```ts
 import { createApiClient } from '@chrischall/mcp-utils';
 
@@ -167,6 +199,37 @@ const data = await api.get('/v1/things', { query: { page: 2 } });
 `RequestTimeoutError` instead of hanging the tool call. A 429 retry gets a fresh
 timeout. Omit it to keep the previous unbounded behavior.
 
+`parseCookieHeader(header)` parses an inbound *request* `Cookie:` header
+(`name=value; name2=value2`) into a `Record<string, string>` (first `=` splits,
+so values may contain `=`; last value wins on a duplicate name). It's the
+counterpart to `parseCookieJar`, which parses *response* `Set-Cookie` headers
+with their attributes and deletion semantics.
+
+`UpstreamHttpError(status, message)` is a directly-`throw new`-able,
+status-carrying HTTP error — the manual-throw parallel to `ApiError` (which
+`createApiClient` throws internally). It `extends ApiError`, so both the
+`err instanceof ApiError && err.status === 404` branch and a narrower
+`instanceof UpstreamHttpError` check work. Use it from a transport/bridge code
+path that doesn't route through `createApiClient` but still needs to branch on a
+404.
+
+```ts
+import { runBoundedBatch } from '@chrischall/mcp-utils';
+
+const rows = await runBoundedBatch(ids, (id, signal) => fetchRow(id, signal), {
+  deadlineMs: 45_000,                        // overall hard deadline for the whole batch
+  concurrency: 4,                            // optional fan-out cap
+  onTimeout: (id, i) => ({ id, pending: true }), // backfill any row the deadline cut off
+});
+```
+
+`runBoundedBatch(items, worker, opts)` races the whole batch against one overall
+`deadlineMs`; any item still unsettled when it fires is filled by
+`onTimeout(item, index)` (and its worker abandoned + `AbortSignal`-signalled) so
+a single hung row can't wedge the call. It always returns a full-length,
+input-ordered array. `setTimer`/`clearTimer` are injectable for tests. This
+hoists zillow's bulk-tool deadline + `pending`-backfill primitive.
+
 ### `dates` — date-format converters
 
 `isoToDmy`, `dmyToIso`, `isoToCompactTimestamp`. For upstreams that don't speak
@@ -184,7 +247,8 @@ deepMapStringField(payload, 'eventDate', dmyToIso);     // '28-08-2025' → '202
 ### `zod` — schema atoms
 
 Reusable schemas (`PositiveInt`, `NonNegInt`, `NonEmptyString`, `IsoDate`,
-`IsoTime`, `schemaOrigin`, `schemaConfirm`), pagination helpers
+`IsoTime`, `NumericIdString`, `SafePathSegment`, `schemaOrigin`,
+`schemaConfirm`), pagination helpers
 (`paginationSchema`, `pageSchema`, `calculateOffset`), tool-annotation builders
 (`toolAnnotations`), and time normalizers (`extractTime`, `normalizeTime`).
 
@@ -196,6 +260,11 @@ const offset = calculateOffset(page, size);
 const annotations = toolAnnotations({ readOnly: true });
 ```
 
+`NumericIdString` (`/^\d+$/`) and `SafePathSegment` (rejects `/`, `..`, `?`,
+`#`, and whitespace) harden caller-supplied ids that get interpolated into
+request paths — defense-in-depth against path traversal and query/fragment
+injection.
+
 ### `auth` — auth resolver skeletons
 
 `createAuthResolver`, `resolveAuthPattern`, `sessionLoginFlow`,
@@ -209,28 +278,80 @@ const resolver = createAuthResolver({ /* ... */ });
 const refresh = createOAuth2Refresher({ /* ... */ });
 ```
 
-### `session` — session registry & token manager *(subpath)*
+### `session` — session registry, token manager & cookie-session manager *(subpath)*
 
 ```ts
 import {
   createSessionRegistry,
   registerSessionTools,
   TokenManager,
+  CookieSessionManager,
 } from '@chrischall/mcp-utils/session';
 
 const registry = createSessionRegistry();
 registerSessionTools(server, { registry /* ... */ });
 ```
 
+The `${prefix}_register_session` tool takes an optional `mark_active`
+(default `false`); passing `mark_active: true` makes the newly-registered
+session active in the same call instead of requiring a follow-up
+`${prefix}_set_active_session`.
+
 Includes `SessionStore`, `normalizeOrigin`, `AuthMode`, and `TokenManager`
 (with `TOKEN_REFRESH_SKEW_MS` for proactive refresh).
 
+`CookieSessionManager<S, R = Response>` is the cookie-session analog of
+`TokenManager` for sites authenticated by a browser-style cookie session rather
+than a bearer token. It owns *when* to log in (single-flight, so concurrent
+callers coalesce into ONE login), clears the in-flight promise on settle (a
+rejected login never sticks — the next `ensure()` retries), and `withSession()`
+re-logs-in and replays a request **exactly once** on a detected expiry (no
+infinite loop). The injected `isExpired(res)` predicate is the hook for body/URL
+heuristics — so a `200` serving an HTML login page or a redirect away from the
+target is treated as expired, not just `401`/`403`. An optional
+`isPermanentError` caches genuine missing-config errors while leaving transient
+login failures retryable.
+
+`isExpired` is **optional** — omit it for ensure-only consumers with no
+per-request expiry path (e.g. Skylight, whose re-auth lives in `TokenManager`);
+it defaults to `() => false`, so `withSession()` simply never replays.
+
+The second type param `R` (default `Response`) is the response type
+`withSession`'s `call` resolves to. The manager is response-agnostic — it only
+hands `R` to `isExpired` and returns it untouched — so override `R` for a custom
+or non-fetch transport (e.g. Artsonia's `{ setCookie?, location?, url, body }`).
+Existing adopters writing `CookieSessionManager<MySession>` keep `R = Response`
+with **no call-site changes**.
+
+```ts
+const sessions = new CookieSessionManager<{ cookieHeader: string; csrfToken?: string }>({
+  login: () => loginWithPassword(),                 // mints a fresh cookie session
+  isExpired: async (res) =>
+    res.status === 401 || /<form[^>]*id="login"/i.test(await res.clone().text()),
+});
+
+const res = await sessions.withSession((s) =>
+  fetch(url, { headers: { cookie: s.cookieHeader } }),
+);
+
+// Custom non-fetch transport: parameterize R (and isExpired reads R's members).
+const custom = new CookieSessionManager<MySession, MyResponse>({
+  login: () => loginWithPassword(),
+  isExpired: (res) => /login\.asp/i.test(res.location ?? res.url),
+});
+```
+
+Replaces the hand-rolled re-login / single-flight / 401-replay code in
+`artsonia-mcp`, `canvas-parent-mcp`, `evite-mcp`, `signupgenius-mcp`, and
+`skylight-mcp`.
+
 ### `fetchproxy` — transport adapter *(subpath, optional peer)*
 
 ```ts
 import {
   createFetchproxyTransport,
   createBootstrapOpts,
+  registerBridgeHealthcheckTool,
   mapWithConcurrency,
   TokenBucket,
   classifyBotWall,
@@ -241,6 +362,43 @@ Wraps `@fetchproxy/server` with the fleet's transport, bot-wall classification,
 deadline/retry, token-bucket rate limiting, and bounded-concurrency helpers, and
 re-exports the fetchproxy typed-error hierarchy.
 
+**Transport verb adapters.** Beyond the `start` / `close` / `status` lifecycle,
+`createFetchproxyTransport` exposes the verb passthroughs redfin / homes /
+compass / musescore had each hand-rolled over the server:
+
+- `fetch(init)` → `{ status, body, url }` via `server.request(...)`;
+- `requestJson(method, path, init?)` → `{ data, result }` via
+  `server.requestJson(...)` (serialization + header defaults + 204→null +
+  `JSON.parse`; the caller keeps its per-site `throwIfNotOk` over `result`);
+- `runProbe(fetchFn, probePath)` → the healthcheck probe loop.
+
+The one per-site bit is the subdomain: pass `defaultSubdomain: 'www'` for sites
+served from `www` (redfin/homes/compass); omit it for apex-served sites
+(musescore). A per-call `subdomain` always overrides the default, and absolute
+`http(s)://` paths self-describe their host. Other per-site verbs (e.g.
+musescore's `download` capability) stay caller-supplied — the factory covers the
+common subset, not the long tail.
+
+**Bridge-healthcheck tool factory.** `registerBridgeHealthcheckTool({ server,
+prefix, probePath, hostLabel, transport, probeFn })` registers a
+`<prefix>_healthcheck` tool that round-trips `probePath` through the bridge and
+reports bridge role / port / timing plus an actionable hint ladder
+(`bridge_down` → wake the SW, `role === null` → check startup, `timeout` →
+extension not connected, …). The failure hint cites the **actual configured
+bridge port** from `bridgeHealth()`, not a hardcoded `37149` — fixing the bug
+the per-site compass + musescore copies shared.
+
+```ts
+registerBridgeHealthcheckTool({
+  server,
+  prefix: 'compass',
+  probePath: '/robots.txt',
+  hostLabel: 'compass.com',
+  transport,
+  probeFn: (path) => client.fetchHtml(path),
+});
+```
+
 ### `html` — scraping helpers *(subpath, optional peer)*
 
 ```ts

package/dist/config/index.d.ts

@@ -62,6 +62,72 @@ export declare function parseBoolEnv(key: string, opts?: ParseBoolEnvOptions): b
  * NOT expanded — only the current user's home is ever substituted.
  */
 export declare function expandPath(p: string): string;
+/** Options for {@link readPortEnv}. */
+export interface ReadPortEnvOptions {
+    /** The source to read from. Defaults to {@link process.env}. */
+    env?: EnvSource;
+}
+/**
+ * Read a TCP port from an environment variable, hardened the way
+ * {@link readEnvVar} hardens any var (trim, treat blank / `'undefined'` /
+ * `'null'` / unsubstituted `${...}` placeholder as unset) PLUS numeric
+ * validation: the value must parse to an integer in the valid port range
+ * `1..65535`.
+ *
+ * Returns `fallback` when the variable is unset, a placeholder, non-numeric, or
+ * out of range. Consolidates the bare `Number(process.env.X_WS_PORT)` pattern
+ * across compass/redfin/homes/musescore, which yields `NaN` on an unexpanded
+ * `${...}` placeholder or junk and then hands `NaN` to the server.
+ *
+ * @example readPortEnv('REDFIN_WS_PORT', 37149)
+ */
+export declare function readPortEnv(key: string, fallback: number, opts?: ReadPortEnvOptions): number;
+/** A minimal injectable file reader: returns the file's UTF-8 contents. */
+export type ReadFileSyncFn = (path: string) => string;
+/** Options for {@link createCachedJsonArrayLoader}. */
+export interface CachedJsonArrayLoaderOptions {
+    /** Name of the env var holding the path to a JSON string-array file. */
+    envVar: string;
+    /** Returned when the var is unset, or the file is missing/unreadable/invalid. */
+    defaults: string[];
+    /** The source to read env from. Defaults to {@link process.env}. */
+    env?: EnvSource;
+    /**
+     * Injectable file reader (for tests). Defaults to a `node:fs` reader that
+     * throws when the file is missing — a missing file is caught and
+     * negative-cached like any other read failure.
+     */
+    readFile?: ReadFileSyncFn;
+    /**
+     * Label woven into the stderr warning on a missing/invalid file (e.g.
+     * `'redfin-mcp'`). Defaults to the env-var name.
+     */
+    label?: string;
+}
+/**
+ * Build a cached, negative-cached loader for an env-named JSON string-array
+ * file — the `loadCommunities` + `DEFAULT_COMMUNITIES` pattern quadruplicated
+ * across redfin/zillow/homes/onehome (only the env var differs:
+ * `REDFIN_/ZILLOW_/HOMES_/ONEHOME_COMMUNITIES_FILE`).
+ *
+ * The returned function:
+ *  - reads the file path from `envVar` via {@link readEnvVar} (placeholder
+ *    hardening), returning `defaults` when unset (and clearing any cache),
+ *  - parses the file as a JSON array of strings; on success caches and returns
+ *    it (keyed by the env-var value, so a path change re-reads),
+ *  - on a missing / unreadable file, invalid JSON, or non-string-array,
+ *    logs a single stderr warning and **negative-caches** — it returns
+ *    `defaults` without re-reading on subsequent calls for the same path,
+ *  - never re-reads a successfully-cached file.
+ *
+ * @example
+ * const loadCommunities = createCachedJsonArrayLoader({
+ *   envVar: 'REDFIN_COMMUNITIES_FILE',
+ *   defaults: DEFAULT_COMMUNITIES,
+ *   label: 'redfin-mcp',
+ * });
+ */
+export declare function createCachedJsonArrayLoader(opts: CachedJsonArrayLoaderOptions): () => string[];
 /** Options for {@link loadDotenvSafely}. */
 export interface LoadDotenvOptions {
     /** Path to the `.env` file. Defaults to dotenv's own resolution (CWD). */

package/dist/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAGA,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE3D,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAaD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,MAAM,GAAG,SAAS,CAerF;AAED,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,MAAM,CAO/E;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAKD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAQjF;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ5C;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,OAAO,CAAC,CAwBrF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAIA,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE3D,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAaD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,MAAM,GAAG,SAAS,CAerF;AAED,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,MAAM,CAO/E;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAKD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAQjF;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ5C;AAED,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,GAAG,CAAC,EAAE,SAAS,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,MAAM,CAShG;AAED,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAEtD,uDAAuD;AACvD,MAAM,WAAW,4BAA4B;IAC3C,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oEAAoE;IACpE,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,4BAA4B,GAAG,MAAM,MAAM,EAAE,CAoD9F;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,OAAO,CAAC,CAwBrF"}

package/dist/config/index.js

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 /**
@@ -93,6 +94,102 @@ export function expandPath(p) {
     }
     return isAbsolute(expanded) ? expanded : resolve(expanded);
 }
+/**
+ * Read a TCP port from an environment variable, hardened the way
+ * {@link readEnvVar} hardens any var (trim, treat blank / `'undefined'` /
+ * `'null'` / unsubstituted `${...}` placeholder as unset) PLUS numeric
+ * validation: the value must parse to an integer in the valid port range
+ * `1..65535`.
+ *
+ * Returns `fallback` when the variable is unset, a placeholder, non-numeric, or
+ * out of range. Consolidates the bare `Number(process.env.X_WS_PORT)` pattern
+ * across compass/redfin/homes/musescore, which yields `NaN` on an unexpanded
+ * `${...}` placeholder or junk and then hands `NaN` to the server.
+ *
+ * @example readPortEnv('REDFIN_WS_PORT', 37149)
+ */
+export function readPortEnv(key, fallback, opts = {}) {
+    const raw = readEnvVar(key, { env: opts.env });
+    if (raw === undefined)
+        return fallback;
+    // Strict integer parse: reject `12abc`, `1.5`, `0x10`, etc. that `Number`
+    // would otherwise coerce or accept.
+    if (!/^\d+$/.test(raw))
+        return fallback;
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return fallback;
+    return port;
+}
+/**
+ * Build a cached, negative-cached loader for an env-named JSON string-array
+ * file — the `loadCommunities` + `DEFAULT_COMMUNITIES` pattern quadruplicated
+ * across redfin/zillow/homes/onehome (only the env var differs:
+ * `REDFIN_/ZILLOW_/HOMES_/ONEHOME_COMMUNITIES_FILE`).
+ *
+ * The returned function:
+ *  - reads the file path from `envVar` via {@link readEnvVar} (placeholder
+ *    hardening), returning `defaults` when unset (and clearing any cache),
+ *  - parses the file as a JSON array of strings; on success caches and returns
+ *    it (keyed by the env-var value, so a path change re-reads),
+ *  - on a missing / unreadable file, invalid JSON, or non-string-array,
+ *    logs a single stderr warning and **negative-caches** — it returns
+ *    `defaults` without re-reading on subsequent calls for the same path,
+ *  - never re-reads a successfully-cached file.
+ *
+ * @example
+ * const loadCommunities = createCachedJsonArrayLoader({
+ *   envVar: 'REDFIN_COMMUNITIES_FILE',
+ *   defaults: DEFAULT_COMMUNITIES,
+ *   label: 'redfin-mcp',
+ * });
+ */
+export function createCachedJsonArrayLoader(opts) {
+    const env = opts.env ?? process.env;
+    const label = opts.label ?? opts.envVar;
+    // Default reader: `node:fs#readFileSync` (utf8). A missing file throws, which
+    // the catch below turns into a negative-cached fallback — mirroring redfin's
+    // original `existsSync` guard without the extra stat.
+    const readFile = opts.readFile ?? ((path) => readFileSync(path, 'utf8'));
+    let cached = null;
+    // Path the cache (positive OR negative) is keyed to. A negative cache is
+    // `cached === null && cachedPath === <path>`: we resolved that path to
+    // defaults and won't re-read it.
+    let cachedPath = null;
+    return function load() {
+        const path = readEnvVar(opts.envVar, { env });
+        if (!path) {
+            // Unset: never cache (the var may be set later) and return defaults.
+            cached = null;
+            cachedPath = null;
+            return opts.defaults;
+        }
+        if (cachedPath === path) {
+            // Same path as last time — positive cache (return it) or negative cache
+            // (cached === null → return defaults without re-reading).
+            return cached ?? opts.defaults;
+        }
+        try {
+            const raw = readFile(path);
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed) || !parsed.every((s) => typeof s === 'string')) {
+                console.error(`[${label}] ${opts.envVar}="${path}" must be a JSON string array — falling back to defaults.`);
+                cached = null;
+                cachedPath = path; // negative-cache this path
+                return opts.defaults;
+            }
+            cached = parsed;
+            cachedPath = path;
+            return cached;
+        }
+        catch (err) {
+            console.error(`[${label}] failed to load ${opts.envVar}="${path}": ${err instanceof Error ? err.message : String(err)} — falling back to defaults.`);
+            cached = null;
+            cachedPath = path; // negative-cache this path
+            return opts.defaults;
+        }
+    };
+}
 /**
  * Load a `.env` file for local development, swallowing any failure.
  *

package/dist/config/index.js.map

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

package/dist/fetchproxy/index.d.ts

@@ -9,7 +9,13 @@
  *
  *  - {@link createFetchproxyTransport} wraps a `FetchproxyServer` in the
  *    `start` / `close` / `status` lifecycle every MCP's transport interface
- *    expects, with optional debug-gated role logging.
+ *    expects, with optional debug-gated role logging, PLUS the opt-in verb
+ *    passthroughs (`fetch` / `requestJson` / `runProbe`) that redfin / homes /
+ *    compass / musescore had each hand-rolled over the server.
+ *  - {@link registerBridgeHealthcheckTool} registers a `<prefix>_healthcheck`
+ *    tool that round-trips a probe path through the bridge and surfaces the
+ *    actionable hint ladder compass + musescore had each copied (with drifted
+ *    internals + a hardcoded-port bug) into `src/tools/healthcheck.ts`.
  *  - {@link createBootstrapOpts} assembles a multi-domain / capture-header /
  *    storage-pointer declaration fragment of `FetchproxyServerOpts`, deriving
  *    the required `capabilities` from the declared bootstrap so callers can't
@@ -18,10 +24,52 @@
  * The adapter shape is identical across 12+ fetchproxy MCPs; collapsing it here
  * keeps the per-row / concurrency / deadline helpers as re-exports rather than
  * re-rolled code.
+ *
+ * Lazy-import note: this whole subpath is gated behind the OPTIONAL
+ * `@fetchproxy/server` peer dep — a consumer only resolves it by importing
+ * `@chrischall/mcp-utils/fetchproxy`, never via the core barrel. The eager
+ * top-level import below therefore never reaches a `.mcpb` bundle that
+ * externalizes `@fetchproxy/server` unless that consumer actually opted into
+ * the bridge. Everything added here routes through that same already-imported
+ * `FetchproxyServer` instance (no NEW top-level `@fetchproxy/server` import),
+ * so the bundle-load smoke posture is unchanged.
  */
-import { FetchproxyServer, type FetchproxyServerOpts } from '@fetchproxy/server';
+import { FetchproxyServer, type FetchproxyServerOpts, type HttpResponse, type BridgeProbeResult } from '@fetchproxy/server';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { FetchproxyServer, mapWithConcurrency, withDeadline, TokenBucket, classifyBotWall, retryOnceOnTimeout, FetchproxyProtocolError, FetchproxyHttpError, FetchproxyBridgeDownError, FetchproxyTimeoutError, classifyBridgeError, classifyRowError, classifyFetchError, backoffDelayMs, BRIDGE_CONCURRENCY, chunk, sleep, extractGlobalAssign, extractBalancedObject, extractImgTags, lastPathSegment, } from '@fetchproxy/server';
 export type { FetchproxyServerOpts, FetchResult, FetchResultError, HttpResponse, RequestOpts, BodylessRequestOpts, BridgeHealth, BridgeProbeResult, BridgeError, FetchErrorKind, BotWallResult, BotWallVendor, TokenBucketOptions, BackoffOptions, DeadlineOutcome, } from '@fetchproxy/server';
+/**
+ * One request to round-trip through the bridge. The path is resolved relative
+ * to the transport's declared domain (a `defaultSubdomain` — e.g. `'www'` — is
+ * applied unless the caller overrides it per-call). This is the common
+ * `FetchInit` redfin / homes / compass / musescore each declared verbatim in
+ * their `src/transport.ts`.
+ */
+export interface FetchproxyFetchInit {
+    /** Path-and-query relative to the declared domain, e.g. `/robots.txt`. */
+    path: string;
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    headers?: Record<string, string>;
+    /** Serialized request body. JSON callers stringify before calling. */
+    body?: string;
+    /**
+     * Per-call subdomain override. Defaults to the transport's `defaultSubdomain`
+     * (and, absent that, the apex). Absolute `http(s)://` paths self-describe
+     * their host, so this is ignored for them.
+     */
+    subdomain?: string;
+    /** Per-call base-domain selector (required only for multi-domain MCPs). */
+    domain?: string;
+}
+/** The success-arm `{status, body, url}` triple every consumer returns. */
+export type FetchproxyFetchResult = HttpResponse;
+/** Options for {@link FetchproxyTransport.requestJson}. */
+export interface FetchproxyRequestJsonInit {
+    headers?: Record<string, string>;
+    body?: unknown;
+    subdomain?: string;
+    domain?: string;
+}
 /**
  * The lifecycle surface every per-MCP fetchproxy transport interface exposes.
  * `createFetchproxyTransport` returns this, typed as the caller's `T` so it can
@@ -48,6 +96,31 @@ export interface FetchproxyTransport {
      * verb.
      */
     readonly server: FetchproxyServer;
+    /**
+     * Verb passthrough: round-trip one request through `server.request(...)`,
+     * applying the transport's `defaultSubdomain`, and return the success-arm
+     * `{status, body, url}` triple. Bridge failures throw the typed errors
+     * (`FetchproxyBridgeDownError` / `FetchproxyTimeoutError` / …), exactly like
+     * `server.request`. This is the `fetch(init)` redfin / homes / compass /
+     * musescore each wrote by hand.
+     */
+    fetch(init: FetchproxyFetchInit): Promise<FetchproxyFetchResult>;
+    /**
+     * Verb passthrough over `server.requestJson(...)` (serialization + header
+     * defaults + 204→null + JSON.parse). Returns BOTH the parsed `data` and the
+     * raw success-arm `result`, so the caller keeps its per-site `throwIfNotOk` /
+     * sign-in guards over `result`. `defaultSubdomain` is applied.
+     */
+    requestJson<T = unknown>(method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, init?: FetchproxyRequestJsonInit): Promise<{
+        data: T | null;
+        result: FetchproxyFetchResult;
+    }>;
+    /**
+     * Verb passthrough over `server.runProbe(...)` — run one healthcheck probe,
+     * measure elapsed ms, classify any thrown error, and project the post-probe
+     * `bridgeHealth()`. Powers {@link registerBridgeHealthcheckTool}.
+     */
+    runProbe(fetchFn: (path: string) => Promise<unknown>, probePath: string): Promise<BridgeProbeResult>;
 }
 /** Options for {@link createFetchproxyTransport}. */
 export type CreateFetchproxyTransportOptions = FetchproxyServerOpts & {
@@ -59,6 +132,14 @@ export type CreateFetchproxyTransportOptions = FetchproxyServerOpts & {
     debugEnvVar?: string;
     /** Env source for {@link debugEnvVar}. Defaults to `process.env`. */
     env?: NodeJS.ProcessEnv;
+    /**
+     * Subdomain the verb adapters (`fetch` / `requestJson`) apply per call unless
+     * the caller overrides it. This is the ONE per-site bit of the verb surface:
+     * redfin / homes / compass pin `'www'`; apex-served sites (musescore) omit it
+     * to hit the bare domain. Absolute `http(s)://` paths self-describe their host
+     * and ignore this entirely.
+     */
+    defaultSubdomain?: string;
 };
 /**
  * Wrap a `FetchproxyServer` in the `start`/`close`/`status` lifecycle the
@@ -155,4 +236,70 @@ export interface BridgeErrorInfo {
  * string kind (drop-in compatible with `@fetchproxy/server`).
  */
 export declare function bridgeErrorInfo(err: unknown): BridgeErrorInfo;
+/** The diagnostic result a `<prefix>_healthcheck` tool returns. */
+export interface BridgeHealthcheckResult {
+    ok: boolean;
+    bridge: BridgeProbeResult['bridge'] & {
+        last_extension_message_at: number | null;
+    };
+    probe: {
+        url: string;
+        elapsed_ms: number;
+        status?: number;
+        body_length?: number;
+    };
+    error?: {
+        kind: BridgeErrorInfo['type'];
+        message: string;
+        /** Server-authored next-step hint (`FetchproxyBridgeDownError.hint`), when present. */
+        bridge_hint?: string;
+    };
+    /** Plain-English next-step suggestion derived from the result. */
+    hint: string;
+}
+/** Options for {@link registerBridgeHealthcheckTool}. */
+export interface RegisterBridgeHealthcheckToolArgs {
+    /** The `McpServer` to register the tool on. */
+    server: McpServer;
+    /** Tool-name + host-banner prefix, e.g. `'compass'` → `compass_healthcheck`. */
+    prefix: string;
+    /** Public probe path to round-trip, e.g. `'/robots.txt'`. */
+    probePath: string;
+    /**
+     * Display host for the probe URL + hint copy, e.g. `'compass.com'` or
+     * `'www.redfin.com'`. The probe URL is `https://<hostLabel><probePath>`.
+     */
+    hostLabel: string;
+    /**
+     * The bridge transport — supplies `runProbe` (the probe loop + classification
+     * + post-probe bridge projection) and `status()` (for the liveness counter the
+     * projection omits). Any {@link FetchproxyTransport}-shaped object works.
+     */
+    transport: Pick<FetchproxyTransport, 'runProbe' | 'status'>;
+    /**
+     * Performs the actual probe fetch for `probePath`. Required — most consumers
+     * pass `(path) => client.fetchHtml(path)` so the probe exercises the same
+     * client path real tools use (sign-in guards and all).
+     */
+    probeFn: (path: string) => Promise<string>;
+}
+/**
+ * Register a `<prefix>_healthcheck` MCP tool that round-trips `probePath`
+ * through the bridge and reports bridge status + role + timing, plus an
+ * actionable hint ladder on failure.
+ *
+ * The probe loop / error classification / post-probe bridge projection all live
+ * in `transport.runProbe` (the `@fetchproxy/server` primitive); this factory
+ * owns only the tool registration, the result shape, and the hint ladder. The
+ * per-site bits (`prefix`, `probePath`, `hostLabel`, the probe `fetchFn`) are
+ * options.
+ *
+ * @example
+ * registerBridgeHealthcheckTool({
+ *   server, prefix: 'compass', probePath: '/robots.txt',
+ *   hostLabel: 'compass.com', transport,
+ *   probeFn: (p) => client.fetchHtml(p),
+ * });
+ */
+export declare function registerBridgeHealthcheckTool(args: RegisterBridgeHealthcheckToolArgs): void;
 //# sourceMappingURL=index.d.ts.map