@cliwant/mcp-sam-gov 1.5.0 → 1.7.0

package/src/cache.ts

@@ -1,73 +1,73 @@
-/**
- * Tiny in-memory TTL cache for hot, idempotent reads.
- *
- * Why this exists
- * ----------------
- * Some calls are extremely repeat-prone within a single agent
- * conversation: `usas_lookup_agency("VA")`, `ecfr_list_titles()`,
- * `fed_register_list_agencies()`, `usas_autocomplete_naics(...)`.
- * The agent will call them five times in a row across different
- * tool sequences. Each is a 250-700ms federal API hit.
- *
- * This cache is per-process (no Redis, no disk). Lives for the
- * lifetime of the MCP server stdio session — typically minutes
- * to hours. TTL is short enough that schema drift gets noticed
- * within an hour.
- *
- * What we cache
- * --------------
- *   - Reference lookups (agencies, NAICS hierarchy, glossary)
- *   - Autocomplete (idempotent for same query string)
- * What we DON'T cache
- * --------------------
- *   - Search results (volume changes; user expects freshness)
- *   - Per-opportunity / per-award detail (stale = wrong)
- *   - Anything with a date filter
- */
-
-type Entry<T> = { value: T; expiresAt: number };
-
-const store = new Map<string, Entry<unknown>>();
-
-const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
-
-/**
- * Wrap an idempotent async producer in a TTL cache.
- *
- *   const result = await memoize("usas:agency:VA", () => lookupAgency("VA"));
- *
- * Returns the cached value if fresh; otherwise computes + stores.
- */
-export async function memoize<T>(
-  key: string,
-  producer: () => Promise<T>,
-  ttlMs: number = DEFAULT_TTL_MS,
-): Promise<T> {
-  const now = Date.now();
-  const hit = store.get(key);
-  if (hit && hit.expiresAt > now) {
-    return hit.value as T;
-  }
-  const value = await producer();
-  store.set(key, { value, expiresAt: now + ttlMs });
-  // Light-touch GC: every 100 sets, sweep expired entries.
-  if (store.size % 100 === 0) sweepExpired();
-  return value;
-}
-
-function sweepExpired() {
-  const now = Date.now();
-  for (const [k, v] of store) {
-    if (v.expiresAt <= now) store.delete(k);
-  }
-}
-
-/** For tests / debug. */
-export function _cacheStats() {
-  return { size: store.size, entries: [...store.keys()] };
-}
-
-/** For tests: evict all entries (so a subsequent call re-runs its producer). */
-export function _clearCache() {
-  store.clear();
-}
+/**
+ * Tiny in-memory TTL cache for hot, idempotent reads.
+ *
+ * Why this exists
+ * ----------------
+ * Some calls are extremely repeat-prone within a single agent
+ * conversation: `usas_lookup_agency("VA")`, `ecfr_list_titles()`,
+ * `fed_register_list_agencies()`, `usas_autocomplete_naics(...)`.
+ * The agent will call them five times in a row across different
+ * tool sequences. Each is a 250-700ms federal API hit.
+ *
+ * This cache is per-process (no Redis, no disk). Lives for the
+ * lifetime of the MCP server stdio session — typically minutes
+ * to hours. TTL is short enough that schema drift gets noticed
+ * within an hour.
+ *
+ * What we cache
+ * --------------
+ *   - Reference lookups (agencies, NAICS hierarchy, glossary)
+ *   - Autocomplete (idempotent for same query string)
+ * What we DON'T cache
+ * --------------------
+ *   - Search results (volume changes; user expects freshness)
+ *   - Per-opportunity / per-award detail (stale = wrong)
+ *   - Anything with a date filter
+ */
+
+type Entry<T> = { value: T; expiresAt: number };
+
+const store = new Map<string, Entry<unknown>>();
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Wrap an idempotent async producer in a TTL cache.
+ *
+ *   const result = await memoize("usas:agency:VA", () => lookupAgency("VA"));
+ *
+ * Returns the cached value if fresh; otherwise computes + stores.
+ */
+export async function memoize<T>(
+  key: string,
+  producer: () => Promise<T>,
+  ttlMs: number = DEFAULT_TTL_MS,
+): Promise<T> {
+  const now = Date.now();
+  const hit = store.get(key);
+  if (hit && hit.expiresAt > now) {
+    return hit.value as T;
+  }
+  const value = await producer();
+  store.set(key, { value, expiresAt: now + ttlMs });
+  // Light-touch GC: every 100 sets, sweep expired entries.
+  if (store.size % 100 === 0) sweepExpired();
+  return value;
+}
+
+function sweepExpired() {
+  const now = Date.now();
+  for (const [k, v] of store) {
+    if (v.expiresAt <= now) store.delete(k);
+  }
+}
+
+/** For tests / debug. */
+export function _cacheStats() {
+  return { size: store.size, entries: [...store.keys()] };
+}
+
+/** For tests: evict all entries (so a subsequent call re-runs its producer). */
+export function _clearCache() {
+  store.clear();
+}

