@cliwant/mcp-sam-gov 1.9.0 → 1.11.0

package/src/sam-gov/client.ts

@@ -353,11 +353,20 @@ export class SamGovClient {
     filters: SamSearchFilters,
   ): Promise<SamSearchResult> {
     const url = new URL(`${PUBLIC_BASE}/sgs/v1/search/`);
+    // Keyless HAL pagination is by PAGE (page × size), not a row offset — the
+    // list endpoint pages correctly (VERIFIED LIVE 2026-07: page=0 and page=1
+    // return disjoint result sets for the same query). Map the caller's row
+    // `offset` onto the page grid; a non-page-aligned offset snaps DOWN to its
+    // page boundary and we return the SERVED offset (page × size) so `_meta`
+    // never claims an offset the upstream didn't honor. (The authenticated path,
+    // buildAuthSearchUrl, honors an arbitrary `offset` directly.)
+    const size = filters.limit ?? 25;
+    const page = Math.max(0, Math.floor((filters.offset ?? 0) / size));
     url.searchParams.set("index", "opp");
-    url.searchParams.set("page", "0");
+    url.searchParams.set("page", String(page));
     url.searchParams.set("mode", "search");
     url.searchParams.set("sort", "-modifiedDate");
-    url.searchParams.set("size", String(filters.limit ?? 25));
+    url.searchParams.set("size", String(size));
     url.searchParams.set("is_active", "true");
     // Keyless HAL facet params — VERIFIED LIVE (2026-07). The list endpoint
     // honors these server-side: result counts drop correctly AND every returned
@@ -457,8 +466,8 @@ export class SamGovClient {
     });
     return {
       totalRecords,
-      limit: filters.limit ?? 25,
-      offset: filters.offset ?? 0,
+      limit: size,
+      offset: page * size, // the SERVED offset (page-aligned), never the raw request
       opportunitiesData: data,
     };
   }

package/src/server.ts

@@ -48,6 +48,10 @@ import * as ckan from "./ckan.js";
 import * as echo from "./echo.js";
 import * as datagov from "./datagov.js";
 import * as datagovCatalog from "./datagov-catalog.js";
+import * as arcgisHub from "./arcgis-hub.js";
+import * as opengov from "./opengov.js";
+import * as bonfire from "./bonfire.js";
+import * as arcgisFeature from "./arcgis-feature.js";
 import * as govinfo from "./govinfo.js";
 import * as fpds from "./fpds.js";
 import * as nih from "./nih.js";
@@ -102,7 +106,7 @@ import { realpathSync } from "node:fs";
 const SERVER_NAME = "mcp-sam-gov";
 // Kept in lockstep with package.json / manifest.json / server.json.
 // Keep in sync with package.json "version" (asserted at release; see CHANGELOG).
-const SERVER_VERSION = "1.9.0";
+const SERVER_VERSION = "1.11.0";
 
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 
@@ -2975,6 +2979,113 @@ const DatagovSearchDatasetsInput = z.object({
     .describe("Opaque continuation cursor (→ after) — pass back the _meta.nextCursor from the previous page. Pagination is a cursor, NOT a numeric offset (offset/nextOffset are null); nextCursor:null means the last page. A bad token (spaces/'../'/'%') ⇒ invalid_input pre-fetch."),
 });
 
+// ─── ArcGIS Hub (hub.arcgis.com — keyless SLED dataset discovery) ─
+// Loop cycle 9. A GLOBAL, OPEN publishing platform (non-US / non-gov publishers
+// included) — DISCOVERY ONLY, provenance surfaced per-row + disclosed every
+// response. Fixed-host SSRF (no per-jurisdiction host vector). q ≥ 2 chars.
+const ArcgisHubDiscoverInput = z.object({
+  query: z
+    .string()
+    .min(2)
+    .max(500)
+    .describe("Keyword search over ArcGIS Hub datasets (→ q), e.g. 'procurement contract', 'zoning permits'. REQUIRED, ≥2 non-whitespace chars (a broad scan of the whole global Hub is refused)."),
+  openDataOnly: z
+    .boolean()
+    .default(true)
+    .describe("When true (default), filter to items the publisher designated as open data (→ filter[openData]=true) — the B2G-relevant subset. Set false to broaden to ALL shared items (vet the publisher even more)."),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(20)
+    .describe("Datasets per page (→ page[size]), 1..100, default 20."),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .default(0)
+    .describe("0-based record offset (→ page[start]=offset+1). Page with _meta.pagination.nextOffset; totalAvailable is the exact Hub match count."),
+});
+
+// ─── OpenGov Procurement (api.procurement.opengov.com — keyless SLED bids) ─
+// SLED bid campaign. 525+ US state/local portals' live solicitations via the
+// public portal's own anonymous backend API (the key-gated api-key API is NOT
+// used). Fixed-host SSRF. governmentCode = the portal slug from list_governments.
+const OpengovListGovernmentsInput = z.object({
+  state: z
+    .string()
+    .length(2)
+    .optional()
+    .describe("2-letter US state filter (client-side), e.g. 'CA', 'FL'. Optional."),
+  query: z
+    .string()
+    .min(1)
+    .max(120)
+    .optional()
+    .describe("Case-insensitive name substring filter (client-side), e.g. 'county', 'school'. Optional."),
+  limit: z.number().int().min(1).max(200).default(50).describe("Portals per page, 1..200, default 50."),
+  offset: z.number().int().min(0).default(0).describe("0-based offset; page with _meta.pagination.nextOffset. totalAvailable = exact filtered portal count."),
+});
+
+const OpengovSearchSolicitationsInput = z.object({
+  governmentCode: z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(opengov.OPENGOV_CODE_RE)
+    .describe("The OpenGov portal slug (from opengov_list_governments `code`), e.g. 'santacruzca', 'orlando', 'u-46'. REQUIRED. Lowercase alnum/hyphen; a bad slug ⇒ invalid_input pre-fetch."),
+  limit: z.number().int().min(1).max(100).default(50).describe("Solicitations per page, 1..100, default 50 (→ API page size)."),
+  offset: z.number().int().min(0).default(0).describe("0-based offset (snapped to the API's fixed page boundary). Page with _meta.pagination.nextOffset."),
+});
+
+// ─── Bonfire (Euna) — keyless per-org open-opportunity RSS (SLED bids) ─
+// SLED bid campaign. Thousands of US state/local govs on Bonfire expose a keyless
+// RSS of open opportunities at {org}.bonfirehub.com/opportunities/rss. Ships a
+// curated 187-org seed directory. Fixed-suffix SSRF. org = charclass slug.
+const BonfireListOrganizationsInput = z.object({
+  state: z.string().length(2).optional().describe("2-letter US state filter (client-side), e.g. 'TX', 'CA'. Optional."),
+  query: z.string().min(1).max(120).optional().describe("Case-insensitive name substring filter (client-side), e.g. 'county', 'ISD'. Optional."),
+  limit: z.number().int().min(1).max(200).default(50).describe("Orgs per page, 1..200, default 50."),
+  offset: z.number().int().min(0).default(0).describe("0-based offset; page with _meta.pagination.nextOffset."),
+});
+
+const BonfireSearchOpportunitiesInput = z.object({
+  org: z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(bonfire.BONFIRE_ORG_RE)
+    .describe("The Bonfire org subdomain slug (from bonfire_list_organizations `org`), e.g. 'harriscountytx', 'broward', 'u-46'. REQUIRED. Lowercase alnum/hyphen; a bad slug ⇒ invalid_input pre-fetch."),
+  limit: z.number().int().min(1).max(200).default(50).describe("Opportunities per page, 1..200, default 50. The RSS is the complete open set; this pages over it."),
+  offset: z.number().int().min(0).default(0).describe("0-based offset; page with _meta.pagination.nextOffset. totalAvailable = the exact open-opportunity count."),
+});
+
+// ─── ArcGIS REST feature query (curated service allowlist — SLED bids/GIS) ─
+// Generic ArcGIS FeatureServer/MapServer layer query over a curated allowlist.
+// First payload: DC OCP PASS procurement layers (live solicitations/contracts/PO/
+// payments). `service` is an enum (SSRF core); where/outFields filter the layer.
+const ArcgisFeatureQueryInput = z.object({
+  service: z
+    .enum(arcgisFeature.ARCGIS_SERVICES.map((s) => s.key) as [string, ...string[]])
+    .describe("The curated ArcGIS layer (SSRF allowlist enum). DC OCP PASS: 'dc_pass_solicitations' (live solicitations ~25k), 'dc_pass_contracts', 'dc_pass_purchase_orders', 'dc_pass_payments'. Other US local govs: 'asheville_purchase_orders'/'asheville_po_summary' (Asheville NC), 'bellevue_vendor_payments'/'bellevue_awarded_contracts' (Bellevue WA), 'miamidade_purchase_orders_2025'/'miamidade_purchase_orders_2017' (Miami-Dade FL, current/2017), 'suffolk_county_ny_contracts_2018' (Suffolk County NY), 'matsu_borough_ak_checkbook' (Matanuska-Susitna Borough AK), 'lasvegas_checkbook' (Las Vegas NV ~373k), 'baltimore_checkbook' (Baltimore City MD ~367k), 'naperville_vendor_payments' (Naperville IL ~127k), 'worcester_ma_checkbook_fy25' (Worcester MA FY25), 'lasvegas_purchasing_contracts' (Las Vegas NV contract register), 'txdot_construction_projects' (Texas DOT, awarded construction company ~85k), 'akdot_construction_awards'/'akdot_aashtoware_proposals' (Alaska DOT&PF bid awards/proposals), 'iowadot_public_bid_awards' (Iowa DOT public bid), 'okdot_cirb_contract_status' (Oklahoma DOT CIRB contract status), 'topeka_checkbook_aggregate' (Topeka KS checkbook FY2015–2023 ~332k). 23 curated services (state DOT bid/award registers: TX/AK/IA/OK + municipal checkbooks/contracts)."),
+  where: z
+    .string()
+    .min(1)
+    .max(500)
+    .optional()
+    .describe("ArcGIS SQL-ish filter (default '1=1'), e.g. \"SOLICITATIONTITLE LIKE '%security%'\" or \"DUE_DATE > 1750000000000\". Filters the read-only layer; a malformed clause ⇒ invalid_input (surfaced)."),
+  outFields: z
+    .string()
+    .min(1)
+    .max(500)
+    .optional()
+    .describe("Comma-separated fields to return (default '*' = all). e.g. 'SOLICITATIONNUMBER,SOLICITATIONTITLE,DUE_DATE,NIGPCODE'."),
+  orderByFields: z.string().min(1).max(200).optional().describe("ArcGIS orderByFields, e.g. 'DUE_DATE DESC'. Optional."),
+  limit: z.number().int().min(1).max(1000).default(50).describe("Records per page (→ resultRecordCount), 1..1000, default 50."),
+  offset: z.number().int().min(0).default(0).describe("0-based offset (→ resultOffset). Page with _meta.pagination.nextOffset; totalAvailable = the layer's exact match count."),
+});
+
 // ─── GovInfo (api.govinfo.gov — the api.data.gov keyed trio's 3rd API) ─
 // ADR-0010. Same DATA_GOV_API_KEY/DEMO_KEY/X-Api-Key discipline as the datagov
 // trio (shared datagovKey.ts seam). `collection` is grammar-checked here AND
