@cliwant/mcp-sam-gov 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.ja.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # @cliwant/mcp-sam-gov
2
2
 
3
3
  > **最も包括的なキーレス連邦データ MCP サーバー。**
4
- > SAM.gov · USAspending · SEC EDGAR · OFAC · FDIC · Federal Register · Regulations.gov · eCFR · FAR/DFARS · BLS · Treasury · NIH · NSF · ClinicalTrials · CMS · NVD/CISA · USITC · Census · FEMA ほか **31 のキーレス連邦データソース、111 ツール。**
4
+ > SAM.gov · USAspending · SEC EDGAR · OFAC · FDIC · Federal Register · Regulations.gov · eCFR · FAR/DFARS · BLS · Treasury · NIH · NSF · ClinicalTrials · CMS · NVD/CISA · USITC · Census · FRED · FEMA ほか **34 の連邦データソース、116 ツール。** キーレス優先 — Census business-patterns と FRED のみ無料キーが必要で、残り 32 ソースはキー不要。
5
5
  > API キー不要、登録不要、サインアップ不要。Claude Desktop, Claude Code, Codex CLI, Cursor, Continue, Gemini CLI、すべての MCP ホスト対応。
6
6
 
7
7
  [English README](./README.md) · [한국어 README](./README.ko.md)
@@ -19,13 +19,13 @@
19
19
  | 🕵️ **パートナー・企業の検証** | "この企業をスクリーニング: OFAC 制裁・SAM 除外・単一監査指摘・銀行健全性・EPA 遵守" | OFAC, SAM, FAC, FDIC, EPA ECHO |
20
20
  | 📈 **財務開示 (SEC)** | "この上場企業の売上推移 + 最新 10-K" | SEC EDGAR |
21
21
  | ⚖️ **規制・立法** | "今四半期の VA サイバーセキュリティ規則? 進行中の Regulations.gov docket?" | Federal Register, Regulations.gov, eCFR, FAR/DFARS, Congress.gov, GovInfo |
22
- | 💲 **価格・労務・財政** | "GSA CALC 労務単価バンド、この郡の SCA 賃金決定、CPI エスカレーション" | GSA CALC, SAM WD, BLS, US Treasury |
22
+ | 💲 **価格・労務・財政** | "GSA CALC 労務単価バンド、この郡の SCA 賃金決定、CPI エスカレーション、出張 per-diem 上限" | GSA CALC, SAM WD, BLS, US Census CBP, FRED, US Treasury, GSA per-diem |
23
23
  | 🏥 **医療・研究資金** | "このテーマの NIH/NSF grant、募集中の臨床試験、この医師への業界支払" | NIH RePORTER, NSF, ClinicalTrials, CMS, NPPES |
24
24
  | 🛡 **サイバー遵守** | "この CVE は CISA KEV 必須パッチ一覧にあるか?" | NVD, CISA KEV |
25
25
  | 🌐 **貿易・地理・災害** | "この品目の HTS 関税、この住所の Census tract、この州の FEMA 宣言" | USITC HTS, Census, FEMA, Socrata, CKAN |
26
26
  | 🎓 **grant・データセット** | "過去 30 日のサイバーセキュリティ grant、連邦オープンデータセット発見" | Grants.gov, data.gov |
27
27
 
28
- **31 のキーレス連邦データソース、合計 111 ツール。API キー 0。** (初期の 52 ツール版でおおよそ p50 ~0.25s / p95 ~0.8s を計測 — ソースや上流負荷で変動する近似値であり保証値ではありません。)
28
+ **34 の連邦データソース、合計 116 ツール キーレス優先: Census business-patterns と FRED のみ無料キーが必要で、残り 32 ソースはキー不要。** (初期の 52 ツール版でおおよそ p50 ~0.25s / p95 ~0.8s を計測 — ソースや上流負荷で変動する近似値であり保証値ではありません。)
29
29
 
30
30
  ---
31
31
 
@@ -52,7 +52,7 @@ Claude Code (CLI) を既に使用している場合:
52
52
  /plugin install cliwant/mcp-sam-gov
