@cliwant/mcp-sam-gov 1.0.0 → 1.2.0

package/dist/server.js

@@ -44,6 +44,9 @@ import * as nih from "./nih.js";
 import * as nsf from "./nsf.js";
 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 gsaPerdiem from "./gsa-perdiem.js";
 import * as fema from "./fema.js";
 import * as fdic from "./fdic.js";
 import * as bls from "./bls.js";
@@ -54,6 +57,7 @@ import * as cms from "./cms.js";
 import * as fac from "./fac.js";
 import * as usitc from "./usitc.js";
 import { fetchAttachmentText } from "./attachments.js";
+import * as keys from "./keys.js";
 import { toToolError, ToolErrorCarrier, errorFromResponse } from "./errors.js";
 import { buildMeta, isMetaBundle, withMeta, } from "./meta.js";
 import { pathToFileURL, fileURLToPath } from "node:url";
@@ -61,7 +65,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.0.0";
+const SERVER_VERSION = "1.2.0";
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 const SamSearchInput = z.object({
     query: z.string().optional().describe("Free-text title query"),
@@ -2789,6 +2793,120 @@ const CensusGeographiesByCoordinatesInput = z
     message: "latitude (or its alias y) is required.",
     path: ["latitude"],
 });
+// ─── US Census County Business Patterns (CBP) — the FIRST key-required source ──
+const CensusBusinessPatternsInput = z.object({
+    naics: z
+        .string()
+        .regex(/^\d{2,6}$/)
+        .optional()
+        .describe("A NAICS-2017 code (2–6 digits), e.g. '5415' (Computer Systems Design & Related Services) or '54' (Professional/Scientific/Technical). Omit to aggregate across all sectors. Validated ^\\d{2,6}$."),
+    geography: z
+        .enum(["us", "state", "county"])
+        .optional()
+        .describe("The geography level (default 'us'). 'state' returns one row per state (or a single state when `state` is given); 'county' returns every county in a state and REQUIRES `state`."),
+    state: z
+        .string()
+        .regex(/^\d{2}$/)
+        .optional()
+        .describe("A 2-digit state FIPS code, e.g. '06' (California), '48' (Texas). Optional filter for geography='state'; REQUIRED for geography='county' (the CBP `in=state:` predicate). Validated ^\\d{2}$."),
+    year: z
+        .string()
+        .regex(/^\d{4}$/)
+        .optional()
+        .describe("The CBP data year (default '2022', the latest confirmed vintage). Validated ^\\d{4}$ (it rides in the request path)."),
+    limit: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("OPTIONAL client-side top-N cap on the returned rows. CBP has NO server-side pagination, so this slices AFTER the full set is fetched and DISCLOSES the omission (totalAvailable stays the full count). Omit to return every matching row."),
+});
+// ─── FRED (Federal Reserve Economic Data) — the SECOND key-required source ──
+// ADR-0048. Macro context (GDP/CPI/rates/unemployment/PPI). REQUIRES a free
+// FRED_API_KEY; without it both tools throw an honest config error (the other 112
+// tools stay keyless). The key rides &api_key= ONLY. Missing observations ('.') → null.
+const FredSearchSeriesInput = z.object({
+    query: z
+        .string()
+        .min(1)
+        .describe("The FRED search_text — free-text terms to discover economic series, e.g. 'unemployment rate', 'CPI', 'GDP', '10-year treasury'. Required."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .optional()
+        .describe("Max series to return (default 25, max 1000). Offset-paginated."),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+});
+const FredSeriesObservationsInput = z.object({
+    seriesId: z
+        .string()
+        .regex(/^[A-Za-z0-9._-]+$/)
+        .describe("A FRED series id, e.g. 'GDP', 'CPIAUCSL' (CPI), 'UNRATE' (unemployment), 'DGS10' (10-yr Treasury), 'PPIACO' (PPI). Discover ids with fred_search_series. Validated ^[A-Za-z0-9._-]+$. Required."),
+    startDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .describe("Earliest observation date (YYYY-MM-DD). Maps to FRED observation_start."),
+    endDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .describe("Latest observation date (YYYY-MM-DD). Maps to FRED observation_end."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100000)
+        .optional()
+        .describe("Max observations to return (default 100, max 100000). Offset-paginated."),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+    sortOrder: z
+        .enum(["asc", "desc"])
+        .optional()
+        .describe("Observation date order: 'asc' (oldest first, FRED default) or 'desc' (newest first)."),
+});
+// ─── 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
+// lifts the rate. EITHER (city+state) OR zip — both/neither ⇒ invalid_input, 0 fetch.
+const GsaPerdiemRatesInput = z
+    .object({
+    city: z
+        .string()
+        .regex(/^[A-Za-z .'\-]{1,60}$/)
+        .optional()
+        .describe("The city name (e.g. 'Washington', 'San Francisco'). Requires `state`. Validated ^[A-Za-z .'\\-]{1,60}$. Use EITHER (city + state) OR zip — not both."),
+    state: z
+        .string()
+        .regex(/^[A-Za-z]{2}$/)
+        .optional()
+        .describe("The 2-letter state/territory code (e.g. 'DC', 'CA'). Required with `city`. Validated ^[A-Za-z]{2}$."),
+    zip: z
+        .string()
+        .regex(/^\d{5}$/)
+        .optional()
+        .describe("A 5-digit ZIP code (e.g. '20001'). The alternative lookup mode to city+state. Validated ^\\d{5}$. Use EITHER zip OR (city + state) — not both."),
+    year: z
+        .string()
+        .regex(/^\d{4}$/)
+        .optional()
+        .describe("The per-diem fiscal year (default '2025'). Validated ^\\d{4}$ (it rides in the request path)."),
+})
+    .describe("Look up GSA per-diem rates by EITHER (city + state) OR zip. Supplying both, or neither, ⇒ invalid_input.");
+// api_key_status takes no input — it is a pure status query over process.env.
+const ApiKeyStatusInput = z.object({});
 // Build a ToolDef whose `handler` is type-checked against the schema's inferred
 // input `I` at the call site (e.g. `input.searchText` is known-present). The
 // `I` binding is erased to `any` in the ToolDef[] array, so entries without a
@@ -4049,9 +4167,72 @@ export const TOOLS = [
         inputSchema: CensusGeographiesByCoordinatesInput,
         handler: (input) => census.geographiesByCoordinates(input),
     }),
+    // ━━━ US Census County Business Patterns — market sizing (1) ━━━ ADR-0047
+    // ★The server's FIRST KEY-REQUIRED source: the Census Data API removed its
+    // keyless tier, so WITHOUT a CENSUS_API_KEY this tool throws an honest
+    // invalid_input config error (the other 111 tools stay keyless). NAICS×geography
+    // establishments / employment / annual payroll — the demand-side market-sizing
+    // lane. Census negative suppression sentinels (-999999999 …) map to null (never
+    // a negative number / never 0). The 2D-array body is parsed by header name.
+    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; Census and FRED are the only key-required sources — every other tool is keyless). 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); Census SUPPRESSED/withheld cells (large negative sentinels like -999999999) map to null — NEVER a negative number and NEVER 0 (a genuine 0 stays 0); 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),
+    }),
+    // ━━━ FRED (Federal Reserve Economic Data) — macro context (2) ━━━ ADR-0048
+    // ★The server's SECOND KEY-REQUIRED source: FRED has NO keyless tier, so WITHOUT
+    // a FRED_API_KEY both tools throw an honest invalid_input config error (the other
+    // 112 tools stay keyless). GDP/CPI/rates/unemployment/PPI — the macro backdrop for
+    // bid escalation / market timing. A missing observation ('.') maps to null (never 0).
+    defineTool({
+        name: "fred_search_series",
+        description: "Discover FRED economic series (GDP, CPI, interest rates, unemployment, PPI…) by free-text search (FRED /fred/series/search; api.stlouisfed.org). ★REQUIRES a free FRED_API_KEY: FRED has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://fred.stlouisfed.org/docs/api/api_key.html; this and fred_series_observations are the key-required macro tools — the other 112 tools stay keyless). Input: `query` (the search_text, required, e.g. 'unemployment rate' / 'CPI' / '10-year treasury'), optional `limit` (default 25, max 1000), `offset`. Returns { series:[{ id, title, frequency, frequencyShort, units, seasonalAdjustment, observationStart, observationEnd, lastUpdated, popularity }] } + honest _meta. Feed `id` into fred_series_observations for the time series. HONESTY: totalAvailable is FRED's EXACT reported `count` (offset pagination via hasMore/nextOffset — never fabricated); every scalar is null-never-empty-string; a genuine no-match ⇒ honest empty (returned:0); a 400 (bad/missing key) ⇒ invalid_input CARRYING FRED's error_message; a 5xx ⇒ THROWS; a 200 non-JSON / non-array `seriess` ⇒ schema_drift. The key rides ONLY in the &api_key= query param — never logged or echoed.",
+        inputSchema: FredSearchSeriesInput,
+        handler: (input) => fred.searchSeries(input),
+    }),
+    defineTool({
+        name: "fred_series_observations",
+        description: "Fetch a FRED series' time series of date/value observations (FRED /fred/series/observations; api.stlouisfed.org). ★REQUIRES a free FRED_API_KEY (FRED has NO keyless tier — without it this tool THROWS an honest config error; get one at https://fred.stlouisfed.org/docs/api/api_key.html). Input: `seriesId` (required, e.g. 'GDP', 'CPIAUCSL', 'UNRATE', 'DGS10', 'PPIACO'; discover with fred_search_series), optional `startDate`/`endDate` (YYYY-MM-DD), `limit` (default 100, max 100000), `offset`, `sortOrder` (asc|desc). Returns { observations:[{ date, value }] } + honest _meta. ★MISSING-VALUE HONESTY (the crux): FRED encodes a missing observation as the literal '.', which maps to value:null (missing) — NEVER 0; a genuine reported 0 is preserved as 0. HONESTY: totalAvailable is FRED's EXACT `count` (offset pagination via hasMore/nextOffset — never fabricated); a 400 (bad seriesId / missing key) ⇒ invalid_input CARRYING FRED's error_message (never a fake empty); a genuine empty ⇒ honest empty; a 5xx ⇒ THROWS; a 200 non-JSON / non-array `observations` ⇒ schema_drift. seriesId is charclass-validated (^[A-Za-z0-9._-]+$) and dates are YYYY-MM-DD; the key rides ONLY in the &api_key= query param.",
+        inputSchema: FredSeriesObservationsInput,
+        handler: (input) => fred.seriesObservations(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
+    // key seam (datagovKey.ts, X-Api-Key header) as datagov_search_datasets — KEYLESS by
+    // default via the shared DEMO_KEY, keylessMode:false. EITHER (city+state) OR zip; both
+    // or neither ⇒ invalid_input, 0 fetch. `value` (monthly lodging) / `meals` are null-
+    // never-0; standardRate/isOconus are STRING booleans coerced to real booleans.
+    defineTool({
+        name: "gsa_perdiem_rates",
+        description: "Look up GSA Federal Travel PER-DIEM rates — the max lodging + Meals & Incidental Expenses (M&IE) reimbursement ceilings for official U.S. government travel (api.gsa.gov /travel/perdiem/v2, keyed — DATA_GOV_API_KEY or the shared DEMO_KEY). Input: EITHER `city` (e.g. 'Washington') + `state` (2-letter, e.g. 'DC') OR `zip` (5-digit) — supplying BOTH, or NEITHER, ⇒ invalid_input with 0 fetch; optional `year` (default '2025'). Returns { rates:[{ city, county, state, zip, year, isOconus, standardRate, mealsUsd, monthlyLodgingUsd:[{ month (1-12), monthName, lodgingUsd }] }] } + honest _meta. HONESTY: lodgingUsd (the API's monthly `value`) is the MAX nightly lodging ceiling for that month — it VARIES SEASONALLY (hence a per-month array), and mealsUsd is the daily M&IE ceiling; both are integer US dollars, null-when-withheld (NEVER 0 — a genuine 0 is preserved). standardRate/isOconus are booleans coerced from the API's string 'true'/'false' (an unrecognized value ⇒ null, never a fabricated false); the months array is preserved AS-IS (never padded to 12). The API returns the COMPLETE rate set (no pagination) ⇒ totalAvailable = the row count, complete:true. A genuine no-match (rates:[]/rate:[]) ⇒ honest empty (returned:0); the API's `errors` field non-null ⇒ invalid_input carrying the message (never a fake empty); a 429 (DEMO_KEY ~10 req/hr, hit quickly) ⇒ rate_limited THROWS; a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON ⇒ schema_drift. DEMO_KEY ~10 req/hr shared ceiling — set DATA_GOV_API_KEY (free at api.data.gov/signup) for 1000/hr. The key rides ONLY in the X-Api-Key header (never the URL/_meta).",
+        inputSchema: GsaPerdiemRatesInput,
+        handler: (input) => gsaPerdiem.perdiemRates(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
+    // 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.",
+        inputSchema: ApiKeyStatusInput,
+        handler: async () => keys.apiKeyStatus(),
+    }),
 ];
 // ─── Server bootstrap ────────────────────────────────────────────
 async function main() {
+    // Auto-load API keys from a `.env` in the working directory BEFORE anything
+    // reads process.env (tools read env at call time; SamGovClient below reads
+    // SAM_GOV_API_KEY immediately). Real env wins over .env (precedence); no .env
+    // present ⇒ zero change ⇒ byte-identical startup. We log only the COUNT — never
+    // which keys or their values.
+    const loadedFromEnvFile = keys.loadDotEnv();
+    if (loadedFromEnvFile > 0) {
+        console.error(`[mcp-sam-gov] loaded ${loadedFromEnvFile} key(s) from .env`);
+    }
     const sam = new SamGovClient({
         apiKey: process.env.SAM_GOV_API_KEY?.trim() || undefined,
         logger: {
@@ -4166,6 +4347,9 @@ function synthesizeDefaultMeta(toolName, sam) {
     else if (toolName.startsWith("fpds_")) {
         source = "www.fpds.gov ezSearch ATOM (FPDS-NG, keyless)";
     }
+    else if (toolName === "api_key_status") {
+        source = "local (process.env + .env)";
+    }
     else {
         source = "unknown";
     }