@cliwant/mcp-sam-gov 1.11.0 → 1.12.0

package/src/server.ts

@@ -106,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.11.0";
+const SERVER_VERSION = "1.12.0";
 
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 
@@ -3759,7 +3759,7 @@ const CensusBusinessPatternsInput = z.object({
     .regex(/^\d{4}$/)
     .optional()
     .describe(
-      "The CBP data year (default '2022', the latest confirmed vintage). Validated ^\\d{4}$ (it rides in the request path).",
+      "The CBP data year (default '2023', the latest published vintage — CBP is released with a ~2-year lag). Validated ^\\d{4}$ (it rides in the request path).",
     ),
   limit: z
     .number()
@@ -6284,7 +6284,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "census_business_patterns",
     description:
-      "Market sizing by NAICS × geography — establishments, employment, and annual payroll from the US Census County Business Patterns (CBP) API (api.census.gov/data/{year}/cbp). ★REQUIRES a free CENSUS_API_KEY: the Census Data API has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://api.census.gov/data/key_signup.html; call api_key_status to see every source's key requirement). Input: optional `naics` (2–6 digit NAICS-2017, e.g. '5415'; omit to aggregate all sectors), `geography` (us|state|county, default us; county REQUIRES `state`), `state` (2-digit FIPS, e.g. '06'), `year` (default '2022'), optional `limit` (client-side top-N; CBP has no server pagination). Returns { rows:[{ name, geoId, naicsCode, naicsLabel, establishments, employees, annualPayrollUsd, state }] } + honest _meta. HONESTY: establishments/employees are integer counts and annualPayrollUsd is annual US dollars (×1000 from the source's $1,000-unit PAYANN); large-negative suppression sentinels map to null — NEVER a negative number and NEVER 0 (a genuine 0 stays 0; note CBP primarily uses noise-infusion + suppression flags, surfaced as reported — see the tool's suppression note); geoId/naicsCode/state are STRINGS (leading zeros survive). CBP returns the COMPLETE geography set for the filter (no pagination) ⇒ totalAvailable = the row count, complete:true. A missing/invalid key ⇒ invalid_input (a 302 to the Missing-Key page); a header-only body ⇒ honest empty (returned:0); a 5xx ⇒ THROWS; a 200 non-JSON ⇒ schema_drift. The key rides ONLY in the &key= query param — never logged or echoed.",
+      "Market sizing by NAICS × geography — establishments, employment, and annual payroll from the US Census County Business Patterns (CBP) API (api.census.gov/data/{year}/cbp). ★REQUIRES a free CENSUS_API_KEY: the Census Data API has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://api.census.gov/data/key_signup.html; call api_key_status to see every source's key requirement). Input: optional `naics` (2–6 digit NAICS-2017, e.g. '5415'; omit to aggregate all sectors), `geography` (us|state|county, default us; county REQUIRES `state`), `state` (2-digit FIPS, e.g. '06'), `year` (default '2023'), optional `limit` (client-side top-N; CBP has no server pagination). Returns { rows:[{ name, geoId, naicsCode, naicsLabel, establishments, employees, annualPayrollUsd, state }] } + honest _meta. HONESTY: establishments/employees are integer counts and annualPayrollUsd is annual US dollars (×1000 from the source's $1,000-unit PAYANN); large-negative suppression sentinels map to null — NEVER a negative number and NEVER 0 (a genuine 0 stays 0; note CBP primarily uses noise-infusion + suppression flags, surfaced as reported — see the tool's suppression note); geoId/naicsCode/state are STRINGS (leading zeros survive). CBP returns the COMPLETE geography set for the filter (no pagination) ⇒ totalAvailable = the row count, complete:true. A missing/invalid key ⇒ invalid_input (a 302 to the Missing-Key page); a header-only body ⇒ honest empty (returned:0); a 5xx ⇒ THROWS; a 200 non-JSON ⇒ schema_drift. The key rides ONLY in the &key= query param — never logged or echoed.",
     inputSchema: CensusBusinessPatternsInput,
     handler: (input) => censusEconomic.businessPatterns(input),
   }),
@@ -6633,6 +6633,7 @@ async function main() {
         name: t.name,
         description: t.description,
         inputSchema: zodToJsonSchema(t.inputSchema),
+        annotations: toolAnnotations(t.name),
       })),
     };
   });
@@ -6808,6 +6809,53 @@ export async function runTool(
   throw new Error(`Unknown tool: ${name}`);
 }
 
