fedvendor

fedvendor

SAM.gov は、米国連邦政府のベンダーが登録され、除外され、入札の依頼を受け、契約を獲得する場です。公開 API は複数あり、それぞれ仕様が異なります。fedvendor は、エンティティ登録、資格停止記録、進行中の契約機会、契約獲得履歴、連邦政府の組織図、FFATA の下請け報告、製品・サービスコードを網羅する 20 個のツールを、1 つのクライアントで利用できるようにします。すべてのツールは 1 つの SAM.gov API キーを使用します。

ほとんどのツールは、SAM.gov が送信した上流の JSON をそのまま返します。例外は契約獲得情報の 3 つのツールです。これらは正規化された {"awardSummary": [...], "totalRecords": int} 形式を返すため、変更情報、検索結果、削除済みレコードをすべて同じ形式で読み取れます。

設定

• SAM_API_KEY（19 個のデータツールで必須） — SAM.gov の公開 API キーです。すべてのリクエストで api_key クエリパラメーターとして送信されます。設定されていない場合、すべてのデータツールは SAM_API_KEY is not set エラーで失敗し、リクエストは送信されません。SAM.gov のキーは 90 日ごとに期限切れになります。401 または 403 の応答はその旨を示し、再生成ページを案内します。get_access_status はキーなしで動作します。キーの状態を報告することが、このツールの役割です。
• SAM_API_BASE_URL（任意） — API のベース URL です。デフォルトは https://api.sam.gov です。

国コードは、基盤となる API の仕様に従い、ISO 3166-1 alpha-3 を使用します。

ツール

エンティティ（Entity Management v3）：

• lookup_entity_by_uei — uei に該当するエンティティを 1 件取得します。 include_sections でレスポンスのセクションを選択します。デフォルトは entityRegistration,coreData です。
• lookup_entity_by_cage — cage に該当するエンティティを 1 件取得します。セクションの指定方法は同じです。
• search_entities — legal_business_name、primary_naics、state（物理住所の州）、business_type_code、sba_business_type_code、registration_status で柔軟に検索し、page と size を指定できます。API のページサイズ上限は 10 で、クライアント側でも上限が適用されます。size が 1～10 の範囲外の場合、リクエストを送信する前に size must be an integer between 1 and 10 エラーで失敗します。
• get_entity_reps_and_certs — uei に該当する FAR/DFARS の表明事項と認証を取得します。これらのセクションは All セクションのリクエストには含まれないため、専用のツールを用意しています。entityRegistration は常に併せて含まれます。
• get_entity_integrity_info — uei に該当する FAPIIS 手続き（完全性情報）を取得します。こちらも entityRegistration とともに明示的にリクエストします。

除外情報（v4）：

• check_exclusion_by_uei — この uei は資格停止中ですか？
• search_exclusions — name、classification、agency で検索し、page と size でページ分割します（この API のページ分割には limit ではなく size を使用します）。

契約機会（v2）：

• search_opportunities — keyword（タイトル）、naics_code、psc_code、notice_type、state、zip で検索します。掲載日（posted_from / posted_to）と回答期限（response_from / response_to）の範囲は MM/dd/yyyy 形式で指定し、limit と offset も指定できます。agency_keyword フィルターは、レスポンスを受信した後にローカルで適用されます。API は省庁のパラメーターを黙って無視するため、fullParentPathName にキーワードが含まれる結果だけを、大文字と小文字を区別せずに残します。
• get_opportunity_description — notice_id に該当する HTML の説明を取得します。

契約獲得情報（v1） — 3 つのツールはいずれも、前述の正規化された契約獲得情報の形式を返します。

• search_contract_awards — agency_id、naics_code、fiscal_year、piid で検索します。契約獲得日（award_date_from + award_date_to）の範囲は MM/dd/yyyy 形式で、1 つの範囲パラメーターとして送信されます。ページ分割には limit（1～100）と offset を使用します。
• lookup_award_by_piid — 1 つの piid に該当するすべての変更情報を取得します。
• search_deleted_awards — 監査証跡用に、削除済みの契約獲得レコードを検索します。

連邦政府の階層（v1）：

• search_federal_organizations — 組織図を fh_org_id、name、org_type（DEPARTMENTや AGENCYなどの略称も使用できます）、 status、agency_code、cgacで検索します。レスポンスでは、 上流の小文字のtotalrecords／orglistキーをそのまま保持します。
• get_organization_hierarchy — fh_org_idで指定した 1つの組織の子組織を取得します。

FFATAサブアワード — 日付はISO形式のyyyy-MM-dd、ページネーションには page_number／page_sizeを使用します。