@@ -4307,7 +4418,7 @@ const GsaPerdiemRatesInput = z
       .regex(/^\d{4}$/)
       .optional()
       .describe(
-        "The per-diem fiscal year (default '2025'). Validated ^\\d{4}$ (it rides in the request path).",
+        "The per-diem fiscal year (default: the current U.S. federal fiscal year, computed at call time — GSA sets rates per FY, Oct 1–Sep 30). Validated ^\\d{4}$ (it rides in the request path).",
       ),
   })
   .describe(
@@ -4432,7 +4543,7 @@ const LdaSearchFilingsInput = z.object({
     .string()
     .min(1)
     .optional()
-    .describe("Filter by the federal government entity lobbied (maps to government_entity — the B2G signal), e.g. 'DEPARTMENT OF DEFENSE'."),
+    .describe("NOTE: the keyless /filings/ endpoint has NO server-side government-entity filter — the LDA API silently ignores it, so this value is NOT applied (reported in _meta.filtersDropped, never as a narrowed total). Government entities are nested per lobbying activity (each filing's lobbyingActivities[].governmentEntities); to find who lobbied an agency, narrow by registrantName/clientName/issue and inspect those nested entities. Retained for discoverability of the limitation."),
   issue: z
     .string()
     .min(1)
@@ -4784,6 +4895,21 @@ export const TOOLS: ToolDef[] = [
             "The organization-name filter is NOT supported by the keyless endpoint and was ignored (results are unfiltered on organization). Set SAM_GOV_API_KEY to filter by organization, or filter client-side on the returned `agency` field.",
           );
         }
+        // Pagination honesty: the keyless HAL endpoint pages by PAGE (page × size),
+        // not an arbitrary row offset, so a requested offset that is not a multiple
+        // of `limit` snaps DOWN to its page boundary. Disclose the snap so the AI
+        // never believes it read rows [offset..offset+limit) when it actually got
+        // the page-aligned window. (An aligned offset — the default paging pattern
+        // of incrementing by `limit` — is served exactly, so no note.)
+        {
+          const reqOffset = input.offset ?? 0;
+          const size = input.limit ?? 25;
+          if (reqOffset % size !== 0) {
+            notes.push(
+              `Keyless SAM pagination is page-based (page × ${size}); the requested offset ${reqOffset} was snapped DOWN to the page boundary ${Math.floor(reqOffset / size) * size}. Page through by incrementing offset in multiples of limit (set SAM_GOV_API_KEY for exact row offsets).`,
+            );
+          }
+        }
         notes.push(...enrichmentNotes);
 
         // freshness is surfaced structurally in `data` (the ResponseMeta type
@@ -5543,7 +5669,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "nist_800_53_controls",
     description:
-      "Look up NIST SP 800-53 Rev 5 security & privacy CONTROLS (keyless) — the requirement backbone for FedRAMP / CMMC / RMF compliance work. Retrieve a control by `controlId` (exact, e.g. 'AC-2', 'SC-7', 'AC-2(1)'), a `family` (2-letter code 'AC'/'SC'/'IA' or a name substring 'Access Control'), and/or a `keyword` (case-insensitive substring over title + statement); `limit`/`offset` pagination. Each row: { id (e.g. 'AC-2'), family (e.g. 'AC — Access Control'), title, statement (the labelled requirement prose), guidance (discussion), enhancements:[{id,title}] (e.g. AC-2(1)) }. Complements cve_lookup + cisa_kev_lookup (the vulnerability side) with the CONTROL/requirement side. HONESTY: source is NIST's OFFICIAL OSCAL catalog published at github.com/usnistgov/oscal-content (authoritative first-party data served from GitHub, not a .gov API host — provenance disclosed in _meta); the catalog has no query API so filtering is CLIENT-SIDE and totalAvailable is the EXACT match count; this is the REQUIREMENT text only — applicability depends on the system's FIPS-199 impact baseline (Low/Moderate/High), which the catalog does not encode (disclosed); a download failure or an implausibly-truncated catalog (< 15 families) THROWS (never a fake-empty 'control not found').",
+      "Look up NIST SP 800-53 Rev 5 security & privacy CONTROLS (keyless) — the requirement backbone for FedRAMP / CMMC / RMF compliance work. Retrieve a control by `controlId` (exact, e.g. 'AC-2', 'SC-7', 'AC-2(1)'), a `family` (2-letter code 'AC'/'SC'/'IA' or a name substring 'Access Control'), and/or a `keyword` (case-insensitive substring over title + statement); `limit`/`offset` pagination. Each row: { id (e.g. 'AC-2'), family (e.g. 'AC — Access Control'), title, status ('withdrawn' | null), statement (the labelled requirement prose; NULL for a WITHDRAWN control, never ''), guidance (discussion), incorporatedInto:[control ids that superseded a withdrawn control, e.g. AC-13 → ['AC-2','AU-6']], enhancements:[{id,title}] (e.g. AC-2(1)) }. Complements cve_lookup + cisa_kev_lookup (the vulnerability side) with the CONTROL/requirement side. HONESTY: source is NIST's OFFICIAL OSCAL catalog published at github.com/usnistgov/oscal-content (authoritative first-party data served from GitHub, not a .gov API host — provenance disclosed in _meta); the exact OSCAL version + last-modified are surfaced in _meta (the catalog is fetched live from the MOVING 'main' branch, so control text can shift between point releases, e.g. 5.1.1 → 5.2.0 — cite the version, not just 'Rev 5'); a WITHDRAWN control (status:'withdrawn') has statement:null and is NOT an active requirement (see incorporatedInto for what replaced it); the catalog has no query API so filtering is CLIENT-SIDE and totalAvailable is the EXACT match count; this is the REQUIREMENT text only — applicability depends on the system's FIPS-199 impact baseline (Low/Moderate/High), which the catalog does not encode (disclosed); a download failure or an implausibly-truncated catalog (< 15 families) THROWS (never a fake-empty 'control not found').",
     inputSchema: NistControlsInput,
     handler: (input) => nistControls.searchControls(input),
   }),