+// ─── MCP tool annotations ────────────────────────────────────────────────────
+// Every tool advertises a human-friendly `title` plus behaviour hints, per the MCP
+// spec and the Anthropic Connectors Directory requirement (title + readOnlyHint).
+// EVERY tool in this server is strictly READ-ONLY (queries public data; none mutate
+// upstream state) and OPEN-WORLD (calls external government/public APIs), so those
+// two hints are uniform. `title` is derived from the tool name via a source-prefix
+// map so e.g. `sam_search_opportunities` → "SAM.gov: Search Opportunities".
+const TOOL_SOURCE_LABELS: Record<string, string> = {
+  sam: "SAM.gov", usas: "USAspending", edgar: "SEC EDGAR", fdic: "FDIC", cms: "CMS",
+  treasury: "Treasury", regulations: "Regulations.gov", openfda: "openFDA",
+  govinfo: "GovInfo", fema: "FEMA", far: "FAR/DFARS", ecfr: "eCFR", census: "Census",
+  clinicaltrials: "ClinicalTrials.gov", bls: "BLS", socrata: "Socrata", opengov: "OpenGov",
+  nsf: "NSF", nonprofit: "Nonprofit", nhtsa: "NHTSA", gsa: "GSA", grants: "Grants.gov",
+  fred: "FRED", fac: "FAC", echo: "EPA ECHO", dol: "DOL", congress: "Congress.gov",
+  ckan: "data.gov", bonfire: "Bonfire", arcgis: "ArcGIS", sba: "SBA", ofac: "OFAC",
+  nws: "NWS", nppes: "NPPES", nist: "NIST", nih: "NIH", lda: "Senate LDA", hts: "USITC HTS",
+  bea: "BEA", cbp: "CBP", cpsc: "CPSC", nvd: "NVD", courtlistener: "CourtListener",
+  fpds: "FPDS", gao: "GAO", epa: "EPA", nsn: "NSN",
+};
+const TOOL_ACRONYMS = new Set([
+  "naics", "psc", "cfda", "npi", "cve", "csv", "id", "url", "rss", "api", "hts", "sic",
+  "dmepos", "cbp", "sam", "fdic", "epa", "ofac", "far", "dfars", "irs", "usc", "cfr",
+]);
+export function humanizeToolTitle(name: string): string {
+  const tokens = name.split("_");
+  // `fed_register_*` is a two-token source label.
+  let source = tokens[0] ?? "";
+  let rest = tokens.slice(1);
+  if (source === "fed" && tokens[1] === "register") {
+    source = "fed_register";
+    rest = tokens.slice(2);
+  }
+  const label = source === "fed_register" ? "Federal Register" : TOOL_SOURCE_LABELS[source];
+  const words = (label ? rest : tokens)
+    .map((w) => (TOOL_ACRONYMS.has(w) ? w.toUpperCase() : w.charAt(0).toUpperCase() + w.slice(1)))
+    .join(" ");
+  return label ? (words ? `${label}: ${words}` : label) : words;
+}
+/** Uniform MCP annotations for a tool: derived title + read-only / open-world hints. */
+export function toolAnnotations(name: string): {
+  title: string;
+  readOnlyHint: true;
+  openWorldHint: true;
+} {
+  return { title: humanizeToolTitle(name), readOnlyHint: true, openWorldHint: true };
+}
+
 /**
  * Hand-rolled Zod → JSON Schema converter (subset we use).
  */

package/src/socrata.ts

@@ -238,14 +238,21 @@ const CATALOG_URL = `https://${CATALOG_HOST}/api/catalog/v1`;
 // regex `$` alone would admit ("abcd-1234\n" passes /…$/ in JS).
 const DATASET_ID_RE = /^[a-z0-9]{4}-[a-z0-9]{4}$/;
 
-// D2 — an AGGREGATE $select projection. Matches a SoQL aggregate function
-// (count/sum/avg/min/max) applied via `fn(` — the `\b…\s*\(` shape avoids false
-// hits on column names like `max_temperature` (no paren) or `xmax(` (no word
-// boundary) — OR an explicit `group by`/`$group`. Case-insensitive. When the
-// caller's own $select is aggregate, the count(*) companion is skipped (its
-// raw-row total would be false for aggregate result rows). See `query`.
+// D2 — a cardinality-CHANGING $select projection: ANY function call (`word(` —
+// count/sum/avg/min/max/median/stddev/count_distinct/percentile/…), the bare
+// `distinct` keyword, or an explicit `group by`/`$group`. Case-insensitive. The
+// `\b\w+\s*\(` shape matches a real function CALL (a word followed by a paren),
+// never a plain column name like `max_temperature` (no paren). When the caller's
+// own $select is one of these, the result rows are NOT raw records, so the
+// count(*) companion (which counts SOURCE rows) would be a FALSE total — e.g.
+// `$select=distinct state` returns 54 rows but count(*) is 137,700 → a wrong total
+// AND a hasMore livelock (paging forever over empty pages). So we skip the
+// companion (totalAvailable:null + page-fullness hasMore). A plain comma-separated
+// column list is NOT matched and keeps its real count(*) total. (A per-row
+// function like `upper(x)` also matches → a conservative null-total, an honest
+// "unknown" rather than risking a wrong one.) See `query`.
 const AGGREGATE_SELECT_RE =
