@cliwant/mcp-sam-gov 1.8.0 → 1.10.0

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.8.0";
+const SERVER_VERSION = "1.10.0";
 
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 
@@ -572,6 +576,22 @@ const EcfrSearchInput = z.object({
 
 const EcfrListTitlesInput = z.object({});
 
+const EcfrGetSectionInput = z.object({
+  titleNumber: z
+    .number()
+    .int()
+    .min(1)
+    .max(50)
+    .describe("CFR title (1–50). e.g. 2 = federal financial assistance (grants), 29 = Labor, 26 = IRS. For FAR/DFARS (title 48) prefer far_clause_lookup."),
+  section: z
+    .string()
+    .describe("The section citation, e.g. '200.1' (2 CFR 200.1) or '52.204-21' — the part number is the pre-dot integer. Charclass-validated (^[0-9]{1,3}\\.[0-9]{1,4}(-[0-9]{1,4})?$)."),
+  date: z
+    .string()
+    .optional()
+    .describe("Optional eCFR issue date YYYY-MM-DD; omit to use the title's LATEST issue (disclosed in _meta)."),
+});
+
 // FAR / DFARS clause lookup (eCFR versioner full endpoint)
 const FarClauseLookupInput = z.object({
   clauseNumber: z
@@ -2959,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
@@ -5381,14 +5508,21 @@ export const TOOLS: ToolDef[] = [
     handler: (input) => fedreg.publicInspection(input),
   }),
 
-  // ━━━ eCFR (5) ━━━
+  // ━━━ eCFR (6) ━━━
   defineTool({
     name: "ecfr_search",
     description:
-      "Full-text search across the entire CFR (Code of Federal Regulations). Use for compliance questions — pass titleNumber=48 for FAR (Federal Acquisition Regulation), titleNumber=2 for federal financial assistance, etc. Returns excerpt + section path + ecfrUrl.",
+      "Full-text search across the entire CFR (Code of Federal Regulations). Use for DISCOVERY — pass titleNumber=48 for FAR (Federal Acquisition Regulation), titleNumber=2 for federal financial assistance, etc. Returns a ranked EXCERPT (snippet, not full text) + section path + ecfrUrl per hit. To then read the COMPLETE text of a hit: for a FAR/DFARS clause (title 48) use far_clause_lookup (adds prescription + revision); for any other title's section use ecfr_get_section; or open the ecfrUrl.",
     inputSchema: EcfrSearchInput,
     handler: (input) => ecfr.search(input),
   }),
+  defineTool({
+    name: "ecfr_get_section",
+    description:
+      "Get the FULL in-force text of ONE CFR section by citation (the companion to ecfr_search, which returns only snippets). Input titleNumber (1–50) + section (e.g. '200.1' → 2 CFR 200.1, uniform grants guidance; '1601.1' → 29 CFR labor) + optional issue date (default = the title's latest). Returns { citation, alternateReference, heading, fullText, issueDate, ecfrUrl }. ★For a FAR/DFARS clause (title 48) prefer far_clause_lookup — it adds the prescription, revision, and FAR-overhaul-risk this generic tool does not; use ecfr_get_section for the OTHER 49 titles (grants/labor/IRS/SBA/…). HONESTY: text is the eCFR's own, de-XMLed (no fabrication); a nonexistent section ⇒ not_found (never a fake/wrong section); the resolved issue date is disclosed (the title's latest is a moving target); a bad section format ⇒ invalid_input (SSRF charclass); an outage ⇒ throws. Keyless.",
+    inputSchema: EcfrGetSectionInput,
+    handler: (input) => ecfr.getSection(input),
+  }),
   defineTool({
     name: "ecfr_list_titles",
     description:
@@ -6007,6 +6141,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

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
@@ -130,7 +136,64 @@ export const SOCRATA_DOMAINS = [
   "data.pa.gov", // PA — e.g. mcba-yywm
   "data.mo.gov", // MO — e.g. gfq7-aa86
   "data.delaware.gov", // DE — e.g. 5zy2-grhr
+  // ── SLED city/county tier (loop cycle 1, 2026-07-18; host-scoped catalog +
+  //    /resource/<4x4>.json 200 bare-array live-verified; all .gov; B2G
+  //    procurement/vendor/contract data — the fragmented local layer above the
+  //    state portals). ─────────────────────────────────────────────────────
+  "data.austintexas.gov", // Austin TX (city) — e.g. 3ebq-e9iz (Purchase Orders)
+  "data.kingcounty.gov", // King County WA — e.g. dqit-zt74 (Procurement Contracts)
+  "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)
 ] as const;
 
 export type SocrataDomain = (typeof SOCRATA_DOMAINS)[number];
@@ -253,6 +316,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.";
@@ -455,16 +556,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;
@@ -476,8 +582,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);
   }
@@ -486,7 +595,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
@@ -508,6 +619,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) {
@@ -519,7 +633,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,