@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 +11 -9
- package/README.ko.md +11 -9
- package/README.md +51 -12
- package/dist/census-economic.d.ts +93 -0
- package/dist/census-economic.d.ts.map +1 -0
- package/dist/census-economic.js +355 -0
- package/dist/census-economic.js.map +1 -0
- package/dist/fred.d.ts +108 -0
- package/dist/fred.d.ts.map +1 -0
- package/dist/fred.js +373 -0
- package/dist/fred.js.map +1 -0
- package/dist/gsa-perdiem.d.ts +74 -0
- package/dist/gsa-perdiem.d.ts.map +1 -0
- package/dist/gsa-perdiem.js +296 -0
- package/dist/gsa-perdiem.js.map +1 -0
- package/dist/keys.d.ts +83 -0
- package/dist/keys.d.ts.map +1 -0
- package/dist/keys.js +173 -0
- package/dist/keys.js.map +1 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +185 -1
- package/dist/server.js.map +1 -1
- package/dist/snapshot.d.ts +33 -16
- package/dist/snapshot.d.ts.map +1 -1
- package/dist/snapshot.js +46 -17
- package/dist/snapshot.js.map +1 -1
- package/package.json +1 -1
- package/src/census-economic.ts +425 -0
- package/src/fred.ts +464 -0
- package/src/gsa-perdiem.ts +361 -0
- package/src/keys.ts +216 -0
- package/src/server.ts +221 -1
- package/src/snapshot.ts +51 -20
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 ほか **
|
|
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
|
|
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
|
-
**
|
|
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 が
|
|
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
|
-
## ツールカタログ (
|
|
167
|
+
## ツールカタログ (116)
|
|
168
168
|
|
|
169
|
-
|
|
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 (
|
|
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
|
-
-
|
|
192
|
-
-
|
|
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 외 **
|
|
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
|
|
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
|
-
**
|
|
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 가
|
|
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
|
-
## 도구 카탈로그 (
|
|
167
|
+
## 도구 카탈로그 (116개)
|
|
168
168
|
|
|
169
|
-
워크플로별 그룹.
|
|
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 (
|
|
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
|
-
-
|
|
192
|
-
-
|
|
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. **
|
|
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
|
[](https://www.npmjs.com/package/@cliwant/mcp-sam-gov)
|
|
10
10
|
[](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,
|
|
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
|
-
**
|
|
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
|
|
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 (
|
|
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 (
|
|
373
|
+
## Tool catalog (116 tools)
|
|
346
374
|
|
|
347
|
-
Grouped by workflow.
|
|
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 (
|
|
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
|
-
**
|
|
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
|
-
- **
|
|
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": "
|
|
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"}
|