@@ -6030,6 +6156,72 @@ export const TOOLS: ToolDef[] = [
     inputSchema: DatagovSearchDatasetsInput,
     handler: (input) => datagovCatalog.searchDatasets(input),
   }),
+  // ━━━ ArcGIS Hub (hub.arcgis.com) — keyless SLED dataset DISCOVERY (loop cycle 9) ━━━
+  // A NEW discovery platform: much US state/local/regional/tribal (SLED) open data
+  // — GIS/infrastructure/permits/boundaries/procurement — lives on ArcGIS Hub, NOT
+  // Socrata/CKAN. Fixed-host SSRF (no per-jurisdiction host vector). ★PROVENANCE: the
+  // Hub is GLOBAL + OPEN (non-US/non-gov publishers), so this is a DISCOVERY aid, not
+  // a curated official-source allowlist — per-row owner/orgName/source/region are
+  // surfaced for vetting + the disclosure rides every response. P1: totalAvailable =
+  // meta.total (exact Hub count). DISCOVERY ONLY (row-query on arbitrary ArcGIS hosts
+  // is a planned, separately-guarded addition).
+  defineTool({
+    name: "arcgis_hub_discover_datasets",
+    description:
+      "Discover ArcGIS Hub datasets by keyword — the SLED/GIS open-data layer that Socrata and CKAN do NOT cover (keyless; hub.arcgis.com/api/v3/datasets). Much US state/local/regional/tribal open data (GIS, infrastructure, permits, zoning, boundaries, procurement) is published on ArcGIS Hub. Input `query` (→q, REQUIRED, ≥2 non-whitespace chars — a broad whole-Hub scan is refused), `openDataOnly` (default TRUE → filter[openData]=true, the B2G-relevant designated-open-data subset; false broadens to all shared items), `limit` (1..100, def 20 → page[size]), `offset` (0-based → page[start]=offset+1). Returns { query, openDataOnly, datasets:[{ id, name, description, owner, orgName, source, region, type, sector, keywords, downloadable, hasApi, created, modified, landingPage, itemId }] } + honest _meta. ★PROVENANCE (the crux — a DIFFERENT trust posture from our other sources): ArcGIS Hub is a GLOBAL, OPEN publishing platform — results include NON-US and NON-GOVERNMENTAL publishers. This is a DISCOVERY aid, NOT a curated official-source allowlist (unlike socrata_query): the per-row owner/orgName/source/region are surfaced VERBATIM so you can VET the publisher before relying on the data, and the global-platform caveat rides EVERY response. DISCOVERY ONLY — metadata + links; to read rows follow the dataset on its own ArcGIS endpoint (a guarded row-query tool is a planned addition). HONESTY: totalAvailable = the EXACT Hub match count (meta.total, NEVER data.length — P1); pagination is a 0-based offset (nextOffset when more remain); every scalar null-never-empty, booleans null-preserving, counts null-never-0; a genuine no-match ⇒ complete:true/returned:0; a 429 ⇒ rate_limited / 5xx/timeout ⇒ upstream_unavailable THROWS (never a fake empty); a 200 non-JSON / non-array data ⇒ schema_drift.",
+    inputSchema: ArcgisHubDiscoverInput,
+    handler: (input) => arcgisHub.discoverDatasets(input),
+  }),
+  // ━━━ OpenGov Procurement (api.procurement.opengov.com) — keyless SLED bids ━━━
+  // SLED bid campaign (from the exhaustive US state+local bid-site research). 525+
+  // state/local government portals' LIVE solicitations, via the public portal's OWN
+  // anonymous backend REST API — the key-gated official api-key API is NOT touched
+  // (genuinely keyless, live-verified). Fixed-host SSRF. Two tools: a directory
+  // (one keyless GET returns all ~560 orgs) + per-org solicitations.
+  defineTool({
+    name: "opengov_list_governments",
+    description:
+      "List the government portals on OpenGov Procurement (formerly ProcureNow) — the directory for opengov_search_solicitations (keyless; api.procurement.opengov.com). OpenGov Procurement hosts the live open-solicitation portals of 525+ US state/local governments (cities, counties, school & special districts across 42 states + DC). The WHOLE directory arrives in ONE keyless GET and is filtered client-side: `state` (2-letter), `query` (case-insensitive name substring); `limit`(1..200)/`offset`. Only ACTIVE, non-internal portals are returned. Output: { governments:[{ code, name, city, state, website }] } + honest _meta. Feed a result's `code` to opengov_search_solicitations. HONESTY: this consumes ONLY the anonymous endpoints the public portal itself calls (the official key-gated api-key API is NOT used) — genuinely keyless; totalAvailable is the EXACT filtered portal count (never the page length); a 429/5xx/timeout THROWS (never a fake empty); a non-array body ⇒ schema_drift.",
+    inputSchema: OpengovListGovernmentsInput,
+    handler: (input) => opengov.listGovernments(input),
+  }),
+  defineTool({
+    name: "opengov_search_solicitations",
+    description:
+      "List a government's public solicitations on OpenGov Procurement (keyless; api.procurement.opengov.com, POST /project/list with the required publicView gate). Input `governmentCode` (the portal slug from opengov_list_governments, e.g. 'santacruzca', 'orlando', 'u-46'; REQUIRED), `limit`(1..100)/`offset`. Returns { governmentCode, solicitations:[{ id, title, solicitationNumber, status, type, department, releaseDate, proposalDeadline, contactName, link }] } + honest _meta. ★STATUS: `status` is surfaced VERBATIM — **open = currently ACCEPTING responses**; pending/evaluation/closed are ALSO returned (publicView shows all public projects), so filter status==='open' for live bids. `link` is the public portal page. HONESTY: totalAvailable = the API's `count` = the org's TOTAL public-project count (all statuses), NEVER the page length and NOT an open-only count (a note discloses this); pagination is the API's fixed page (offset is snapped to the page boundary, disclosed); a genuine no-match ⇒ complete:true/returned:0; a 429/5xx/timeout THROWS (never a fake empty); a non-array `projects` ⇒ schema_drift; a bad `governmentCode` ⇒ invalid_input pre-fetch. Genuinely keyless (the key-gated official API is NOT used).",
+    inputSchema: OpengovSearchSolicitationsInput,
+    handler: (input) => opengov.searchSolicitations(input),
+  }),
+  // ━━━ Bonfire (Euna) — keyless per-org open-opportunity RSS (SLED bids) ━━━
+  // SLED bid campaign. Thousands of US state/local govs on Bonfire expose a keyless
+  // RSS of open opportunities. Ships a curated 187-org live-verified seed directory
+  // (Bonfire's authoritative org API is auth-gated → out of bounds). Fixed-suffix
+  // SSRF (.bonfirehub.com). RSS = the complete open set (totalAvailable honest).
+  defineTool({
+    name: "bonfire_list_organizations",
+    description:
+      "List US governments on the Bonfire (Euna) eProcurement platform — the directory for bonfire_search_opportunities (keyless). Bonfire hosts thousands of US state/local governments' open-bid portals, each with a keyless RSS feed. Filter the curated seed by `state` (2-letter) / `query` (case-insensitive name substring); `limit`(1..200)/`offset`. Output: { organizations:[{ org, name, state }] }. Feed a result's `org` to bonfire_search_opportunities. ★HONESTY: this is a CURATED, live-verified SEED of 187 US orgs — Bonfire has NO keyless org-list API (its authoritative directory is auth-gated, out of bounds), and Euna markets up to ~900 US orgs, so the seed is PARTIAL (disclosed in _meta); probe `{slug}.bonfirehub.com/opportunities/rss` to extend. totalAvailable = the exact filtered seed count.",
+    inputSchema: BonfireListOrganizationsInput,
+    handler: (input) => bonfire.listOrganizations(input),
+  }),
+  defineTool({
+    name: "bonfire_search_opportunities",
+    description:
+      "List a government's currently-OPEN solicitations on Bonfire (keyless; {org}.bonfirehub.com/opportunities/rss, RSS 2.0). Input `org` (the subdomain slug from bonfire_list_organizations, e.g. 'harriscountytx', 'broward', 'u-46'; REQUIRED), `limit`(1..200)/`offset`. Returns { org, opportunities:[{ referenceNumber, name, description, closeDate, link, pubDate }] } + honest _meta. HONESTY: the RSS is the COMPLETE set of the org's currently-open opportunities (no server pagination), so totalAvailable = the exact open-opportunity count (never a page length) and this tool pages over it client-side; an empty feed (returned 0) means no open opportunities right now (honest empty, complete:true); `closeDate` is parsed best-effort from the description; a 429/5xx/404/timeout THROWS (never a fake empty); a 200 non-RSS body ⇒ schema_drift; a bad `org` ⇒ invalid_input pre-fetch. Fixed-suffix SSRF (.bonfirehub.com) + redirect:error. Keyless (Bonfire's auth-gated directory API is NOT used).",
+    inputSchema: BonfireSearchOpportunitiesInput,
+    handler: (input) => bonfire.searchOpportunities(input),
+  }),
+  // ━━━ ArcGIS REST feature query (curated allowlist) — SLED bids/GIS ━━━
+  // Generic query companion to arcgis_hub_discover_datasets. First payload: the DC
+  // OCP PASS procurement layers (live solicitations + contracts/PO/payments), a
+  // keyless live-solicitation feed via ArcGIS REST. `service` enum = SSRF core.
+  defineTool({
+    name: "arcgis_feature_query",
+    description:
+      "Query rows from a curated US-government ArcGIS REST feature layer (keyless) — the QUERY companion to arcgis_hub_discover_datasets (which discovers Hub datasets). A large amount of SLED procurement/GIS data lives on ArcGIS. First payload: the **DC Office of Contracting & Procurement 'PASS'** layers — `dc_pass_solicitations` (DC's LIVE open solicitations, ~25k: SOLICITATIONNUMBER, SOLICITATIONTITLE, DUE_DATE, OPENDATE, CLOSEDATE, NIGPCODE, CONTRACTINGOFFICER, AWARD_TO, 46 fields), `dc_pass_contracts` (~50k), `dc_pass_purchase_orders` (~275k), `dc_pass_payments` (~1.55M). Inputs: `service` (the allowlist ENUM — the SSRF core, never a free host), `where` (ArcGIS SQL-ish filter, default '1=1', e.g. \"SOLICITATIONTITLE LIKE '%security%'\"), `outFields` (default '*'), `orderByFields`, `limit`(1..1000)/`offset`. Returns { service, records:[{…attributes verbatim…}] } + honest _meta. HONESTY: totalAvailable = the layer's EXACT match count (a returnCountOnly companion query, never the page length; a count failure ⇒ null + note, rows still returned); ★ArcGIS date fields are epoch MILLISECONDS and a negative/sentinel (≈1900) is a placeholder — surfaced verbatim, never coerced; a genuine no-match ⇒ complete:true/returned:0; a 429/5xx/timeout THROWS; an ArcGIS {error} body (e.g. a bad where) ⇒ invalid_input/upstream (surfaced, never a fake empty); a non-array features ⇒ schema_drift. SSRF: fixed allowlist base + hostname assertion + redirect:error (where/outFields cannot alter the host).",
+    inputSchema: ArcgisFeatureQueryInput,
+    handler: (input) => arcgisFeature.featureQuery(input),
+  }),
   // ━━━ GovInfo (api.govinfo.gov) — the api.data.gov keyed trio's 3rd API (3) ━━━ ADR-0010
   // GPO-authoritative bulk publications (BILLS/PLAW/USCODE/CREC/CFR-FR editions/
   // BUDGET/GAOREPORTS) with PDF/XML/MODS downloads + provenance. 2nd consumer of the
