@cliwant/mcp-sam-gov 1.4.0 → 1.5.0

package/src/epa-envirofacts.ts

@@ -175,7 +175,16 @@ export type EpaTriFacilitiesArgs = {
 
 /** Validate + encode ONE user path-segment value (facilityName / county). */
 function validateName(value: string, field: string): string {
-  if (value.length > NAME_MAX || !NAME_RE.test(value) || value.includes("..")) {
+  // Reject `..` (path traversal) AND a lone `.` — both are URL dot-segments that
+  // WHATWG `URL` silently COLLAPSES, which would drop the CONTAINING value from the
+  // path, slide the next literal into its place, and leave `_meta.filtersApplied`
+  // claiming a filter the wire request no longer carries (a false-filtersApplied bug).
+  if (
+    value.length > NAME_MAX ||
+    !NAME_RE.test(value) ||
+    value.includes("..") ||
+    value === "."
+  ) {
     throw new ToolErrorCarrier({
       kind: "invalid_input",
       retryable: false,
@@ -326,11 +335,18 @@ export async function triFacilities(
   const notes: string[] = [CLOSED_NOTE, NOMINAL_NOTE];
   if (countFailed) notes.push(COUNT_FALLBACK_NOTE);
 
+  // When the total is UNKNOWN (count sub-query degraded) AND this is not the first
+  // page, we cannot claim the response is the ENTIRE result set — rows 0..offset-1
+  // are absent and no total confirms coverage. Force truncated so buildMeta never
+  // derives complete:true on a partial last page fetched at offset>0 with null total.
+  const cannotProveComplete = totalAvailable === null && offset > 0;
+
   const meta: Partial<ResponseMeta> = {
     source: `${EPA_HOST} EPA Envirofacts /efservice/${EPA_TABLE} (TRI facilities; keyless)`,
     keylessMode: true,
     returned,
     totalAvailable,
+    ...(cannotProveComplete ? { truncated: true } : {}),
     filtersApplied,
     filtersDropped: [],
     fieldsUnavailable: [],

package/src/errors.ts

@@ -208,6 +208,17 @@ export async function fetchWithRetry(
         e instanceof Error &&
         (e.name === "TimeoutError" || e.name === "AbortError")
       ) {
+        // HONESTY (dogfooding 2026-07-16): if a PRIOR attempt already classified a
+        // real upstream signal — a 429 rate_limit — do NOT mask it as a generic
+        // "timed out". The abort here is a DOWNSTREAM artifact of waiting out that
+        // rate limit (the retry-after wait outran getJson's AbortSignal, so the
+        // next fetch hits the already-aborted signal). Surfacing "timed out" hides
+        // the true cause (rate-limited) AND its remedy (wait / supply an API key)
+        // and drops the retryable+retryAfterSeconds guidance. Prefer the real
+        // rate_limited error. (A pure timeout with no prior 429 keeps "timed out".)
+        if (lastErr && lastErr.kind === "rate_limited") {
+          throw new ToolErrorCarrier(lastErr);
+        }
         throw new ToolErrorCarrier({
           kind: "upstream_unavailable",
           message: `Request to ${endpointLabel} timed out.`,

package/src/far.ts

@@ -156,7 +156,9 @@ async function title48Currency(): Promise<{
   latestAmendedOn: string | null;
 }> {
   return memoize("far:title48-currency", async () => {
-    const { titles } = await listTitles();
+    // listTitles now returns a MetaBundle (honesty envelope); the titles live on
+    // `.data.titles`.
+    const { titles } = (await listTitles()).data;
     const t48 = titles.find((t) => t.number === 48);
     return {
       upToDateAsOf: t48?.upToDateAsOf ?? null,

package/src/federal-register.ts

@@ -261,16 +261,35 @@ export async function listAgencies(args: { perPage?: number }) {
     const json = await fetchJson<Resp>(
       `${FED_REG}/agencies.json?per_page=${args.perPage ?? 100}`,
     );
-    return {
-      agencies: (json ?? []).map((a) => ({
-        id: a.id ?? 0,
-        name: a.name ?? "",
-        shortName: a.short_name,
-        slug: a.slug ?? "",
-        description: a.description ?? "",
-        parentId: a.parent_id,
-      })),
-    };
+    const agencies = (json ?? []).map((a) => ({
+      id: a.id ?? 0,
+      name: a.name ?? "",
+      shortName: a.short_name,
+      slug: a.slug ?? "",
+      description: a.description ?? "",
+      parentId: a.parent_id,
+    }));
+    // Carry the honesty envelope every other tool has (dogfooding 2026-07-15: this
+    // list tool previously returned a bare {agencies} with no _meta). The
+    // agencies.json endpoint returns the COMPLETE canonical agency set in one
+    // response and IGNORES per_page upstream (live-verified 2026-07-15: per_page
+    // 10/100/1000 all return the full 472) — so the count IS the total, perPage is
+    // not honored, and complete derives true.
+    return withMeta(
+      { agencies },
+      {
+        source: "federalregister.gov/api/v1 (agencies.json)",
+        keylessMode: true,
+        returned: agencies.length,
+        totalAvailable: agencies.length,
+        truncated: false,
+        filtersApplied: [],
+        filtersDropped: [],
+        notes: [
+          "Complete canonical list of all Federal Register agencies — the endpoint returns every agency in a single response and IGNORES the perPage argument upstream (the full set is always returned).",
+        ],
+      },
+    );
   });
 }
 

package/src/fema.ts

@@ -88,6 +88,40 @@ export { num };
 // ─── Fixed host + curated dataset registry (SSRF core) ────────────
 export const FEMA_HOST = "www.fema.gov";
 
+// The HazardMitigationAssistanceProjects dataset filters on the FULL state NAME
+// ('Alabama'), NOT the 2-letter code the SIBLING FEMA tools (PA/declarations) use —
+// so a caller who naturally passes 'AL' (as those tools accept) would get a
+// confidently-wrong empty (total:0). Map a 2-letter USPS code → the canonical FEMA
+// full name so the HMA tool accepts EITHER form; a full name (or an unknown token)
+// passes through unchanged. (Same confidently-wrong-empty class this codebase guards
+// elsewhere — don't ship a new tool with that foot-gun.)
+const US_STATE_ABBR_TO_NAME: Readonly<Record<string, string>> = {
+  AL: "Alabama", AK: "Alaska", AZ: "Arizona", AR: "Arkansas", CA: "California",
+  CO: "Colorado", CT: "Connecticut", DE: "Delaware", DC: "District of Columbia",
+  FL: "Florida", GA: "Georgia", HI: "Hawaii", ID: "Idaho", IL: "Illinois",
+  IN: "Indiana", IA: "Iowa", KS: "Kansas", KY: "Kentucky", LA: "Louisiana",
+  ME: "Maine", MD: "Maryland", MA: "Massachusetts", MI: "Michigan", MN: "Minnesota",
+  MS: "Mississippi", MO: "Missouri", MT: "Montana", NE: "Nebraska", NV: "Nevada",
+  NH: "New Hampshire", NJ: "New Jersey", NM: "New Mexico", NY: "New York",
+  NC: "North Carolina", ND: "North Dakota", OH: "Ohio", OK: "Oklahoma", OR: "Oregon",
+  PA: "Pennsylvania", RI: "Rhode Island", SC: "South Carolina", SD: "South Dakota",
+  TN: "Tennessee", TX: "Texas", UT: "Utah", VT: "Vermont", VA: "Virginia",
+  WA: "Washington", WV: "West Virginia", WI: "Wisconsin", WY: "Wyoming",
+  PR: "Puerto Rico", VI: "Virgin Islands", GU: "Guam", AS: "American Samoa",
+  MP: "Northern Mariana Islands",
+};
+
+/** Resolve a HMA `state` arg: a 2-letter USPS code → the FEMA full name; a full
+ *  name (or any non-2-letter token) is returned unchanged. */
+export function resolveHmaState(state: string): string {
+  const t = state.trim();
+  if (/^[A-Za-z]{2}$/.test(t)) {
+    const full = US_STATE_ABBR_TO_NAME[t.toUpperCase()];
+    if (full) return full;
+  }
+  return state;
+}
+
 /** A pinned dataset entry — the single source of truth for entityName + version
  *  + the per-tool $filter field whitelist + the amount fields to null-coerce. */
 type FemaDatasetDef = {
@@ -153,6 +187,33 @@ export const FEMA_DATASETS = {
     ]),
     amountFields: [],
   },
+  // Hazard Mitigation Assistance projects — 56,034 rows (LIVE-VERIFIED 2026-07-16).
+  // The disaster-RESILIENCE grant axis (HMGP/FMA/PDM/BRIC mitigation grants to
+  // state/local/tribal subrecipients) — distinct from PA's disaster-RECOVERY spend.
+  // The planned "3rd tool" of ADR-0016 §3. THIS dataset's `state` is the FULL state
+  // NAME ('Alabama'; `stateAbbreviation` → HTTP 400). Every field below LIVE-VERIFIED
+  // to NARROW (2026-07-16): state 2457/'Alabama', programArea 42657/'HMGP',
+  // disasterNumber 330/1605, status 36123/'Closed', programFy 2780/2005, region
+  // 15922/4, projectAmount ge 1e6 → 10257.
+  hazard_mitigation: {
+    entityName: "HazardMitigationAssistanceProjects",
+    version: "v4",
+    filterFields: new Set([
+      "state",
+      "programArea",
+      "disasterNumber",
+      "status",
+      "programFy",
+      "region",
+      "projectAmount",
+    ]),
+    amountFields: [
+      "projectAmount",
+      "federalShareObligated",
+      "initialObligationAmount",
+      "netValueBenefits",
+    ],
+  },
 } satisfies Record<string, FemaDatasetDef>;
 
 export type FemaDatasetKey = keyof typeof FEMA_DATASETS;
@@ -539,3 +600,81 @@ export async function disasterDeclarations(args: {
   const { body } = await getOpenFema("disaster_declarations", params);
   return shapeResponse({ body, datasetKey: "disaster_declarations", offset, limit, filtersApplied });
 }
+
+// ─── Tool 3: fema_search_hazard_mitigation ────────────────────────
+/**
+ * Search FEMA Hazard Mitigation Assistance projects (the disaster-RESILIENCE grant
+ * axis — HMGP/FMA/PDM/BRIC mitigation grants to state/local/tribal subrecipients,
+ * distinct from Public Assistance's disaster-RECOVERY spend). Dataset
+ * HazardMitigationAssistanceProjects v4. Structured filters → module-built `$filter`
+ * (each field LIVE-VERIFIED to narrow):
+ *   state → state eq (FULL state NAME, e.g. "Alabama" — NOT the 2-letter code;
+ *   stateAbbreviation 400s here) · programArea eq (HMGP / FMA / PDM / BRIC / LPDM /
+ *   FMA-SL) · disasterNumber eq · status eq (e.g. "Closed") · programFy eq ·
+ *   region eq (FEMA region number 1–10) · minProjectAmount → projectAmount ge ·
+ *   maxProjectAmount → projectAmount le.
+ * Rows carry projectAmount / federalShareObligated / initialObligationAmount /
+ * netValueBenefits as number|null. Honest `_meta` (totalAvailable = exact filtered
+ * metadata.count).
+ */
+export async function searchHazardMitigation(args: {
+  state?: string;
+  programArea?: string;
+  disasterNumber?: number;
+  status?: string;
+  programFy?: number;
+  region?: number;
+  minProjectAmount?: number;
+  maxProjectAmount?: number;
+  limit?: number;
+  offset?: number;
+}): Promise<MetaBundle> {
+  const limit = args.limit ?? 100;
+  const offset = args.offset ?? 0;
+
+  const clauses: FilterClause[] = [];
+  const filtersApplied: string[] = [];
+  if (args.state !== undefined) {
+    // Accept a 2-letter code (as the sibling FEMA tools do) OR a full name — HMA's
+    // upstream filters on the FULL name, so a bare 'AL' would silently return 0.
+    clauses.push({ field: "state", op: "eq", type: "string", value: resolveHmaState(args.state) });
+    filtersApplied.push("state");
+  }
+  if (args.programArea !== undefined) {
+    clauses.push({ field: "programArea", op: "eq", type: "string", value: args.programArea });
+    filtersApplied.push("programArea");
+  }
+  if (args.disasterNumber !== undefined) {
+    clauses.push({ field: "disasterNumber", op: "eq", type: "number", value: args.disasterNumber });
+    filtersApplied.push("disasterNumber");
+  }
+  if (args.status !== undefined) {
+    clauses.push({ field: "status", op: "eq", type: "string", value: args.status });
+    filtersApplied.push("status");
+  }
+  if (args.programFy !== undefined) {
+    clauses.push({ field: "programFy", op: "eq", type: "number", value: args.programFy });
+    filtersApplied.push("programFy");
+  }
+  if (args.region !== undefined) {
+    clauses.push({ field: "region", op: "eq", type: "number", value: args.region });
+    filtersApplied.push("region");
+  }
+  if (args.minProjectAmount !== undefined) {
+    clauses.push({ field: "projectAmount", op: "ge", type: "number", value: args.minProjectAmount });
+    filtersApplied.push("minProjectAmount");
+  }
+  if (args.maxProjectAmount !== undefined) {
+    clauses.push({ field: "projectAmount", op: "le", type: "number", value: args.maxProjectAmount });
+    filtersApplied.push("maxProjectAmount");
+  }
+
+  const params = new URLSearchParams();
+  params.set("$top", String(limit));
+  params.set("$skip", String(offset));
+  const filter = buildFilter("hazard_mitigation", clauses);
+  if (filter) params.set("$filter", filter);
+
+  const { body } = await getOpenFema("hazard_mitigation", params);
+  return shapeResponse({ body, datasetKey: "hazard_mitigation", offset, limit, filtersApplied });
+}

package/src/gov-domains.ts

@@ -0,0 +1,237 @@
+/**
+ * get.gov — the authoritative US .gov domain registry (CISA). KEYLESS.
+ *
+ * The .gov program (run by CISA) publishes the COMPLETE registry as CSVs in its
+ * official repo github.com/cisagov/dotgov-data — the canonical published location
+ * (get.gov links there; there is no query API for the full set). It is NOT a .gov
+ * API host, so provenance is disclosed on every response (the ProPublica /
+ * CourtListener republisher pattern — except here CISA is the first-party registrar).
+ *
+ * B2G value: resolve WHICH organization owns a .gov domain, enumerate federal
+ * agencies, and MAP SLED entities (state / county / city / school-district /
+ * special-district / tribal) for market targeting — a distinct authoritative
+ * gov-org registry no other tool here exposes.
+ *
+ * SSRF: fixed host `raw.githubusercontent.com` + fixed path prefix
+ * `/cisagov/dotgov-data/main/` + a scope-selected FIXED filename (federal | full) —
+ * no free host, path, or filename. `redirect:"error"` on the fetch.
+ *
+ * PII: the CSV carries a "Security contact email" column (an ORG security mailbox,
+ * e.g. security@agency.gov). We DROP it — this tool resolves ORGANIZATIONS, not
+ * contacts, and excluding it keeps the output free of contact info.
+ *
+ * Filtering is CLIENT-SIDE over the full published CSV (the registry has no query
+ * API) — disclosed in `_meta.notes`. `totalAvailable` is the EXACT match count.
+ */
+
+import { getText } from "./datasource.js";
+import { driftError } from "./datasource.js";
+import { memoize } from "./cache.js";
+import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
+
+export const DOTGOV_HOST = "raw.githubusercontent.com";
+const DOTGOV_PATH_PREFIX = "https://raw.githubusercontent.com/cisagov/dotgov-data/main/";
+
+// scope → the pinned filename (no free path). "all" = federal + SLED (~16k rows),
+// "federal" = federal only (~1.3k rows).
+const DOTGOV_FILES = {
+  all: "current-full.csv",
+  federal: "current-federal.csv",
+} as const;
+export type GovDomainScope = keyof typeof DOTGOV_FILES;
+
+const SOURCE_LABEL = "getgov:cisagov/dotgov-data";
+const PROVENANCE_NOTE =
+  "Source: the CISA get.gov OFFICIAL .gov domain registry, published as CSV at github.com/cisagov/dotgov-data (the canonical location; get.gov links there). CISA is the first-party .gov registrar; this is authoritative public data served from GitHub, not a .gov API host.";
+const CLIENT_FILTER_NOTE =
+  "The registry has no query API — the full published CSV is fetched and filtered CLIENT-SIDE (organization/domain/city are case-insensitive SUBSTRING matches; state/domainType are case-insensitive). totalAvailable is the EXACT count of matching rows.";
+const FRESHNESS_NOTE =
+  "The CISA dotgov-data CSV is refreshed ~daily; this response reflects the currently-published snapshot (served from a 6-hour cache).";
+const EMAIL_DROP_NOTE =
+  "The registry's 'Security contact email' column (an organization security mailbox) is intentionally EXCLUDED — this tool resolves organizations, not contacts.";
+
+export type GovDomainRow = {
+  domain: string;
+  domainType: string;
+  organization: string;
+  suborganization: string | null;
+  city: string | null;
+  state: string | null;
+};
+
+// ─── Minimal RFC-4180 CSV parser (quoted fields + embedded commas/newlines) ──
+/**
+ * Parse a full CSV document into rows of string fields. Handles double-quoted
+ * fields, escaped `""` quotes, and commas/newlines INSIDE quotes. Self-contained
+ * (no external dep) — the get.gov CSV is small (~1.4 MB) so a whole-string parse is
+ * fine. Returns every record's raw field array (including the header row).
+ */
+export function parseCsv(text: string): string[][] {
+  const rows: string[][] = [];
+  let field = "";
+  let row: string[] = [];
+  let inQuotes = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i++; // consume the escaped quote
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += c;
+      }
+    } else if (c === '"') {
+      inQuotes = true;
+    } else if (c === ",") {
+      row.push(field);
+      field = "";
+    } else if (c === "\n") {
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = "";
+    } else if (c === "\r") {
+      // CRLF: the \n case pushes the record; ignore the stray CR.
+    } else {
+      field += c;
+    }
+  }
+  // Flush a trailing field/row if the file did not end with a newline.
+  if (field.length > 0 || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows;
+}
+
+/** Coerce a CSV field to a trimmed non-empty string, else null (never ""). */
+function s(v: string | undefined): string | null {
+  if (v === undefined) return null;
+  const t = v.trim();
+  return t.length > 0 ? t : null;
+}
+
+/**
+ * Fetch + parse ONE scope's registry CSV into rows, memoized ~6h. Header-mapped by
+ * COLUMN NAME (not fixed index) so an upstream column reorder does not silently
+ * mis-map; a missing required header ⇒ schema_drift (never a fake-empty). The
+ * "Security contact email" column is dropped at the map step.
+ */
+async function loadRegistry(scope: GovDomainScope): Promise<GovDomainRow[]> {
+  return memoize(`getgov:${scope}`, async () => {
+    const url = `${DOTGOV_PATH_PREFIX}${DOTGOV_FILES[scope]}`;
+    // Belt-and-suspenders SSRF: the URL is built only from the pinned prefix +
+    // pinned filename, but assert it before the fetch.
+    const built = new URL(url);
+    if (built.hostname !== DOTGOV_HOST || built.protocol !== "https:") {
+      throw driftError(
+        SOURCE_LABEL,
+        `Constructed get.gov URL host ${JSON.stringify(built.hostname)} is not ${DOTGOV_HOST} over https — refusing to fetch (SSRF safety).`,
+      );
+    }
+    const text = await getText(url, { label: SOURCE_LABEL, redirect: "error", timeoutMs: 20_000 });
+    const rows = parseCsv(text);
+    const headerRow = rows[0];
+    if (!headerRow) {
+      throw driftError(SOURCE_LABEL, "get.gov registry CSV was empty — treating as schema drift, never a fake-empty result.");
+    }
+    const header = headerRow.map((h) => h.trim());
+    const idx = (name: string) => header.indexOf(name);
+    const iDomain = idx("Domain name");
+    const iType = idx("Domain type");
+    const iOrg = idx("Organization name");
+    const iSub = idx("Suborganization name");
+    const iCity = idx("City");
+    const iState = idx("State");
+    // The four load-bearing columns MUST be present (a rename ⇒ schema drift, not a
+    // silently mis-mapped/empty result).
+    if (iDomain < 0 || iType < 0 || iOrg < 0) {
+      throw driftError(
+        SOURCE_LABEL,
+        `get.gov registry CSV header is missing a required column (Domain name / Domain type / Organization name) — schema drift. Got: ${header.join(", ")}.`,
+      );
+    }
+    return rows.slice(1).map((r) => ({
+      domain: (r[iDomain] ?? "").trim(),
+      domainType: (r[iType] ?? "").trim(),
+      organization: (r[iOrg] ?? "").trim(),
+      suborganization: iSub >= 0 ? s(r[iSub]) : null,
+      city: iCity >= 0 ? s(r[iCity]) : null,
+      state: iState >= 0 ? s(r[iState]) : null,
+      // NOTE: "Security contact email" is deliberately NOT read/emitted.
+    }));
+  });
+}
+
+// ─── Tool: search_gov_domains ─────────────────────────────────────
+/**
+ * Search the CISA get.gov .gov domain registry. Client-side filters over the
+ * published CSV: organization/domain/city are case-insensitive SUBSTRING matches;
+ * state (2-letter) and domainType are case-insensitive. scope 'all' (federal + SLED,
+ * default) | 'federal'. Honest `_meta` (exact match total; provenance + client-side
+ * disclosure).
+ */
+export async function searchGovDomains(args: {
+  scope?: GovDomainScope;
+  organization?: string;
+  domain?: string;
+  domainType?: string;
+  state?: string;
+  city?: string;
+  limit?: number;
+  offset?: number;
+}): Promise<MetaBundle> {
+  const scope: GovDomainScope = args.scope ?? "all";
+  const limit = args.limit ?? 50;
+  const offset = args.offset ?? 0;
+
+  const all = await loadRegistry(scope);
+
+  const filtersApplied: string[] = [];
+  const ci = (v: string | undefined) => (v ?? "").toLowerCase();
+  const orgQ = ci(args.organization);
+  const domQ = ci(args.domain);
+  const typeQ = ci(args.domainType);
+  const stateQ = ci(args.state);
+  const cityQ = ci(args.city);
+  if (args.organization !== undefined) filtersApplied.push("organization");
+  if (args.domain !== undefined) filtersApplied.push("domain");
+  if (args.domainType !== undefined) filtersApplied.push("domainType");
+  if (args.state !== undefined) filtersApplied.push("state");
+  if (args.city !== undefined) filtersApplied.push("city");
+
+  const matched = all.filter((row) => {
+    if (orgQ && !row.organization.toLowerCase().includes(orgQ)) return false;
+    if (domQ && !row.domain.toLowerCase().includes(domQ)) return false;
+    if (typeQ && !row.domainType.toLowerCase().includes(typeQ)) return false;
+    if (stateQ && (row.state ?? "").toLowerCase() !== stateQ) return false;
+    if (cityQ && !(row.city ?? "").toLowerCase().includes(cityQ)) 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(
+    { scope, domains: page },
+    {
+      source: `getgov ${DOTGOV_FILES[scope]} (CISA .gov registry, keyless)`,
+      keylessMode: true,
+      returned,
+      totalAvailable,
+      truncated: hasMore,
+      filtersApplied,
+      filtersDropped: [],
+      fieldsUnavailable: ["securityContactEmail (org mailbox — intentionally excluded)"],
+      pagination: { offset, limit, hasMore, nextOffset },
+      notes: [PROVENANCE_NOTE, CLIENT_FILTER_NOTE, FRESHNESS_NOTE, EMAIL_DROP_NOTE],
+    } satisfies Partial<ResponseMeta>,
+  );
+}