53
53
  ```
54
54
 
55
- MCP サーバー + Claude が 111 ツールをいつ・どう呼ぶかを教える [SKILL.md ワークフローガイド](./skills/sam-gov/SKILL.md) を同時登録。
55
+ MCP サーバー + Claude が 116 ツールをいつ・どう呼ぶかを教える [SKILL.md ワークフローガイド](./skills/sam-gov/SKILL.md) を同時登録。
56
56
 
57
57
  ### 🔵 パス 3 — Codex / Cursor / Continue / Gemini 等の手動インストール
58
58
 
@@ -164,22 +164,23 @@ npm install --omit=dev
164
164
 
165
165
  ---
166
166
 
167
- ## ツールカタログ (111)
167
+ ## ツールカタログ (116)
168
168
 
169
- ワークフロー別グループ。全ツールは既定でキーレス。全 per-tool 一覧と入力 schema・誠実性 caveat の原文は [英語 README のカタログセクション](./README.md#tool-catalog-111-tools) を正とします。
169
+ ワークフロー別グループ。キーレス優先 — 大半はキー不要、Census business-patterns と FRED は無料キーが必要。全 per-tool 一覧と入力 schema・誠実性 caveat の原文は [英語 README のカタログセクション](./README.md#tool-catalog-116-tools) を正とします。
170
170
 
171
171
  - **案件 + ソリシテーション — SAM.gov + Grants.gov (10)**: `sam_search_opportunities` `sam_search_shaping` `sam_get_opportunity` `sam_fetch_description` `sam_fetch_attachment_text` `sam_attachment_url` `sam_lookup_organization` `sam_lookup_notice_fields` `grants_search` `grants_get_opportunity`
172
172
  - **spending・受注・競合 — USAspending + FPDS + GAO (29)**: `usas_search_awards` `usas_search_individual_awards` `usas_get_award_detail` `usas_search_awards_by_recipient` `usas_search_subawards` `usas_search_recompetes` `usas_search_expiring_contracts`(deprecated) `usas_analyze_incumbent` `usas_search_teaming_partners` `usas_spending_over_time` `usas_search_agency_spending` `usas_search_subagency_spending` `usas_search_psc_spending` `usas_search_cfda_spending` `usas_search_state_spending` `usas_search_federal_account_spending` `usas_search_recipients` `usas_get_recipient_profile` `usas_get_agency_profile` `usas_get_agency_awards_summary` `usas_get_agency_budget_function` `usas_list_toptier_agencies` `usas_lookup_agency` `usas_autocomplete_naics` `usas_autocomplete_recipient` `usas_naics_hierarchy` `usas_glossary` `fpds_search_awards` `gao_protest_lookup`
173
173
  - **パートナー・企業の検証 — OFAC · SAM · FAC · FDIC · EPA (14)**: `ofac_screen_entity` `sam_check_exclusions` `sam_integrity_lookup` `fac_search_audits` `fac_get_findings` `fdic_search_institutions` `fdic_institution_financials` `fdic_risk_ratios` `fdic_institution_history` `fdic_branch_deposits` `fdic_bank_failures` `fdic_industry_summary` `echo_search_facilities` `echo_facility_report`
174
174
  - **財務開示 — SEC EDGAR (8)**: `edgar_lookup_cik` `edgar_company_filings` `edgar_company_facts` `edgar_company_concept` `edgar_xbrl_frames` `edgar_full_text_search` `edgar_filing_index` `edgar_daily_filing_index`
175
175
  - **規制・立法 — Federal Register · Regulations.gov · eCFR · FAR · Congress · GovInfo (18)**: `fed_register_search_documents` `fed_register_get_document` `fed_register_public_inspection` `fed_register_list_agencies` `regulations_search_dockets` `regulations_search_documents` `regulations_search_comments` `regulations_get_docket` `ecfr_search` `ecfr_list_titles` `far_clause_lookup` `far_search` `far_compliance_matrix` `congress_search_bills` `congress_get_bill` `govinfo_search_packages` `govinfo_get_package` `govinfo_list_collections`
176
- - **価格・労務・財政 — GSA CALC · SAM WD · BLS · Treasury (10)**: `gsa_benchmark_labor_rates` `sam_search_wage_determinations` `sam_get_wage_rates` `bls_timeseries` `bls_oews_wages` `bls_qcew` `treasury_debt_to_penny` `treasury_avg_interest_rates` `treasury_monthly_statement` `treasury_query_dataset`
176
+ - **価格・労務・財政 — GSA CALC · SAM WD · BLS · Census CBP · FRED · Treasury · GSA per-diem (14)**: `gsa_benchmark_labor_rates` `sam_search_wage_determinations` `sam_get_wage_rates` `bls_timeseries` `bls_oews_wages` `bls_qcew` `treasury_debt_to_penny` `treasury_avg_interest_rates` `treasury_monthly_statement` `treasury_query_dataset` `census_business_patterns`(無料 CENSUS_API_KEY 必要) `fred_search_series`(無料 FRED_API_KEY 必要) `fred_series_observations`(無料 FRED_API_KEY 必要) `gsa_perdiem_rates`(DEMO_KEY キーレス)
177
177
  - **医療・研究資金 — NIH · NSF · ClinicalTrials · CMS · NPPES (9)**: `nih_reporter_search_projects` `nsf_search_awards` `nsf_get_award` `clinicaltrials_search_studies` `clinicaltrials_get_study` `clinicaltrials_facet_counts` `cms_search_datasets` `cms_query_dataset` `nppes_lookup_provider`
178
178
  - **サイバー遵守 — NVD + CISA KEV (2)**: `cve_lookup` `cisa_kev_lookup`
179
179
  - **貿易・関税 — USITC (1)**: `hts_lookup`
180
180
  - **地理・災害・州/市オープンデータ — Census · FEMA · Socrata · CKAN (8)**: `census_geocode_address` `census_geographies_by_coordinates` `fema_disaster_declarations` `fema_search_public_assistance` `socrata_discover_datasets` `socrata_query` `ckan_discover_datasets` `ckan_query`
181
181
  - **データセット発見 — data.gov (1)**: `datagov_search_datasets`
182
182
  - **中小企業 — SBA (1)**: `sba_size_standard`
183
+ - **サーバーユーティリティ — キー探索 (1)**: `api_key_status`(各ソースに必要なキー・required/optional・登録 URL・現在の設定有無を列挙; 値は表示しない)
183
184
 
184
185
  ---
185
186
 
@@ -188,8 +189,9 @@ npm install --omit=dev
188
189
  本サーバーの原則は一つ: **もっともらしい捏造より誠実な失敗。** 以下はすべて公開データの*可用性*に関するものであり、いかなるアクセス制御も回避しません。
189
190
 
190
191
  - **キーレス優先、ダウンしたソースは例外を*投げる*。** すべてのソースが API キーなしで動作します。ソースが rate-limit・ブロック・ダウンした場合、ツールは**型付きエラー**(`rate_limited` / `upstream_unavailable` / `schema_drift` …)を返し、行を捏造したりダウンしたサービスを「結果 0」/「見つからない」と報告しません。本物の空結果と障害は常に区別できます。
191
- - **任意のオフラインスナップショット (既定 off)。** ゆっくり変わる参照データ(toptier 機関一覧、上位 NAICS ツリー、USAspending 用語集、SBA 規模基準、最新 Treasury「Debt to the Penny」)に限り、**スナップショットミラー**を自前でホストできます。ライブソースが自身の egress から到達不能なときだけ読む静的な公開データキャッシュです。スナップショットが提供されるとき**決してライブとして表示しません** — 応答に `_meta.dataPath: "snapshot"` + `asOf` タイムスタンプが付き、`complete` は強制的に off。未設定なら純ライブ(今日と byte-identical)
192
- - **有効化:** `SAMGOV_SNAPSHOT_BASE_URL` をスナップショットのホスティング base URL に設定。未設定(既定) = ライブ専用。
192
+ - **オフラインスナップショット (既定 on)。** ゆっくり変わる参照データ(toptier 機関一覧、上位 NAICS ツリー、USAspending 用語集、SBA 規模基準、最新 Treasury「Debt to the Penny」)は、ライブの連邦ソースが egress から一時的に到達不能なとき、サーバーが既定で `raw.githubusercontent.com/cliwant/mcp-sam-gov/snapshots` にホストされた**公開・週次更新スナップショット**へフォールバックします。ライブの**ハード障害**(障害 / IP 評判ブロック)時のみ取得し、通常運用中は決して取得しません 公開データ、テレメトリなし。スナップショットが提供されるとき**決してライブとして表示しません** — 応答に `_meta.dataPath: "snapshot"` + `asOf` タイムスタンプが付き、`complete` は強制的に off。rate limit(429)は常に**尊重**し、ミラーへ回避しません。
193
+ - **無効化(純ライブ専用):** `SAMGOV_SNAPSHOT_BASE_URL=off` を設定するとスナップショット経路は追加されず、ライブ専用クライアントと byte-identical。
194
+ - **自前ミラーを指定:** `SAMGOV_SNAPSHOT_BASE_URL` を自分の base URL に設定すれば、公開既定値の代わりに自前ホスティング。
193
195
  - **スナップショットのビルド:** ブロックされていないクリーンな egress(ノート PC / 自宅 / クリーンな CI)から `node scripts/build-snapshots.mjs` を実行。**ソース別到達性を自己診断**し、reachability 表 + `manifest.json` を出力します。部分カバレッジでは到達できるソースのみ更新し、残りは **last-good ファイルをそのまま残します**(古くても誠実、決して空にしない)。*すべての*ソースが到達不能なときのみ非ゼロ終了(egress 全面ブロックの合図 — よりクリーンな egress で再実行)。
194
196
  - **誠実な境界。** これは**公開データの可用性のみ**を扱います。ビルダーは公開・再配布可能(public-domain / CC0)なデータのみ取り込み、リーダーは `accessLevel: "public"` でない封筒の提供を拒否します。**rate limit を尊重**(429 を回避しない)し、**プロキシ・IP ローテーション・認証/ペイウォール/CAPTCHA 回避なし**、off-host リダイレクトも拒否します。ブロックされた場合の誠実な解決策は、よりクリーンな egress からビルドすることであり、ブロックの回避ではありません。
195
197
 
package/README.ko.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # @cliwant/mcp-sam-gov
2
2
 
3
3
  > **가장 포괄적인 keyless 연방 데이터 MCP 서버.**
4
- > SAM.gov · USAspending · SEC EDGAR · OFAC · FDIC · Federal Register · Regulations.gov · eCFR · FAR/DFARS · BLS · Treasury · NIH · NSF · ClinicalTrials · CMS · NVD/CISA · USITC · Census · FEMA 외 **31keyless 연방 데이터 소스, 111개 도구.**
4
+ > SAM.gov · USAspending · SEC EDGAR · OFAC · FDIC · Federal Register · Regulations.gov · eCFR · FAR/DFARS · BLS · Treasury · NIH · NSF · ClinicalTrials · CMS · NVD/CISA · USITC · Census · FRED · FEMA 외 **34개 연방 데이터 소스, 116개 도구.** keyless 우선 — Census business-patterns 와 FRED 만 무료 키가 필요하고 나머지 32개 소스는 키가 필요 없습니다.
5
5
  > API 키 / 등록 / 가입 불필요. Claude Desktop, Claude Code, Codex CLI, Cursor, Continue, Gemini CLI, 모든 MCP 호스트 호환.
6
6
 
7
7
  [English README](./README.md) · [日本語 README](./README.ja.md)
@@ -19,13 +19,13 @@
19
19
  | 🕵️ **파트너·기업 검증** | "이 업체 스크리닝: OFAC 제재·SAM 배제·단일감사 지적·은행 건전성·EPA 준수" | OFAC, SAM, FAC, FDIC, EPA ECHO |
20
20
  | 📈 **재무 공시 (SEC)** | "이 상장사 매출 추이 + 최신 10-K" | SEC EDGAR |
21
21
  | ⚖️ **규정·입법** | "이번 분기 VA 사이버보안 규정? 열려있는 Regulations.gov docket?" | Federal Register, Regulations.gov, eCFR, FAR/DFARS, Congress.gov, GovInfo |
22
- | 💲 **가격·노무·재정** | "GSA CALC 노무 단가 밴드, 이 카운티 SCA 임금결정, CPI 에스컬레이션" | GSA CALC, SAM WD, BLS, US Treasury |
22
+ | 💲 **가격·노무·재정** | "GSA CALC 노무 단가 밴드, 이 카운티 SCA 임금결정, CPI 에스컬레이션, 출장 per-diem 상한" | GSA CALC, SAM WD, BLS, US Census CBP, FRED, US Treasury, GSA per-diem |
23
23
  | 🏥 **보건·연구 자금** | "이 주제 NIH/NSF grant, 모집 중 임상시험, 이 의사에 대한 산업계 지급" | NIH RePORTER, NSF, ClinicalTrials, CMS, NPPES |
24
24
  | 🛡 **사이버 준수** | "이 CVE 가 CISA KEV 필수 패치 목록에 있나?" | NVD, CISA KEV |
25
25
  | 🌐 **무역·지리·재난** | "이 품목 HTS 관세, 이 주소 Census tract, 이 주의 FEMA 선포" | USITC HTS, Census, FEMA, Socrata, CKAN |
26
26
  | 🎓 **grant·데이터셋** | "최근 30일 사이버보안 grant, 연방 오픈 데이터셋 발굴" | Grants.gov, data.gov |
27
27
 
28
- **31keyless 연방 데이터 소스, 총 111도구. API 0개.** (초기 52-도구 빌드 기준 대략 p50 ~0.25s / p95 ~0.8s 측정 — 소스·업스트림 부하에 따라 변동하는 근사치이며 보장값이 아님.)
28
+ **34개 연방 데이터 소스, 총 116도구 keyless 우선: Census business-patterns 와 FRED 만 무료 키가 필요하고 나머지 32개 소스는 키가 필요 없습니다.** (초기 52-도구 빌드 기준 대략 p50 ~0.25s / p95 ~0.8s 측정 — 소스·업스트림 부하에 따라 변동하는 근사치이며 보장값이 아님.)
29
29
 
30
30
  ---
31
31
 
@@ -52,7 +52,7 @@ PowerShell, npm 등 필요 없음.
52
52
  /plugin install cliwant/mcp-sam-gov
53
53
  ```