@@ -6269,7 +6461,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "cbp_border_wait_times",
     description:
-      "Live CBP land-border-port wait times — current commercial-vehicle (and passenger) crossing delays at every US Canadian- and Mexican-border port (keyless; bwt.cbp.gov). The FREIGHT / LOGISTICS situational-awareness lane: per-port commercial-vehicle standard + FAST lane delay (minutes), operational status, open-lane count, and maximum lanes. Filters (optional): `border` (case-insensitive substring, 'Canadian'/'Mexican'), `portName` (substring, e.g. 'Laredo'); `limit`/`offset` pagination. Each row: { portNumber, portName, crossingName, border, portStatus (Open/Closed), asOf, commercialVehicle:{ maxLanes, standard:{operationalStatus, delayMinutes, lanesOpen, updateTime}, fast:{…} } }. HONESTY: this is REAL-TIME operational data — each lane carries its own updateTime (surfaced verbatim; freshness never implied live-to-the-second); delayMinutes/lanesOpen are number|null (a real 0 stays 0; an empty/N/A value — e.g. a closed lane — is null, NEVER a fabricated 0, because a closed lane's delay is UNKNOWN, not zero); the API returns the WHOLE port set so totalAvailable is the EXACT matched-port count; an outage/4xx/timeout THROWS and a non-array body ⇒ schema_drift (never a fake empty).",
+      "Live CBP land-border-port wait times — current commercial-vehicle (freight-truck) crossing delays at every US Canadian- and Mexican-border port (keyless; bwt.cbp.gov). The FREIGHT / LOGISTICS situational-awareness lane: per-port commercial-vehicle standard + FAST lane delay (minutes), operational status, open-lane count, and maximum lanes — passenger/pedestrian lanes are NOT surfaced (freight lane only). Filters (optional, applied CLIENT-SIDE over the full fetched port set — the feed has NO server-side filter; an empty-string value is reported in _meta.filtersDropped, not applied): `border` (case-insensitive substring, 'Canadian'/'Mexican'), `portName` (substring, e.g. 'Laredo'); `limit`/`offset` pagination. Each row: { portNumber, portName, crossingName, border, portStatus (Open/Closed), asOf, commercialVehicle:{ maxLanes, standard:{operationalStatus, delayMinutes, lanesOpen, updateTime}, fast:{…} } }. HONESTY: this is REAL-TIME operational data — each lane carries its own updateTime (surfaced verbatim; freshness never implied live-to-the-second); delayMinutes/lanesOpen are number|null (a real 0 stays 0; an empty/N/A value — e.g. a closed lane — is null, NEVER a fabricated 0, because a closed lane's delay is UNKNOWN, not zero); the API returns the WHOLE port set so totalAvailable is the EXACT matched-port count; an outage/4xx/timeout THROWS and a non-array body ⇒ schema_drift (never a fake empty).",
     inputSchema: CbpBorderWaitInput,
     handler: (input) => cbpBorder.borderWaitTimes(input),
   }),
