@cliwant/mcp-sam-gov 1.13.2 → 1.14.0

package/dist/toolsets.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Toolset profiles for MCP_SAM_GOV_TOOLSETS.
+ *
+ * Each of the 152 registered tools belongs to exactly one named toolset.
+ * A user may load a subset by setting the env var (comma- or space-separated,
+ * case-insensitive). Unset or "all" → all 152 tools loaded (default; byte-
+ * identical to today's behaviour). Unknown names → stderr warning AND a note
+ * in the server instructions; if no valid name remains → fall back to all,
+ * with a stderr warning and an instructions note.
+ *
+ * `feedback` and `api_key_status` are always loaded in every profile.
+ * Their toolset mapping is "core" (so a one-set-per-tool mapping is maintained),
+ * but `resolveToolsets` always injects them into any profile's loaded set.
+ * They are listed in the README table as "always loaded".
+ *
+ * Available toolsets:
+ *   core        — SAM.gov discovery/awards/wage determinations/exclusions/integrity,
+ *                 Grants.gov, all USAspending, FPDS, GAO, FAR/eCFR/Federal Register,
+ *                 SBA, OFAC, GSA labor-rate benchmarks; api_key_status + feedback
+ *                 (always loaded in every profile)
+ *   sled        — State/local (SLED): OpenGov, Bonfire, ArcGIS, Socrata,
+ *                 data.gov/CKAN, Tableau, Open Checkbook, search.gov domains
+ *   vetting     — Partner due-diligence: FAC, FDIC, EPA ECHO/TRI,
+ *                 CourtListener, nonprofit (IRS 990), Senate LDA lobbying
+ *   disclosure  — SEC EDGAR financial filings and XBRL frames
+ *   regulatory  — Regulations.gov, Congress.gov, GovInfo
+ *   pricing     — GSA per-diem, BLS, Treasury, BEA, Census business-patterns,
+ *                 FRED, DOL, USITC HTS
+ *   health      — CMS, NPPES, NIH, NSF, ClinicalTrials.gov, openFDA
+ *   safety      — NHTSA vehicle recalls, CPSC consumer-product recalls
+ *   geo         — Census geocode, FEMA disasters, NWS alerts, CBP border wait
+ *                 times, data.gov catalog
+ *   cyber       — NVD CVE, CISA KEV, NIST SP 800-53
+ */
+/** Every valid toolset name. */
+export declare const ALL_TOOLSET_NAMES: readonly ["core", "sled", "vetting", "disclosure", "regulatory", "pricing", "health", "safety", "geo", "cyber"];
+export type ToolsetName = typeof ALL_TOOLSET_NAMES[number];
+/**
+ * Short 2–4 word description for each toolset, shown in the server instructions
+ * when a profile is active so agents know what other sets exist.
+ */
+export declare const TOOLSET_HINTS: Readonly<Record<ToolsetName, string>>;
+/**
+ * Tools that are always loaded regardless of the active profile.
+ * Their toolset mapping is "core" (one-set-per-tool), but resolveToolsets
+ * injects them into every profile's loaded set.
+ */
+export declare const ALWAYS_LOADED_TOOLS: ReadonlySet<string>;
+/**
+ * Canonical mapping: tool name → toolset.
+ * Every registered tool must appear exactly once.
+ * Tests enforce: union === all 152 tools, no entry for an unregistered name.
+ *
+ * After moves (review 2026-09-18):
+ *   ofac_screen_entity       vetting → core  (govcon users screen SAM exclusions + OFAC together)
+ *   gsa_benchmark_labor_rates pricing → core  (proposal pricing; needed in core govcon workflows)
+ *   hts_lookup               geo → pricing    (tariff/duty data; groups with cost/rate tools)
+ *
+ * Resulting counts: core=60, sled=13, vetting=16, disclosure=8, regulatory=9,
+ *   pricing=15, health=17, safety=3, geo=8, cyber=3.  Total=152.
+ */
+export declare const TOOL_TOOLSET_MAP: Readonly<Record<string, ToolsetName>>;
+export type ResolveResult = {
+    /** Tools that are loaded (by name). */
+    loaded: Set<string>;
+    /** Valid toolset names that were requested. */
+    sets: string[];
+    /** Names that were not recognised as valid toolset names. */
+    unknown: string[];
+    /** True if we fell back to all because no valid name survived. */
+    fellBack: boolean;
+};
+/**
+ * Parse MCP_SAM_GOV_TOOLSETS and return the set of tool names to expose.
+ *
+ * Pure: takes the env value and the full tool-name list as inputs, reads
+ * nothing from `process.env`, and has no side-effects. Call sites (server.ts)
+ * are responsible for logging any warnings to stderr.
+ *
+ * `feedback` and `api_key_status` are always injected into `loaded` regardless
+ * of the requested profile (ALWAYS_LOADED_TOOLS invariant).
+ *
+ * @param envValue  The raw value of MCP_SAM_GOV_TOOLSETS (undefined / empty = all).
+ * @param toolNames The complete list of registered tool names (from TOOLS).
+ */
+export declare function resolveToolsets(envValue: string | undefined, toolNames: readonly string[]): ResolveResult;
+/**
+ * Filter a tool list to only those in the loaded set.
+ * Exported so server.ts can call this and tests can import and verify the logic
+ * without mutating dist/server.js.
+ */
+export declare function filterToolsFor<T extends {
+    name: string;
+}>(tools: readonly T[], loaded: ReadonlySet<string>): T[];
+/**
+ * Build the structured tool_not_loaded error envelope.
+ * Exported so server.ts can call this and tests can import and verify the logic
+ * without mutating dist/server.js.
+ *
+ * @param toolName   The name of the tool that was called but not loaded.
+ * @param loadedSets The currently loaded toolset names (from ResolveResult.sets).
+ */
+export declare function toolNotLoadedEnvelope(toolName: string, loadedSets: readonly string[]): {
+    ok: false;
+    error: {
+        kind: "tool_not_loaded";
+        message: string;
+        retryable: false;
+    };
+};
+//# sourceMappingURL=toolsets.d.ts.map

package/dist/toolsets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolsets.d.ts","sourceRoot":"","sources":["../src/toolsets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,gCAAgC;AAChC,eAAO,MAAM,iBAAiB,iHAWpB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAW/D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAGlD,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAmMlE,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,uCAAuC;IACvC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,6DAA6D;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kEAAkE;IAClE,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,aAAa,CAkEf;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACvD,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,GAC1B,CAAC,EAAE,CAEL;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B;IACD,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE;QAAE,IAAI,EAAE,iBAAiB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,KAAK,CAAA;KAAE,CAAC;CACvE,CAyBA"}

package/dist/toolsets.js

@@ -0,0 +1,390 @@
+/**
+ * Toolset profiles for MCP_SAM_GOV_TOOLSETS.
+ *
+ * Each of the 152 registered tools belongs to exactly one named toolset.
+ * A user may load a subset by setting the env var (comma- or space-separated,
+ * case-insensitive). Unset or "all" → all 152 tools loaded (default; byte-
+ * identical to today's behaviour). Unknown names → stderr warning AND a note
+ * in the server instructions; if no valid name remains → fall back to all,
+ * with a stderr warning and an instructions note.
+ *
+ * `feedback` and `api_key_status` are always loaded in every profile.
+ * Their toolset mapping is "core" (so a one-set-per-tool mapping is maintained),
+ * but `resolveToolsets` always injects them into any profile's loaded set.
+ * They are listed in the README table as "always loaded".
+ *
+ * Available toolsets:
+ *   core        — SAM.gov discovery/awards/wage determinations/exclusions/integrity,
+ *                 Grants.gov, all USAspending, FPDS, GAO, FAR/eCFR/Federal Register,
+ *                 SBA, OFAC, GSA labor-rate benchmarks; api_key_status + feedback
+ *                 (always loaded in every profile)
+ *   sled        — State/local (SLED): OpenGov, Bonfire, ArcGIS, Socrata,
+ *                 data.gov/CKAN, Tableau, Open Checkbook, search.gov domains
+ *   vetting     — Partner due-diligence: FAC, FDIC, EPA ECHO/TRI,
+ *                 CourtListener, nonprofit (IRS 990), Senate LDA lobbying
+ *   disclosure  — SEC EDGAR financial filings and XBRL frames
+ *   regulatory  — Regulations.gov, Congress.gov, GovInfo
+ *   pricing     — GSA per-diem, BLS, Treasury, BEA, Census business-patterns,
+ *                 FRED, DOL, USITC HTS
+ *   health      — CMS, NPPES, NIH, NSF, ClinicalTrials.gov, openFDA
+ *   safety      — NHTSA vehicle recalls, CPSC consumer-product recalls
+ *   geo         — Census geocode, FEMA disasters, NWS alerts, CBP border wait
+ *                 times, data.gov catalog
+ *   cyber       — NVD CVE, CISA KEV, NIST SP 800-53
+ */
+/** Every valid toolset name. */
+export const ALL_TOOLSET_NAMES = [
+    "core",
+    "sled",
+    "vetting",
+    "disclosure",
+    "regulatory",
+    "pricing",
+    "health",
+    "safety",
+    "geo",
+    "cyber",
+];
+/**
+ * Short 2–4 word description for each toolset, shown in the server instructions
+ * when a profile is active so agents know what other sets exist.
+ */
+export const TOOLSET_HINTS = {
+    core: "SAM, USAspending, FAR",
+    sled: "state/local procurement",
+    vetting: "FAC, FDIC, EPA, OFAC",
+    disclosure: "SEC EDGAR filings",
+    regulatory: "Regs.gov, Congress, GovInfo",
+    pricing: "GSA, BLS, Treasury, DOL",
+    health: "CMS, NIH, openFDA",
+    safety: "NHTSA, CPSC recalls",
+    geo: "Census geocode, FEMA, NWS",
+    cyber: "CVE, CISA KEV, NIST",
+};
+/**
+ * Tools that are always loaded regardless of the active profile.
+ * Their toolset mapping is "core" (one-set-per-tool), but resolveToolsets
+ * injects them into every profile's loaded set.
+ */
+export const ALWAYS_LOADED_TOOLS = new Set([
+    "feedback",
+    "api_key_status",
+]);
+/**
+ * Canonical mapping: tool name → toolset.
+ * Every registered tool must appear exactly once.
+ * Tests enforce: union === all 152 tools, no entry for an unregistered name.
+ *
+ * After moves (review 2026-09-18):
+ *   ofac_screen_entity       vetting → core  (govcon users screen SAM exclusions + OFAC together)
+ *   gsa_benchmark_labor_rates pricing → core  (proposal pricing; needed in core govcon workflows)
+ *   hts_lookup               geo → pricing    (tariff/duty data; groups with cost/rate tools)
+ *
+ * Resulting counts: core=60, sled=13, vetting=16, disclosure=8, regulatory=9,
+ *   pricing=15, health=17, safety=3, geo=8, cyber=3.  Total=152.
+ */
+export const TOOL_TOOLSET_MAP = {
+    // ── core (60) ──────────────────────────────────────────────────────────────
+    // SAM.gov: discovery, attachments, wage-determinations, exclusions, integrity
+    sam_search_opportunities: "core",
+    sam_search_shaping: "core",
+    sam_get_opportunity: "core",
+    sam_fetch_description: "core",
+    sam_attachment_url: "core",
+    sam_fetch_attachment_text: "core",
+    sam_lookup_organization: "core",
+    sam_lookup_notice_fields: "core",
+    sam_check_exclusions: "core",
+    sam_get_wage_rates: "core",
+    sam_search_wage_determinations: "core",
+    sam_integrity_lookup: "core",
+    // Grants.gov
+    grants_search: "core",
+    grants_get_opportunity: "core",
+    // USAspending (29)
+    usas_search_awards: "core",
+    usas_search_individual_awards: "core",
+    usas_search_subagency_spending: "core",
+    usas_lookup_agency: "core",
+    usas_search_awards_by_recipient: "core",
+    usas_search_subawards: "core",
+    usas_search_recompetes: "core",
+    usas_search_expiring_contracts: "core",
+    usas_get_award_detail: "core",
+    usas_analyze_incumbent: "core",
+    usas_spending_over_time: "core",
+    usas_search_psc_spending: "core",
+    usas_search_state_spending: "core",
+    usas_search_cfda_spending: "core",
+    usas_search_federal_account_spending: "core",
+    usas_search_agency_spending: "core",
+    usas_get_agency_profile: "core",
+    usas_get_agency_awards_summary: "core",
+    usas_get_agency_budget_function: "core",
+    usas_search_recipients: "core",
+    usas_get_recipient_profile: "core",
+    usas_autocomplete_naics: "core",
+    usas_autocomplete_recipient: "core",
+    usas_disaster_spending: "core",
+    usas_glossary: "core",
+    usas_list_disaster_codes: "core",
+    usas_list_toptier_agencies: "core",
+    usas_naics_hierarchy: "core",
+    usas_search_teaming_partners: "core",
+    // FPDS
+    fpds_search_awards: "core",
+    // GAO
+    gao_protest_lookup: "core",
+    // FAR / DFARS
+    far_search: "core",
+    far_clause_lookup: "core",
+    far_compliance_matrix: "core",
+    // eCFR
+    ecfr_search: "core",
+    ecfr_list_titles: "core",
+    ecfr_get_section: "core",
+    // Federal Register
+    fed_register_search_documents: "core",
+    fed_register_get_document: "core",
+    fed_register_list_agencies: "core",
+    fed_register_public_inspection: "core",
+    // SBA
+    sba_size_standard: "core",
+    // OFAC (moved from vetting — govcon users screen SAM exclusions + OFAC together)
+    ofac_screen_entity: "core",
+    // GSA labor-rate benchmarks (moved from pricing — needed in core proposal-pricing)
+    gsa_benchmark_labor_rates: "core",
+    // Always-loaded utilities (every profile; mapped to core for 1-set invariant)
+    api_key_status: "core",
+    feedback: "core",
+    // ── sled (13) ──────────────────────────────────────────────────────────────
+    // State/local procurement + spend
+    opengov_list_governments: "sled",
+    opengov_search_solicitations: "sled",
+    bonfire_list_organizations: "sled",
+    bonfire_search_opportunities: "sled",
+    arcgis_hub_discover_datasets: "sled",
+    arcgis_feature_query: "sled",
+    socrata_discover_datasets: "sled",
+    socrata_query: "sled",
+    ckan_discover_datasets: "sled",
+    ckan_query: "sled",
+    tableau_view_csv: "sled",
+    open_checkbook_search: "sled",
+    search_gov_domains: "sled",
+    // ── vetting (16) ───────────────────────────────────────────────────────────
+    // Partner due-diligence (ofac_screen_entity moved to core)
+    fac_search_audits: "vetting",
+    fac_get_findings: "vetting",
+    fdic_search_institutions: "vetting",
+    fdic_institution_financials: "vetting",
+    fdic_institution_history: "vetting",
+    fdic_bank_failures: "vetting",
+    fdic_branch_deposits: "vetting",
+    fdic_industry_summary: "vetting",
+    fdic_risk_ratios: "vetting",
+    echo_search_facilities: "vetting",
+    echo_facility_report: "vetting",
+    epa_tri_facilities: "vetting",
+    courtlistener_search_opinions: "vetting",
+    nonprofit_search: "vetting",
+    nonprofit_financials: "vetting",
+    lda_search_filings: "vetting",
+    // ── disclosure (8) ─────────────────────────────────────────────────────────
+    // SEC EDGAR
+    edgar_company_concept: "disclosure",
+    edgar_company_facts: "disclosure",
+    edgar_company_filings: "disclosure",
+    edgar_daily_filing_index: "disclosure",
+    edgar_filing_index: "disclosure",
+    edgar_full_text_search: "disclosure",
+    edgar_lookup_cik: "disclosure",
+    edgar_xbrl_frames: "disclosure",
+    // ── regulatory (9) ─────────────────────────────────────────────────────────
+    // Regulations.gov, Congress.gov, GovInfo
+    regulations_search_documents: "regulatory",
+    regulations_search_comments: "regulatory",
+    regulations_search_dockets: "regulatory",
+    regulations_get_docket: "regulatory",
+    congress_search_bills: "regulatory",
+    congress_get_bill: "regulatory",
+    govinfo_list_collections: "regulatory",
+    govinfo_search_packages: "regulatory",
+    govinfo_get_package: "regulatory",
+    // ── pricing (15) ───────────────────────────────────────────────────────────
+    // GSA per-diem, BLS, Treasury, BEA, Census business-patterns, FRED, DOL, USITC HTS
+    // (gsa_benchmark_labor_rates moved to core; hts_lookup moved in from geo)
+    gsa_perdiem_rates: "pricing",
+    bls_oews_wages: "pricing",
+    bls_qcew: "pricing",
+    bls_timeseries: "pricing",
+    treasury_avg_interest_rates: "pricing",
+    treasury_debt_to_penny: "pricing",
+    treasury_monthly_statement: "pricing",
+    treasury_query_dataset: "pricing",
+    bea_regional_data: "pricing",
+    census_business_patterns: "pricing",
+    fred_search_series: "pricing",
+    fred_series_observations: "pricing",
+    dol_list_datasets: "pricing",
+    dol_get_dataset: "pricing",
+    hts_lookup: "pricing",
+    // ── health (17) ────────────────────────────────────────────────────────────
+    // CMS, NPPES, NIH, NSF, ClinicalTrials.gov, openFDA
+    cms_medicare_provider_services: "health",
+    cms_hospital_compare: "health",
+    cms_facility_directory: "health",
+    cms_dmepos_suppliers: "health",
+    cms_revoked_providers: "health",
+    cms_query_dataset: "health",
+    cms_search_datasets: "health",
+    nppes_lookup_provider: "health",
+    nih_reporter_search_projects: "health",
+    nsf_search_awards: "health",
+    nsf_get_award: "health",
+    clinicaltrials_search_studies: "health",
+    clinicaltrials_get_study: "health",
+    clinicaltrials_facet_counts: "health",
+    openfda_enforcement: "health",
+    openfda_device_clearances: "health",
+    openfda_drug_approvals: "health",
+    // ── safety (3) ─────────────────────────────────────────────────────────────
+    // NHTSA, CPSC
+    nhtsa_recalls: "safety",
+    nhtsa_complaints: "safety",
+    cpsc_recalls: "safety",
+    // ── geo (8) ────────────────────────────────────────────────────────────────
+    // Census geocode, FEMA, NWS, CBP, data.gov catalog
+    // (hts_lookup moved to pricing)
+    census_geocode_address: "geo",
+    census_geographies_by_coordinates: "geo",
+    fema_disaster_declarations: "geo",
+    fema_search_hazard_mitigation: "geo",
+    fema_search_public_assistance: "geo",
+    nws_active_alerts: "geo",
+    cbp_border_wait_times: "geo",
+    datagov_search_datasets: "geo",
+    // ── cyber (3) ──────────────────────────────────────────────────────────────
+    // NVD CVE, CISA KEV, NIST 800-53
+    cve_lookup: "cyber",
+    cisa_kev_lookup: "cyber",
+    nist_800_53_controls: "cyber",
+};
+/**
+ * Parse MCP_SAM_GOV_TOOLSETS and return the set of tool names to expose.
+ *
+ * Pure: takes the env value and the full tool-name list as inputs, reads
+ * nothing from `process.env`, and has no side-effects. Call sites (server.ts)
+ * are responsible for logging any warnings to stderr.
+ *
+ * `feedback` and `api_key_status` are always injected into `loaded` regardless
+ * of the requested profile (ALWAYS_LOADED_TOOLS invariant).
+ *
+ * @param envValue  The raw value of MCP_SAM_GOV_TOOLSETS (undefined / empty = all).
+ * @param toolNames The complete list of registered tool names (from TOOLS).
+ */
+export function resolveToolsets(envValue, toolNames) {
+    const allLoaded = new Set(toolNames);
+    // Unset or empty → all.
+    if (!envValue || !envValue.trim()) {
+        return { loaded: allLoaded, sets: ["all"], unknown: [], fellBack: false };
+    }
+    // Split on commas and/or whitespace, normalise to lower-case.
+    const tokens = envValue
+        .split(/[\s,]+/)
+        .map((t) => t.toLowerCase().trim())
+        .filter(Boolean);
+    // "all" anywhere → all.
+    if (tokens.includes("all")) {
+        return { loaded: allLoaded, sets: ["all"], unknown: [], fellBack: false };
+    }
+    const validSet = new Set(ALL_TOOLSET_NAMES);
+    const validNames = [];
+    const unknownNames = [];
+    for (const token of tokens) {
+        if (validSet.has(token)) {
+            if (!validNames.includes(token))
+                validNames.push(token);
+        }
+        else {
+            unknownNames.push(token);
+        }
+    }
+    // No valid names → fall back to all.
+    if (validNames.length === 0) {
+        return {
+            loaded: allLoaded,
+            sets: ["all"],
+            unknown: unknownNames,
+            fellBack: true,
+        };
+    }
+    // Build the loaded set: union of all tools in the requested toolsets.
+    const requestedSets = new Set(validNames);
+    const loaded = new Set();
+    for (const toolName of toolNames) {
+        const ts = TOOL_TOOLSET_MAP[toolName];
+        if (ts && requestedSets.has(ts)) {
+            loaded.add(toolName);
+        }
+    }
+    // Always inject always-loaded tools (feedback, api_key_status) regardless
+    // of the profile. They are already in core's mapping but must appear in every
+    // profile's loaded set.
+    for (const toolName of toolNames) {
+        if (ALWAYS_LOADED_TOOLS.has(toolName)) {
+            loaded.add(toolName);
+        }
+    }
+    return {
+        loaded,
+        sets: validNames,
+        unknown: unknownNames,
+        fellBack: false,
+    };
+}
+/**
+ * Filter a tool list to only those in the loaded set.
+ * Exported so server.ts can call this and tests can import and verify the logic
+ * without mutating dist/server.js.
+ */
+export function filterToolsFor(tools, loaded) {
+    return tools.filter((t) => loaded.has(t.name));
+}
+/**
+ * Build the structured tool_not_loaded error envelope.
+ * Exported so server.ts can call this and tests can import and verify the logic
+ * without mutating dist/server.js.
+ *
+ * @param toolName   The name of the tool that was called but not loaded.
+ * @param loadedSets The currently loaded toolset names (from ResolveResult.sets).
+ */
+export function toolNotLoadedEnvelope(toolName, loadedSets) {
+    const toolset = TOOL_TOOLSET_MAP[toolName] ?? "unknown";
+    // Suggest the union of currently loaded sets + the needed set (not just the
+    // needed set alone, which would silently drop the user's current profile).
+    const isAll = loadedSets.length === 1 && loadedSets[0] === "all";
+    let suggestion;
+    if (isAll) {
+        // All tools are already loaded — the tool simply doesn't exist.
+        suggestion = `MCP_SAM_GOV_TOOLSETS=all`;
+    }
+    else if (toolset === "unknown") {
+        suggestion = `MCP_SAM_GOV_TOOLSETS=all`;
+    }
+    else {
+        // Build union: current loaded sets + the required set, deduped.
+        const unionSets = [...loadedSets];
+        if (!unionSets.includes(toolset))
+            unionSets.push(toolset);
+        suggestion = `MCP_SAM_GOV_TOOLSETS=${unionSets.join(",")}`;
+    }
+    const error = {
+        kind: "tool_not_loaded",
+        message: `Tool '${toolName}' belongs to the '${toolset}' toolset, which is not loaded. ` +
+            `Set ${suggestion} to enable it.`,
+        retryable: false,
+    };
+    return { ok: false, error };
+}
+//# sourceMappingURL=toolsets.js.map

package/dist/toolsets.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cliwant/mcp-sam-gov",
-  "version": "1.13.2",
+  "version": "1.14.0",
   "mcpName": "io.github.cliwant/mcp-sam-gov",
   "description": "Most comprehensive keyless-first MCP server for US federal + state/local (SLED) contracting + spending + regulation: SAM.gov, USAspending, Federal Register, eCFR, Grants.gov, plus SLED procurement bids (OpenGov, Bonfire, ArcGIS, Socrata 53 hosts). 152 tools (147 need no API key), plug into Claude Desktop / Claude Code / Codex CLI / Cursor / Continue / Gemini CLI.",
   "keywords": [

package/src/bls.ts

@@ -149,10 +149,11 @@ const BLS_ID_TO_KEY: ReadonlyMap<string, BlsSeriesKey> = new Map(
 );
 
 // ─── Raw-seriesId charclass (SSRF + "verify the ID" honesty) ──────
-// `^[A-Z0-9]{1,20}$` — uppercase alnum, explicit length bound. In JS (no `m`
+// `^[A-Z0-9]{1,25}$` — uppercase alnum, explicit length bound. In JS (no `m`
 // flag) `$` matches only end-of-input, and `[A-Z0-9]` cannot include `\n`, so a
 // trailing newline is rejected. Rejects `../`, encoded traversal, `@host`, `;`.
-const SERIES_ID_RE = /^[A-Z0-9]{1,20}$/;
+// 25 chars covers OEWS series IDs (e.g. OEUN000000000000015125201, 25 chars).
+const SERIES_ID_RE = /^[A-Z0-9]{1,25}$/;
 
 // ─── Year bounds ──────────────────────────────────────────────────
 const YEAR_MIN = 1900;
@@ -417,7 +418,7 @@ export async function timeseries(args: BlsTimeseriesArgs): Promise<MetaBundle> {
     if (typeof raw !== "string" || !SERIES_ID_RE.test(raw)) {
       throw new ToolErrorCarrier({
         kind: "invalid_input",
-        message: `Invalid seriesId ${JSON.stringify(raw)} — expected 1..20 uppercase alphanumeric characters (^[A-Z0-9]{1,20}$). A BLS series ID like 'CUUR0000SA0'; punctuation/whitespace/lowercase are rejected (SSRF + "verify the ID" honesty).`,
+        message: `Invalid seriesId ${JSON.stringify(raw)} — expected 1..25 uppercase alphanumeric characters (^[A-Z0-9]{1,25}$). A BLS series ID like 'CUUR0000SA0' or OEWS 'OEUN000000000000015125201' (25 chars); punctuation/whitespace/lowercase are rejected (SSRF + "verify the ID" honesty).`,
         retryable: false,
         upstreamEndpoint: label,
       });

package/src/errors.ts

@@ -32,7 +32,12 @@ export type ErrorKind =
   /** API returned 200 but we couldn't parse / shape doesn't match. */
   | "schema_drift"
   /** Anything else. Don't retry. */
-  | "unknown";
+  | "unknown"
+  /**
+   * The tool exists in the registry but is not loaded in the current toolset
+   * profile. Set MCP_SAM_GOV_TOOLSETS to enable the required toolset.
+   */
+  | "tool_not_loaded";
 
 export type ToolError = {
   kind: ErrorKind;