@cliwant/mcp-sam-gov 1.8.0 → 1.10.0

package/dist/server.js

@@ -38,6 +38,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";
@@ -86,7 +90,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) ────────────────────────────────────
 const SamSearchInput = z.object({
     query: z.string().optional().describe("Free-text title query"),
@@ -456,6 +460,21 @@ const EcfrSearchInput = z.object({
     perPage: z.number().min(1).max(20).optional(),
 });
 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
@@ -2493,6 +2512,107 @@ const DatagovSearchDatasetsInput = z.object({
         .optional()
         .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))
+        .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
@@ -4507,13 +4627,19 @@ export const TOOLS = [
         inputSchema: FedRegPublicInspectionInput,
         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.",
+        description: "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: "List all 50 CFR titles with name + last_amended_on date. Use to discover what's in each title (Title 48 = FAR, Title 32 = National Defense, Title 14 = Aeronautics, etc.).",
@@ -5057,6 +5183,66 @@ export const TOOLS = [
         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