@@ -6298,7 +6490,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "gsa_perdiem_rates",
     description:
-      "Look up GSA Federal Travel PER-DIEM rates — the max lodging + Meals & Incidental Expenses (M&IE) reimbursement ceilings for official U.S. government travel (api.gsa.gov /travel/perdiem/v2, keyed — DATA_GOV_API_KEY or the shared DEMO_KEY). Input: EITHER `city` (e.g. 'Washington') + `state` (2-letter, e.g. 'DC') OR `zip` (5-digit) — supplying BOTH, or NEITHER, ⇒ invalid_input with 0 fetch; optional `year` (default '2025'). Returns { rates:[{ city, county, state, zip, year, isOconus, standardRate, mealsUsd, monthlyLodgingUsd:[{ month (1-12), monthName, lodgingUsd }] }] } + honest _meta. HONESTY: lodgingUsd (the API's monthly `value`) is the MAX nightly lodging ceiling for that month — it VARIES SEASONALLY (hence a per-month array), and mealsUsd is the daily M&IE ceiling; both are integer US dollars, null-when-withheld (NEVER 0 — a genuine 0 is preserved). standardRate/isOconus are booleans coerced from the API's string 'true'/'false' (an unrecognized value ⇒ null, never a fabricated false); the months array is preserved AS-IS (never padded to 12). The API returns the COMPLETE rate set (no pagination) ⇒ totalAvailable = the row count, complete:true. A genuine no-match (rates:[]/rate:[]) ⇒ honest empty (returned:0); the API's `errors` field non-null ⇒ invalid_input carrying the message (never a fake empty); a 429 (DEMO_KEY ~10 req/hr, hit quickly) ⇒ rate_limited THROWS; a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON ⇒ schema_drift. DEMO_KEY ~10 req/hr shared ceiling — set DATA_GOV_API_KEY (free at api.data.gov/signup) for 1000/hr. The key rides ONLY in the X-Api-Key header (never the URL/_meta).",
+      "Look up GSA Federal Travel PER-DIEM rates — the max lodging + Meals & Incidental Expenses (M&IE) reimbursement ceilings for official U.S. government travel (api.gsa.gov /travel/perdiem/v2, keyed — DATA_GOV_API_KEY or the shared DEMO_KEY). Input: EITHER `city` (e.g. 'Washington') + `state` (2-letter, e.g. 'DC') OR `zip` (5-digit) — supplying BOTH, or NEITHER, ⇒ invalid_input with 0 fetch; optional `year` (default: the current U.S. federal fiscal year). Returns { rates:[{ city, county, state, zip, year, isOconus, standardRate, mealsUsd, monthlyLodgingUsd:[{ month (1-12), monthName, lodgingUsd }] }] } + honest _meta. HONESTY: lodgingUsd (the API's monthly `value`) is the MAX nightly lodging ceiling for that month — it VARIES SEASONALLY (hence a per-month array), and mealsUsd is the daily M&IE ceiling; both are integer US dollars, null-when-withheld (NEVER 0 — a genuine 0 is preserved). standardRate/isOconus are booleans coerced from the API's string 'true'/'false' (an unrecognized value ⇒ null, never a fabricated false); the months array is preserved AS-IS (never padded to 12). The API returns the COMPLETE rate set (no pagination) ⇒ totalAvailable = the row count, complete:true. A genuine no-match (rates:[]/rate:[]) ⇒ honest empty (returned:0); the API's `errors` field non-null ⇒ invalid_input carrying the message (never a fake empty); a 429 (DEMO_KEY ~10 req/hr, hit quickly) ⇒ rate_limited THROWS; a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON ⇒ schema_drift. DEMO_KEY ~10 req/hr shared ceiling — set DATA_GOV_API_KEY (free at api.data.gov/signup) for 1000/hr. The key rides ONLY in the X-Api-Key header (never the URL/_meta).",
     inputSchema: GsaPerdiemRatesInput,
     handler: (input) => gsaPerdiem.perdiemRates(input),
   }),
@@ -6333,7 +6525,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "lda_search_filings",
     description:
-      "Search US Senate LDA (Lobbying Disclosure Act) filings — who is paid HOW MUCH to lobby WHICH federal agency on WHICH issue (lda.senate.gov/api/v1/filings, KEYLESS — anonymous access works; an optional free LDA_API_KEY only raises the rate limit). All inputs optional: `registrantName` (the lobbying firm/in-house filer), `clientName` (who it's for), `lobbyistName`, `filingYear` (4-digit), `filingType` (short code, e.g. 'Q1'/'RR'/'YE'), `agency` (the federal government_entity lobbied — the B2G signal), `issue` (specific lobbying issues text), `page` (1-based, default 1), `pageSize` (1..25, default 25). Returns { filings:[{ filingUuid, filingType, filingYear, filingPeriod, incomeUsd, expensesUsd, registrant, client, lobbyingActivities:[{ issueCode, description, governmentEntities:[names] }], documentUrl, postedDate, terminationDate }] } + honest _meta. HONESTY: totalAvailable is the API's REAL total match count (the corpus is ~1.95M filings) — NOT the rows on this page; pagination is page-based (pass the next page number when hasMore). incomeUsd/expensesUsd are parsed from the null-or-decimal-string income/expenses — null (not reported) ⇒ null, NEVER 0 (a genuine 0 stays 0); a filing reports EITHER income OR expenses, so the other is typically null. Missing lobbying_activities/government_entities ⇒ empty arrays (never fabricated). A genuine no-match (results:[]) ⇒ honest empty (returned:0); a 400 (bad filter) ⇒ invalid_input surfacing the API's message; a 429 ⇒ rate_limited THROWS (Retry-After honored, never routed around); a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON / non-array results / non-number count ⇒ schema_drift. The optional key rides ONLY in the Authorization: Token header (never the URL/_meta).",
+      "Search US Senate LDA (Lobbying Disclosure Act) filings — who is paid HOW MUCH to lobby WHICH federal agency on WHICH issue (lda.senate.gov/api/v1/filings, KEYLESS — anonymous access works; an optional free LDA_API_KEY only raises the rate limit). All inputs optional: `registrantName` (the lobbying firm/in-house filer), `clientName` (who it's for), `lobbyistName`, `filingYear` (4-digit), `filingType` (short code, e.g. 'Q1'/'RR'/'YE'), `agency` (NOTE: /filings/ has NO server-side agency filter — the LDA API silently ignores it, so it is reported in _meta.filtersDropped and NOT applied; government entities are nested per activity in lobbyingActivities[].governmentEntities), `issue` (specific lobbying issues text), `page` (1-based, default 1), `pageSize` (1..25, default 25). Returns { filings:[{ filingUuid, filingType, filingYear, filingPeriod, incomeUsd, expensesUsd, registrant, client, lobbyingActivities:[{ issueCode, description, governmentEntities:[names] }], documentUrl, postedDate, terminationDate }] } + honest _meta. HONESTY: totalAvailable is the API's REAL total match count (the corpus is ~1.95M filings) — NOT the rows on this page; pagination is page-based (pass the next page number when hasMore). incomeUsd/expensesUsd are parsed from the null-or-decimal-string income/expenses — null (not reported) ⇒ null, NEVER 0 (a genuine 0 stays 0); a filing reports EITHER income OR expenses, so the other is typically null. Missing lobbying_activities/government_entities ⇒ empty arrays (never fabricated). A genuine no-match (results:[]) ⇒ honest empty (returned:0); a 400 (bad filter) ⇒ invalid_input surfacing the API's message; a 429 ⇒ rate_limited THROWS (Retry-After honored, never routed around); a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON / non-array results / non-number count ⇒ schema_drift. The optional key rides ONLY in the Authorization: Token header (never the URL/_meta).",
     inputSchema: LdaSearchFilingsInput,
     handler: (input) => lda.searchFilings(input),
   }),
