@cliwant/mcp-sam-gov 0.3.0 → 1.0.0

package/README.md

@@ -4,7 +4,7 @@
 
 ### **$4 trillion of public federal data, one `npm install` away.**
 
-The most comprehensive **keyless** MCP server for US federal contracting + spending + regulation. **36 tools** that work today, in any AI agent.
+The most comprehensive **keyless** MCP server for US federal contracting + spending + regulation + partner vetting. **111 tools across 31 keyless federal data sources** that work today, in any AI agent.
 
 [![npm](https://img.shields.io/npm/v/@cliwant/mcp-sam-gov?color=cb3837&label=%40cliwant%2Fmcp-sam-gov&logo=npm)](https://www.npmjs.com/package/@cliwant/mcp-sam-gov)
 [![mcp-registry](https://img.shields.io/badge/MCP%20Registry-active-2ea44f?logo=anthropic)](https://registry.modelcontextprotocol.io/v0/servers?search=cliwant)
@@ -50,7 +50,7 @@ The most comprehensive **keyless** MCP server for US federal contracting + spend
 |---|---|
 | GovWin: $30K-$100K/yr per seat | Free, MIT license |
 | API key registration → wait 24h → quota tier shopping | `npm install` → working in 60s |
-| 5 separate vendor APIs / scrapers | 1 unified surface, 36 tools |
+| 5+ separate vendor APIs / scrapers | 1 unified surface, 111 tools across 31 sources |
 | LLMs hallucinate NAICS codes / agency names | Anti-hallucination autocomplete guards built-in |
 | Brittle scraping breaks weekly | Daily live smoke test ([badge above](#)) |
 | Procurement officer → IT ticket → 3-week wait | Claude Desktop double-click install |
@@ -61,19 +61,20 @@ The federal data this wraps is **public domain**. There is no good reason it sho
 
 ## What this gives Claude (and other AI agents)
 
-| Domain | What you can ask | Tools |
+| Domain | What you can ask | Sources |
 |---|---|---|
-| 🔍 **Active opportunities** | "Find SAM.gov solicitations under NAICS 541512 closing this month" | 5 SAM.gov tools |
-| 💰 **Awards & recipients** | "Show me Booz Allen wins at VA last fiscal year" | 8 USAspending tools |
-| 📊 **Aggregate analysis** | "Top 10 PSC categories at DoD by spending FY26" | 6 USAspending tools |
-| 🏛 **Agency profiles** | "What's VA's mission? FY25 budget breakdown?" | 3 USAspending tools |
-| 🏢 **Recipient profiles** | "Pull Booz Allen's full recipient profile + alternate names" | 2 USAspending tools |
-| 🧠 **Anti-hallucination** | NAICS / recipient / agency autocomplete + glossary | 5 USAspending tools |
-| 📜 **Federal Register** | "What VA cybersecurity rules were published this quarter?" | 3 tools |
-| ⚖️ **Regulations (FAR/CFR)** | "Find FAR sections about SDVOSB set-aside" | 2 eCFR tools |
-| 🎓 **Federal grants** | "Cybersecurity grants posted in the last 30 days" | 2 Grants.gov tools |
-
-**36 tools total. Zero API keys. p50 latency 257ms, p95 766ms** (live benchmarks against federal APIs).
+| 🔍 **Opportunities & solicitations** | "Find SAM.gov solicitations under NAICS 541512 closing this month" — read the SOW, POCs, attachments | SAM.gov, Grants.gov |
+| 💰 **Spending, awards & competition** | "Show me Booz Allen wins at VA last fiscal year; top 10 PSC categories at DoD" | USAspending, FPDS, GAO |
+| 🕵️ **Entity & partner vetting** | "Screen this firm: OFAC sanctions, SAM exclusions, single-audit findings, bank health, EPA compliance" | OFAC, SAM, FAC, FDIC, EPA ECHO |
+| 📈 **Financial disclosure (SEC)** | "Pull this public company's revenue trend and latest 10-K filings" | SEC EDGAR |
+| ⚖️ **Regulatory & legislative** | "What VA cybersecurity rules were published this quarter? Any open Regulations.gov dockets?" | Federal Register, Regulations.gov, eCFR, FAR/DFARS, Congress.gov, GovInfo |
+| 💲 **Pricing, labor & fiscal** | "GSA CALC labor-rate band for a systems analyst; SCA wage determination for this county; CPI escalation" | GSA CALC, SAM WDs, BLS, US Treasury |
+| 🏥 **Health & research funding** | "NIH/NSF grants on this topic; recruiting clinical trials; industry payments to this physician" | NIH RePORTER, NSF, ClinicalTrials.gov, CMS Open Payments, NPPES |
+| 🛡 **Cyber compliance** | "Is this CVE on the CISA KEV must-patch list?" | NVD, CISA KEV |
+| 🌐 **Trade, geo & disaster** | "HTS tariff for this product; Census tract for this address; FEMA declarations in this state" | USITC HTS, US Census, FEMA, Socrata, CKAN |
+| 🎓 **Grants & datasets** | "Cybersecurity grants posted in the last 30 days; discover federal open datasets" | Grants.gov, data.gov |
+
+**111 tools across 31 keyless federal data sources. Zero API keys.** (An earlier 52-tool build measured roughly p50 ~0.25s / p95 ~0.8s against production federal APIs; latency varies by source and upstream load — treat it as fast, not a benchmarked guarantee.)
 
 ---
 
@@ -100,7 +101,7 @@ If you already use Claude Code (the CLI):
 /plugin install cliwant/mcp-sam-gov
 ```
 
-This installs the MCP server **plus** a [SKILL.md](./skills/sam-gov/SKILL.md) workflow guide that teaches Claude when + how to use each of the 36 tools.
+This installs the MCP server **plus** a [SKILL.md](./skills/sam-gov/SKILL.md) workflow guide that teaches Claude when + how to use each of the 111 tools.
 
 ### 🔵 Path 3 — Manual install for any MCP host (Codex, Cursor, Continue, Gemini)
 
@@ -168,7 +169,7 @@ Then point your host config at the absolute path:
 
 (Or skip this entirely — use Path 1's `.mcpb` and it auto-configures.)
 
-Restart Claude Desktop fully (system tray quit on Windows / Quit menu on macOS), then look for the 🔨 icon. You should see "sam-gov (36 tools)".
+Restart Claude Desktop fully (system tray quit on Windows / Quit menu on macOS), then look for the 🔨 icon. You should see "sam-gov (111 tools)".
 
 ### Claude Code
 
@@ -263,11 +264,42 @@ Once installed, you can ask in natural language. The agent picks the right tool
 - "VA 541512 contracts expiring in next 12 months over $1M"
 - "Pull period of performance for award CONT_AWD_..."
 
-### Regulatory
+### Regulatory & legislative
 - "Find FAR sections about SDVOSB set-aside requirements"
+- "Turn this RFP's cited FAR/DFARS clause list into a Section L/M compliance matrix"
 - "What new VA cybersecurity rules were published this quarter?"
+- "Any Federal Register documents on the public-inspection desk from DoD today?"
+- "Search Regulations.gov dockets on 'contractor cybersecurity' and pull the public comments"
+- "Discover federal open datasets about 'wildfire' on data.gov"
 - "Is there a Federal Register doc number 2026-08333? Pull the citation."
 
+### Partner & entity vetting
+- "Screen 'Acme Defense LLC' against the OFAC sanctions list and SAM exclusions"
+- "Look up NPI 1234567890 in NPPES — is this provider active?"
+- "Does this subcontractor have adverse Single Audit findings in the Federal Audit Clearinghouse?"
+- "How healthy is the bank on cert #3510 — risk ratios and quarterly financials?"
+- "Pull this public company's revenue trend and latest 10-K from SEC EDGAR"
+- "Any EPA compliance/enforcement flags for this facility?"
+
+### Compliance & eligibility
+- "What's the SBA small-business size standard for NAICS 541512?"
+- "Search the eCFR for the exact text of a rule"
+- "What's the US import duty rate (HTS) for lithium-ion batteries?"
+
+### Pricing, labor & fiscal
+- "GSA CALC ceiling-rate band for a senior systems analyst"
+- "Find the SCA wage determination for Baltimore County, MD and give me the fringe rates"
+- "How much has CPI-U risen over the last 3 years for an escalation clause?"
+- "What's the current total US public debt (Debt to the Penny)?"
+
+### Cyber
+- "Is CVE-2021-44228 (Log4Shell) on the CISA KEV must-patch list, and what's the due date?"
+
+### Health & research funding
+- "NIH RePORTER projects on mRNA vaccines funded last year"
+- "Recruiting clinical trials for diabetes sponsored by industry"
+- "Industry payments to physicians in CA from the CMS Open Payments Research dataset"
+
 ### Grants
 - "Cybersecurity grants posted in the last 30 days"
 - "Pull grant id 361238"
@@ -291,93 +323,223 @@ The MCP server runs **keyless** by default. For higher SAM.gov rate limits + the
 
 Get a free key at [sam.gov/SAM/pages/public/searchKeyData.jsf](https://sam.gov/SAM/pages/public/searchKeyData.jsf). The agent doesn't need to know — the key path is transparent.
 
+### `DATA_GOV_API_KEY` — the api.data.gov / api.gsa.gov family
+
+A handful of sources ride the shared **api.data.gov** gateway — Congress.gov, GovInfo, Regulations.gov, FAC, NPPES, and the data.gov v4 dataset catalog. They work **keyless** out of the box via the public `DEMO_KEY` (a low shared hourly quota). Set `DATA_GOV_API_KEY` to raise those limits substantially:
+
+```json
+{
+  "mcpServers": {
+    "sam-gov": {
+      "command": "mcp-sam-gov",
+      "env": { "DATA_GOV_API_KEY": "your-key-here" }
+    }
+  }
+}
+```
+
+Get one free (instant, no wait) at [api.data.gov/signup](https://api.data.gov/signup). The same key is accepted across all api.data.gov / api.gsa.gov sources. Like the SAM key, it is sent only on the wire (never logged); unset simply means `DEMO_KEY`. BLS sources similarly accept an optional free `BLS_API_KEY` to lift their daily quota.
+
 ---
 
-## Tool catalog (36 tools)
+## Tool catalog (111 tools)
+
+Grouped by workflow. Every tool is keyless by default; a handful gain higher limits from an optional free key (noted above). Descriptions are condensed — each tool's own `inputSchema` carries the full contract and honesty caveats.
 
 <details>
-<summary><b>SAM.gov — opportunities + attachments (5 tools)</b></summary>
+<summary><b>Opportunities & solicitations — SAM.gov + Grants.gov (10 tools)</b></summary>
 
-- `sam_search_opportunities` — keyless HAL search (~47K active)
+- `sam_search_opportunities` — keyless HAL search of active SAM.gov contracting opportunities
+- `sam_search_shaping` — pre-solicitation radar (Sources Sought / Presol / Special Notices before the RFP exists)
 - `sam_get_opportunity` — full detail by 32-char hex noticeId (POCs + attachments + body)
 - `sam_fetch_description` — full RFP body as plain text
-- `sam_attachment_url` — public download URL for resourceId
-- `sam_lookup_organization` — federal-organization id → fullParentPathName
+- `sam_fetch_attachment_text` — extract attachment text (RFP / SOW / Q&A / wage tables) from PDF + DOCX + text/HTML
+- `sam_attachment_url` — build the public download URL for an attachment resourceId
+- `sam_lookup_organization` — federal-organization id → canonical fullParentPathName
+- `sam_lookup_notice_fields` — batch-fill nulled naics/set-aside/PoP/deadline for 1–100 noticeIds from the opt-in GSA daily CSV
+- `grants_search` — Grants.gov federal grant opportunities (financial assistance, distinct from SAM contracts)
+- `grants_get_opportunity` — full detail for a single grant opportunity by id
 </details>
 
 <details>
-<summary><b>USAspending — awards + recipients (8 tools)</b></summary>
-
-- `usas_search_awards` — share-of-wallet at agency × NAICS
-- `usas_search_individual_awards` — line items (returns generatedInternalId)
-- `usas_search_subagency_spending` — buyer-office breakdown
-- `usas_lookup_agency` — abbreviation → canonical name
-- `usas_search_awards_by_recipient` — recipient win history
-- `usas_search_subawards` — supply-chain / teaming
-- `usas_search_expiring_contracts` — recompete radar
-- `usas_get_award_detail` — period of performance, options, set-aside, competition
+<summary><b>Spending, awards & competition — USAspending + FPDS + GAO (29 tools)</b></summary>
+
+- `usas_search_awards` — aggregate share-of-wallet at agency × NAICS
+- `usas_search_individual_awards` — line-item federal contracts (returns generatedInternalId)
+- `usas_get_award_detail` — full award detail: period of performance, options, set-aside, competition
+- `usas_search_awards_by_recipient` — every contract a recipient won in an agency × NAICS slice
+- `usas_search_subawards` — enumerate subcontracts on prime awards (supply chain / teaming)
+- `usas_search_recompetes` — recompete radar (PoP ending in a window, soonest-first, no silent drops)
+- `usas_search_expiring_contracts` — **deprecated** alias of `usas_search_recompetes` (legacy shape)
+- `usas_analyze_incumbent` — per-award incumbent + public recompete-pressure hints (labels, not a score)
+- `usas_search_teaming_partners` — small-business teaming discovery by cert × NAICS × agency, exclusion-screened
+- `usas_spending_over_time` — contract-spending time series (fiscal_year / quarter / month)
+- `usas_search_agency_spending` — spending broken down by awarding agency
+- `usas_search_subagency_spending` — break a parent agency down by sub-agency / office
+- `usas_search_psc_spending` — spending by Product Service Code (PSC)
+- `usas_search_cfda_spending` — spending by CFDA grant-program code
+- `usas_search_state_spending` — spending by state / territory
+- `usas_search_federal_account_spending` — spending by federal account / Treasury Account Symbol (TAS)
+- `usas_search_recipients` — recipient list with parent/child hierarchy
+- `usas_get_recipient_profile` — full recipient detail (UEI, alternate names, totals)
+- `usas_get_agency_profile` — agency profile by toptier code (mission, abbreviation, website)
+- `usas_get_agency_awards_summary` — award activity for a fiscal year (transaction count + obligations)
+- `usas_get_agency_budget_function` — budget-function breakdown for an agency × fiscal year
+- `usas_list_toptier_agencies` — all toptier agencies + current-FY obligations
+- `usas_lookup_agency` — resolve 'VA' / 'DHS' → canonical toptier name + 4-digit code
+- `usas_autocomplete_naics` — anti-hallucination NAICS guard
+- `usas_autocomplete_recipient` — anti-hallucination recipient guard
+- `usas_naics_hierarchy` — navigate the NAICS tree (2→4→6) + active-contract count per code
+- `usas_glossary` — 151 federal-spending terms
+- `fpds_search_awards` — FPDS-NG federal contract award actions (the authoritative award-action feed)
+- `gao_protest_lookup` — recent GAO bid-protest decisions from the public Legal-Products RSS feed (recent window only)
 </details>
 
 <details>
-<summary><b>USAspending — aggregate analysis (6 tools)</b></summary>
-
-- `usas_spending_over_time` — fiscal_year / quarter / month time series
-- `usas_search_psc_spending` — PSC market structure
-- `usas_search_state_spending` — geographic distribution
-- `usas_search_cfda_spending` — grant programs
-- `usas_search_federal_account_spending` — Treasury Account Symbols (TAS)
-- `usas_search_agency_spending` — top buying agencies for NAICS / set-aside
+<summary><b>Entity & partner vetting — OFAC · SAM · FAC · FDIC · EPA (14 tools)</b></summary>
+
+- `ofac_screen_entity` — keyless OFAC denied-party / sanctions screening
+- `sam_check_exclusions` — keyless SAM debarment/exclusion screening by name and/or UEI/CAGE
+- `sam_integrity_lookup` — one-call integrity screen (exclusion verdict + honest FAPIIS pointer)
+- `fac_search_audits` — Single Audit summaries from the Federal Audit Clearinghouse
+- `fac_get_findings` — drill into the audit-RISK findings for an entity
+- `fdic_search_institutions` — search the FDIC-insured-institution directory
+- `fdic_institution_financials` — quarterly financial time-series for one institution (by cert #)
+- `fdic_risk_ratios` — counterparty risk ratios for one institution
+- `fdic_institution_history` — structural-change event log (mergers, charter changes)
+- `fdic_branch_deposits` — branch-deposit footprint
+- `fdic_bank_failures` — historical bank failures & assistance transactions
+- `fdic_industry_summary` — industry & state banking-sector annual aggregates
+- `echo_search_facilities` — search EPA-regulated facilities by state with compliance/enforcement screening
+- `echo_facility_report` — EPA ECHO Detailed Facility Report for one facility (by FRS RegistryID)
 </details>
 
 <details>
-<summary><b>USAspending — agency profile (3 tools)</b></summary>
+<summary><b>Financial disclosure — SEC EDGAR (8 tools)</b></summary>
+
+- `edgar_lookup_cik` — resolve a company ticker or name to its 10-digit SEC CIK
+- `edgar_company_filings` — a company's SEC filings
+- `edgar_company_facts` — curated XBRL financial facts for a filer
+- `edgar_company_concept` — one filer × one XBRL concept × the complete reported time-series
+- `edgar_xbrl_frames` — cross-filer XBRL cross-section (one concept across all filers for a period)
+- `edgar_full_text_search` — full-text search across EDGAR filings, 2001–present
+- `edgar_filing_index` — bulk cross-filer filing index for a quarter
+- `edgar_daily_filing_index` — per-day cross-filer filing index
+</details>
 
-- `usas_get_agency_profile` — mission, abbreviation, website
-- `usas_get_agency_awards_summary` — transaction count + obligations
-- `usas_get_agency_budget_function` — budget breakdown by program area
+<details>
+<summary><b>Regulatory & legislative — Federal Register · Regulations.gov · eCFR · FAR · Congress · GovInfo (18 tools)</b></summary>
+
+- `fed_register_search_documents` — search Federal Register documents by query / agency / type / date
+- `fed_register_get_document` — full detail for a document by number (citation, body URL, CFR refs)
+- `fed_register_public_inspection` — the Federal Register public-inspection desk (pre-publication)
+- `fed_register_list_agencies` — Federal Register agency slugs reference
+- `regulations_search_dockets` — search Regulations.gov rulemaking dockets
+- `regulations_search_documents` — search Regulations.gov rulemaking documents (rules, proposed rules, notices)
+- `regulations_search_comments` — search public comments on rulemakings
+- `regulations_get_docket` — fetch one Regulations.gov docket by id
+- `ecfr_search` — full-text search across the entire CFR (titleNumber=48 for FAR)
+- `ecfr_list_titles` — all 50 CFR titles + last-amended dates
+- `far_clause_lookup` — authoritative FAR/DFARS clause text + its prescription (exact clause number)
+- `far_search` — FAR/DFARS-scoped search (excludes GSAM, collapses to current in-force version)
+- `far_compliance_matrix` — cited-clause list → proposal-ready Section L/M compliance matrix (eligibility gates flagged)
+- `congress_search_bills` — search Congress.gov bills / legislation
+- `congress_get_bill` — one bill by congress / type / number
+- `govinfo_search_packages` — search GovInfo (GPO-authoritative) packages in a collection
+- `govinfo_get_package` — one GovInfo package summary + download links (txt/xml/pdf/mods)
+- `govinfo_list_collections` — the GovInfo collection catalog
 </details>
 
 <details>
-<summary><b>USAspending — recipient profile (2 tools)</b></summary>
+<summary><b>Pricing, labor & fiscal — GSA CALC · SAM WDs · BLS · US Treasury (10 tools)</b></summary>
+
+- `gsa_benchmark_labor_rates` — GSA CALC awarded ceiling-rate market band for a labor category (a distribution, not one price)
+- `sam_search_wage_determinations` — find SCA / Davis-Bacon wage determinations for a locality
+- `sam_get_wage_rates` — prevailing-wage + fringe / H&W rate table parsed from a WD, plus the EO minimum-wage floor
+- `bls_timeseries` — BLS time series (CPI-U / ECI escalation, PPI, employment) — the pricing/escalation layer
+- `bls_oews_wages` — benchmark occupational wages & employment (BLS OEWS) by area × occupation
+- `bls_qcew` — county × NAICS market size / wages / location quotient (competition density)
+- `treasury_debt_to_penny` — daily total US public debt outstanding (Treasury Fiscal Data)
+- `treasury_avg_interest_rates` — average interest rate the Treasury pays by security type
+- `treasury_monthly_statement` — Monthly Treasury Statement: receipts, outlays, deficit/surplus by month
+- `treasury_query_dataset` — escape-hatch query over 5 confirmed Treasury Fiscal Data datasets
+</details>
 
-- `usas_search_recipients` — list with parent/child hierarchy
-- `usas_get_recipient_profile` — full detail (DUNS, UEI, alternate names, totals)
+<details>
+<summary><b>Health & research funding — NIH · NSF · ClinicalTrials · CMS · NPPES (9 tools)</b></summary>
+
+- `nih_reporter_search_projects` — awarded NIH RePORTER research-grant projects
+- `nsf_search_awards` — awarded NSF research-grant awards
+- `nsf_get_award` — one NSF award by its numeric award id
+- `clinicaltrials_search_studies` — federally-registered clinical studies with sponsor/funder enrichment
+- `clinicaltrials_get_study` — one clinical study by NCT id (incl. brief summary)
+- `clinicaltrials_facet_counts` — exact per-value study-count distribution over the whole registry
+- `cms_search_datasets` — discover CMS Open Payments (Sunshine Act) datasets
+- `cms_query_dataset` — query a CMS Open Payments datastore distribution (industry→physician payments)
+- `nppes_lookup_provider` — CMS/HHS NPPES NPI Registry provider lookup
 </details>
 
 <details>
-<summary><b>USAspending — reference / autocomplete (5 tools)</b></summary>
+<summary><b>Cyber compliance — NVD + CISA KEV (2 tools)</b></summary>
 
-- `usas_autocomplete_naics` — anti-hallucination NAICS guard
-- `usas_autocomplete_recipient` — anti-hallucination recipient guard
-- `usas_naics_hierarchy` — navigate NAICS tree
-- `usas_glossary` — 151 federal-spending terms
-- `usas_list_toptier_agencies` — list all toptier agencies + obligations
+- `cve_lookup` — look up NIST NVD CVE records
+- `cisa_kev_lookup` — filter the CISA Known Exploited Vulnerabilities catalog (binding BOD 22-01 remediation due-dates)
 </details>
 
 <details>
-<summary><b>Federal Register — rules + notices (3 tools)</b></summary>
+<summary><b>Trade & tariffs — USITC (1 tool)</b></summary>
 
-- `fed_register_search_documents` — search by query / agency / type / date
-- `fed_register_get_document` — citation, body URL, CFR refs
-- `fed_register_list_agencies` — agency slugs reference
+- `hts_lookup` — US import-tariff classification + duty rates from the USITC Harmonized Tariff Schedule
 </details>
 
 <details>
-<summary><b>eCFR — Code of Federal Regulations (2 tools)</b></summary>
+<summary><b>Geo, disaster & state/local open data — Census · FEMA · Socrata · CKAN (8 tools)</b></summary>
+
+- `census_geocode_address` — resolve a one-line US address → matched address + Census geographies (tract, CD, place)
+- `census_geographies_by_coordinates` — resolve a longitude/latitude point → Census geographies
+- `fema_disaster_declarations` — FEMA disaster / emergency declarations by state, type, incident, year
+- `fema_search_public_assistance` — FEMA Public Assistance funded projects
+- `socrata_discover_datasets` — find Socrata dataset 4x4 ids by keyword
+- `socrata_query` — query rows from an allowlisted Socrata/SODA open-data portal
+- `ckan_discover_datasets` — find CKAN datastore resource ids by keyword
+- `ckan_query` — query rows from an allowlisted CKAN datastore resource (state/city spend/checkbook)
+</details>
 
-- `ecfr_search` — full-text search (titleNumber=48 for FAR)
-- `ecfr_list_titles` — all 50 CFR titles + last-amended dates
+<details>
+<summary><b>Dataset discovery — data.gov (1 tool)</b></summary>
+
+- `datagov_search_datasets` — search the data.gov v4 catalog for federal open datasets across all publishing agencies
 </details>
 
 <details>
-<summary><b>Grants.gov — federal grants (2 tools)</b></summary>
+<summary><b>Small business — SBA (1 tool)</b></summary>
 
-- `grants_search` — opportunity search
-- `grants_get_opportunity` — full grant detail
+- `sba_size_standard` — SBA small-business size standard for a 6-digit NAICS (set-aside eligibility gate)
 </details>
 
 ---
 
+## Reliability & offline snapshots
+
+This server is built around one rule: **honest failure over confident fabrication.** Everything below is about *availability* of public data — none of it bypasses access controls.
+
+**Keyless-first, and a down source *throws*.** Every source works with no API key. When a source is rate-limited, blocked, or down, the tool returns a **typed error** (`rate_limited` / `upstream_unavailable` / `schema_drift` / …) — it never invents rows and never reports a DOWN service as "0 results" or "not found". A genuine empty result and an outage are always distinguishable.
+
+**Optional offline snapshots (off by default).** Some reference data changes slowly — the toptier-agency list, the top-level NAICS tree, the USAspending glossary, SBA size standards, the latest Treasury "Debt to the Penny." For those, you can optionally host a **snapshot mirror**: a static, public-data cache the server reads *only* when the live source is unreachable from your egress. A served snapshot is **never presented as live** — the response carries `_meta.dataPath: "snapshot"` plus an `asOf` timestamp, and `complete` is forced off, so an AI agent (and you) always see the staleness. Unset ⇒ pure live, byte-for-byte identical to today's behavior.
+
+- **Enable it:** set `SAMGOV_SNAPSHOT_BASE_URL` to the base URL where you host the snapshots. Unset (the default) = live-only, no snapshot path is ever added.
+
+  ```json
+  { "mcpServers": { "sam-gov": { "command": "mcp-sam-gov",
+      "env": { "SAMGOV_SNAPSHOT_BASE_URL": "https://your-cdn.example.com/snapshots" } } } }
+  ```
+
+- **Build the snapshots:** run `node scripts/build-snapshots.mjs` from any clean, non-blocked egress (a laptop / home / clean CI runner). It **self-diagnoses per-source reachability**, prints a reachability table, and writes a `manifest.json`. On partial coverage it refreshes only the sources it can reach and **leaves the last-good file in place** for the rest (stale-but-honest, never blanked). It exits non-zero only when *zero* sources were reachable (a fully blocked egress — the signal to re-run from a cleaner one).
+
+- **The honest boundary.** This covers **public-data availability only.** The snapshot builder ingests only public, redistributable (public-domain / CC0) data, and the reader refuses to serve any envelope not marked `accessLevel: "public"`. It **honors rate limits** (a 429 is never routed around), uses **no proxies, no IP rotation, no auth/paywall/CAPTCHA bypass**, and refuses off-host redirects. If a source is blocked, the honest remedy is to build from a cleaner egress — not to evade the block.
+
+---
+
 ## Troubleshooting
 
 | Symptom | Fix |
@@ -412,7 +574,7 @@ const opp = await sam.getOpportunity("5ef3db5daeb54099a96d487783a38bd0");
 ```
 
 ```ts
-// USAspending wrappers (22 functions)
+// USAspending wrappers
 import * as usas from "@cliwant/mcp-sam-gov/usaspending";
 
 const recompete = await usas.searchExpiringContracts({

package/dist/attachments.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @cliwant/mcp-sam-gov/attachments — read the ACTUAL solicitation document.
+ *
+ * Why this exists
+ * ----------------
+ * An AI doing procurement research needs the real RFP/SOW/Q&A/wage-table TEXT,
+ * not just the synopsis (`sam_fetch_description`) or metadata. A SAM notice
+ * carries ATTACHMENTS (`resourceLinks` → keyless download URLs) that hold the
+ * true requirements. The rest of the server exposes those URLs but cannot read
+ * them; this module fetches one keyless and returns its extracted text so the
+ * agent can analyze the buy.
+ *
+ * SAM attachments are predominantly PDF (compressed streams / CID fonts — not
+ * hand-rollable), so PDF text extraction uses `unpdf` (a single self-contained
+ * package that bundles pdfjs; no transitive deps). text/HTML also occur and are
+ * decoded/stripped locally. DOCX is a ZIP whose `word/document.xml` holds the
+ * body text (deflate-compressed); we parse the ZIP container by hand and inflate
+ * that entry with Node's built-in `node:zlib` — NO new dependency. Other
+ * binaries are NOT half-parsed — they return `text:null` with an honest note.
+ *
+ * Truthfulness invariants (a reviewer WILL attack these):
+ *   - A DOWN fetch (5xx / network / timeout) THROWS `upstream_unavailable`
+ *     (retryable). A down service is NOT an empty attachment — never `text:""`.
+ *   - A 404 THROWS `not_found` (the attachment id is gone).
+ *   - A PDF that fails to parse (encrypted/corrupt) → `text:null` +
+ *     `extractionError` note — NEVER a crash, NEVER a fake "".
+ *   - A DOCX that fails to parse (corrupt/not-a-zip/no `word/document.xml`) →
+ *     `text:null` + a disclosed note — NEVER a crash, NEVER a fake "".
+ *   - A non-extractable format (binary) → `text:null` + honest note.
+ *   - SSRF: only sam.gov / api.sam.gov hosts are fetched; anything else →
+ *     `invalid_input` with NO network call.
+ *   - `truncated`/`pages` are honest.
+ */
+import { type MetaBundle } from "./meta.js";
+/** The detected document family. */
+export type AttachmentFormat = "pdf" | "docx" | "html" | "text" | "binary";
+/** The tool's success payload (rides in a MetaBundle). */
+export type AttachmentTextData = {
+    url: string;
+    filename: string | null;
+    contentType: string | null;
+    format: AttachmentFormat;
+    sizeBytes: number;
+    pages: number | null;
+    text: string | null;
+    truncated: boolean;
+    extracted: boolean;
+};
+export type FetchAttachmentTextArgs = {
+    url: string;
+    maxChars?: number;
+};
+/**
+ * Fetch a SAM attachment keyless and return its extracted TEXT.
+ *
+ * See the module header for the truthfulness invariants. Throws a
+ * `ToolErrorCarrier` for: bad/non-SAM URL (`invalid_input`, no fetch), a 404
+ * (`not_found`), or a down fetch (`upstream_unavailable`, retryable). Otherwise
+ * ALWAYS returns a payload — a document we cannot extract yields `text:null` +
+ * a disclosed note, never an exception and never a fabricated string.
+ */
+export declare function fetchAttachmentText(args: FetchAttachmentTextArgs): Promise<MetaBundle<AttachmentTextData>>;
+//# sourceMappingURL=attachments.d.ts.map

package/dist/attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../src/attachments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AA0FtD,oCAAoC;AACpC,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AA8Q3E,0DAA0D;AAC1D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAgOzC"}