fedvendor

fedvendor

SAM.gov 是美国联邦供应商体系进行注册、排除、征集和授标的平台，而相关信息分散在六个习惯各异的公共 API 中。fedvendor 将它们封装在一个客户端中：提供二十种工具，涵盖实体注册、暂停资格记录、实时合同机会、授标历史、联邦组织架构、FFATA 分包报告以及产品／服务代码，所有工具均使用同一个 SAM.gov API 密钥。

大多数工具会原样返回 SAM.gov 提供的上游 JSON。三个授标工具是例外：它们会返回规范化的 {"awardSummary": [...], "totalRecords": int} 结构，因此变更、搜索结果和已删除记录的读取方式一致。

配置

• SAM_API_KEY（十九种数据工具必需）——你的 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 查询一个实体。 include_sections 用于选择响应部分，默认为 entityRegistration,coreData。
• lookup_entity_by_cage——按 cage 查询一个实体，部分选择方式相同。
• 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 使用 size 而非 limit 分页）。

合同机会（v2）：

• search_opportunities——按 keyword（标题）、naics_code、psc_code、notice_type、state 和 zip 搜索，并支持以 MM/dd/yyyy 格式指定发布日期（posted_from／posted_to）和响应截止日期（response_from／response_to）范围，以及 limit 和 offset。agency_keyword 筛选器会在收到响应后于本地应用——API 会静默忽略其部门参数——只保留 fullParentPathName 中包含该关键词（不区分大小写）的结果。
• get_opportunity_description——获取 notice_id 对应的 HTML 描述。

合同授标（v1）——以下三种工具均返回上述规范化的授标结构：

• search_contract_awards——按 agency_id、naics_code、fiscal_year 和 piid 搜索；授标日期范围（award_date_from + award_date_to，MM/dd/yyyy）会作为一个方括号范围参数发送。分页参数为 limit（1–100）和 offset。
• lookup_award_by_piid——查询一个 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 获取某个组织的子级组织。

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 — 获取某个 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 天有效期，以及按账户类型划分的每日请求限额（无 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

每个工具都是一个子命令，接受一个 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 — 版权所有 (c) 2026 Rene Turcios