@cliwant/mcp-sam-gov 1.14.0 → 1.15.0

package/src/server.ts

@@ -21,7 +21,9 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
+  ListResourcesRequestSchema,
   ListToolsRequestSchema,
+  ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import {
@@ -96,6 +98,7 @@ import * as keys from "./keys.js";
 import { toToolError, ToolErrorCarrier, errorFromResponse } from "./errors.js";
 import * as feedback from "./feedback.js";
 import { checkForUpdate } from "./update-check.js";
+import { renderDataMapMarkdown } from "./data-map.js";
 import {
   buildMeta,
   isMetaBundle,
@@ -116,7 +119,7 @@ import {
 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.14.0";
+const SERVER_VERSION = "1.15.0";
 
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 
@@ -1940,7 +1943,8 @@ const EdgarCompanyConceptInput = z.object({
 const SocrataDomainEnum = z
   .enum(socrata.SOCRATA_DOMAINS)
   .describe(
-    "Which allowlisted Socrata portal to query (curated .gov hosts + USAC E-rate .org; the SSRF host allowlist — no free host). e.g. data.ny.gov, data.texas.gov, data.wa.gov, opendata.usac.org.",
+    "Which allowlisted Socrata portal to query (the SSRF host allowlist — no free host). " +
+    "Jurisdiction of non-obvious hosts: cthru.data.socrata.com=MASSACHUSETTS statewide (CTHRU); atlanta.data.socrata.com=Atlanta GA; controllerdata.lacity.org+data.lacity.org=Los Angeles; www.dallasopendata.com=Dallas TX; data.brla.gov=Baton Rouge LA; data.kcmo.org=Kansas City MO; data.cstx.gov=College Station TX; data.weho.org=West Hollywood CA; opendata.usac.org+datahub.usac.org=federal USAC E-rate. data.colorado.gov's procurement data is CITY OF DENVER, not CO state.",
   );
 
 const SocrataQueryInput = z.object({
@@ -2001,7 +2005,8 @@ const SocrataDiscoverDatasetsInput = z.object({
     .min(1)
     .describe("Keyword(s) to find datasets, e.g. 'procurement', 'vendor payments', 'checkbook'."),
   domain: SocrataDomainEnum.optional().describe(
-    "Optional: scope discovery to ONE allowlisted portal. Omit to search the whole allowlist. NOTE: the federated catalog does not index every host (e.g. USAC E-rate returns 0) — those remain queryable via socrata_query with a known 4x4.",
+    "Optional: scope discovery to ONE portal; omit to search all. The catalog does not index every host (USAC returns 0); those stay queryable via socrata_query with a known 4x4. " +
+    "Jurisdiction of non-obvious hosts: cthru.data.socrata.com=MASSACHUSETTS statewide (CTHRU); atlanta.data.socrata.com=Atlanta GA; controllerdata.lacity.org+data.lacity.org=Los Angeles; www.dallasopendata.com=Dallas TX; data.brla.gov=Baton Rouge LA; data.kcmo.org=Kansas City MO; data.cstx.gov=College Station TX; data.weho.org=West Hollywood CA; opendata.usac.org+datahub.usac.org=federal USAC E-rate. data.colorado.gov's procurement data is CITY OF DENVER, not CO state.",
   ),
   limit: z
     .number()
@@ -3106,7 +3111,7 @@ const TableauViewCsvInput = z.object({
 const ArcgisFeatureQueryInput = z.object({
   service: z
     .enum(arcgisFeature.ARCGIS_SERVICES.map((s) => s.key) as [string, ...string[]])
-    .describe("Service key (SSRF allowlist; 27 services). DC OCP PASS (solicitations/contracts/purchase_orders/payments). US local govs: Asheville NC, Bellevue WA, Miami-Dade FL×2, Suffolk County NY, Mat-Su AK, Las Vegas NV×2, Baltimore MD, Naperville IL, Worcester MA, Topeka KS (FY2015–23); TX/AK/IA/OK DOT bid/award registers. ND DOT flex-funding to local agencies (nddot_flex×4 — NOT vendor contracts)."),
+    .describe("Service key (SSRF allowlist; 29 services). DC OCP PASS (solicitations/contracts/purchase_orders/payments). US local govs: Asheville NC, Bellevue WA, Miami-Dade FL×2, Suffolk County NY, Mat-Su AK, Las Vegas NV×2, Baltimore MD, Naperville IL, Worcester MA, Topeka KS (FY2015–23), Hennepin County MN (CIP pipeline), Charlotte-Mecklenburg NC (CIP pipeline); TX/AK/IA/OK DOT bid/award registers. ND DOT flex-funding to local agencies (nddot_flex×4 — NOT vendor contracts)."),
   where: z
     .string()
     .min(1)
@@ -5838,7 +5843,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "socrata_query",
     description:
-      "Query rows from an allowlisted Socrata/SODA open-data portal (keyless; ~a dozen US state portals + USAC E-rate on one identical API — state spend/checkbook/contract/vendor-payment datasets). Input `domain` (curated allowlist enum — the SSRF host guard), `datasetId` (4x4, from socrata_discover_datasets), optional SoQL `select`/`where`/`order`/`q`, `limit` (≤1000, def 100), `offset`, `withTotal` (def true). HONESTY: SODA's row response has no total, so a count(*) companion supplies an exact totalAvailable; if it fails the rows still return with totalAvailable:null + a note (hasMore is then inferred from page-fill, never a false complete). Genuine-empty ⇒ complete:true/total:0; an outage/400/404 THROWS (never a fake empty). Value fields are strings.",
+      "Query rows from an allowlisted Socrata/SODA open-data portal (keyless; ~a dozen US state portals + USAC E-rate on one identical API — state spend/checkbook/contract/vendor-payment datasets). State procurement mirrors: NY ehig-g5x3, NJ ubnu-tqu7, WA s8d5-pj78, MA cthru.data.socrata.com pegc-naaa (~49M payment rows). Full map: read resource samgov://data-map/state-local. Input `domain` (curated allowlist enum — the SSRF host guard), `datasetId` (4x4, from socrata_discover_datasets), optional SoQL `select`/`where`/`order`/`q`, `limit` (≤1000, def 100), `offset`, `withTotal` (def true). HONESTY: SODA's row response has no total, so a count(*) companion supplies an exact totalAvailable; if it fails the rows still return with totalAvailable:null + a note (hasMore is then inferred from page-fill, never a false complete). Genuine-empty ⇒ complete:true/total:0; an outage/400/404 THROWS (never a fake empty). Value fields are strings.",
     inputSchema: SocrataQueryInput,
     handler: (input) => socrata.query(input),
   }),
@@ -5853,7 +5858,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "ckan_query",
     description:
-      "Query rows from an allowlisted CKAN datastore resource (keyless; the FIRST source on the R2 DataSource port — state/city spend/checkbook/procurement/vendor tables on the identical CKAN Action API). Input `host` (curated allowlist enum — the SSRF host guard: data.ca.gov, data.virginia.gov, data.boston.gov), `resourceId` (36-char lowercase UUID, from ckan_discover_datasets), optional `q` (full-text), `filters` (constrained object {field:value} we JSON.stringify), `sort`, `limit` (≤1000, def 100), `offset`. HONESTY: CKAN's envelope carries a real result.total — the DEFAULT is an EXACT total (exact totalAvailable + hasMore); the rare estimated total (total_was_estimated:true) is disclosed via totalIsEstimated + a note and does NOT drive pagination (it can be above OR below the truth). Genuine-empty ⇒ complete:true/total:0; an outage/404/409 or success:false THROWS (never a fake empty). Values are typed per result.fields[].type.",
+      "Query rows from an allowlisted CKAN datastore resource (keyless; state/city spend/checkbook/procurement/vendor tables on the CKAN Action API). VA eVA PO lines: host=data.virginia.gov resourceId=3c7f1bde-35b0-4fbf-b89c-978a19124d53. Full map: read resource samgov://data-map/state-local. Input `host` (curated allowlist enum — the SSRF host guard: data.ca.gov, data.virginia.gov, data.boston.gov), `resourceId` (36-char lowercase UUID, from ckan_discover_datasets), optional `q` (full-text), `filters` (constrained object {field:value} we JSON.stringify), `sort`, `limit` (≤1000, def 100), `offset`. HONESTY: CKAN's envelope carries a real result.total — the DEFAULT is an EXACT total (exact totalAvailable + hasMore); the rare estimated total (total_was_estimated:true) is disclosed via totalIsEstimated + a note and does NOT drive pagination (it can be above OR below the truth). Genuine-empty ⇒ complete:true/total:0; an outage/404/409 or success:false THROWS (never a fake empty). Values are typed per result.fields[].type.",
     inputSchema: CkanQueryInput,
     handler: (input) => ckan.query(input),
   }),
@@ -6210,13 +6215,13 @@ export const TOOLS: ToolDef[] = [
   }),
   // ━━━ 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 186-org live-verified seed directory
+  // RSS of open opportunities. Ships a curated 195-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 186 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.",
+      "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 195 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),
   }),
@@ -6662,7 +6667,7 @@ async function main() {
   // B2: unknown toolset names are reported here (not only stderr) because
   // stderr is invisible in Claude Desktop.
   const BASE_INSTRUCTIONS =
-    "This server wraps US government open data (keyless-first). If a tool result looks wrong, a tool stays broken, or the user wants a capability this server lacks, help improve it: call the `feedback` tool — or use the `report` URL present on schema_drift / upstream_unavailable errors — to get a PREFILLED GitHub issue link, and offer it to the user to open and submit. Nothing is posted automatically; the user submits. Never include secrets or personal data in a report (the repo is public).";
+    "This server wraps US government open data (keyless-first). State/local dataset IDs (Socrata, CKAN, etc.) are listed in the MCP resource samgov://data-map/state-local. If a tool result looks wrong, a tool stays broken, or the user wants a capability this server lacks, help improve it: call the `feedback` tool — or use the `report` URL present on schema_drift / upstream_unavailable errors — to get a PREFILLED GitHub issue link, and offer it to the user to open and submit. Nothing is posted automatically; the user submits. Never include secrets or personal data in a report (the repo is public).";
 
   let serverInstructions: string;
   if (isAllTools && tsResult.unknown.length === 0) {
@@ -6694,7 +6699,7 @@ async function main() {
   const server = new Server(
     { name: SERVER_NAME, version: SERVER_VERSION },
     {
-      capabilities: { tools: {} },
+      capabilities: { tools: {}, resources: {} },
       // Surfaced to the agent at initialize. Tells it how to route real-usage
       // friction back to the project WITHOUT the server ever posting anything.
       instructions: serverInstructions,
@@ -6712,6 +6717,42 @@ async function main() {
     };
   });
 
+  // ── MCP Resources: state & local data map ──────────────────────────────
+  const DATA_MAP_URI = "samgov://data-map/state-local";
+  const DATA_MAP_NAME = "State & local data map";
+  const DATA_MAP_DESCRIPTION =
+    "Jurisdiction → verified tool call → row count for every allowlisted state/local Socrata, CKAN, Tableau and Open Checkbook dataset.";
+
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+      resources: [
+        {
+          uri: DATA_MAP_URI,
+          name: DATA_MAP_NAME,
+          description: DATA_MAP_DESCRIPTION,
+          mimeType: "text/markdown",
+        },
+      ],
+    };
+  });
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+    const { uri } = req.params;
+    if (uri !== DATA_MAP_URI) {
+      throw new Error(`Unknown resource: ${uri}`);
+    }
+    return {
+      contents: [
+        {
+          uri: DATA_MAP_URI,
+          mimeType: "text/markdown",
+          text: renderDataMapMarkdown(),
+        },
+      ],
+    };
+  });
+  // ── end MCP Resources ──────────────────────────────────────────────────
+
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const { name, arguments: args } = req.params;
     // Check if the tool exists but is not loaded in the current toolset profile.

package/src/socrata.ts

@@ -179,7 +179,8 @@ export const SOCRATA_DOMAINS = [
   //    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)
+  "data.sfgov.org", // San Francisco / DataSF — PERMANENTLY MIGRATED to data.sf.gov (301 all paths, 2026-09); kept allowlisted so requests reach the migration handler (see MIGRATED_SOCRATA_HOSTS below) instead of returning invalid_input. Use data.sf.gov for all new calls.
+  "data.sf.gov", // San Francisco / DataSF (canonical post-migration .gov domain) — e.g. cqi5-hm2d (Supplier Contracts 49,186 rows), hmh3-ff63 (Airport/SFO Contract Opportunities)
   "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
@@ -230,6 +231,24 @@ export type SocrataDomain = (typeof SOCRATA_DOMAINS)[number];
 
 const SOCRATA_DOMAIN_SET: ReadonlySet<string> = new Set(SOCRATA_DOMAINS);
 
+/**
+ * Known host migrations (permanent 301 redirects). A domain here has permanently
+ * moved; redirect:"error" means any fetch to the old host will fail immediately.
+ * Rather than returning a retryable upstream_unavailable (which implies the
+ * problem may resolve on its own), we pre-flight check this map and return
+ * invalid_input — non-retryable, naming the replacement — so the caller can
+ * update the `domain` parameter instead of spinning on a doomed retry loop.
+ *
+ * Keep the old host in SOCRATA_DOMAINS so it passes the allowlist gate (invalid
+ * domains are rejected before reaching this check). Only add an entry here when
+ * the migration is confirmed by a live 301 probe with a stable redirect_url.
+ *
+ *   data.sfgov.org → data.sf.gov   (confirmed 2026-09-21; all paths 301)
+ */
+const MIGRATED_SOCRATA_HOSTS: ReadonlyMap<string, string> = new Map([
+  ["data.sfgov.org", "data.sf.gov"],
+]);
+
 const CATALOG_HOST = "api.us.socrata.com";
 const CATALOG_URL = `https://${CATALOG_HOST}/api/catalog/v1`;
 
@@ -297,6 +316,18 @@ async function getSocrataResource(
       retryable: false,
     });
   }
+  // Migration pre-flight (MIGRATED_SOCRATA_HOSTS): if the domain has permanently
+  // moved, redirect:"error" means any fetch will immediately fail with a 301.
+  // Return invalid_input (non-retryable) now — before wasting a network round-trip
+  // — naming the replacement so the caller can update the domain parameter.
+  const migratedTo = MIGRATED_SOCRATA_HOSTS.get(domain);
+  if (migratedTo !== undefined) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Socrata host ${JSON.stringify(domain)} has permanently moved to ${JSON.stringify(migratedTo)}. Update the \`domain\` parameter to ${JSON.stringify(migratedTo)} — retrying ${JSON.stringify(domain)} will not succeed.`,
+      retryable: false,
+    });
+  }
   if (datasetId.length !== 9 || !DATASET_ID_RE.test(datasetId)) {
     throw new ToolErrorCarrier({
       kind: "invalid_input",
@@ -375,6 +406,15 @@ async function getHostCatalog(
       retryable: false,
     });
   }
+  // Migration pre-flight — same policy as getSocrataResource (see comment there).
+  const migratedTo = MIGRATED_SOCRATA_HOSTS.get(domain);
+  if (migratedTo !== undefined) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Socrata host ${JSON.stringify(domain)} has permanently moved to ${JSON.stringify(migratedTo)}. Update the \`domain\` parameter to ${JSON.stringify(migratedTo)} — retrying ${JSON.stringify(domain)} will not succeed.`,
+      retryable: false,
+    });
+  }
   const url = `https://${domain}/api/catalog/v1?${params.toString()}`;
   const built = new URL(url);
   if (built.hostname !== domain || built.protocol !== "https:") {
@@ -419,6 +459,12 @@ async function fetchCount(
   const params = new URLSearchParams();
   if (where) params.set("$where", where);
   if (q) params.set("$q", q);
+  // ★ MUST stay count(*) — DO NOT change to count(1) or SELECT count(1).
+  // Cloudflare-fronted Socrata hosts (e.g. opendata.maryland.gov) deterministically
+  // 403 ("Just a moment...") on count(1) and `$query=SELECT count(1)` — their WAF
+  // treats the pattern as SQLi-like — while count(*) consistently returns 200.
+  // Verified 3/3 on opendata.maryland.gov (2026-09-21): count(1)→403, count(*)→200
+  // (342 rows). Maryland is not broken; the shape here is load-bearing.
   params.set("$select", "count(*)");
   let body: unknown;
   try {