• search_acquisition_subawards — piid、 referenced_idv_piid、agency_id、 statusで絞り込んだ下請契約レポートを検索します。
• search_assistance_subawards — fain、 prime_award_key、agency_code、 statusで絞り込んだ助成金サブアワードレポートを検索します。

PSCコード：

• lookup_psc_code — 1つのpsc_codeの全レコードを取得します。
• search_psc_free_text — フリーテキストの queryでコードを検索します。

複合ツール：

• vendor_responsibility_check — ueiに対するFAR 9.104-1の 責任確認を一度の呼び出しで実行します。エンティティの検索と 除外対象の検索を単一の呼び出しで行い、 {"uei", "entity", "exclusions", "flags"}として返します。フラグは ローカルで構成され、他の条件に該当しない場合は entity_not_found、registration_inactive、excluded、または clearになります。
• get_access_status — 認証情報の準備状況を確認します。 SAM_API_KEYが設定されているか、キーの有効期限が90日であること、 アカウント種別ごとの1日のリクエスト上限 （SAM.govのロールを持たない非連邦ユーザーは10、ロールを持つユーザー または連邦政府の個人アカウントは1000、連邦政府のシステムアカウントは10000） を返します。リクエストは行いません。

検証に失敗した場合、リクエストを送信する前に特定のメッセージが返されます。 必須の文字列では<arg> must be a non-empty string、サイズ／上限の範囲については 上記のメッセージ、案件およびアワードの日付では <arg> must use MM/dd/yyyy、サブアワードの日付では <arg> must use yyyy-MM-ddが返されます。 その他の上流の非2xxレスポンスでは sam.gov error: HTTP <status>が返され、APIに到達できない場合は sam.gov unreachableが返されます。

再構成した名称

ツールのインターフェース、ベースURL、ドキュメントに記載されたパラメーター名は、SAM.gov APIドキュメントと元のツールの公開説明に基づいています。一部の詳細は再構成したものであり、その旨を明記しています。 get_access_statusの名称は、認証情報確認に関するベンダーファミリーの公開パターンに従っています。除外対象エンドポイントのueiSAMパラメーター、Federal Hierarchyのパラメーター名、アワードの範囲指定パラメーター名、PSCエンドポイントのsearchby=keywordの値、アワードのワイヤ名であるagency_id／naics_code／fiscal_year、複合ツールのフラグ文字列は、ドキュメントに記載された動作を表現したものであり、名前を逐語的に固定したものではありません。全体を通して、MCPの引数名はドキュメントに記載されたワイヤ名をsnake_caseで表記しています。

CLI

各ツールは、1つのJSON引数文字列を受け取るサブコマンドです。

export SAM_API_KEY="<your key>"
npx @reneturcios/fedvendor lookup_entity_by_uei '{"uei":"ABC123XYZ"}'
npx @reneturcios/fedvendor lookup_entity_by_cage '{"cage":"1A2B3"}'
npx @reneturcios/fedvendor search_entities '{"legal_business_name":"Acme","size":5}'
npx @reneturcios/fedvendor get_entity_reps_and_certs '{"uei":"ABC123XYZ"}'
npx @reneturcios/fedvendor check_exclusion_by_uei '{"uei":"ABC123XYZ"}'
npx @reneturcios/fedvendor search_opportunities '{"keyword":"software","agency_keyword":"defense"}'
npx @reneturcios/fedvendor search_contract_awards '{"fiscal_year":"2026","limit":10}'
npx @reneturcios/fedvendor lookup_award_by_piid '{"piid":"W91ZLK24P0001"}'
npx @reneturcios/fedvendor search_federal_organizations '{"org_type":"DEPARTMENT"}'
npx @reneturcios/fedvendor lookup_psc_code '{"psc_code":"D399"}'
npx @reneturcios/fedvendor vendor_responsibility_check '{"uei":"ABC123XYZ"}'
npx @reneturcios/fedvendor get_access_status '{}'
npx @reneturcios/fedvendor --version

出力はツールの結果テキストです（成功時は上流のJSON）。終了コード：成功時は0、実行時エラー（検証エラー、キー不足、上流エラーを含む）時は1、使用方法のエラー時は2です。

MCP サーバー

npx -y @reneturcios/fedvendor mcp

MCPクライアントの設定（キーはクライアントの環境変数を通じて指定します）：

{
  "mcpServers": {
    "fedvendor": {
      "command": "npx",
      "args": ["-y", "@reneturcios/fedvendor", "mcp"],
      "env": {
        "SAM_API_KEY": "<your key>"
      }
    }
  }
}

Docker

docker run -i -e SAM_API_KEY="<your key>" ghcr.io/cloudcorprecords/fedvendor
docker run --rm -e SAM_API_KEY="<your key>" ghcr.io/cloudcorprecords/fedvendor get_access_status '{}'

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios