@cliwant/mcp-sam-gov 1.2.0 → 1.3.0

package/src/server.ts

@@ -56,7 +56,10 @@ import * as clinicaltrials from "./clinicaltrials.js";
 import * as census from "./census.js";
 import * as censusEconomic from "./census-economic.js";
 import * as fred from "./fred.js";
+import * as bea from "./bea.js";
 import * as gsaPerdiem from "./gsa-perdiem.js";
+import * as dol from "./dol.js";
+import * as lda from "./lda.js";
 import * as fema from "./fema.js";
 import * as fdic from "./fdic.js";
 import * as bls from "./bls.js";
@@ -81,7 +84,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.2.0";
+const SERVER_VERSION = "1.3.0";
 
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 
@@ -3486,6 +3489,45 @@ const FredSeriesObservationsInput = z.object({
     .describe("Observation date order: 'asc' (oldest first, FRED default) or 'desc' (newest first)."),
 });
 
+// ─── BEA Regional Economic Accounts (apps.bea.gov) — the THIRD key-required source ──
+// ADR-0051. County/state/MSA GDP-by-industry (CAGDP2/SAGDP2N) + personal income
+// (CAINC1/SAINC1) — the regional/sub-national place-of-performance lane. REQUIRES a
+// free BEA_API_KEY; without it the tool throws an honest config error (the other 116
+// tools stay keyless). ★A missing/invalid key returns HTTP 200 with a
+// BEAAPI.Results.Error carrier (NOT an HTTP error), detected pre-drift. The key rides
+// UserID= ONLY. DataValue is a comma string; suppression codes ((NA)/(D)/…) → null.
+const BeaRegionalDataInput = z.object({
+  tableName: z
+    .string()
+    .regex(/^[A-Za-z0-9]{2,20}$/)
+    .describe(
+      "A BEA Regional table code (2–20 alphanumerics), e.g. 'CAGDP2' (county GDP by industry), 'SAGDP2N' (state GDP by industry), 'CAINC1'/'SAINC1' (personal income). Validated ^[A-Za-z0-9]{2,20}$. Required.",
+    ),
+  geoFips: z
+    .string()
+    .regex(/^[A-Za-z0-9]{2,10}$/)
+    .describe(
+      "The BEA GeoFips selector: 'STATE' (all states), a county FIPS like '06075', or an MSA code. Validated ^[A-Za-z0-9]{2,10}$. Required.",
+    ),
+  lineCode: z
+    .string()
+    .regex(/^([0-9]{1,4}|ALL)$/)
+    .describe(
+      "The industry/statistic line code — an integer (1–4 digits), e.g. '1', or 'ALL' for every line in the table. Validated ^([0-9]{1,4}|ALL)$. Required.",
+    ),
+  year: z
+    .string()
+    .regex(/^(\d{4}|LAST5|ALL)$/)
+    .optional()
+    .describe(
+      "The data year: a 4-digit year (e.g. '2022'), 'LAST5' (the latest 5 years, default), or 'ALL'. Validated ^(\\d{4}|LAST5|ALL)$.",
+    ),
+  frequency: z
+    .enum(["A", "Q"])
+    .optional()
+    .describe("Data frequency: 'A' (annual, default) or 'Q' (quarterly)."),
+});
+
 // ─── GSA Federal Travel Per-Diem (api.gsa.gov) — travel-cost lane ──
 // ADR-0050. Lodging + M&IE reimbursement ceilings by city/state OR zip for a year.
 // KEYLESS by default via the shared DEMO_KEY (datagovKey.ts seam); DATA_GOV_API_KEY
@@ -3525,6 +3567,145 @@ const GsaPerdiemRatesInput = z
     "Look up GSA per-diem rates by EITHER (city + state) OR zip. Supplying both, or neither, ⇒ invalid_input.",
   );
 
+// ─── US DOL Data API v4 (apiprod.dol.gov) — the labor-enforcement lane ──
+// ADR-0053. A DELIBERATE key split: dol_list_datasets (the CATALOG) is KEYLESS;
+// dol_get_dataset (the DATA endpoint) is the 4th REQUIRED key (DOL_API_KEY, no keyless
+// tier — throws pre-fetch without it). The key rides the X-API-KEY HEADER ONLY. The
+// data envelope is key-gated/unverified ⇒ records are surfaced verbatim + totalAvailable
+// defaults null (never `returned` faked as the total). agency/query filter is CLIENT-SIDE.
+const DolListDatasetsInput = z.object({
+  agency: z
+    .string()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe(
+      "CLIENT-SIDE filter by agency abbreviation (e.g. 'WHD', 'OSHA', 'ILAB', 'ETA') or a substring of the agency name. The DOL catalog API does not filter server-side, so this is applied to the fetched catalog.",
+    ),
+  query: z
+    .string()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe(
+      "CLIENT-SIDE free-text filter (substring over dataset name / description / category / table / endpoint), e.g. 'child labor', 'wage', 'inspection'.",
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe("Datasets to return per page (default 25, max 200). Offset-paginated over the (filtered) catalog."),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+});
+
+const DolGetDatasetInput = z.object({
+  agency: z
+    .string()
+    .regex(/^[A-Za-z0-9_]+$/)
+    .describe(
+      "The agency abbreviation (the `agencyAbbr` from dol_list_datasets), e.g. 'WHD', 'OSHA', 'ILAB'. Rides in the request PATH. Validated ^[A-Za-z0-9_]+$. Required.",
+    ),
+  table: z
+    .string()
+    .regex(/^[A-Za-z0-9_]+$/)
+    .describe(
+      "The dataset endpoint — the `apiUrl` field from dol_list_datasets (the DOL 'api_url', NOT the tablename), e.g. 'Child_Labor_Report__2016_to_2022'. Rides in the request PATH. Validated ^[A-Za-z0-9_]+$. Required.",
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("Max records to return (default 10, max 100). Offset-paginated."),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+  filterField: z
+    .string()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("Optional: a dataset field name to filter on (paired with filterValue → a DOL filter_object equality filter). Supply BOTH or NEITHER."),
+  filterValue: z
+    .string()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe("Optional: the value the filterField must equal. Supply BOTH filterField and filterValue, or NEITHER."),
+  fields: z
+    .array(z.string().min(1))
+    .optional()
+    .describe("Optional: best-effort column selection (a subset of field names to return). Not documented for v4; the API ignores or 400s an unsupported selection (surfaced honestly)."),
+});
+
+// ─── US Senate LDA lobbying filings (lda.senate.gov) — the lobbying/B2G lane ──
+// ADR-0052. Who is paid HOW MUCH to lobby WHICH federal agency on WHICH issue.
+// KEYLESS (anonymous 200); an optional free LDA_API_KEY only raises the rate limit
+// and rides the Authorization: Token … header ONLY. `count` is the REAL total
+// (~1.95M) — never results.length; page-based pagination (page/pageSize ≤25). All
+// filter VALUES ride URLSearchParams; filingYear/page/pageSize charclass/range-guarded.
+const LdaSearchFilingsInput = z.object({
+  registrantName: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Filter by the registrant (the lobbying firm / in-house filer) name, e.g. 'Akin Gump'. Substring match, upstream-validated."),
+  clientName: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Filter by the client name (who the lobbying is FOR), e.g. 'Google'. Substring match, upstream-validated."),
+  lobbyistName: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Filter by an individual lobbyist's name. Substring match, upstream-validated."),
+  filingYear: z
+    .string()
+    .regex(/^\d{4}$/)
+    .optional()
+    .describe("Filter by filing year, a 4-digit year (e.g. '2024'). Validated ^\\d{4}$."),
+  filingType: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Filter by the filing type short code (e.g. 'Q1' Q1 report, 'RR' registration, 'YE' year-end). A bad code ⇒ upstream HTTP 400 ⇒ invalid_input (surfaced)."),
+  agency: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Filter by the federal government entity lobbied (maps to government_entity — the B2G signal), e.g. 'DEPARTMENT OF DEFENSE'."),
+  issue: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Filter by the specific lobbying issues text (maps to filing_specific_lobbying_issues), e.g. 'appropriations'."),
+  page: z
+    .number()
+    .int()
+    .min(1)
+    .default(1)
+    .describe("1-based page number (default 1). Page with the next page number from _meta.notes / when _meta.pagination.hasMore."),
+  pageSize: z
+    .number()
+    .int()
+    .min(1)
+    .max(25)
+    .default(25)
+    .describe("Filings per page, 1..25 (the LDA API caps at 25), default 25."),
+});
+
 // api_key_status takes no input — it is a pure status query over process.env.
 const ApiKeyStatusInput = z.object({});
 
@@ -5023,6 +5204,21 @@ export const TOOLS: ToolDef[] = [
     inputSchema: FredSeriesObservationsInput,
     handler: (input) => fred.seriesObservations(input),
   }),
+  // ━━━ BEA Regional Economic Accounts (apps.bea.gov) — regional GDP/income (1) ━━━ ADR-0051
+  // ★The server's THIRD KEY-REQUIRED source: the BEA Data API has NO keyless tier, so
+  // WITHOUT a BEA_API_KEY this tool throws an honest invalid_input config error (the
+  // other 116 tools stay keyless). County/state/MSA GDP-by-industry + personal income —
+  // the regional place-of-performance lane. ★The P2 crux: a missing/invalid key returns
+  // HTTP 200 carrying BEAAPI.Results.Error (NOT an HTTP error status), which is detected
+  // BEFORE the Data-array drift check and surfaced as invalid_input (never a fake empty).
+  // DataValue is a comma-formatted string; suppression codes ((NA)/(D)/(NM)/(L)/*) → null.
+  defineTool({
+    name: "bea_regional_data",
+    description:
+      "Regional (county / state / MSA) economic data — GDP by industry and personal income — from the US Bureau of Economic Analysis (BEA) Regional Economic Accounts (apps.bea.gov/api/data, dataset 'Regional'). ★REQUIRES a free BEA_API_KEY: the BEA Data API has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://apps.bea.gov/API/signup/; Census, FRED, and BEA are the only key-required sources — every other tool is keyless). Input: `tableName` (required, e.g. 'CAGDP2' county GDP by industry, 'SAGDP2N' state GDP, 'CAINC1'/'SAINC1' personal income), `geoFips` (required — 'STATE' for all states, a county FIPS like '06075', or an MSA code), `lineCode` (required — an integer industry line like '1', or 'ALL'), optional `year` ('LAST5' default, a 4-digit year, or 'ALL'), `frequency` ('A' annual default, or 'Q'). Returns { rows:[{ geoFips, geoName, timePeriod, lineCode, dataValue, unitOfMeasure, unitMult, noteRef }], notes:[{ noteRef, noteText }] } + honest _meta. ★HONESTY (the crux): a missing/invalid key — or ANY bad parameter — returns HTTP 200 carrying an Error object (NOT an HTTP error status); this is detected and surfaced as invalid_input carrying BEA's APIErrorDescription — NEVER a fake empty. dataValue is parsed from BEA's comma-formatted string ('1,234,567'→1234567); BEA suppression/not-available codes ((NA)/(D)/(NM)/(L)/*) map to null — NEVER 0 (a genuine 0 stays 0). unitMult (a power-of-10 multiplier) and unitOfMeasure are reported ALONGSIDE the raw dataValue — the value is NOT multiplied in (apply unitMult yourself). BEA returns the COMPLETE set for the filter (no pagination) ⇒ totalAvailable = the row count, complete:true; a genuine empty Data:[] ⇒ honest empty (returned:0); a 5xx ⇒ THROWS; a 200 non-JSON ⇒ schema_drift. The key rides ONLY in the UserID= query param — never logged or echoed.",
+    inputSchema: BeaRegionalDataInput,
+    handler: (input) => bea.regionalData(input),
+  }),
   // ━━━ GSA Federal Travel Per-Diem (api.gsa.gov) — travel-cost lane (1) ━━━ ADR-0050
   // The lodging + M&IE reimbursement ceilings the federal government pays for official
   // travel, by city/state OR zip for a year. SAME host (api.gsa.gov) + SAME api.data.gov
@@ -5037,15 +5233,50 @@ export const TOOLS: ToolDef[] = [
     inputSchema: GsaPerdiemRatesInput,
     handler: (input) => gsaPerdiem.perdiemRates(input),
   }),