package/src/cbp-border.ts

@@ -1,177 +1,177 @@
-/**
- * cbp-border.ts — CBP Border Wait Times (bwt.cbp.gov, KEYLESS) — the FREIGHT /
- * LOGISTICS lane. Live commercial-vehicle (and passenger) wait times at every US
- * land border port (Canadian + Mexican): per-port lane delays, operational status,
- * and open-lane counts. Answers "what's the current commercial-truck delay at port
- * X" — real-time freight-crossing situational awareness for logistics/trade vendors.
- *
- * SOURCE: CBP's official Border Wait Times API (bwt.cbp.gov/api/bwtnew) — a .gov host,
- * keyless, returns a JSON ARRAY of ports. This is REAL-TIME operational data: each
- * lane carries its own `update_time` (surfaced verbatim) — freshness is disclosed and
- * never implied to be live-to-the-second.
- *
- * HONESTY: fixed host + redirect:"error" (SSRF); a non-array body ⇒ driftError (never
- * a fake empty); an outage/4xx/timeout THROWS. delay/lanes are upstream STRINGS →
- * number|null (a real 0 stays 0; an empty/N/A value is null, NEVER a fabricated 0 — a
- * closed lane's delay is UNKNOWN, not "0 minutes"). totalAvailable = the EXACT count
- * of matched ports (client-side filter; the API returns the whole set).
- */
-
-import { getJson, driftError } from "./datasource.js";
-import { memoize } from "./cache.js";
-import { num } from "./coerce.js";
-import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
-
-export const CBP_HOST = "bwt.cbp.gov";
-const CBP_URL = "https://bwt.cbp.gov/api/bwtnew";
-const CBP_LABEL = "cbp:border-wait-times";
-const CBP_TIMEOUT_MS = 15_000;
-// Real-time feed — a SHORT 60s cache (upstream politeness) while staying fresh; the
-// per-lane update_time is the authoritative freshness signal, disclosed per port.
-const CBP_CACHE_TTL_MS = 60_000;
-
-const FRESHNESS_NOTE =
-  "REAL-TIME operational data: each lane carries its own asOf/updateTime (surfaced verbatim) — this is a live border-wait snapshot, not a historical series. A closed port or lane reports operationalStatus accordingly; its delayMinutes is null (UNKNOWN), never a fabricated 0.";
-const PROVENANCE_NOTE =
-  "Source: CBP Border Wait Times API (bwt.cbp.gov), keyless. Covers all US land border ports on the Canadian and Mexican borders.";
-
-type RawLane = {
-  update_time?: string;
-  operational_status?: string;
-  delay_minutes?: string;
-  lanes_open?: string;
-};
-type RawPort = {
-  port_number?: string;
-  border?: string;
-  port_name?: string;
-  crossing_name?: string;
-  date?: string;
-  time?: string;
-  port_status?: string;
-  commercial_vehicle_lanes?: { maximum_lanes?: unknown } & Record<string, unknown>;
-  passenger_vehicle_lanes?: Record<string, unknown>;
-};
-
-export type CbpLane = {
-  operationalStatus: string | null;
-  delayMinutes: number | null; // null-never-0: a real 0 stays 0; empty/N/A ⇒ null
-  lanesOpen: number | null;
-  updateTime: string | null;
-};
-export type CbpPort = {
-  portNumber: string | null;
-  portName: string | null;
-  crossingName: string | null;
-  border: string | null; // "Canadian Border" | "Mexican Border"
-  portStatus: string | null; // "Open" | "Closed"
-  asOf: string | null; // date + time from the feed
-  commercialVehicle: { maxLanes: number | null; standard: CbpLane; fast: CbpLane };
-};
-
-/** Trim to a non-empty string or null (never ""). */
-function s(v: unknown): string | null {
-  if (typeof v !== "string") return v == null ? null : String(v);
-  const t = v.trim();
-  return t.length > 0 ? t : null;
-}
-
-/** Map ONE lane object → curated lane (delay/lanes via `num`: 0 stays 0, ""→null). */
-function mapLane(lane: unknown): CbpLane {
-  const l = (lane ?? {}) as RawLane;
-  return {
-    operationalStatus: s(l.operational_status),
-    delayMinutes: num(l.delay_minutes),
-    lanesOpen: num(l.lanes_open),
-    updateTime: s(l.update_time),
-  };
-}
-
-function mapPort(port: RawPort): CbpPort {
-  const cv = (port.commercial_vehicle_lanes ?? {}) as Record<string, unknown>;
-  const date = s(port.date);
-  const time = s(port.time);
-  return {
-    portNumber: s(port.port_number),
-    portName: s(port.port_name),
-    crossingName: s(port.crossing_name),
-    border: s(port.border),
-    portStatus: s(port.port_status),
-    asOf: date && time ? `${date} ${time}` : (date ?? time),
-    commercialVehicle: {
-      maxLanes: num(cv.maximum_lanes),
-      standard: mapLane(cv.standard_lanes),
-      fast: mapLane(cv.FAST_lanes),
-    },
-  };
-}
-
-/** Fetch + parse the full port array, memoized 60s. A non-array body ⇒ driftError. */
-async function loadPorts(): Promise<CbpPort[]> {
-  return memoize(
-    "cbp:bwt",
-    async () => {
-      const built = new URL(CBP_URL);
-      if (built.hostname !== CBP_HOST || built.protocol !== "https:") {
-        throw driftError(CBP_LABEL, `Constructed CBP URL host ${JSON.stringify(built.hostname)} is not ${CBP_HOST} over https — refusing to fetch (SSRF safety).`);
-      }
-      const body = await getJson(CBP_URL, { label: CBP_LABEL, redirect: "error", timeoutMs: CBP_TIMEOUT_MS });
-      if (!Array.isArray(body)) {
-        throw driftError(CBP_LABEL, "CBP Border Wait Times returned a non-array body — schema drift, never a fake-empty result.");
-      }
-      return (body as RawPort[]).map(mapPort);
-    },
-    CBP_CACHE_TTL_MS,
-  );
-}
-
-// ─── Tool: cbp_border_wait_times ──────────────────────────────────
-/**
- * List CBP land-border-port commercial-vehicle (+ passenger) wait times, optionally
- * filtered by border (Canadian/Mexican) and/or port name (substring). Client-side
- * filter over the live feed; honest `_meta` (exact match total + real-time freshness).
- */
-export async function borderWaitTimes(args: {
-  border?: string;
-  portName?: string;
-  limit?: number;
-  offset?: number;
-}): Promise<MetaBundle> {
-  const limit = args.limit ?? 100;
-  const offset = args.offset ?? 0;
-  const all = await loadPorts();
-
-  const filtersApplied: string[] = [];
-  const borderQ = args.border?.trim().toLowerCase();
-  const portQ = args.portName?.trim().toLowerCase();
-  if (args.border !== undefined) filtersApplied.push("border");
-  if (args.portName !== undefined) filtersApplied.push("portName");
-
-  const matched = all.filter((p) => {
-    if (borderQ && !(p.border ?? "").toLowerCase().includes(borderQ)) return false;
-    if (portQ && !(p.portName ?? "").toLowerCase().includes(portQ)) return false;
-    return true;
-  });
-
-  const totalAvailable = matched.length;
-  const page = matched.slice(offset, offset + limit);
-  const returned = page.length;
-  const hasMore = offset + returned < totalAvailable;
-  const nextOffset = hasMore ? offset + returned : null;
-
-  return withMeta(
-    { ports: page },
-    {
-      source: "bwt.cbp.gov Border Wait Times (keyless)",
-      keylessMode: true,
-      returned,
-      totalAvailable,
-      truncated: hasMore,
-      filtersApplied,
-      filtersDropped: [],
-      fieldsUnavailable: [],
-      pagination: { offset, limit, hasMore, nextOffset },
-      notes: [PROVENANCE_NOTE, FRESHNESS_NOTE],
-    } satisfies Partial<ResponseMeta>,
-  );
-}
+/**
+ * cbp-border.ts — CBP Border Wait Times (bwt.cbp.gov, KEYLESS) — the FREIGHT /
+ * LOGISTICS lane. Live commercial-vehicle (and passenger) wait times at every US
+ * land border port (Canadian + Mexican): per-port lane delays, operational status,
+ * and open-lane counts. Answers "what's the current commercial-truck delay at port
+ * X" — real-time freight-crossing situational awareness for logistics/trade vendors.
+ *
+ * SOURCE: CBP's official Border Wait Times API (bwt.cbp.gov/api/bwtnew) — a .gov host,
+ * keyless, returns a JSON ARRAY of ports. This is REAL-TIME operational data: each
+ * lane carries its own `update_time` (surfaced verbatim) — freshness is disclosed and
+ * never implied to be live-to-the-second.
+ *
+ * HONESTY: fixed host + redirect:"error" (SSRF); a non-array body ⇒ driftError (never
+ * a fake empty); an outage/4xx/timeout THROWS. delay/lanes are upstream STRINGS →
+ * number|null (a real 0 stays 0; an empty/N/A value is null, NEVER a fabricated 0 — a
+ * closed lane's delay is UNKNOWN, not "0 minutes"). totalAvailable = the EXACT count
+ * of matched ports (client-side filter; the API returns the whole set).
+ */
+
+import { getJson, driftError } from "./datasource.js";
+import { memoize } from "./cache.js";
+import { num } from "./coerce.js";
+import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
+
+export const CBP_HOST = "bwt.cbp.gov";
+const CBP_URL = "https://bwt.cbp.gov/api/bwtnew";
+const CBP_LABEL = "cbp:border-wait-times";
+const CBP_TIMEOUT_MS = 15_000;
+// Real-time feed — a SHORT 60s cache (upstream politeness) while staying fresh; the
+// per-lane update_time is the authoritative freshness signal, disclosed per port.
+const CBP_CACHE_TTL_MS = 60_000;
+
+const FRESHNESS_NOTE =
+  "REAL-TIME operational data: each lane carries its own asOf/updateTime (surfaced verbatim) — this is a live border-wait snapshot, not a historical series. A closed port or lane reports operationalStatus accordingly; its delayMinutes is null (UNKNOWN), never a fabricated 0.";
+const PROVENANCE_NOTE =
+  "Source: CBP Border Wait Times API (bwt.cbp.gov), keyless. Covers all US land border ports on the Canadian and Mexican borders.";
+
+type RawLane = {
+  update_time?: string;
+  operational_status?: string;
+  delay_minutes?: string;
+  lanes_open?: string;
+};
+type RawPort = {
+  port_number?: string;
+  border?: string;
+  port_name?: string;
+  crossing_name?: string;
+  date?: string;
+  time?: string;
+  port_status?: string;
+  commercial_vehicle_lanes?: { maximum_lanes?: unknown } & Record<string, unknown>;
+  passenger_vehicle_lanes?: Record<string, unknown>;
+};
+
+export type CbpLane = {
+  operationalStatus: string | null;
+  delayMinutes: number | null; // null-never-0: a real 0 stays 0; empty/N/A ⇒ null
+  lanesOpen: number | null;
+  updateTime: string | null;
+};
+export type CbpPort = {
+  portNumber: string | null;
+  portName: string | null;
+  crossingName: string | null;
+  border: string | null; // "Canadian Border" | "Mexican Border"
+  portStatus: string | null; // "Open" | "Closed"
+  asOf: string | null; // date + time from the feed
+  commercialVehicle: { maxLanes: number | null; standard: CbpLane; fast: CbpLane };
+};
+
+/** Trim to a non-empty string or null (never ""). */
+function s(v: unknown): string | null {
+  if (typeof v !== "string") return v == null ? null : String(v);
+  const t = v.trim();
+  return t.length > 0 ? t : null;
+}
+
+/** Map ONE lane object → curated lane (delay/lanes via `num`: 0 stays 0, ""→null). */
+function mapLane(lane: unknown): CbpLane {
+  const l = (lane ?? {}) as RawLane;
+  return {
+    operationalStatus: s(l.operational_status),
+    delayMinutes: num(l.delay_minutes),
+    lanesOpen: num(l.lanes_open),
+    updateTime: s(l.update_time),
+  };
+}
+
+function mapPort(port: RawPort): CbpPort {
+  const cv = (port.commercial_vehicle_lanes ?? {}) as Record<string, unknown>;
+  const date = s(port.date);
+  const time = s(port.time);
+  return {
+    portNumber: s(port.port_number),
+    portName: s(port.port_name),
+    crossingName: s(port.crossing_name),
+    border: s(port.border),
+    portStatus: s(port.port_status),
+    asOf: date && time ? `${date} ${time}` : (date ?? time),
+    commercialVehicle: {
+      maxLanes: num(cv.maximum_lanes),
+      standard: mapLane(cv.standard_lanes),
+      fast: mapLane(cv.FAST_lanes),
+    },
+  };
+}
+
+/** Fetch + parse the full port array, memoized 60s. A non-array body ⇒ driftError. */
+async function loadPorts(): Promise<CbpPort[]> {
+  return memoize(
+    "cbp:bwt",
+    async () => {
+      const built = new URL(CBP_URL);
+      if (built.hostname !== CBP_HOST || built.protocol !== "https:") {
+        throw driftError(CBP_LABEL, `Constructed CBP URL host ${JSON.stringify(built.hostname)} is not ${CBP_HOST} over https — refusing to fetch (SSRF safety).`);
+      }
+      const body = await getJson(CBP_URL, { label: CBP_LABEL, redirect: "error", timeoutMs: CBP_TIMEOUT_MS });
+      if (!Array.isArray(body)) {
+        throw driftError(CBP_LABEL, "CBP Border Wait Times returned a non-array body — schema drift, never a fake-empty result.");
+      }
+      return (body as RawPort[]).map(mapPort);
+    },
+    CBP_CACHE_TTL_MS,
+  );
+}
+
+// ─── Tool: cbp_border_wait_times ──────────────────────────────────
+/**
+ * List CBP land-border-port commercial-vehicle (+ passenger) wait times, optionally
+ * filtered by border (Canadian/Mexican) and/or port name (substring). Client-side
+ * filter over the live feed; honest `_meta` (exact match total + real-time freshness).
+ */
+export async function borderWaitTimes(args: {
+  border?: string;
+  portName?: string;
+  limit?: number;
+  offset?: number;
+}): Promise<MetaBundle> {
+  const limit = args.limit ?? 100;
+  const offset = args.offset ?? 0;
+  const all = await loadPorts();
+
+  const filtersApplied: string[] = [];
+  const borderQ = args.border?.trim().toLowerCase();
+  const portQ = args.portName?.trim().toLowerCase();
+  if (args.border !== undefined) filtersApplied.push("border");
+  if (args.portName !== undefined) filtersApplied.push("portName");
+
+  const matched = all.filter((p) => {
+    if (borderQ && !(p.border ?? "").toLowerCase().includes(borderQ)) return false;
+    if (portQ && !(p.portName ?? "").toLowerCase().includes(portQ)) return false;
+    return true;
+  });
+
+  const totalAvailable = matched.length;
+  const page = matched.slice(offset, offset + limit);
+  const returned = page.length;
+  const hasMore = offset + returned < totalAvailable;
+  const nextOffset = hasMore ? offset + returned : null;
+
+  return withMeta(
+    { ports: page },
+    {
+      source: "bwt.cbp.gov Border Wait Times (keyless)",
+      keylessMode: true,
+      returned,
+      totalAvailable,
+      truncated: hasMore,
+      filtersApplied,
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      pagination: { offset, limit, hasMore, nextOffset },
+      notes: [PROVENANCE_NOTE, FRESHNESS_NOTE],
+    } satisfies Partial<ResponseMeta>,
+  );
+}