@cliwant/mcp-sam-gov 1.0.0 → 1.1.0

package/dist/keys.js

@@ -0,0 +1,173 @@
+/**
+ * @cliwant/mcp-sam-gov/keys — API-key discovery + `.env` auto-loading.
+ *
+ * Why this exists
+ * ----------------
+ * The server rides 31 federal sources. MOST are fully keyless. But the set of
+ * *optional* keys (raise a rate limit, unlock one filter) plus the two *required*
+ * keys (Census business-patterns, FRED) has grown to the point where a user — or
+ * the AI driving the server — cannot tell, without reading source code:
+ *   - which env var each source reads,
+ *   - whether a key is REQUIRED or merely OPTIONAL,
+ *   - where to get one (free), and
+ *   - whether it is currently configured.
+ *
+ * `apiKeyStatus()` answers all four, truthfully, WITHOUT ever revealing a key's
+ * value (only a `currentlySet` boolean). `loadDotEnv()` lets a user configure
+ * keys ONCE in a `.env` file instead of the host's env block.
+ *
+ * Grounding: every `envVar` below is the exact string the code reads via
+ * `process.env.<NAME>` — DATA_GOV_API_KEY (datagovKey.ts), SAM_GOV_API_KEY
+ * (server.ts), BLS_API_KEY (bls.ts), NVD_API_KEY (nvd.ts), SOCRATA_APP_TOKEN
+ * (socrata.ts), CENSUS_API_KEY (census-economic.ts), FRED_API_KEY (fred.ts).
+ * No invented keys, sources, or signup URLs.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * The 7 keys the server reads — code-grounded, no inventions.
+ *
+ * REQUIRED (2): CENSUS_API_KEY, FRED_API_KEY — those sources have no keyless
+ * tier, so the tool throws without them. OPTIONAL (5): everything else works
+ * keyless; a key only raises a rate limit or unlocks a single filter.
+ */
+export const KEY_REGISTRY = [
+    {
+        envVar: "DATA_GOV_API_KEY",
+        sources: [
+            "api.data.gov keyed sources: Regulations.gov, Congress.gov, GovInfo, Federal Audit Clearinghouse (FAC), data.gov catalog",
+        ],
+        required: false,
+        signupUrl: "https://api.data.gov/signup/",
+        unlocks: "higher rate limits on the api.data.gov keyed sources (lifts the shared DEMO_KEY ~30/hr cap to ~1,000/hr)",
+        note: "Keyless by default via the public DEMO_KEY; a key only raises the shared hourly quota. (NPPES, CMS, and Federal Register are keyless on their own hosts and do NOT use this key.)",
+    },
+    {
+        envVar: "SAM_GOV_API_KEY",
+        sources: ["SAM.gov opportunities"],
+        required: false,
+        signupUrl: "https://open.gsa.gov/api/get-opportunities-public-api/",
+        unlocks: "the authenticated v2 opportunity search + the organization-name filter",
+        note: "Keyless HAL endpoint works without it; a key enables the keyed v2 path and org-name filtering. Register at sam.gov / api.sam.gov.",
+    },
+    {
+        envVar: "BLS_API_KEY",
+        sources: ["Bureau of Labor Statistics (BLS)"],
+        required: false,
+        signupUrl: "https://data.bls.gov/registrationEngine/",
+        unlocks: "the BLS v2 tier (~500 queries/day, 50 series/query, ~20-year span) vs keyless v1 (~25 queries/day)",
+        note: "Keyless v1 works out of the box; a key upgrades to the higher v2 limits.",
+    },
+    {
+        envVar: "NVD_API_KEY",
+        sources: ["NIST NVD (cve_lookup)"],
+        required: false,
+        signupUrl: "https://nvd.nist.gov/developers/request-an-api-key",
+        unlocks: "a higher NVD rate limit",
+        note: "Keyless by default; a key lifts the request rate limit.",
+    },
+    {
+        envVar: "SOCRATA_APP_TOKEN",
+        sources: ["Socrata (state/city open-data portals)"],
+        required: false,
+        signupUrl: "https://evergreen.data.socrata.com/signup",
+        unlocks: "higher Socrata throttling limits",
+        note: "Keyless by default; a token raises the per-host throttle. Any Socrata portal's developer settings issues one.",
+    },
+    {
+        envVar: "CENSUS_API_KEY",
+        sources: ["US Census (census_business_patterns)"],
+        required: true,
+        signupUrl: "https://api.census.gov/data/key_signup.html",
+        unlocks: "the census_business_patterns tool (there is no keyless tier — it throws without a key)",
+        note: "REQUIRED: the Census economic API has no keyless access.",
+    },
+    {
+        envVar: "FRED_API_KEY",
+        sources: ["FRED (fred_search_series, fred_series_observations)"],
+        required: true,
+        signupUrl: "https://fred.stlouisfed.org/docs/api/api_key.html",
+        unlocks: "the 2 FRED tools (there is no keyless tier — they throw without a key)",
+        note: "REQUIRED: the FRED API has no keyless access.",
+    },
+];
+/** true iff the env var is set to a non-empty (after-trim) string. */
+function isSet(envVar) {
+    const v = process.env[envVar];
+    return typeof v === "string" && v.trim().length > 0;
+}
+/**
+ * Report which API keys the server can use and whether each is configured.
+ *
+ * SECURITY: the returned object carries ONLY a `currentlySet` boolean per key —
+ * the key's VALUE is NEVER read into the output. (`isSet` inspects the value to
+ * compute the boolean, but the value itself never leaves this function.)
+ */
+export function apiKeyStatus() {
+    const keys = KEY_REGISTRY.map((k) => ({
+        ...k,
+        currentlySet: isSet(k.envVar),
+    }));
+    const requiredMissing = keys
+        .filter((k) => k.required && !k.currentlySet)
+        .map((k) => k.envVar);
+    const optionalMissing = keys
+        .filter((k) => !k.required && !k.currentlySet)
+        .map((k) => k.envVar);
+    return { keys, requiredMissing, optionalMissing, allKeysFree: true };
+}
+/**
+ * MINIMAL, dependency-free `.env` loader.
+ *
+ * Reads `${cwd||process.cwd()}/.env` if present and sets `process.env[KEY]` for
+ * each `KEY=VALUE` line — but ONLY if that key is not already set, so a real
+ * environment variable always wins over `.env` (standard precedence). Supports
+ * `export KEY=VALUE`, `#` comments, blank lines, and surrounding single/double
+ * quotes on the value. NEVER throws: a missing file returns 0 (⇒ byte-identical
+ * startup), and a malformed line is skipped rather than fatal.
+ *
+ * @returns the number of vars newly set into process.env.
+ */
+export function loadDotEnv(cwd) {
+    const path = join(cwd ?? process.cwd(), ".env");
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        // Missing / unreadable .env ⇒ zero change. This is the common case and
+        // MUST be a no-op so startup is byte-identical when no .env exists.
+        return 0;
+    }
+    let loaded = 0;
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        // Optional `export ` prefix.
+        const body = line.startsWith("export ")
+            ? line.slice("export ".length).trim()
+            : line;
+        const eq = body.indexOf("=");
+        if (eq <= 0)
+            continue; // no `=`, or empty key ⇒ skip (malformed).
+        const key = body.slice(0, eq).trim();
+        if (!key)
+            continue;
+        let value = body.slice(eq + 1).trim();
+        // Strip a single matching pair of surrounding quotes.
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        // Precedence: if the key is already set in the real environment, it wins —
+        // we set `process.env[key]` ONLY when it is not already present.
+        if (process.env[key] !== undefined)
+            continue;
+        process.env[key] = value;
+        loaded++;
+    }
+    return loaded;
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,YAAY,EAKb,MAAM,oBAAoB,CAAC;AAyxG5B,KAAK,OAAO,GAAG;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC;IAO1B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE;QAAE,GAAG,EAAE,YAAY,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE,CAAC;AAoBF,eAAO,MAAM,KAAK,EAAE,OAAO,EAq5C1B,CAAC;AA+HF,wBAAsB,OAAO,CAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,YAAY,GAChB,OAAO,CAAC,OAAO,CAAC,CAalB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,YAAY,EAKb,MAAM,oBAAoB,CAAC;AAo4G5B,KAAK,OAAO,GAAG;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC;IAO1B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE;QAAE,GAAG,EAAE,YAAY,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE,CAAC;AAoBF,eAAO,MAAM,KAAK,EAAE,OAAO,EAk8C1B,CAAC;AA6IF,wBAAsB,OAAO,CAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,YAAY,GAChB,OAAO,CAAC,OAAO,CAAC,CAalB"}

package/dist/server.js

@@ -44,6 +44,8 @@ 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 fema from "./fema.js";
 import * as fdic from "./fdic.js";
 import * as bls from "./bls.js";
@@ -54,6 +56,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 +64,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.1.0";
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 const SamSearchInput = z.object({
     query: z.string().optional().describe("Free-text title query"),
@@ -2789,6 +2792,92 @@ 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)."),
+});
+// 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 +4138,59 @@ 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),
+    }),
+    // ━━━ 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 +4305,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";
     }