+  // ━━━ US DOL Data API v4 (apiprod.dol.gov) — the labor-enforcement lane (2) ━━━ ADR-0053
+  // A DELIBERATE key split: dol_list_datasets (the dataset CATALOG) is KEYLESS;
+  // dol_get_dataset (the DATA endpoint) is the server's 4th REQUIRED key (DOL_API_KEY —
+  // the data endpoint has NO keyless tier, so without the key it THROWS pre-fetch). The
+  // key rides the X-API-KEY HEADER ONLY. The data-record envelope is key-gated/unverified
+  // ⇒ records are surfaced VERBATIM + totalAvailable defaults null (never `returned` faked
+  // as the total). agency/query filtering on the catalog is CLIENT-SIDE.
+  defineTool({
+    name: "dol_list_datasets",
+    description:
+      "List the US Department of Labor Data API v4 dataset catalog (apiprod.dol.gov /v4/datasets) — the machine inventory of DOL enforcement/statistics datasets (WHD wage & hour, OSHA inspections, ILAB child/forced-labor reports, MSHA mine safety, ETA …). KEYLESS: the catalog needs NO API key (only dol_get_dataset does). Input (all optional): `agency` (CLIENT-SIDE filter by agency abbreviation like 'WHD'/'OSHA'/'ILAB', or an agency-name substring), `query` (CLIENT-SIDE free-text substring over dataset name/description/category/table/endpoint), `limit` (default 25, max 200), `offset`. Returns { datasets:[{ name, tablename, apiUrl, agency, agencyAbbr, description, frequency, datasetType, category }] } + honest _meta. ★Feed a row's `apiUrl` (the DOL 'api_url' endpoint) + its `agencyAbbr` into dol_get_dataset to fetch that dataset's records. HONESTY: agency/query filtering is CLIENT-SIDE (the DOL catalog API does not filter server-side, verified live); totalAvailable is the catalog's REAL total (meta.total_count) for an unfiltered scan, or the exact filtered-set size (the whole catalog is fetched in one page); offset pagination. Every scalar is null-never-empty-string. A non-array `datasets` / 200 non-JSON ⇒ schema_drift; a 5xx ⇒ THROWS.",
+    inputSchema: DolListDatasetsInput,
+    handler: (input) => dol.listDatasets(input),
+  }),
+  defineTool({
+    name: "dol_get_dataset",
+    description:
+      "Fetch records from ONE US DOL dataset (apiprod.dol.gov /v4/get/{agency}/{endpoint}/json). ★REQUIRES a free DOL_API_KEY: the DOL DATA endpoint has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://dol.gov/developer; the dataset CATALOG — dol_list_datasets — and agency list stay keyless). Input: `agency` (required — the `agencyAbbr` from dol_list_datasets, e.g. 'WHD', 'OSHA', 'ILAB'; rides the PATH, ^[A-Za-z0-9_]+$), `table` (required — the dataset's `apiUrl` endpoint from dol_list_datasets, e.g. 'Child_Labor_Report__2016_to_2022'; rides the PATH, ^[A-Za-z0-9_]+$), optional `limit` (default 10, max 100), `offset`, `filterField`+`filterValue` (a paired equality filter → a DOL filter_object), `fields` (best-effort column selection). Returns { records:[…verbatim dataset rows…] } + honest _meta. HONESTY: records are surfaced VERBATIM (the data-record envelope is key-gated and unverified, so field names/values are preserved as-is — a genuine 0 stays 0, a missing field stays null; the tool never coerces or fabricates). totalAvailable is a real count field ONLY when the response carries one, else null (an honest unknown — `returned` is NEVER passed off as the total); offset pagination (a full page ⇒ hasMore, page forward to confirm). A missing/invalid key (401/403) ⇒ invalid_input carrying the DOL_API_KEY guidance (never empty); a 400 ⇒ invalid_input; a genuine empty ⇒ honest empty (returned:0); a 429 ⇒ rate_limited THROWS (Retry-After honored); a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON / no row array ⇒ schema_drift. The key rides ONLY in the X-API-KEY request header — never the URL / _meta / a log.",
+    inputSchema: DolGetDatasetInput,
+    handler: (input) => dol.getDataset(input),
+  }),
+  // ━━━ US Senate LDA lobbying filings (lda.senate.gov) — the lobbying/B2G lane (1) ━━━ ADR-0052
+  // Who is paid HOW MUCH to lobby WHICH federal agency on WHICH issue — the
+  // registrant→client→government-entity signal no contract/spending source carries.
+  // KEYLESS (anonymous 200); the OPTIONAL free LDA_API_KEY only raises the rate limit
+  // and rides the Authorization: Token … header ONLY (the socrata app-token lineage —
+  // NOT key-required). ★count is the API's REAL total (~1.95M) — never results.length;
+  // page-based pagination. income/expenses are null-or-decimal-string ⇒ null-never-0.
+  defineTool({
+    name: "lda_search_filings",
+    description:
+      "Search US Senate LDA (Lobbying Disclosure Act) filings — who is paid HOW MUCH to lobby WHICH federal agency on WHICH issue (lda.senate.gov/api/v1/filings, KEYLESS — anonymous access works; an optional free LDA_API_KEY only raises the rate limit). All inputs optional: `registrantName` (the lobbying firm/in-house filer), `clientName` (who it's for), `lobbyistName`, `filingYear` (4-digit), `filingType` (short code, e.g. 'Q1'/'RR'/'YE'), `agency` (the federal government_entity lobbied — the B2G signal), `issue` (specific lobbying issues text), `page` (1-based, default 1), `pageSize` (1..25, default 25). Returns { filings:[{ filingUuid, filingType, filingYear, filingPeriod, incomeUsd, expensesUsd, registrant, client, lobbyingActivities:[{ issueCode, description, governmentEntities:[names] }], documentUrl, postedDate, terminationDate }] } + honest _meta. HONESTY: totalAvailable is the API's REAL total match count (the corpus is ~1.95M filings) — NOT the rows on this page; pagination is page-based (pass the next page number when hasMore). incomeUsd/expensesUsd are parsed from the null-or-decimal-string income/expenses — null (not reported) ⇒ null, NEVER 0 (a genuine 0 stays 0); a filing reports EITHER income OR expenses, so the other is typically null. Missing lobbying_activities/government_entities ⇒ empty arrays (never fabricated). A genuine no-match (results:[]) ⇒ honest empty (returned:0); a 400 (bad filter) ⇒ invalid_input surfacing the API's message; a 429 ⇒ rate_limited THROWS (Retry-After honored, never routed around); a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON / non-array results / non-number count ⇒ schema_drift. The optional key rides ONLY in the Authorization: Token header (never the URL/_meta).",
+    inputSchema: LdaSearchFilingsInput,
+    handler: (input) => lda.searchFilings(input),
+  }),
   // ━━━ Self-service key discovery (1) ━━━
   // KEYLESS. A local status query — reads process.env (+ any .env auto-loaded at
   // startup) and reports, per key, whether it is set (a BOOLEAN — the key VALUE is
