@cliwant/mcp-sam-gov 1.3.0 → 1.4.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 +15 -7
- package/README.ko.md +15 -7
- package/README.md +48 -8
- package/dist/bea.d.ts +1 -1
- package/dist/bea.js +1 -1
- package/dist/census-economic.d.ts +1 -1
- package/dist/census-economic.d.ts.map +1 -1
- package/dist/census-economic.js +12 -6
- package/dist/census-economic.js.map +1 -1
- package/dist/cms-facility.d.ts +112 -0
- package/dist/cms-facility.d.ts.map +1 -0
- package/dist/cms-facility.js +311 -0
- package/dist/cms-facility.js.map +1 -0
- package/dist/cms-hospital.d.ts +105 -0
- package/dist/cms-hospital.d.ts.map +1 -0
- package/dist/cms-hospital.js +290 -0
- package/dist/cms-hospital.js.map +1 -0
- package/dist/cms-supplier.d.ts +133 -0
- package/dist/cms-supplier.d.ts.map +1 -0
- package/dist/cms-supplier.js +414 -0
- package/dist/cms-supplier.js.map +1 -0
- package/dist/cms-utilization.d.ts +113 -0
- package/dist/cms-utilization.d.ts.map +1 -0
- package/dist/cms-utilization.js +328 -0
- package/dist/cms-utilization.js.map +1 -0
- package/dist/courtlistener.d.ts +115 -0
- package/dist/courtlistener.d.ts.map +1 -0
- package/dist/courtlistener.js +398 -0
- package/dist/courtlistener.js.map +1 -0
- package/dist/cpsc.d.ts +81 -0
- package/dist/cpsc.d.ts.map +1 -0
- package/dist/cpsc.js +283 -0
- package/dist/cpsc.js.map +1 -0
- package/dist/dol.d.ts +2 -2
- package/dist/dol.js +5 -5
- package/dist/dol.js.map +1 -1
- package/dist/epa-envirofacts.d.ts +97 -0
- package/dist/epa-envirofacts.d.ts.map +1 -0
- package/dist/epa-envirofacts.js +292 -0
- package/dist/epa-envirofacts.js.map +1 -0
- package/dist/fred.d.ts +1 -1
- package/dist/fred.js +1 -1
- package/dist/keys.d.ts +6 -5
- package/dist/keys.d.ts.map +1 -1
- package/dist/keys.js +25 -6
- package/dist/keys.js.map +1 -1
- package/dist/nhtsa.d.ts +91 -0
- package/dist/nhtsa.d.ts.map +1 -0
- package/dist/nhtsa.js +263 -0
- package/dist/nhtsa.js.map +1 -0
- package/dist/nonprofit.d.ts +116 -0
- package/dist/nonprofit.d.ts.map +1 -0
- package/dist/nonprofit.js +342 -0
- package/dist/nonprofit.js.map +1 -0
- package/dist/openfda-device.d.ts +85 -0
- package/dist/openfda-device.d.ts.map +1 -0
- package/dist/openfda-device.js +277 -0
- package/dist/openfda-device.js.map +1 -0
- package/dist/openfda.d.ts +133 -0
- package/dist/openfda.d.ts.map +1 -0
- package/dist/openfda.js +402 -0
- package/dist/openfda.js.map +1 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +666 -7
- package/dist/server.js.map +1 -1
- package/package.json +2 -1
- package/src/bea.ts +1 -1
- package/src/census-economic.ts +12 -6
- package/src/cms-facility.ts +379 -0
- package/src/cms-hospital.ts +344 -0
- package/src/cms-supplier.ts +527 -0
- package/src/cms-utilization.ts +389 -0
- package/src/courtlistener.ts +465 -0
- package/src/cpsc.ts +333 -0
- package/src/dol.ts +5 -5
- package/src/epa-envirofacts.ts +342 -0
- package/src/fred.ts +1 -1
- package/src/keys.ts +27 -6
- package/src/nhtsa.ts +352 -0
- package/src/nonprofit.ts +460 -0
- package/src/openfda-device.ts +356 -0
- package/src/openfda.ts +495 -0
- package/src/server.ts +765 -7
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 · FRED · BEA · DOL · 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 · BEA · DOL · FEMA · openFDA · NHTSA · CPSC · EPA Envirofacts · CourtListener · IRS-990(ProPublica) ほか **44 の連邦データソース、134 ツール。** キーレス優先 — Census business-patterns · FRED · BEA · DOL データエンドポイントの 4 ソースのみ無料キーが必要で、残り 40 ソースはキー不要。
|
|
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)
|
|
@@ -16,7 +16,11 @@
|
|
|
16
16
|
|---|---|---|
|
|
17
17
|
| 🔍 **案件 + ソリシテーション** | "今月締切の NAICS 541512 SAM.gov 案件 — SOW・担当者・添付まで" | SAM.gov, Grants.gov |
|
|
18
18
|
| 💰 **spending・受注・競合** | "VA の Booz Allen 昨年度受注、DoD PSC カテゴリ Top 10" | USAspending, FPDS, GAO |
|
|
19
|
-
| 🕵️ **パートナー・企業の検証** | "この企業をスクリーニング: OFAC 制裁・SAM 除外・単一監査指摘・銀行健全性・EPA
|
|
19
|
+
| 🕵️ **パートナー・企業の検証** | "この企業をスクリーニング: OFAC 制裁・SAM 除外・単一監査指摘・銀行健全性・EPA 遵守+有害物質排出" | OFAC, SAM, FAC, FDIC, EPA ECHO, EPA Envirofacts |
|
|
20
|
+
| 🛒 **製品安全・リコール** | "このサプライヤー製品に FDA/NHTSA/CPSC のリコール・執行はあるか?" | openFDA, NHTSA, CPSC |
|
|
21
|
+
| ⚖️ **訴訟・裁判所** | "この請負業者に関する連邦請求裁判所の入札異議・連邦巡回控訴裁判所の判例" | CourtListener (Free Law Project) |
|
|
22
|
+
| 🏢 **非営利ベンダー** | "下請け前にこの非営利団体の IRS-990 財務を確認" | IRS 990 (ProPublica 経由) |
|
|
23
|
+
| 🏥 **医療提供者・施設** | "この provider の Medicare 利用・支払、病院品質評価、取消リスト該当有無" | CMS (data.cms.gov) |
|
|
20
24
|
| 📈 **財務開示 (SEC)** | "この上場企業の売上推移 + 最新 10-K" | SEC EDGAR |
|
|
21
25
|
| ⚖️ **規制・立法** | "今四半期の VA サイバーセキュリティ規則? 進行中の Regulations.gov docket?" | Federal Register, Regulations.gov, eCFR, FAR/DFARS, Congress.gov, GovInfo |
|
|
22
26
|
| 💲 **価格・労務・財政** | "GSA CALC 労務単価バンド、この郡の SCA 賃金決定、CPI エスカレーション、出張 per-diem 上限、地域の産業別 GDP、DOL 賃金・労働執行履歴" | GSA CALC, SAM WD, BLS, US Census CBP, FRED, BEA, US Treasury, GSA per-diem, US DOL |
|
|
@@ -26,7 +30,7 @@
|
|
|
26
30
|
| 🌐 **貿易・地理・災害** | "この品目の HTS 関税、この住所の Census tract、この州の FEMA 宣言" | USITC HTS, Census, FEMA, Socrata, CKAN |
|
|
27
31
|
| 🎓 **grant・データセット** | "過去 30 日のサイバーセキュリティ grant、連邦オープンデータセット発見" | Grants.gov, data.gov |
|
|
28
32
|
|
|
29
|
-
**
|
|
33
|
+
**44 の連邦データソース、合計 134 ツール — キーレス優先: Census business-patterns · FRED · BEA · DOL データエンドポイントの 4 ソースのみ無料キーが必要で、残り 40 ソースはキー不要。** (初期の 52 ツール版でおおよそ p50 ~0.25s / p95 ~0.8s を計測 — ソースや上流負荷で変動する近似値であり保証値ではありません。)
|
|
30
34
|
|
|
31
35
|
---
|
|
32
36
|
|
|
@@ -53,7 +57,7 @@ Claude Code (CLI) を既に使用している場合:
|
|
|
53
57
|
/plugin install cliwant/mcp-sam-gov
|
|
54
58
|
```
|
|
55
59
|
|
|
56
|
-
MCP サーバー + Claude が
|
|
60
|
+
MCP サーバー + Claude が 134 ツールをいつ・どう呼ぶかを教える [SKILL.md ワークフローガイド](./skills/sam-gov/SKILL.md) を同時登録。
|
|
57
61
|
|
|
58
62
|
### 🔵 パス 3 — Codex / Cursor / Continue / Gemini 等の手動インストール
|
|
59
63
|
|
|
@@ -167,17 +171,21 @@ npm install --omit=dev
|
|
|
167
171
|
|
|
168
172
|
---
|
|
169
173
|
|
|
170
|
-
## ツールカタログ (
|
|
174
|
+
## ツールカタログ (134)
|
|
171
175
|
|
|
172
|
-
ワークフロー別グループ。キーレス優先 — 大半はキー不要、Census business-patterns · FRED · BEA · DOL データエンドポイントは無料キーが必要。全 per-tool 一覧と入力 schema・誠実性 caveat の原文は [英語 README のカタログセクション](./README.md#tool-catalog-
|
|
176
|
+
ワークフロー別グループ。キーレス優先 — 大半はキー不要、Census business-patterns · FRED · BEA · DOL データエンドポイントは無料キーが必要。全 per-tool 一覧と入力 schema・誠実性 caveat の原文は [英語 README のカタログセクション](./README.md#tool-catalog-134-tools) を正とします。
|
|
173
177
|
|
|
174
178
|
- **案件 + ソリシテーション — 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`
|
|
175
179
|
- **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`
|
|
176
|
-
- **パートナー・企業の検証 — OFAC · SAM · FAC · FDIC · EPA (
|
|
180
|
+
- **パートナー・企業の検証 — OFAC · SAM · FAC · FDIC · EPA (15)**: `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` `epa_tri_facilities`(EPA Envirofacts TRI 有害物質排出施設 — 環境/ESG 検証)
|
|
181
|
+
- **製品安全・リコール — openFDA · NHTSA · CPSC (5)**: `openfda_enforcement`(FDA 医薬品・医療機器・食品のリコール・執行) `openfda_device_clearances`(FDA 510(k) 医療機器承認) `nhtsa_recalls`(NHTSA 車両リコール) `nhtsa_complaints`(NHTSA 車両安全苦情) `cpsc_recalls`(CPSC 消費者製品リコール)
|
|
182
|
+
- **訴訟・裁判所 — CourtListener (1)**: `courtlistener_search_opinions`(米連邦裁判所の判例 — 連邦請求裁判所の契約請求/入札異議、連邦巡回控訴裁判所; CourtListener/Free Law Project 経由、明示)
|
|
183
|
+
- **非営利ベンダー — IRS 990 via ProPublica (2)**: `nonprofit_search`(IRS-990 非営利検索 by 名称/州/NTEE) `nonprofit_financials`(IRS-990 非営利財務 by EIN) — ProPublica Nonprofit Explorer 経由(明示)
|
|
177
184
|
- **財務開示 — 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`
|
|
178
185
|
- **規制・立法 — 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`
|
|
179
186
|
- **価格・労務・財政 — GSA CALC · SAM WD · BLS · Census CBP · FRED · BEA · Treasury · GSA per-diem (15)**: `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` `bea_regional_data`(無料 BEA_API_KEY 必要) `census_business_patterns`(無料 CENSUS_API_KEY 必要) `fred_search_series`(無料 FRED_API_KEY 必要) `fred_series_observations`(無料 FRED_API_KEY 必要) `gsa_perdiem_rates`(DEMO_KEY キーレス)
|
|
180
187
|
- **医療・研究資金 — 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`
|
|
188
|
+
- **医療提供者・施設 — CMS (5)**: `cms_medicare_provider_services`(Medicare provider 利用・支払 — 医療市場規模) `cms_hospital_compare`(CMS 病院品質評価) `cms_facility_directory`(介護施設/在宅医療/ホスピス/透析施設ディレクトリ) `cms_dmepos_suppliers`(DMEPOS 医療機器サプライヤーディレクトリ + Medicare 支出) `cms_revoked_providers`(Medicare 取消/除外リスト — 遵守検証)
|
|
181
189
|
- **サイバー遵守 — NVD + CISA KEV (2)**: `cve_lookup` `cisa_kev_lookup`
|
|
182
190
|
- **貿易・関税 — USITC (1)**: `hts_lookup`
|
|
183
191
|
- **地理・災害・州/市オープンデータ — 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`
|
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 · FRED · BEA · DOL · 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 · BEA · DOL · FEMA · openFDA · NHTSA · CPSC · EPA Envirofacts · CourtListener · IRS-990(ProPublica) 외 **44개 연방 데이터 소스, 134개 도구.** keyless 우선 — Census business-patterns · FRED · BEA · DOL 데이터 엔드포인트 4개 소스만 무료 키가 필요하고 나머지 40개 소스는 키가 필요 없습니다.
|
|
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)
|
|
@@ -16,7 +16,11 @@
|
|
|
16
16
|
|---|---|---|
|
|
17
17
|
| 🔍 **입찰 + 솔리시테이션** | "이번 달 마감되는 NAICS 541512 SAM.gov 입찰 — SOW·담당자·첨부까지" | SAM.gov, Grants.gov |
|
|
18
18
|
| 💰 **spending·수주·경쟁** | "VA 에서 Booz Allen 작년 수주, DoD PSC 카테고리 top 10" | USAspending, FPDS, GAO |
|
|
19
|
-
| 🕵️ **파트너·기업 검증** | "이 업체 스크리닝: OFAC 제재·SAM 배제·단일감사 지적·은행 건전성·EPA
|
|
19
|
+
| 🕵️ **파트너·기업 검증** | "이 업체 스크리닝: OFAC 제재·SAM 배제·단일감사 지적·은행 건전성·EPA 준수+독성물질 배출" | OFAC, SAM, FAC, FDIC, EPA ECHO, EPA Envirofacts |
|
|
20
|
+
| 🛒 **제품 안전·리콜** | "이 공급업체 제품에 FDA/NHTSA/CPSC 리콜·집행 있나?" | openFDA, NHTSA, CPSC |
|
|
21
|
+
| ⚖️ **소송·법원** | "이 계약자 관련 연방청구법원 입찰 이의제기·연방순회항소법원 판례" | CourtListener (Free Law Project) |
|
|
22
|
+
| 🏢 **비영리 벤더** | "하청 전 이 비영리단체 IRS-990 재무 확인" | IRS 990 (ProPublica 경유) |
|
|
23
|
+
| 🏥 **의료 제공자·시설** | "이 provider Medicare 이용·지급, 병원 품질 등급, 취소 목록 여부" | CMS (data.cms.gov) |
|
|
20
24
|
| 📈 **재무 공시 (SEC)** | "이 상장사 매출 추이 + 최신 10-K" | SEC EDGAR |
|
|
21
25
|
| ⚖️ **규정·입법** | "이번 분기 VA 사이버보안 규정? 열려있는 Regulations.gov docket?" | Federal Register, Regulations.gov, eCFR, FAR/DFARS, Congress.gov, GovInfo |
|
|
22
26
|
| 💲 **가격·노무·재정** | "GSA CALC 노무 단가 밴드, 이 카운티 SCA 임금결정, CPI 에스컬레이션, 출장 per-diem 상한, 지역 산업별 GDP, DOL 임금·근로 집행 이력" | GSA CALC, SAM WD, BLS, US Census CBP, FRED, BEA, US Treasury, GSA per-diem, US DOL |
|
|
@@ -26,7 +30,7 @@
|
|
|
26
30
|
| 🌐 **무역·지리·재난** | "이 품목 HTS 관세, 이 주소 Census tract, 이 주의 FEMA 선포" | USITC HTS, Census, FEMA, Socrata, CKAN |
|
|
27
31
|
| 🎓 **grant·데이터셋** | "최근 30일 사이버보안 grant, 연방 오픈 데이터셋 발굴" | Grants.gov, data.gov |
|
|
28
32
|
|
|
29
|
-
**
|
|
33
|
+
**44개 연방 데이터 소스, 총 134개 도구 — keyless 우선: Census business-patterns · FRED · BEA · DOL 데이터 엔드포인트 4개 소스만 무료 키가 필요하고 나머지 40개 소스는 키가 필요 없습니다.** (초기 52-도구 빌드 기준 대략 p50 ~0.25s / p95 ~0.8s 측정 — 소스·업스트림 부하에 따라 변동하는 근사치이며 보장값이 아님.)
|
|
30
34
|
|
|
31
35
|
---
|
|
32
36
|
|
|
@@ -53,7 +57,7 @@ PowerShell, npm 등 필요 없음.
|
|
|
53
57
|
/plugin install cliwant/mcp-sam-gov
|
|
54
58
|
```
|
|
55
59
|
|
|
56
|
-
MCP 서버 + Claude 가
|
|
60
|
+
MCP 서버 + Claude 가 134개 도구를 언제 / 어떻게 호출할지 가르치는 [SKILL.md 워크플로 가이드](./skills/sam-gov/SKILL.md) 동시 등록.
|
|
57
61
|
|
|
58
62
|
### 🔵 경로 3 — Codex / Cursor / Continue / Gemini 등 수동 설치
|
|
59
63
|
|
|
@@ -167,17 +171,21 @@ npm install --omit=dev
|
|
|
167
171
|
|
|
168
172
|
---
|
|
169
173
|
|
|
170
|
-
## 도구 카탈로그 (
|
|
174
|
+
## 도구 카탈로그 (134개)
|
|
171
175
|
|
|
172
|
-
워크플로별 그룹. keyless 우선 — 대부분 키가 필요 없고, Census business-patterns · FRED · BEA · DOL 데이터 엔드포인트는 무료 키가 필요합니다. 전체 per-tool 목록과 입력 schema·정직성 caveat 원문은 [영문 README 의 카탈로그 섹션](./README.md#tool-catalog-
|
|
176
|
+
워크플로별 그룹. keyless 우선 — 대부분 키가 필요 없고, Census business-patterns · FRED · BEA · DOL 데이터 엔드포인트는 무료 키가 필요합니다. 전체 per-tool 목록과 입력 schema·정직성 caveat 원문은 [영문 README 의 카탈로그 섹션](./README.md#tool-catalog-134-tools)을 기준으로 하세요.
|
|
173
177
|
|
|
174
178
|
- **입찰 + 솔리시테이션 — 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`
|
|
175
179
|
- **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`
|
|
176
|
-
- **파트너·기업 검증 — OFAC · SAM · FAC · FDIC · EPA (
|
|
180
|
+
- **파트너·기업 검증 — OFAC · SAM · FAC · FDIC · EPA (15)**: `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` `epa_tri_facilities`(EPA Envirofacts TRI 독성물질 배출 시설 — 환경/ESG 검증)
|
|
181
|
+
- **제품 안전·리콜 — openFDA · NHTSA · CPSC (5)**: `openfda_enforcement`(FDA 의약품·의료기기·식품 리콜·집행) `openfda_device_clearances`(FDA 510(k) 의료기기 승인) `nhtsa_recalls`(NHTSA 차량 리콜) `nhtsa_complaints`(NHTSA 차량 안전 불만) `cpsc_recalls`(CPSC 소비자 제품 리콜)
|
|
182
|
+
- **소송·법원 — CourtListener (1)**: `courtlistener_search_opinions`(미 연방 법원 판례 — 연방청구법원 계약 청구/입찰 이의, 연방순회항소법원; CourtListener/Free Law Project 경유, 명시)
|
|
183
|
+
- **비영리 벤더 — IRS 990 via ProPublica (2)**: `nonprofit_search`(IRS-990 비영리 검색 by 이름/주/NTEE) `nonprofit_financials`(IRS-990 비영리 재무 by EIN) — ProPublica Nonprofit Explorer 경유(명시)
|
|
177
184
|
- **재무 공시 — 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`
|
|
178
185
|
- **규정·입법 — 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`
|
|
179
186
|
- **가격·노무·재정 — GSA CALC · SAM WD · BLS · Census CBP · FRED · BEA · Treasury · GSA per-diem (15)**: `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` `bea_regional_data`(무료 BEA_API_KEY 필요) `census_business_patterns`(무료 CENSUS_API_KEY 필요) `fred_search_series`(무료 FRED_API_KEY 필요) `fred_series_observations`(무료 FRED_API_KEY 필요) `gsa_perdiem_rates`(DEMO_KEY keyless)
|
|
180
187
|
- **보건·연구 자금 — 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`
|
|
188
|
+
- **의료 제공자·시설 — CMS (5)**: `cms_medicare_provider_services`(Medicare provider 이용·지급 — 의료 시장규모) `cms_hospital_compare`(CMS 병원 품질 등급) `cms_facility_directory`(요양원/재택의료/호스피스/투석 시설 디렉터리) `cms_dmepos_suppliers`(DMEPOS 의료기기 공급자 디렉터리 + Medicare 지출) `cms_revoked_providers`(Medicare 취소/배제 목록 — 준수 검증)
|
|
181
189
|
- **사이버 준수 — NVD + CISA KEV (2)**: `cve_lookup` `cisa_kev_lookup`
|
|
182
190
|
- **무역·관세 — USITC (1)**: `hts_lookup`
|
|
183
191
|
- **지리·재난·주/시 오픈데이터 — 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`
|
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-first** 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. **134 tools across 44 federal data sources** — keyless-first: only 4 sources (Census business-patterns, FRED, BEA, and DOL's data endpoint) need a free key; the other 40 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-first** MCP server for US federal contracting +
|
|
|
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, 134 tools across 44 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 |
|
|
@@ -65,7 +65,11 @@ The federal data this wraps is **public domain**. There is no good reason it sho
|
|
|
65
65
|
|---|---|---|
|
|
66
66
|
| 🔍 **Opportunities & solicitations** | "Find SAM.gov solicitations under NAICS 541512 closing this month" — read the SOW, POCs, attachments | SAM.gov, Grants.gov |
|
|
67
67
|
| 💰 **Spending, awards & competition** | "Show me Booz Allen wins at VA last fiscal year; top 10 PSC categories at DoD" | USAspending, FPDS, GAO |
|
|
68
|
-
| 🕵️ **Entity & partner vetting** | "Screen this firm: OFAC sanctions, SAM exclusions, single-audit findings, bank health, EPA compliance" | OFAC, SAM, FAC, FDIC, EPA ECHO |
|
|
68
|
+
| 🕵️ **Entity & partner vetting** | "Screen this firm: OFAC sanctions, SAM exclusions, single-audit findings, bank health, EPA compliance + toxics-release" | OFAC, SAM, FAC, FDIC, EPA ECHO, EPA Envirofacts |
|
|
69
|
+
| 🛒 **Product safety & recalls** | "Any FDA/NHTSA/CPSC recalls or enforcement against this supplier's products?" | openFDA, NHTSA, CPSC |
|
|
70
|
+
| ⚖️ **Litigation & courts** | "Any Court of Federal Claims bid protests or Federal Circuit opinions involving this contractor?" | CourtListener (Free Law Project) |
|
|
71
|
+
| 🏢 **Nonprofit vendors** | "Pull this nonprofit's IRS-990 financials before we subcontract to it" | IRS 990 (via ProPublica) |
|
|
72
|
+
| 🏥 **Healthcare providers & facilities** | "Medicare utilization & payments for this provider; hospital quality ratings; is this provider on the revocation list?" | CMS (data.cms.gov) |
|
|
69
73
|
| 📈 **Financial disclosure (SEC)** | "Pull this public company's revenue trend and latest 10-K filings" | SEC EDGAR |
|
|
70
74
|
| ⚖️ **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
75
|
| 💲 **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; regional GDP by industry; DOL wage-hour enforcement history" | GSA CALC, SAM WDs, BLS, US Census CBP, FRED, BEA, US Treasury, GSA per-diem, US DOL |
|
|
@@ -75,7 +79,7 @@ The federal data this wraps is **public domain**. There is no good reason it sho
|
|
|
75
79
|
| 🌐 **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 |
|
|
76
80
|
| 🎓 **Grants & datasets** | "Cybersecurity grants posted in the last 30 days; discover federal open datasets" | Grants.gov, data.gov |
|
|
77
81
|
|
|
78
|
-
**
|
|
82
|
+
**134 tools across 44 federal data sources — keyless-first: only 4 sources (Census business-patterns, FRED, BEA, and DOL's data endpoint) need a free key; the other 40 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.)
|
|
79
83
|
|
|
80
84
|
---
|
|
81
85
|
|
|
@@ -102,7 +106,7 @@ If you already use Claude Code (the CLI):
|
|
|
102
106
|
/plugin install cliwant/mcp-sam-gov
|
|
103
107
|
```
|
|
104
108
|
|
|
105
|
-
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
|
|
109
|
+
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 134 tools.
|
|
106
110
|
|
|
107
111
|
### 🔵 Path 3 — Manual install for any MCP host (Codex, Cursor, Continue, Gemini)
|
|
108
112
|
|
|
@@ -170,7 +174,7 @@ Then point your host config at the absolute path:
|
|
|
170
174
|
|
|
171
175
|
(Or skip this entirely — use Path 1's `.mcpb` and it auto-configures.)
|
|
172
176
|
|
|
173
|
-
Restart Claude Desktop fully (system tray quit on Windows / Quit menu on macOS), then look for the 🔨 icon. You should see "sam-gov (
|
|
177
|
+
Restart Claude Desktop fully (system tray quit on Windows / Quit menu on macOS), then look for the 🔨 icon. You should see "sam-gov (134 tools)".
|
|
174
178
|
|
|
175
179
|
### Claude Code
|
|
176
180
|
|
|
@@ -356,6 +360,8 @@ Get one free (instant, no wait) at [api.data.gov/signup](https://api.data.gov/si
|
|
|
356
360
|
| `LDA_API_KEY` | Optional | higher rate limit on `lda_search_filings` (Senate LDA lobbying; keyless by default) | [lda.senate.gov/api/register](https://lda.senate.gov/api/register/) |
|
|
357
361
|
| `BLS_API_KEY` | Optional | the BLS v2 tier (~500 queries/day vs keyless ~25/day) | [data.bls.gov/registrationEngine](https://data.bls.gov/registrationEngine/) |
|
|
358
362
|
| `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) |
|
|
363
|
+
| `OPENFDA_API_KEY` | Optional | higher openFDA rate limit (`openfda_enforcement`, `openfda_device_clearances`; both work keyless) | [open.fda.gov/apis/authentication](https://open.fda.gov/apis/authentication/) |
|
|
364
|
+
| `COURTLISTENER_API_TOKEN` | Optional | higher CourtListener rate limit (`courtlistener_search_opinions`; works keyless) | [courtlistener.com/help/api/rest](https://www.courtlistener.com/help/api/rest/) |
|
|
359
365
|
| `SOCRATA_APP_TOKEN` | Optional | higher Socrata throttling limits | [evergreen.data.socrata.com/signup](https://evergreen.data.socrata.com/signup) |
|
|
360
366
|
|
|
361
367
|
**Two ways to set any key** — pick one:
|
|
@@ -374,7 +380,7 @@ Get one free (instant, no wait) at [api.data.gov/signup](https://api.data.gov/si
|
|
|
374
380
|
|
|
375
381
|
---
|
|
376
382
|
|
|
377
|
-
## Tool catalog (
|
|
383
|
+
## Tool catalog (134 tools)
|
|
378
384
|
|
|
379
385
|
Grouped by workflow. Keyless-first — most tools need no key; Census business-patterns, FRED, BEA, and DOL's data endpoint 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.
|
|
380
386
|
|
|
@@ -428,7 +434,7 @@ Grouped by workflow. Keyless-first — most tools need no key; Census business-p
|
|
|
428
434
|
</details>
|
|
429
435
|
|
|
430
436
|
<details>
|
|
431
|
-
<summary><b>Entity & partner vetting — OFAC · SAM · FAC · FDIC · EPA (
|
|
437
|
+
<summary><b>Entity & partner vetting — OFAC · SAM · FAC · FDIC · EPA (15 tools)</b></summary>
|
|
432
438
|
|
|
433
439
|
- `ofac_screen_entity` — keyless OFAC denied-party / sanctions screening
|
|
434
440
|
- `sam_check_exclusions` — keyless SAM debarment/exclusion screening by name and/or UEI/CAGE
|
|
@@ -444,6 +450,30 @@ Grouped by workflow. Keyless-first — most tools need no key; Census business-p
|
|
|
444
450
|
- `fdic_industry_summary` — industry & state banking-sector annual aggregates
|
|
445
451
|
- `echo_search_facilities` — search EPA-regulated facilities by state with compliance/enforcement screening
|
|
446
452
|
- `echo_facility_report` — EPA ECHO Detailed Facility Report for one facility (by FRS RegistryID)
|
|
453
|
+
- `epa_tri_facilities` — EPA Envirofacts TRI (Toxics Release Inventory) facilities by state/industry (environmental / ESG vetting)
|
|
454
|
+
</details>
|
|
455
|
+
|
|
456
|
+
<details>
|
|
457
|
+
<summary><b>Product safety & recalls — openFDA · NHTSA · CPSC (5 tools)</b></summary>
|
|
458
|
+
|
|
459
|
+
- `openfda_enforcement` — FDA drug / device / food recalls & enforcement actions (product-safety supplier vetting)
|
|
460
|
+
- `openfda_device_clearances` — FDA 510(k) medical-device clearances (device-maker capability check)
|
|
461
|
+
- `nhtsa_recalls` — NHTSA vehicle recalls by make / model / year
|
|
462
|
+
- `nhtsa_complaints` — NHTSA vehicle safety complaints by make / model / year
|
|
463
|
+
- `cpsc_recalls` — CPSC consumer-product recalls (product supplier vetting)
|
|
464
|
+
</details>
|
|
465
|
+
|
|
466
|
+
<details>
|
|
467
|
+
<summary><b>Litigation & courts — CourtListener (1 tool)</b></summary>
|
|
468
|
+
|
|
469
|
+
- `courtlistener_search_opinions` — US federal court opinions (COFC contract claims / bid protests, Federal Circuit) — data via CourtListener / Free Law Project (disclosed)
|
|
470
|
+
</details>
|
|
471
|
+
|
|
472
|
+
<details>
|
|
473
|
+
<summary><b>Nonprofit vendors — IRS 990 via ProPublica (2 tools)</b></summary>
|
|
474
|
+
|
|
475
|
+
- `nonprofit_search` — IRS-990 nonprofit search by name / state / NTEE — via ProPublica Nonprofit Explorer (disclosed)
|
|
476
|
+
- `nonprofit_financials` — IRS-990 nonprofit financials by EIN — via ProPublica Nonprofit Explorer (disclosed)
|
|
447
477
|
</details>
|
|
448
478
|
|
|
449
479
|
<details>
|
|
@@ -516,6 +546,16 @@ Grouped by workflow. Keyless-first — most tools need no key; Census business-p
|
|
|
516
546
|
- `nppes_lookup_provider` — CMS/HHS NPPES NPI Registry provider lookup
|
|
517
547
|
</details>
|
|
518
548
|
|
|
549
|
+
<details>
|
|
550
|
+
<summary><b>Healthcare providers & facilities — CMS (5 tools)</b></summary>
|
|
551
|
+
|
|
552
|
+
- `cms_medicare_provider_services` — Medicare provider utilization & payments (healthcare market sizing)
|
|
553
|
+
- `cms_hospital_compare` — CMS Hospital Compare quality ratings
|
|
554
|
+
- `cms_facility_directory` — CMS nursing-home / home-health / hospice / dialysis facility directories
|
|
555
|
+
- `cms_dmepos_suppliers` — CMS DMEPOS (durable medical equipment) supplier directory + Medicare spend
|
|
556
|
+
- `cms_revoked_providers` — CMS Medicare revocation / exclusion list (provider compliance vetting)
|
|
557
|
+
</details>
|
|
558
|
+
|
|
519
559
|
<details>
|
|
520
560
|
<summary><b>Cyber compliance — NVD + CISA KEV (2 tools)</b></summary>
|
|
521
561
|
|
package/dist/bea.d.ts
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* ★ THIS IS THE SERVER'S THIRD KEY-REQUIRED SOURCE (Census CBP #1, FRED #2). The
|
|
9
9
|
* BEA Data API has NO keyless tier: every request needs `UserID=`. So, honestly:
|
|
10
10
|
* with NO `BEA_API_KEY` this tool THROWS an `invalid_input` config error BEFORE
|
|
11
|
-
* any fetch (never a fake-empty, never a keyless-pretend). The other
|
|
11
|
+
* any fetch (never a fake-empty, never a keyless-pretend). The other tools
|
|
12
12
|
* stay keyless — this key is scoped to this one source. (Contrast the OPTIONAL
|
|
13
13
|
* keys of datagov/bls/nvd, which lift a tier but are not required.)
|
|
14
14
|
*
|
package/dist/bea.js
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* ★ THIS IS THE SERVER'S THIRD KEY-REQUIRED SOURCE (Census CBP #1, FRED #2). The
|
|
9
9
|
* BEA Data API has NO keyless tier: every request needs `UserID=`. So, honestly:
|
|
10
10
|
* with NO `BEA_API_KEY` this tool THROWS an `invalid_input` config error BEFORE
|
|
11
|
-
* any fetch (never a fake-empty, never a keyless-pretend). The other
|
|
11
|
+
* any fetch (never a fake-empty, never a keyless-pretend). The other tools
|
|
12
12
|
* stay keyless — this key is scoped to this one source. (Contrast the OPTIONAL
|
|
13
13
|
* keys of datagov/bls/nvd, which lift a tier but are not required.)
|
|
14
14
|
*
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* its keyless tier — a request WITHOUT a key is 302-redirected to a "Missing
|
|
9
9
|
* Key" HTML page. So, honestly: with NO `CENSUS_API_KEY` this tool THROWS an
|
|
10
10
|
* `invalid_input` config error BEFORE any fetch (never a fake-empty, never a
|
|
11
|
-
* keyless-pretend). The other
|
|
11
|
+
* keyless-pretend). The other tools stay keyless — this key is scoped to
|
|
12
12
|
* this one source. (Contrast the OPTIONAL keys of datagov/bls/nvd, which lift a
|
|
13
13
|
* tier but are not required.)
|
|
14
14
|
*
|
|
@@ -1 +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;
|
|
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;AAqCf,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"}
|
package/dist/census-economic.js
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* its keyless tier — a request WITHOUT a key is 302-redirected to a "Missing
|
|
9
9
|
* Key" HTML page. So, honestly: with NO `CENSUS_API_KEY` this tool THROWS an
|
|
10
10
|
* `invalid_input` config error BEFORE any fetch (never a fake-empty, never a
|
|
11
|
-
* keyless-pretend). The other
|
|
11
|
+
* keyless-pretend). The other tools stay keyless — this key is scoped to
|
|
12
12
|
* this one source. (Contrast the OPTIONAL keys of datagov/bls/nvd, which lift a
|
|
13
13
|
* tier but are not required.)
|
|
14
14
|
*
|
|
@@ -77,16 +77,22 @@ const YEAR_RE = /^\d{4}$/; // rides in the PATH — strict 4-digit (no path inje
|
|
|
77
77
|
const NAICS_RE = /^\d{2,6}$/; // 2–6 digit NAICS-2017 sector/code
|
|
78
78
|
const STATE_FIPS_RE = /^\d{2}$/; // 2-digit state FIPS
|
|
79
79
|
const GEOGRAPHIES = new Set(["us", "state", "county"]);
|
|
80
|
-
//
|
|
81
|
-
// unavailable cell as a large NEGATIVE value (-999999999 / -888888888 /
|
|
82
|
-
// -666666666 …)
|
|
83
|
-
// value at/below this floor is a sentinel, NOT data.
|
|
80
|
+
// DEFENSIVE large-negative sentinel floor. Some Census products (ACS/SAIPE) encode a
|
|
81
|
+
// withheld/unavailable cell as a large NEGATIVE jam value (-999999999 / -888888888 /
|
|
82
|
+
// -666666666 …); establishment/employment/payroll counts are non-negative, so any
|
|
83
|
+
// value at/below this floor is a sentinel, NOT data → mapped to null.
|
|
84
|
+
// ★HONESTY CAVEAT: CBP itself does NOT primarily use these jam values — modern CBP
|
|
85
|
+
// uses NOISE INFUSION (EMP_N noise-range columns) + suppression FLAGS (EMP_N_F …),
|
|
86
|
+
// which this tool does NOT currently request or interpret (it surfaces values as
|
|
87
|
+
// reported). So this floor is a conservative cross-product guard, not CBP's confirmed
|
|
88
|
+
// mechanism; a keyed live verification of CBP's exact withheld-cell encoding is pending
|
|
89
|
+
// (no CENSUS_API_KEY was available at build time). See SUPPRESSED_NOTE.
|
|
84
90
|
const CENSUS_SENTINEL_FLOOR = -100000000;
|
|
85
91
|
const DEFAULT_YEAR = "2022"; // the latest confirmed CBP vintage (ADR-0047)
|
|
86
92
|
// ─── Honesty notes (ADR-0047 required set) ────────────────────────
|
|
87
93
|
const KEY_REQUIRED_NOTE = "This source REQUIRES a free CENSUS_API_KEY (the Census Data API has no keyless tier). The key is sent ONLY as the &key= query parameter to api.census.gov and is NEVER logged, echoed, or placed in this response.";
|
|
88
94
|
const PAYROLL_UNITS_NOTE = "annualPayrollUsd is ANNUAL payroll in US dollars, converted from the Census PAYANN field's $1,000 units (×1000). establishments and employees are integer counts (as-of the reference year).";
|
|
89
|
-
const SUPPRESSED_NOTE = "
|
|
95
|
+
const SUPPRESSED_NOTE = "Disclosure protection: any large-negative jam sentinel (e.g. -999999999) is mapped to null (withheld) — NEVER a negative number and NEVER 0; a genuine 0 is preserved as 0. NOTE: modern CBP applies NOISE INFUSION (perturbed values) plus suppression flag columns (e.g. EMP_N_F) rather than jam sentinels; this tool surfaces values as reported and does not currently interpret suppression flags, so a flagged/noise-infused cell is returned as its reported number — treat exact small counts as approximate.";
|
|
90
96
|
const NO_PAGINATION_NOTE = "CBP returns the COMPLETE set of geographies matching the filter (no server-side pagination); totalAvailable equals the number of rows returned. Narrow with naics / geography to reduce the row count.";
|
|
91
97
|
// ─── The key seam (REQUIRED; value NEVER leaked past the &key= param) ──
|
|
92
98
|
/** Read CENSUS_API_KEY from env; trim; return the value or undefined (unset/blank). */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"census-economic.js","sourceRoot":"","sources":["../src/census-economic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAsC,MAAM,WAAW,CAAC;AAEzE,8EAA8E;AAC9E,iFAAiF;AACjF,WAAW;AACX,OAAO,EAAE,GAAG,EAAE,CAAC;AAEf,qEAAqE;AACrE,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;AAC1C,MAAM,iBAAiB,GAAG,kBAAkB,CAAC,CAAC,gDAAgD;AAE9F,qEAAqE;AACrE,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,yDAAyD;AACpF,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,mCAAmC;AACjE,MAAM,aAAa,GAAG,SAAS,CAAC,CAAC,qBAAqB;AACtD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEvD,
|
|
1
|
+
{"version":3,"file":"census-economic.js","sourceRoot":"","sources":["../src/census-economic.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* cms-facility.ts — CMS "facility directory" across FOUR provider-data datasets
|
|
3
|
+
* (`data.cms.gov`, the provider-data DKAN datastore-query API; ADR-0063). KEYLESS.
|
|
4
|
+
*
|
|
5
|
+
* WHAT IT ADDS: `cms_facility_directory` — a healthcare-facility directory / market
|
|
6
|
+
* lane that generalizes cms_hospital_compare (ADR-0062) BEYOND hospitals: a caller
|
|
7
|
+
* picks a `facilityType` (nursing_home | home_health | hospice | dialysis) and the
|
|
8
|
+
* tool routes to the RIGHT CMS provider-data dataset, returning each facility's
|
|
9
|
+
* name / address / city / state / zip / ownership. The facility-level complement to
|
|
10
|
+
* the utilization and hospital lanes — WHERE these Medicare-certified facilities are.
|
|
11
|
+
*
|
|
12
|
+
* ★THE facilityType → DATASET-ID CONSTANT MAP (the load-bearing SSRF guard): the
|
|
13
|
+
* USER value never enters the URL path. `facilityType` is a Zod ENUM; it indexes a
|
|
14
|
+
* MODULE-CONSTANT map to a VETTED dataset id (e.g. nursing_home → "4pq5-n9py") that
|
|
15
|
+
* is spliced into the path. An unknown facilityType is blocked by the enum
|
|
16
|
+
* (invalid_input) BEFORE any fetch — only one of four compile-time ids can ever
|
|
17
|
+
* reach the path.
|
|
18
|
+
*
|
|
19
|
+
* ★THE ONE-REQUEST COUNT PATTERN (P1 honesty, inherited from cms-hospital): the DKAN
|
|
20
|
+
* datastore-query response is `{ count, results, schema, query }` — `count` is the
|
|
21
|
+
* EXACT per-filter total in the SAME body as the rows. So totalAvailable = the
|
|
22
|
+
* response's top-level `count` (nursing_home ⇒ 14695), NEVER `results.length`.
|
|
23
|
+
*
|
|
24
|
+
* ★FIELD-NAME VARIANCE ACROSS DATASETS (the one genuinely-new complexity vs.
|
|
25
|
+
* cms-hospital) — live-verified 2026-07-15. The facility NAME, ADDRESS, and
|
|
26
|
+
* OWNERSHIP columns are NAMED DIFFERENTLY per dataset, so each is COALESCED over a
|
|
27
|
+
* fixed candidate order (null if none present — NEVER an empty string, NEVER
|
|
28
|
+
* fabricated):
|
|
29
|
+
* name : provider_name → facility_name → legal_business_name
|
|
30
|
+
* address : address → provider_address → address_line_1
|
|
31
|
+
* ownership : ownership_type → type_of_ownership → profit_or_nonprofit
|
|
32
|
+
* (city = citytown, state = state, zip = zip_code are uniform across all four.)
|
|
33
|
+
* Per-dataset verified columns:
|
|
34
|
+
* nursing_home 4pq5-n9py: provider_name / provider_address / ownership_type
|
|
35
|
+
* home_health 6jpm-sxkc: provider_name / address / type_of_ownership
|
|
36
|
+
* hospice yc9t-dgbk: facility_name / address_line_1 / ownership_type
|
|
37
|
+
* dialysis 23ew-n7w9: facility_name / address_line_1 / profit_or_nonprofit
|
|
38
|
+
* ★ADR-0063 said nursing_home's address is `address`; it is actually
|
|
39
|
+
* `provider_address` (probed live) — the coalescing candidate list covers it.
|
|
40
|
+
*
|
|
41
|
+
* ★THE facilityName FILTER COLUMN also varies: the `contains` filter targets the
|
|
42
|
+
* dataset's OWN primary-name column (provider_name for nursing_home/home_health,
|
|
43
|
+
* facility_name for hospice/dialysis) — stored per-type in the constant map.
|
|
44
|
+
*
|
|
45
|
+
* The module writes ZERO fetch/coercion/error/meta code — it REUSES `getJson`
|
|
46
|
+
* (redirect:"error") / `driftError` (datasource.ts), `str` (coerce.ts,
|
|
47
|
+
* null-never-empty-string), and `withMeta`·`buildMeta` (meta.ts, offset pagination
|
|
48
|
+
* + totalAvailable). It MIRRORS cms-hospital.ts's fixed-host SSRF idiom (a single
|
|
49
|
+
* host const + a post-construction hostname/protocol assertion + redirect:"error" +
|
|
50
|
+
* `conditions[i][…]` bracket keys and values carried via URLSearchParams) and its
|
|
51
|
+
* schema_drift catch-ladder (ToolErrorCarrier rethrow FIRST → SyntaxError→driftError
|
|
52
|
+
* → bare rethrow).
|
|
53
|
+
*
|
|
54
|
+
* GET https://data.cms.gov/provider-data/api/1/datastore/query/{datasetId}/0
|
|
55
|
+
* ?limit=&offset=&conditions[0][property]=state&conditions[0][value]=VA&conditions[0][operator]==
|
|
56
|
+
* → { count: 383, results: [ { provider_name, provider_address, … }, … ], schema, query }
|
|
57
|
+
*
|
|
58
|
+
* ★ SSRF: the host is a compile-time literal (`CMS_HOST`); the dataset id is chosen
|
|
59
|
+
* by a Zod-enum key from a MODULE-CONSTANT map (never the user string). Every USER
|
|
60
|
+
* filter VALUE rides as a URLSearchParams VALUE (`conditions[i][value]=…`) — the
|
|
61
|
+
* bracket key AND the value are encoded, so a value can never break out of the
|
|
62
|
+
* path or inject a parameter. state is `^[A-Za-z]{2}$`; facilityName is a bounded
|
|
63
|
+
* free-text charclass; size/offset are coerced to integers. A post-construction
|
|
64
|
+
* hostname/protocol assertion + `redirect:"error"` fail closed on any off-host 3xx.
|
|
65
|
+
*
|
|
66
|
+
* ★ HONESTY (ADR-0063 P1–P5, live-verified 2026-07-15 on data.cms.gov):
|
|
67
|
+
* [P1] totalAvailable = the response's top-level `count` (EXACT per-filter total),
|
|
68
|
+
* NOT the slice length. hasMore = offset+returned < count.
|
|
69
|
+
* [P2] results:[] ⇒ honest empty (returned:0). An invalid facilityType is blocked
|
|
70
|
+
* by the Zod enum (invalid_input). getJson maps a 4xx/5xx via
|
|
71
|
+
* errorFromResponse and THROWS (503 ⇒ upstream_unavailable, 400 ⇒
|
|
72
|
+
* invalid_input, 404 ⇒ not_found); a 200 non-JSON body OR a body missing
|
|
73
|
+
* `count`/`results` ⇒ schema_drift (NEVER a fabricated empty).
|
|
74
|
+
* [P3] name/address/ownership are COALESCED over the candidate order — null if none
|
|
75
|
+
* (NEVER an empty string, NEVER fabricated). String fields via str().
|
|
76
|
+
* [P4] results non-array OR count non-number ⇒ driftError.
|
|
77
|
+
*/
|
|
78
|
+
import { str } from "./coerce.js";
|
|
79
|
+
import { type MetaBundle } from "./meta.js";
|
|
80
|
+
export { str };
|
|
81
|
+
type FacilityType = "nursing_home" | "home_health" | "hospice" | "dialysis";
|
|
82
|
+
export type Facility = {
|
|
83
|
+
name: string | null;
|
|
84
|
+
address: string | null;
|
|
85
|
+
city: string | null;
|
|
86
|
+
state: string | null;
|
|
87
|
+
zip: string | null;
|
|
88
|
+
facilityType: FacilityType;
|
|
89
|
+
ownership: string | null;
|
|
90
|
+
};
|
|
91
|
+
/**
|
|
92
|
+
* Coalesce a row's value over a candidate column order → string | null.
|
|
93
|
+
* Returns the FIRST column whose str() is non-null (str nulls ""/whitespace/"null");
|
|
94
|
+
* null if NONE — NEVER an empty string, NEVER a fabricated value (P3).
|
|
95
|
+
*/
|
|
96
|
+
export declare function coalesceField(row: Record<string, unknown>, fields: string[]): string | null;
|
|
97
|
+
export type CmsFacilityDirectoryArgs = {
|
|
98
|
+
facilityType?: string;
|
|
99
|
+
state?: string;
|
|
100
|
+
facilityName?: string;
|
|
101
|
+
size?: number;
|
|
102
|
+
offset?: number;
|
|
103
|
+
};
|
|
104
|
+
/**
|
|
105
|
+
* Fetch CMS provider-data facility rows for a `facilityType` (+ optional state /
|
|
106
|
+
* facility-name fragment) → normalized facility rows + honest `_meta`. The
|
|
107
|
+
* facilityType (a Zod enum) indexes the FACILITY_DATASETS constant map to a vetted
|
|
108
|
+
* dataset id — the user value never enters the path. A SINGLE request: the response's
|
|
109
|
+
* top-level `count` is the EXACT per-filter total (P1 — never the slice length).
|
|
110
|
+
*/
|
|
111
|
+
export declare function facilityDirectory(args: CmsFacilityDirectoryArgs): Promise<MetaBundle>;
|
|
112
|
+
//# sourceMappingURL=cms-facility.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cms-facility.d.ts","sourceRoot":"","sources":["../src/cms-facility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAIH,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAIzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAkBf,KAAK,YAAY,GAAG,cAAc,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AA8D5E,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,MAAM,EAAE,GACf,MAAM,GAAG,IAAI,CAMf;AA0CD,MAAM,MAAM,wBAAwB,GAAG;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,UAAU,CAAC,CAkIrB"}
|