54
54
 
55
- MCP 서버 + Claude 가 111개 도구를 언제 / 어떻게 호출할지 가르치는 [SKILL.md 워크플로 가이드](./skills/sam-gov/SKILL.md) 동시 등록.
55
+ MCP 서버 + Claude 가 116개 도구를 언제 / 어떻게 호출할지 가르치는 [SKILL.md 워크플로 가이드](./skills/sam-gov/SKILL.md) 동시 등록.
56
56
 
57
57
  ### 🔵 경로 3 — Codex / Cursor / Continue / Gemini 등 수동 설치
58
58
 
@@ -164,22 +164,23 @@ npm install --omit=dev
164
164
 
165
165
  ---
166
166
 
167
- ## 도구 카탈로그 (111개)
167
+ ## 도구 카탈로그 (116개)
168
168
 
169
- 워크플로별 그룹. 모든 도구는 기본 keyless. 전체 per-tool 목록과 입력 schema·정직성 caveat 원문은 [영문 README 의 카탈로그 섹션](./README.md#tool-catalog-111-tools)을 기준으로 하세요.
169
+ 워크플로별 그룹. keyless 우선 대부분 키가 필요 없고, Census business-patterns 와 FRED 는 무료 키가 필요합니다. 전체 per-tool 목록과 입력 schema·정직성 caveat 원문은 [영문 README 의 카탈로그 섹션](./README.md#tool-catalog-116-tools)을 기준으로 하세요.
170
170
 
171
171
  - **입찰 + 솔리시테이션 — SAM.gov + Grants.gov (10)**: `sam_search_opportunities` `sam_search_shaping` `sam_get_opportunity` `sam_fetch_description` `sam_fetch_attachment_text` `sam_attachment_url` `sam_lookup_organization` `sam_lookup_notice_fields` `grants_search` `grants_get_opportunity`
172
172
  - **spending·수주·경쟁 — USAspending + FPDS + GAO (29)**: `usas_search_awards` `usas_search_individual_awards` `usas_get_award_detail` `usas_search_awards_by_recipient` `usas_search_subawards` `usas_search_recompetes` `usas_search_expiring_contracts`(deprecated) `usas_analyze_incumbent` `usas_search_teaming_partners` `usas_spending_over_time` `usas_search_agency_spending` `usas_search_subagency_spending` `usas_search_psc_spending` `usas_search_cfda_spending` `usas_search_state_spending` `usas_search_federal_account_spending` `usas_search_recipients` `usas_get_recipient_profile` `usas_get_agency_profile` `usas_get_agency_awards_summary` `usas_get_agency_budget_function` `usas_list_toptier_agencies` `usas_lookup_agency` `usas_autocomplete_naics` `usas_autocomplete_recipient` `usas_naics_hierarchy` `usas_glossary` `fpds_search_awards` `gao_protest_lookup`
173
173
  - **파트너·기업 검증 — OFAC · SAM · FAC · FDIC · EPA (14)**: `ofac_screen_entity` `sam_check_exclusions` `sam_integrity_lookup` `fac_search_audits` `fac_get_findings` `fdic_search_institutions` `fdic_institution_financials` `fdic_risk_ratios` `fdic_institution_history` `fdic_branch_deposits` `fdic_bank_failures` `fdic_industry_summary` `echo_search_facilities` `echo_facility_report`
174
174
  - **재무 공시 — SEC EDGAR (8)**: `edgar_lookup_cik` `edgar_company_filings` `edgar_company_facts` `edgar_company_concept` `edgar_xbrl_frames` `edgar_full_text_search` `edgar_filing_index` `edgar_daily_filing_index`
175
175
  - **규정·입법 — Federal Register · Regulations.gov · eCFR · FAR · Congress · GovInfo (18)**: `fed_register_search_documents` `fed_register_get_document` `fed_register_public_inspection` `fed_register_list_agencies` `regulations_search_dockets` `regulations_search_documents` `regulations_search_comments` `regulations_get_docket` `ecfr_search` `ecfr_list_titles` `far_clause_lookup` `far_search` `far_compliance_matrix` `congress_search_bills` `congress_get_bill` `govinfo_search_packages` `govinfo_get_package` `govinfo_list_collections`
176
- - **가격·노무·재정 — GSA CALC · SAM WD · BLS · Treasury (10)**: `gsa_benchmark_labor_rates` `sam_search_wage_determinations` `sam_get_wage_rates` `bls_timeseries` `bls_oews_wages` `bls_qcew` `treasury_debt_to_penny` `treasury_avg_interest_rates` `treasury_monthly_statement` `treasury_query_dataset`
176
+ - **가격·노무·재정 — GSA CALC · SAM WD · BLS · Census CBP · FRED · Treasury · GSA per-diem (14)**: `gsa_benchmark_labor_rates` `sam_search_wage_determinations` `sam_get_wage_rates` `bls_timeseries` `bls_oews_wages` `bls_qcew` `treasury_debt_to_penny` `treasury_avg_interest_rates` `treasury_monthly_statement` `treasury_query_dataset` `census_business_patterns`(무료 CENSUS_API_KEY 필요) `fred_search_series`(무료 FRED_API_KEY 필요) `fred_series_observations`(무료 FRED_API_KEY 필요) `gsa_perdiem_rates`(DEMO_KEY keyless)
177
177
  - **보건·연구 자금 — NIH · NSF · ClinicalTrials · CMS · NPPES (9)**: `nih_reporter_search_projects` `nsf_search_awards` `nsf_get_award` `clinicaltrials_search_studies` `clinicaltrials_get_study` `clinicaltrials_facet_counts` `cms_search_datasets` `cms_query_dataset` `nppes_lookup_provider`
178
178
  - **사이버 준수 — NVD + CISA KEV (2)**: `cve_lookup` `cisa_kev_lookup`
179
179
  - **무역·관세 — USITC (1)**: `hts_lookup`
180
180
  - **지리·재난·주/시 오픈데이터 — Census · FEMA · Socrata · CKAN (8)**: `census_geocode_address` `census_geographies_by_coordinates` `fema_disaster_declarations` `fema_search_public_assistance` `socrata_discover_datasets` `socrata_query` `ckan_discover_datasets` `ckan_query`
181
181
  - **데이터셋 발굴 — data.gov (1)**: `datagov_search_datasets`
182
182
  - **소상공인 — SBA (1)**: `sba_size_standard`
183
+ - **서버 유틸리티 — 키 발견 (1)**: `api_key_status`(각 소스에 필요한 키·required/optional·발급 URL·현재 설정 여부 나열; 값은 노출 안 함)
183
184
 
184
185
  ---
185
186
 
@@ -188,8 +189,9 @@ npm install --omit=dev
188
189
  이 서버의 원칙은 하나입니다: **그럴듯한 조작보다 정직한 실패.** 아래는 모두 공개 데이터의 *가용성*에 관한 것이며, 어떤 접근 통제도 우회하지 않습니다.
189
190
 
190
191
  - **Keyless 우선, 다운된 소스는 예외를 *던진다*.** 모든 소스가 API 키 없이 동작합니다. 소스가 rate-limit·차단·다운되면 도구는 **타입이 지정된 에러**(`rate_limited` / `upstream_unavailable` / `schema_drift` …)를 반환하며, 행을 지어내거나 다운된 서비스를 "결과 0" / "없음"으로 보고하지 않습니다. 진짜 빈 결과와 장애는 항상 구별됩니다.
191
- - **선택적 오프라인 스냅샷 (기본 off).** 느리게 바뀌는 참조 데이터(toptier 기관 목록, 상위 NAICS 트리, USAspending 용어집, SBA 규모 기준, 최신 Treasury "Debt to the Penny") 한해, **스냅샷 미러**를 직접 호스팅할 있습니다. 라이브 소스가 자신의 egress 에서 도달 불가일 때만 읽는 정적 공개-데이터 캐시입니다. 스냅샷이 서빙되면 **절대 라이브처럼 표시하지 않습니다** — 응답에 `_meta.dataPath: "snapshot"` + `asOf` 타임스탬프가 붙고 `complete` 는 강제로 꺼집니다. 미설정 순수 라이브(오늘과 byte-identical).
192
- - **켜기:** `SAMGOV_SNAPSHOT_BASE_URL` 스냅샷 호스팅 base URL 설정. 미설정(기본) = 라이브 전용.
192
+ - **오프라인 스냅샷 (기본 on).** 느리게 바뀌는 참조 데이터(toptier 기관 목록, 상위 NAICS 트리, USAspending 용어집, SBA 규모 기준, 최신 Treasury "Debt to the Penny")는, 라이브 연방 소스가 egress 에서 잠시 도달 불가일 때 서버가 기본적으로 `raw.githubusercontent.com/cliwant/mcp-sam-gov/snapshots` 에 호스팅된 **공개·주간 갱신 스냅샷**으로 폴백합니다. 라이브 **하드 실패**(장애 / IP 평판 차단) 시에만 가져오며 평상시엔 절대 아닙니다 — 공개 데이터, 텔레메트리 없음. 스냅샷이 서빙되면 **절대 라이브처럼 표시하지 않습니다** — 응답에 `_meta.dataPath: "snapshot"` + `asOf` 타임스탬프가 붙고 `complete` 는 강제로 꺼집니다. rate limit(429)은 항상 **준수**하며 미러로 우회하지 않습니다.
193
+ - **끄기(순수 라이브 전용):** `SAMGOV_SNAPSHOT_BASE_URL=off` 설정 스냅샷 경로가 추가되지 않고 라이브 전용 클라이언트와 byte-identical.
194
+ - **자체 미러 지정:** `SAMGOV_SNAPSHOT_BASE_URL` 을 자신의 base URL 로 설정하면 공개 기본값 대신 직접 호스팅.
193
195
  - **스냅샷 빌드:** 차단되지 않은 깨끗한 egress(노트북 / 집 / 깨끗한 CI)에서 `node scripts/build-snapshots.mjs` 실행. **소스별 도달성을 자가 진단**하고 reachability 표 + `manifest.json` 을 출력합니다. 부분 커버리지에서는 도달 가능한 소스만 갱신하고 나머지는 **last-good 파일을 그대로 둡니다**(오래됐어도 정직, 절대 비우지 않음). *모든* 소스가 도달 불가일 때만 non-zero 종료(egress 전면 차단 신호 — 더 깨끗한 egress 에서 재실행).
194
196
  - **정직한 경계.** 이것은 **공개-데이터 가용성만** 다룹니다. 빌더는 공개·재배포 가능(public-domain / CC0) 데이터만 수집하고, 리더는 `accessLevel: "public"` 이 아닌 봉투는 서빙을 거부합니다. **rate limit 을 준수**(429 를 우회하지 않음)하고 **프록시·IP 로테이션·인증/페이월/CAPTCHA 우회 없음**, off-host 리다이렉트도 거부합니다. 차단되면 정직한 해법은 더 깨끗한 egress 에서 빌드하는 것이지 차단을 회피하는 것이 아닙니다.
195
197
 
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  ### **$4 trillion of public federal data, one `npm install` away.**
6
6
 
7
- 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.
7
+ The most comprehensive **keyless-first** MCP server for US federal contracting + spending + regulation + partner vetting. **116 tools across 34 federal data sources** keyless-first: only Census business-patterns and FRED need a free key; the other 32 sources need none. Works today, in any AI agent.
8
8
 
9
9
  [![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)
10
10
  [![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
50
50
  |---|---|
51
51
  | GovWin: $30K-$100K/yr per seat | Free, MIT license |
52
52
  | API key registration → wait 24h → quota tier shopping | `npm install` → working in 60s |
53
- | 5+ separate vendor APIs / scrapers | 1 unified surface, 111 tools across 31 sources |
53
+ | 5+ separate vendor APIs / scrapers | 1 unified surface, 116 tools across 34 sources |
54
54
  | LLMs hallucinate NAICS codes / agency names | Anti-hallucination autocomplete guards built-in |
55
55
  | Brittle scraping breaks weekly | Daily live smoke test ([badge above](#)) |
56
56
  | Procurement officer → IT ticket → 3-week wait | Claude Desktop double-click install |
@@ -68,13 +68,13 @@ The federal data this wraps is **public domain**. There is no good reason it sho
68
68
  | 🕵️ **Entity & partner vetting** | "Screen this firm: OFAC sanctions, SAM exclusions, single-audit findings, bank health, EPA compliance" | OFAC, SAM, FAC, FDIC, EPA ECHO |
69
69
  | 📈 **Financial disclosure (SEC)** | "Pull this public company's revenue trend and latest 10-K filings" | SEC EDGAR |
70
70
  | ⚖️ **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 |
71
- | 💲 **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 |
71
+ | 💲 **Pricing, labor & fiscal** | "GSA CALC labor-rate band for a systems analyst; SCA wage determination for this county; CPI escalation; per-diem cap for a trip" | GSA CALC, SAM WDs, BLS, US Census CBP, FRED, US Treasury, GSA per-diem |
72
72
  | 🏥 **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 |
73
73
  | 🛡 **Cyber compliance** | "Is this CVE on the CISA KEV must-patch list?" | NVD, CISA KEV |
74
74
  | 🌐 **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 |
75
75
  | 🎓 **Grants & datasets** | "Cybersecurity grants posted in the last 30 days; discover federal open datasets" | Grants.gov, data.gov |
76
76
 
77
- **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.)
77
+ **116 tools across 34 federal data sources keyless-first: only Census business-patterns and FRED need a free key; the other 32 sources need none.** (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.)
78
78
 
79
79
  ---
80
80
 
@@ -101,7 +101,7 @@ If you already use Claude Code (the CLI):
101
101
  /plugin install cliwant/mcp-sam-gov
102
102
  ```
103
103
 
104
- 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.
104
+ 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 116 tools.
105
105
 
106
106
  ### 🔵 Path 3 — Manual install for any MCP host (Codex, Cursor, Continue, Gemini)
107
107
 
@@ -169,7 +169,7 @@ Then point your host config at the absolute path:
169
169
 
170
170
  (Or skip this entirely — use Path 1's `.mcpb` and it auto-configures.)
171
171
 
172
- 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)".
172
+ Restart Claude Desktop fully (system tray quit on Windows / Quit menu on macOS), then look for the 🔨 icon. You should see "sam-gov (116 tools)".
173
173
 
174
174
  ### Claude Code
175
175
 
@@ -340,11 +340,39 @@ A handful of sources ride the shared **api.data.gov** gateway — Congress.gov,
340
340
 
341
341
  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.
342
342
 
343
+ ### Keys & higher limits — the full inventory
344
+
345
+ **Most tools are keyless.** Only **Census** (`census_business_patterns`) and **FRED** (`fred_search_series`, `fred_series_observations`) *require* a key — those sources have no keyless tier, so the tool throws without one. The other five keys are *optional*: they only raise a rate limit or unlock a single filter. **Every key below is free.**
346
+
347
+ | Env var | Required? | What it unlocks | Free signup |
348
+ |---|---|---|---|
349
+ | `CENSUS_API_KEY` | **Required** | `census_business_patterns` (no keyless tier — throws without it) | [api.census.gov/data/key_signup.html](https://api.census.gov/data/key_signup.html) |
350
+ | `FRED_API_KEY` | **Required** | the 2 FRED tools (no keyless tier — throw without it) | [fred.stlouisfed.org/docs/api/api_key.html](https://fred.stlouisfed.org/docs/api/api_key.html) |
351
+ | `DATA_GOV_API_KEY` | Optional | higher limits on all api.data.gov sources (Regulations.gov, FAC, NPPES, CMS, data.gov catalog, GSA per-diem) — lifts the shared `DEMO_KEY` cap | [api.data.gov/signup](https://api.data.gov/signup/) |
352
+ | `SAM_GOV_API_KEY` | Optional | authenticated SAM.gov v2 search + the organization-name filter | [open.gsa.gov/api/get-opportunities-public-api](https://open.gsa.gov/api/get-opportunities-public-api/) |
353
+ | `BLS_API_KEY` | Optional | the BLS v2 tier (~500 queries/day vs keyless ~25/day) | [data.bls.gov/registrationEngine](https://data.bls.gov/registrationEngine/) |
354
+ | `NVD_API_KEY` | Optional | a higher NVD rate limit (`cve_lookup`) | [nvd.nist.gov/developers/request-an-api-key](https://nvd.nist.gov/developers/request-an-api-key) |
355
+ | `SOCRATA_APP_TOKEN` | Optional | higher Socrata throttling limits | [evergreen.data.socrata.com/signup](https://evergreen.data.socrata.com/signup) |
356
+
357
+ **Two ways to set any key** — pick one:
358
+
359
+ 1. **Host env block** — the `"env": { … }` object shown in the examples above.
360
+ 2. **A `.env` file** in the server's working directory — configure your keys **once**:
361
+ ```
362
+ CENSUS_API_KEY=your-key-here
363
+ FRED_API_KEY=your-key-here
364
+ # optional — raise limits / unlock filters
365
+ SAM_GOV_API_KEY=your-key-here
366
+ ```
367
+ The server auto-loads `.env` at startup. A real environment variable always wins over `.env` (standard precedence), and `.env` is git-ignored so your keys never get committed.
368
+
369
+ **Ask the server which keys it needs.** The keyless **`api_key_status`** tool lists every key, whether it's required or optional, the free signup URL + what it unlocks, and whether each is **currently configured** (a boolean — the key value is never shown). Creating the account at the signup URL is your one manual step; the server automates *discovery* (`api_key_status`) and *configuration* (`.env`). To confirm a key actually works, call that source's own tool.
370
+
343
371
  ---
344
372
 
345
- ## Tool catalog (111 tools)
373
+ ## Tool catalog (116 tools)
346
374
 
347
- 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.
375
+ Grouped by workflow. Keyless-first most tools need no key; Census business-patterns and FRED require a free key, and a handful of others 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.
348
376
 
349
377
  <details>
350
378
  <summary><b>Opportunities & solicitations — SAM.gov + Grants.gov (10 tools)</b></summary>
@@ -451,7 +479,7 @@ Grouped by workflow. Every tool is keyless by default; a handful gain higher lim
451
479
  </details>
452
480
 
453
481
  <details>
454
- <summary><b>Pricing, labor & fiscal — GSA CALC · SAM WDs · BLS · US Treasury (10 tools)</b></summary>
482
+ <summary><b>Pricing, labor & fiscal — GSA CALC · SAM WDs · BLS · Census CBP · FRED · US Treasury · GSA per-diem (14 tools)</b></summary>
455
483
 
456
484
  - `gsa_benchmark_labor_rates` — GSA CALC awarded ceiling-rate market band for a labor category (a distribution, not one price)
457
485
  - `sam_search_wage_determinations` — find SCA / Davis-Bacon wage determinations for a locality
@@ -463,6 +491,10 @@ Grouped by workflow. Every tool is keyless by default; a handful gain higher lim
463
491
  - `treasury_avg_interest_rates` — average interest rate the Treasury pays by security type
464
492
  - `treasury_monthly_statement` — Monthly Treasury Statement: receipts, outlays, deficit/surplus by month
465
493
  - `treasury_query_dataset` — escape-hatch query over 5 confirmed Treasury Fiscal Data datasets
494
+ - `census_business_patterns` — establishments / employment / annual payroll by NAICS × geography (Census CBP; requires free CENSUS_API_KEY)
495
+ - `fred_search_series` — search the FRED macroeconomic series catalog (GDP/CPI/rates/unemployment; requires free FRED_API_KEY)
496
+ - `fred_series_observations` — time-series observations for a FRED series (missing values → null; requires free FRED_API_KEY)
497
+ - `gsa_perdiem_rates` — federal travel per-diem: monthly lodging + M&IE meals caps by city+state or zip (keyless via DEMO_KEY)
466
498
  </details>
467
499
 
468
500
  <details>
@@ -517,6 +549,12 @@ Grouped by workflow. Every tool is keyless by default; a handful gain higher lim
517
549
  - `sba_size_standard` — SBA small-business size standard for a 6-digit NAICS (set-aside eligibility gate)
518
550
  </details>
519
551
 
552
+ <details>
553
+ <summary><b>Server utilities — key discovery (1 tool)</b></summary>
554
+
555
+ - `api_key_status` — list which API keys the server can use, required vs optional, signup URLs, and whether each is currently set (value never shown)
556
+ </details>
557
+
520
558
  ---
521
559
 
522
560
  ## Reliability & offline snapshots
@@ -525,13 +563,14 @@ This server is built around one rule: **honest failure over confident fabricatio
525
563
 
526
564
  **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.
527
565
 
528
- **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.
566
+ **Offline snapshots (on 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." By default, when a live federal source is briefly unreachable from your egress, the server falls back to a **public, weekly-refreshed snapshot** of that slow-changing reference data, hosted at `raw.githubusercontent.com/cliwant/mcp-sam-gov/snapshots`. It only fetches on a **live hard-failure** (an outage / IP-reputation block), never during normal operation — public data, no telemetry. 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. A rate limit (429) is always **honored**, never routed around onto the mirror.
529
567
 
530
- - **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.
568
+ - **Disable it (pure live-only):** set `SAMGOV_SNAPSHOT_BASE_URL=off`. Then no snapshot path is ever added and behavior is byte-for-byte identical to a live-only client.
569
+ - **Point at your own mirror:** set `SAMGOV_SNAPSHOT_BASE_URL` to your base URL to host the snapshots yourself instead of using the public default.
531
570
 
532
571
  ```json
533
572
  { "mcpServers": { "sam-gov": { "command": "mcp-sam-gov",
534
- "env": { "SAMGOV_SNAPSHOT_BASE_URL": "https://your-cdn.example.com/snapshots" } } } }
573
+ "env": { "SAMGOV_SNAPSHOT_BASE_URL": "off" } } } }
535
574
  ```
536
575
 
537
576
  - **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).
@@ -0,0 +1,93 @@
1
+ /**
2
+ * US Census — County Business Patterns (CBP) — the MARKET-SIZING lane
3
+ * (ADR-0047, Wave-4 source #1). NAICS × geography establishments / employment /
4
+ * annual payroll — the demand-side complement to BLS-QCEW + USAspending in the
5
+ * B2G market-sizing set.
6
+ *
7
+ * ★ THIS IS THE SERVER'S FIRST KEY-REQUIRED SOURCE. The Census Data API removed
8
+ * its keyless tier — a request WITHOUT a key is 302-redirected to a "Missing
9
+ * Key" HTML page. So, honestly: with NO `CENSUS_API_KEY` this tool THROWS an
10
+ * `invalid_input` config error BEFORE any fetch (never a fake-empty, never a
11
+ * keyless-pretend). The other 111 tools stay keyless — this key is scoped to
12
+ * this one source. (Contrast the OPTIONAL keys of datagov/bls/nvd, which lift a
13
+ * tier but are not required.)
14
+ *
15
+ * DIFFERENT HOST than census.ts (the geocoder, geocoding.geo.census.gov): the
16
+ * DATA API is `api.census.gov/data/{year}/cbp`. This module COPIES (does NOT
17
+ * import) the census.ts fixed-host SSRF idiom (a single host const + a
18
+ * post-construction `new URL().hostname` assertion + `redirect:"error"`) and does
19
+ * NOT touch census_geocode.
20
+ *
21
+ * Coercion/meta code is REUSED (`driftError`, `errorFromResponse`, `num`
22
+ * coerce.ts null-never-0, `withMeta`/`buildMeta`). The ONE bespoke bit is the
23
+ * fetch: a single `fetch(redirect:"manual")` (NOT the shared getJson) so a
24
+ * missing/invalid-key 302 surfaces as an INSPECTABLE opaque-redirect → honest
25
+ * invalid_input, instead of undici's redirect:"error" TypeError that
26
+ * fetchWithRetry would mask as a retryable outage (see the fetch block). The
27
+ * optional-key leak discipline is MIRRORED from datagovKey.ts/bls.ts — but here
28
+ * the key is REQUIRED and rides ONLY in the `&key=` query param, NOWHERE else
29
+ * (never the label, `_meta.source`, notes, or a log — the K-test).
30
+ *
31
+ * GET https://api.census.gov/data/{year}/cbp
32
+ * ?get=NAME,NAICS2017_LABEL,ESTAB,EMP,PAYANN,GEO_ID
33
+ * &for=<geoClause> (us:* | state:* | state:NN | county:*)
34
+ * &in=state:NN (county queries only)
35
+ * &NAICS2017=<naics> (optional NAICS filter)
36
+ * &key=<CENSUS_API_KEY> (REQUIRED)
37
+ * → a 2D JSON ARRAY: row 0 = column headers, rows 1..N = data. e.g.
38
+ * [["NAME","ESTAB","EMP","PAYANN","NAICS2017","NAICS2017_LABEL","state"],
39
+ * ["California","39755","...","...","5415","...","06"], ...]
40
+ *
41
+ * ★ HONESTY (ADR-0047 P1–P5):
42
+ * [KEY] no key ⇒ invalid_input THROW pre-fetch (0 fetch); the message names
43
+ * CENSUS_API_KEY + the free-signup URL. A wire 302 (a key that IS set but is
44
+ * invalid → the Missing-Key page) is caught via redirect:"manual" as an
45
+ * opaque-redirect ⇒ invalid_input "check CENSUS_API_KEY" (never a
46
+ * fake-empty, never a masked outage).
47
+ * [P1] CBP returns the COMPLETE geography set for the filter (no server
48
+ * pagination) ⇒ totalAvailable = the row count, complete:true. NEVER
49
+ * fabricated (RED if totalAvailable = header-length or invented).
50
+ * [P3] ★the sentinel→null crux: Census suppresses/withholds cells with large
51
+ * NEGATIVE sentinels (-999999999 / -888888888 / -666666666 …). `censusNum`
52
+ * maps any value ≤ -100000000 to **null** (withheld) — NEVER a negative
53
+ * number, NEVER 0. A genuine 0 stays 0. `annualPayrollUsd = PAYANN×1000`
54
+ * (PAYANN is in $1,000 units), null-preserving.
55
+ * [P2] a 302 ⇒ invalid_input (key); a header-only body ⇒ honest empty
56
+ * (returned:0, complete:true); a 5xx ⇒ upstream_unavailable THROW; a 200
57
+ * non-JSON ⇒ schema_drift.
58
+ * [P4] a body that is not an array, or whose row 0 is not a string[] header
59
+ * row ⇒ driftError (never a fabricated empty).
60
+ * [SSRF] fixed host; `year` re-guarded ^\d{4}$ (it rides in the PATH); `naics`
61
+ * ^\d{2,6}$; `state` ^\d{2}$; geography enum {us,state,county}. All
62
+ * predicate VALUES ride in URLSearchParams. The key rides `&key=` ONLY.
63
+ */
64
+ import { num } from "./coerce.js";
65
+ import { type MetaBundle } from "./meta.js";
66
+ export { num };
67
+ /** Read CENSUS_API_KEY from env; trim; return the value or undefined (unset/blank). */
68
+ export declare function censusApiKey(): string | undefined;
69
+ export type CbpRow = {
70
+ name: string | null;
71
+ geoId: string | null;
72
+ naicsCode: string | null;
73
+ naicsLabel: string | null;
74
+ establishments: number | null;
75
+ employees: number | null;
76
+ annualPayrollUsd: number | null;
77
+ state: string | null;
78
+ };
79
+ export type CensusBusinessPatternsArgs = {
80
+ naics?: string;
81
+ geography?: string;
82
+ state?: string;
83
+ year?: string;
84
+ limit?: number;
85
+ };
86
+ /**
87
+ * Fetch County Business Patterns rows for a NAICS × geography filter → normalized
88
+ * establishment / employment / annual-payroll rows + honest `_meta`. REQUIRES
89
+ * CENSUS_API_KEY (throws invalid_input pre-fetch when unset). The 2D-array body is
90
+ * parsed by HEADER NAME (order-independent); suppressed cells map to null.
91
+ */
92
+ export declare function businessPatterns(args: CensusBusinessPatternsArgs): Promise<MetaBundle>;
93
+ //# sourceMappingURL=census-economic.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"census-economic.d.ts","sourceRoot":"","sources":["../src/census-economic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAIH,OAAO,EAAE,GAAG,EAAO,MAAM,aAAa,CAAC;AACvC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAKzE,OAAO,EAAE,GAAG,EAAE,CAAC;AA+Bf,uFAAuF;AACvF,wBAAgB,YAAY,IAAI,MAAM,GAAG,SAAS,CAIjD;AAGD,MAAM,MAAM,MAAM,GAAG;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAiBF,MAAM,MAAM,0BAA0B,GAAG;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,UAAU,CAAC,CA+QrB"}