@@ -6619,7 +6811,7 @@ export async function runTool(
 /**
  * Hand-rolled Zod → JSON Schema converter (subset we use).
  */
-function zodToJsonSchema(schema: z.ZodTypeAny): Record<string, unknown> {
+export function zodToJsonSchema(schema: z.ZodTypeAny): Record<string, unknown> {
   const def = (schema as unknown as { _def: { typeName: string } })._def;
   const tn = def.typeName;
   const description = (schema as unknown as { description?: string }).description;
@@ -6671,6 +6863,19 @@ function zodToJsonSchema(schema: z.ZodTypeAny): Record<string, unknown> {
     const innerSchema = zodToJsonSchema(inner);
     return description ? { ...innerSchema, description } : innerSchema;
   }
+  if (tn === "ZodEffects") {
+    // .refine() / .superRefine() / .transform() wrap the REAL schema at
+    // `_def.schema` (used for cross-field rules like "npi OR state required").
+    // Without this branch these fall through to the {type:"string"} default,
+    // publishing a degenerate object-less inputSchema that a schema-driven MCP
+    // client cannot construct a call against — even though the runtime Zod still
+    // demands the full object. Unwrap so the published schema keeps its real
+    // properties / required / enums.
+    const inner = (schema as unknown as { _def: { schema: z.ZodTypeAny } })._def
+      .schema;
+    const innerSchema = zodToJsonSchema(inner);
+    return description ? { ...innerSchema, description } : innerSchema;
+  }
   return { type: "string", ...(description ? { description } : {}) };
 }
 

package/src/socrata.ts

@@ -1,5 +1,5 @@
 /**
- * Socrata / SODA — keyless open data for state / local (SLED) + E-rate portals.
+ * Socrata / SODA — keyless open data for state / local (SLED) + federal + E-rate portals.
  *
  * First SLED source (ADR-0004); 3rd consumer of the fetch/map/meta shape after
  * treasury.ts / edgar.ts. Fully PUBLIC, KEYLESS. ONE connector reaches ~a dozen
@@ -7,7 +7,8 @@
  * 4x4 dataset id. Hosts are a CURATED allowlist (see SSRF below); the caller
  * never supplies a free host or a free path.
  *   Row query:  https://{domain}/resource/{4x4}.json?$select=…&$where=…&$limit=…
- *   Catalog:    https://api.us.socrata.com/api/catalog/v1?domains={domain}&q=…
+ *   Catalog (host-scoped): https://{domain}/api/catalog/v1?search_context={domain}&q=…
+ *   Catalog (all-host):    https://api.us.socrata.com/api/catalog/v1?domains=…&q=…
  *
  * Three layers (mirror treasury.ts / edgar.ts):
  *   fetch — `getSocrataResource` / `getCatalog`: SSRF-guard, build the URL,
@@ -67,14 +68,19 @@
  * wrong shape (possible upstream API change). A hard schema_drift throw is
  * reserved for a PRIMARY query (rows / catalog), NEVER the secondary count.
  *
- * ALLOWLIST — LIVE-VERIFIED 2026-07-10 (each carries a real sample 4x4). All
- * `.gov` except `opendata.usac.org`:
+ * ALLOWLIST — each entry carries a real sample 4x4, live-verified on its tier's
+ * date (base state slice 2026-07-10; local + major-city + federal 2026-07-18).
+ * All `.gov` except the documented non-.gov exceptions: `opendata.usac.org` and
+ * the four major-city portals (.us/.org — see the inline blocks below):
  *   m6 — `opendata.usac.org` is a `.org` (USAC, a Congress-designated non-profit;
  *        E-rate). It is on the periodic re-verification checklist. NOTE: the
- *        federated discovery catalog (api.us.socrata.com) does NOT index USAC
- *        (returns resultSetSize 0), so `socrata_discover_datasets` will not
- *        surface it — but `socrata_query` works against it with a known 4x4
- *        (live: opendata.usac.org/resource/avi8-svp9.json → 200 bare array).
+ *        FEDERATED discovery catalog (api.us.socrata.com) does NOT index USAC
+ *        (resultSetSize 0), so the ALL-HOST `socrata_discover_datasets` (domain
+ *        omitted) won't surface it; as of loop cycle 8 a DOMAIN-scoped discover
+ *        uses USAC's own catalog (search_context) and DOES surface it (live:
+ *        opendata.usac.org/api/catalog/v1?search_context=… → resultSetSize 8).
+ *        `socrata_query` works regardless with a known 4x4 (live:
+ *        opendata.usac.org/resource/avi8-svp9.json → 200 bare array).
  *   M1 — MA is DROPPED from slice 1: `cthru.data.socrata.com` is a commercial
  *        vendor host (Tyler Technologies `.socrata.com`, not gov-controlled) and
  *        no `.gov` MA Socrata host verifies (`data.mass.gov` → the catalog
@@ -139,7 +145,85 @@ export const SOCRATA_DOMAINS = [
   "data.montgomerycountymd.gov", // Montgomery County MD — e.g. vmu2-pnrc (Contracts)
   "data.mesaaz.gov", // Mesa AZ (city) — e.g. j7s9-qiuq (Vendor Payments)
   "data.cambridgema.gov", // Cambridge MA (city) — e.g. gp98-ja4f (Contracts bid list)
+  // ── Federal open-data portal tier (loop cycle 7, 2026-07-18). The FIRST
+  //    federal Socrata hosts (prior tiers were state + local only); all .gov,
+  //    host-scoped catalog + /resource/<4x4>.json 200 bare-array + count(*)
+  //    companion live-verified. High-value B2G federal datasets (carrier/company
+  //    census, transportation infrastructure & stats, public health).
+  //    NOTE (m3/under-index): the FEDERATED aggregator (api.us.socrata.com)
+  //    under-indexes these hosts (DOT: 3 federated vs 1,873 host-scoped). As of
+  //    loop cycle 8, `socrata_discover_datasets` WITH a domain uses each host's
+  //    OWN catalog (search_context) → complete per-host discovery; only the
+  //    all-host search (domain omitted) still relies on the federated aggregator
+  //    (its `_meta` note discloses the gap). ──────────────────────────────────
+  "data.transportation.gov", // US DOT — e.g. az4n-8mr2 (Company Census File, ~4.47M carriers)
+  "data.cdc.gov", // US CDC — e.g. 9bhg-hcku (Provisional COVID-19 Deaths)
+  "data.bts.gov", // US BTS (DOT) — e.g. keg4-3bc2 (Border Crossing Entry Data)
+  // ── SLED procurement bid-catalog tier (loop cycle 11, 2026-07-19; from the
+  //    exhaustive US state+local bid-site research). All .gov; host-scoped catalog
+  //    + /resource/<4x4>.json 200 bare-array live-verified. Distinctive value:
+  //    these carry LIVE bid-cycle data (bid tabulations / anticipated
+  //    solicitations), not only award/spend. (★4 other candidate hosts —
+  //    data.iowa.gov, data.scottsdaleaz.gov, data.gilbertaz.gov, opendata.hawaii.gov
+  //    — were REJECTED: their /api/catalog/v1 AND /resource endpoints 404 (Next.js/
+  //    Express apps, not Socrata — a research-agent "Socrata" claim that live
+  //    verification disproved). Never add a host without a 200 bare-array probe.) ─
+  "datacatalog.cookcountyil.gov", // Cook County IL — e.g. 32au-zaqn (Bid Tabulations ~5,607; +awards qh8j-6k63, intent-to-award bgq7-v7ms — 17 procurement datasets)
+  "data.illinois.gov", // IL — e.g. 6rb8-ntpm (Future Solicitations = anticipated construction bids); re-included (cycle-1 excluded on federated-discover 0, but host-scoped catalog + /resource verified 2026-07-19)
+  "data.cincinnati-oh.gov", // Cincinnati OH (city) — e.g. 2iq3-bugw (Certified Vendors MBE/WBE; +contracts 85xi-xdtw)
+  // ── Major-city OFFICIAL portals (loop cycle 5, 2026-07-18). NON-.gov but the
+  //    unambiguously-official municipal open-data portals for the largest local
+  //    procurement markets (NYC OpenData / Chicago / DataSF / LA Controller) —
+  //    host-scoped catalog + /resource 200 bare-array verified. Trust-boundary
+  //    (like the USAC .org exception): the SSRF guard is the CURATED, FROZEN
+  //    allowlist, not the TLD; these five are the documented non-.gov entries. ──
+  "data.cityofnewyork.us", // NYC OpenData (.us, official) — e.g. dg92-zbpx (City Record: procurement notices)
+  "data.cityofchicago.org", // Chicago (.org, official) — e.g. rsxa-ify5 (Contracts)
+  "data.sfgov.org", // San Francisco / DataSF (.org, official) — e.g. cqi5-hm2d (Supplier Contracts)
+  "controllerdata.lacity.org", // LA City Controller (.org, official) — e.g. pggv-e4fn (Checkbook L.A.)
   "opendata.usac.org", // USAC E-rate (.org, m6) — e.g. avi8-svp9
+  // ── County/city procurement sweep (loop cycle 17, 2026-07-20). Discovered via
+  //    the Socrata federated catalog (api.us.socrata.com) filtered to procurement/
+  //    bid/contract datasets, then each host-scoped $select=count(*) + /resource
+  //    200 bare-array live-verified. US local govs only (Canada/AU + demo/test +
+  //    off-theme aggregate hosts filtered out). Mix of official .gov/.org/.com
+  //    municipal portals (same documented non-.gov trust-boundary as above). ──
+  "data.kcmo.org", // Kansas City MO (.org, official) — e.g. 4mdg-usvj (Vendor Payments ~144k; 22 procurement datasets)
+  "data.brla.gov", // Baton Rouge / East Baton Rouge Parish LA (.gov) — e.g. e5pk-us93 (Upcoming Procurement Opportunities; 19 procurement datasets)
+  "www.dallasopendata.com", // Dallas TX (.com, official) — e.g. x5ih-idh7 (Vendor Payments FY2019–present ~166k)
+  "data.lacity.org", // Los Angeles CA (.org, official) — e.g. hf3r-utnq (RAMP Open Bid Opportunities — live bids)
+  "data.ramseycountymn.gov", // Ramsey County MN (.gov) — e.g. iu7r-dzmj (Solicitations & Addenda, with due_date/download_url ~516)
+  "data.richmondgov.com", // Richmond VA (.com, official) — e.g. xqn7-jvv2 (City Contracts: contract_value/supplier/procurement_type ~1,387)
+  // ── County/city procurement sweep, wave 2 (loop cycle 19, 2026-07-20). Same
+  //    federated-catalog mining + host-scoped count(*) + /resource 200 bare-array
+  //    verification. All large real checkbook/PO/vendor-payment datasets. ──
+  "opendata.howardcountymd.gov", // Howard County MD (.gov) — e.g. mesh-jggc (Vendors Receiving Payments $30k+ ~35k)
+  "data.providenceri.gov", // Providence RI (.gov) — e.g. 425y-pm5m (City & School Dept Purchase Orders ~228k)
+  "fiscalfocus.pittsburghpa.gov", // Pittsburgh PA (.gov) — e.g. t8t2-4b5n (Checkbook Data ~1.01M)
+  "data.coloradosprings.gov", // Colorado Springs CO (.gov) — e.g. yn6y-xikx (Open Checkbook Vendors ~19k)
+  "data.framinghamma.gov", // Framingham MA (.gov) — e.g. cqve-ehkr (Checkbook ~324k)
+  "data.fultoncountyga.gov", // Fulton County GA (.gov) — e.g. mxhc-krcg (Vendor Payments/disbursements ~217k)
+  "atlanta.data.socrata.com", // City of Atlanta GA (Socrata-hosted official portal) — e.g. jmke-icfi (Open Checkbook Ledger ~1.78M)
+  "opendata.cityofmesquite.com", // Mesquite TX (.com, official) — e.g. 6tva-azs5 (Check Register ~144k)
+  // ── County/city procurement sweep, wave 3 (loop cycle 20, 2026-07-20). Expanded
+  //    federated-catalog queries (rfp/rfq/disbursement/expenditure/commodity) +
+  //    offset paging. Provenance confirmed via /api/views attribution or the gov
+  //    domain itself; hosts with only an individual-name attribution on a generic
+  //    *.data.socrata.com subdomain (washoe, newcastle) were DEFERRED. ──
+  "datahub.usac.org", // USAC E-Rate (.org, same org as opendata.usac.org) — e.g. 39tn-hjzv (E-Rate Open Competitive Bidding, FCC Form 470 — schools/libraries LIVE bids ~2.2M)
+  "performance.ci.janesville.wi.us", // City of Janesville WI (.us official municipal domain) — e.g. fd4q-2kma (Open Expenditures Ledger ~1.0M)
+  "datahub.austintexas.gov", // Austin TX secondary hub (.gov) — e.g. 3ebq-e9iz (Purchase Order Quantity/Price detail, commodity/goods procurements ~318k)
+  "cthru.data.socrata.com", // Commonwealth of Massachusetts, Office of the Comptroller — CTHRU statewide spending (attribution-confirmed) — e.g. kv7m-35wn (Budget/Actual + spending authorizations ~48k)
+  "data.macoupincountyil.gov", // Macoupin County IL (.gov) — e.g. wysn-7qcg (Open Expenditures Ledger ~156k)
+  "data.oaklandca.gov", // Oakland CA (.gov) — e.g. 4ewt-5m6f (budget expenditures ~66k)
+  "data.princegeorgescountymd.gov", // Prince George's County MD (.gov) — e.g. csi4-9jzc (Spending Information: payee_name/agency/amount ~62k)
+  "data.cstx.gov", // College Station TX (.gov) — e.g. i5cx-63zy (Open Budget Expenditures ~42k)
+  "datahub.transportation.gov", // US DOT secondary hub (.gov) — e.g. 255k-mnvp (Disbursements by States for Highways SF-2 ~15k)
+  // ── County/city procurement sweep, wave 4 / tail (loop cycle 21, 2026-07-20).
+  //    Diminishing returns (most remaining catalog hits are Canada/AU, demo/test,
+  //    duplicates, or off-theme); these two are the clean US wins. ──
+  "citydata.mesaaz.gov", // Mesa AZ secondary hub (.gov, attr "Office of Management and Budget") — e.g. vdg8-dx96 (City Expenditures ~15.4M)
+  "data.weho.org", // City of West Hollywood CA (.org, official portal) — e.g. atdr-sk64 (Active Contracts: contract_number/contractor_name/status/type — live/current ~1,030)
 ] as const;
 
 export type SocrataDomain = (typeof SOCRATA_DOMAINS)[number];
@@ -262,6 +346,44 @@ async function getCatalog(params: URLSearchParams): Promise<unknown> {
   });
 }
 
+/**
+ * GET a HOST-SCOPED discovery catalog (`https://{domain}/api/catalog/v1?
+ * search_context={domain}&…`). Unlike the FEDERATED `getCatalog`
+ * (api.us.socrata.com), each portal's OWN catalog COMPLETELY indexes its own
+ * datasets — the federated aggregator under-indexes many hosts (loop cycle 8:
+ * USAC → 0, DOT → 3 of 1,873). Used whenever a specific `domain` is requested;
+ * the all-host search (domain omitted) still needs the federated aggregator.
+ * SSRF: identical guard to getSocrataResource — domain ∈ allowlist + the
+ * CONSTRUCTED URL's hostname === domain (https); redirect:"error" (B1); the
+ * host-only label carries the domain (never the token, m7).
+ */
+async function getHostCatalog(
+  domain: string,
+  params: URLSearchParams,
+): Promise<unknown> {
+  if (!SOCRATA_DOMAIN_SET.has(domain)) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Socrata domain ${JSON.stringify(domain)} is not on the curated allowlist. Allowed: ${SOCRATA_DOMAINS.join(", ")}.`,
+      retryable: false,
+    });
+  }
+  const url = `https://${domain}/api/catalog/v1?${params.toString()}`;
+  const built = new URL(url);
+  if (built.hostname !== domain || built.protocol !== "https:") {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Constructed Socrata host-catalog URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the allowlisted domain ${JSON.stringify(domain)} over https — refusing to fetch (SSRF safety).`,
+      retryable: false,
+    });
+  }
+  return getJson(url, {
+    label: "socrata:catalog:" + domain,
+    headers: appTokenHeader(),
+    redirect: "error",
+  });
+}
+
 // ─── map + meta helpers ───────────────────────────────────────────
 const STRING_COERCION_NOTE =
   "Row value fields arrive as strings verbatim from SODA (e.g. \"13650.00\", \"1\") — parse client-side. A missing value is absent, never 0.";
@@ -464,16 +586,21 @@ function mapCatalogRow(row: unknown): CatalogDataset {
 }
 
 /**
- * Discover dataset 4x4 ids via the Socrata catalog (memoized ~10 min). Omitting
- * `domain` searches the WHOLE allowlist (repeated `domains=`); passing one scopes
- * to it. Returns `[{ id, name, description, domain, updatedAt, link }]` +
- * `totalAvailable = resultSetSize`. Feeds `datasetId` to socrata_query.
+ * Discover dataset 4x4 ids via the Socrata catalog (memoized ~10 min). Passing a
+ * `domain` queries that portal's OWN catalog (search_context) — a COMPLETE
+ * per-host index; omitting it searches the WHOLE allowlist via the federated
+ * api.us.socrata.com aggregator (repeated `domains=`). Returns `[{ id, name,
+ * description, domain, updatedAt, link }]` + `totalAvailable = resultSetSize`.
+ * Feeds `datasetId` to socrata_query.
  *
  * m3 — this is the catalog's PRIMARY response: a non-number `resultSetSize` is a
  * hard schema_drift throw (nothing valid to return), never a fabricated total.
- * (Note: the catalog does not index every allowlisted host — e.g. USAC — so a
- * host may return 0 here yet still be queryable via socrata_query with a known
- * 4x4.)
+ *
+ * UNDER-INDEX (loop cycle 8 fix): the FEDERATED aggregator under-indexes many
+ * hosts (USAC → 0; DOT → 3 of 1,873), so the all-host search (domain omitted) can
+ * miss datasets — its `_meta` note discloses this. A DOMAIN-scoped search now
+ * uses that host's OWN catalog, which indexes it completely (USAC/DOT/etc. fully
+ * discoverable). socrata_query works regardless with a known 4x4.
  */
 export async function discoverDatasets(args: {
   q: string;
@@ -485,8 +612,11 @@ export async function discoverDatasets(args: {
   params.set("q", args.q);
   params.set("only", "datasets");
   params.set("limit", String(limit));
+  // A specific domain → that portal's OWN catalog (search_context), a COMPLETE
+  // per-host index. Omitting domain → the federated aggregator (repeated
+  // domains=), the only way to search across all hosts (loop cycle 8).
   if (args.domain) {
-    params.append("domains", args.domain);
+    params.set("search_context", args.domain);
   } else {
     for (const d of SOCRATA_DOMAINS) params.append("domains", d);
   }
@@ -495,7 +625,9 @@ export async function discoverDatasets(args: {
   const { totalAvailable, results } = await memoize(
     key,
     async () => {
-      const body = await getCatalog(params);
+      const body = args.domain
+        ? await getHostCatalog(args.domain, params)
+        : await getCatalog(params);
       const b = (body ?? {}) as { results?: unknown; resultSetSize?: unknown };
       // m3 — hard drift on the PRIMARY response (contrast the best-effort count).
       // The check stays INSIDE the memoize callback so a bad shape is never
@@ -517,6 +649,9 @@ export async function discoverDatasets(args: {
   const scope = args.domain ? `domain ${args.domain}` : `the ${SOCRATA_DOMAINS.length}-host allowlist`;
   const notes: string[] = [
     `Catalog search over ${scope} (only=datasets). Feed a result's id to socrata_query as datasetId.`,
+    args.domain
+      ? `Source: the ${args.domain} portal's OWN catalog (search_context) — a COMPLETE per-host index.`
+      : `Source: the federated ${CATALOG_HOST} aggregator, which UNDER-INDEXES some hosts (e.g. USAC, DOT) — pass a specific domain to use that host's own complete catalog.`,
     `App token: ${appTokenPresent() ? "present (X-App-Token sent; value never logged)" : "absent (keyless)"}.`,
   ];
   if (totalAvailable !== null && returned < totalAvailable) {
@@ -528,7 +663,7 @@ export async function discoverDatasets(args: {
   return withMeta(
     { query: args.q, domain: args.domain ?? null, results },
     {
-      source: `${CATALOG_HOST} catalog ${SOURCE_SUFFIX}`,
+      source: `${args.domain ?? CATALOG_HOST} catalog ${SOURCE_SUFFIX}`,
       keylessMode: true,
       returned,
       totalAvailable,