-  /\b(?:count|sum|avg|min|max)\s*\(|\bgroup\s+by\b|\$group\b/i;
+  /\b\w+\s*\(|\bdistinct\b|\bgroup\s+by\b|\$group\b/i;
 
 // ─── HONESTY-CRITICAL coercions (null, never 0, for absent) ───────
 // `num`/`str` are the shared, audited null-never-0 coercions in ./coerce.js

package/src/usaspending.ts

@@ -1468,7 +1468,7 @@ export async function searchRecompetes(args: {
     awardId: string;
     generatedInternalId: string;
     incumbent: string;
-    amount: number;
+    amount: number | null;
     currentEndDate: string;
     daysUntilCurrentEnd: number;
     potentialEndDate?: string | null;
@@ -1515,8 +1515,11 @@ export async function searchRecompetes(args: {
         pastWindow = true;
         break;
       }
-      const amount = row["Award Amount"] ?? 0;
-      if (amount < minAwardValue) continue;
+      // Filter/sort on a numeric view (absent = 0 for COMPARISON only), but EMIT the
+      // raw value below so an ABSENT amount stays null — P3 null-never-0, matching every
+      // sibling search tool ("an ABSENT Award Amount → null, NEVER a fabricated $0").
+      const amountNum = row["Award Amount"] ?? 0;
+      if (amountNum < minAwardValue) continue;
       const potentialEnd = includePotentialEnd
         ? row["Period of Performance Potential End Date"] ?? null
         : undefined;
@@ -1529,7 +1532,7 @@ export async function searchRecompetes(args: {
         awardId: row["Award ID"] ?? "",
         generatedInternalId: row.generated_internal_id ?? "",
         incumbent: row["Recipient Name"] ?? "",
-        amount,
+        amount: row["Award Amount"] ?? null,
         currentEndDate: end as string,
         daysUntilCurrentEnd: d,
         ...(includePotentialEnd
@@ -1557,7 +1560,10 @@ export async function searchRecompetes(args: {
   results.sort((a, b) => {
     if (a.daysUntilCurrentEnd !== b.daysUntilCurrentEnd)
       return a.daysUntilCurrentEnd - b.daysUntilCurrentEnd;
-    if (b.amount !== a.amount) return b.amount - a.amount;
+    // A null amount (P3 — absent, not $0) sorts as 0 for this tiebreak ONLY; it is
+    // never surfaced as 0 in the output.
+    const av = a.amount ?? 0, bv = b.amount ?? 0;
+    if (bv !== av) return bv - av;
     return a.awardId.localeCompare(b.awardId);
   });
 
@@ -1570,10 +1576,15 @@ export async function searchRecompetes(args: {
   // (early-stop fired). If the scan budget truncated, it is unknown → null,
   // and the returned set is a lower bound.
   const totalAvailable = scanTruncated ? null : totalInWindow;
-  const nextOffset = startIdx + pageSize;
-  const hasMore = scanTruncated
-    ? true // more may exist beyond the scanned pages
-    : nextOffset < totalInWindow;
+  // `nextOffset` may ONLY advance into rows we ACTUALLY scanned. The un-scanned
+  // remainder (scanTruncated) is NOT offset-reachable: paging past totalInWindow
+  // re-runs the whole bounded scan and returns EMPTY pages forever — the
+  // "re-fetch the SAME page" livelock every other tool in this module emits
+  // nextOffset:null to avoid. So advance the cursor only while more SCANNED rows
+  // remain; signal the un-scanned tail via hasMore:true + nextOffset:null (the
+  // notes already tell the caller to raise scanBudgetPages, not to paginate).
+  const moreInScanned = startIdx + pageSize < totalInWindow;
+  const hasMore = moreInScanned || scanTruncated;
   const truncated = hasMore || scanTruncated;
 
   const notes: string[] = [
@@ -1612,7 +1623,7 @@ export async function searchRecompetes(args: {
     pagination: {
       offset: startIdx,
       limit: pageSize,
-      nextOffset: hasMore ? nextOffset : null,
+      nextOffset: moreInScanned ? startIdx + pageSize : null,
       hasMore,
     },
     filtersApplied,