-  // NEVER read into the output). Makes the 2-required + 5-optional key situation
+  // NEVER read into the output). Makes the 4-required + 6-optional key situation
   // discoverable without reading source or docs.
   defineTool({
     name: "api_key_status",
     description:
-      "List every API key this server can use, whether each is REQUIRED or OPTIONAL, the free signup URL + what it unlocks, and whether it is CURRENTLY configured — a boolean only; the key VALUE is NEVER shown. KEYLESS (no input). Most sources are keyless; only Census (census_business_patterns) and FRED (2 tools) REQUIRE a key (they throw without one), the other 5 keys are OPTIONAL (raise a rate limit or unlock one filter). Keys can be set as host env vars OR in a `.env` file in the server's working directory (auto-loaded at startup; real env wins over .env). Returns { keys:[{ envVar, sources[], required, signupUrl, unlocks, note, currentlySet }], requiredMissing:[envVars], optionalMissing:[envVars], allKeysFree:true }. This tool tells you the CONFIG state; to verify a key actually WORKS, call that source's own tool. Getting a key (creating the account at the signup URL) is your step — the server automates discovery + configuration, not signup.",
+      "List every API key this server can use, whether each is REQUIRED or OPTIONAL, the free signup URL + what it unlocks, and whether it is CURRENTLY configured — a boolean only; the key VALUE is NEVER shown. KEYLESS (no input). Most sources are keyless; four sources need a key — Census (census_business_patterns), FRED (2 tools), and BEA (bea_regional_data) require one outright, and DOL's DATA endpoint (dol_get_dataset) needs one too (its catalog, dol_list_datasets, stays keyless) — the other 6 keys are OPTIONAL (raise a rate limit or unlock one filter). Keys can be set as host env vars OR in a `.env` file in the server's working directory (auto-loaded at startup; real env wins over .env). Returns { keys:[{ envVar, sources[], required, signupUrl, unlocks, note, currentlySet }], requiredMissing:[envVars], optionalMissing:[envVars], allKeysFree:true }. This tool tells you the CONFIG state; to verify a key actually WORKS, call that source's own tool. Getting a key (creating the account at the signup URL) is your step — the server automates discovery + configuration, not signup.",
     inputSchema: ApiKeyStatusInput,
     handler: async () => keys.apiKeyStatus(),
   }),