Samgov

SAM.gov — 联邦采购与实体注册

美国总务管理局的奖励管理系统。它是联邦合同机会、实体（供应商）注册、预留类别标识、排除记录（取消资格）和援助项目的权威来源。任何向联邦政府销售产品或服务的人都应阅读。

属于 Pipeworx 的一部分——这是一个 MCP 网关，可将 AI Agent 连接到 1689+ 个实时数据源。这是独立、非官方的集成，与上游提供方无关联、未获其认可，也未由其发布。

这为何对 AI Agent 很重要

分为三个不同的领域：

1. 合同机会（RFP、RFQ、意向征询等）——联邦政府目前正在采购什么。→ sam_search_opportunities({keyword})。查询某个具体招标项目：sam_get_opportunity({solicitation_number})。

2. 实体记录——已注册的供应商，包含 CAGE 代码、UEI、NAICS 代码和认证。→ sam_entity_search({business_name})。

3. 预留类别机会——小型企业、退伍军人所有企业、女性所有企业、HUBZone 等。→ sam_set_aside_opportunities({set_aside})。

搭配 USAspending（授标后的合同数据）和 govcon_contractor_profile 复合工具，可支持完整的 Agent 工作流。

身份验证

SAM.gov 要求使用从 https://sam.gov/data-services 获取的免费 API 密钥。通过 _apiKey 传入。调用方未提供密钥时，网关回退使用的共享 PLATFORM_SAM_KEY 是个人级密钥，每日配额严格限制为 10 次请求——根据 2026-09-01 的实时测量，该密钥恰好响应了 10 次调用，当天剩余的 UTC 时间内均返回 900804 Message throttled out，且 nextAccessTime 设置为下一个 UTC 午夜。关于 sam_search_opportunities 现在为何大多不再需要密钥，请参阅下方的镜像说明。实体搜索和排除记录搜索现在也不再需要密钥（迁移 135）：两者均从 SAM.gov 公共实体注册和排除数据摘录的本地快照中返回结果。2026-09-13 的实时验证未提供密钥——sam_entity_search 从包含 889,932 行的镜像中返回了 Lockheed Martin，sam_search_exclusions 则从包含 168,462 行的镜像中返回结果。只有 sam_get_opportunity 和 sam_set_aside_opportunities 仍会在每次调用时访问需要密钥的实时 API；传入 live:true 时，sam_entity_search 也会访问该 API。

建议使用自己的密钥。 GSA 根据账户所具备的条件设定配额，而不是根据付费金额：没有 SAM.gov 角色的非联邦个人密钥每日限额为 10 次（共享密钥目前就属于这一层级）；账户添加角色后，同一个密钥每日限额为 1,000 次；非联邦系统账户的每日限额也为 1,000 次——以上均免费（https://open.gsa.gov/api/entity-api/）。因此，传入 _apiKey 并非规避 Pipeworx 限制，而是通过更改账户资料获得 100 倍的配额。

共享密钥用尽时，这些工具不会只返回一条上游错误：它们会说明配额是每日限额，列出 SAM.gov 报告的确切重置时间，并指出两种解决方法（传入 _apiKey，或使用无需密钥即可按关键词搜索的 sam_search_opportunities）。每日配额无法靠重试恢复；如果不明确告知 Agent 这一点，它就会不断重试。

数据镜像（fleet #343）

sam_search_opportunities 会优先读取 Supabase 镜像，只有在此之后才会使用共享 API 密钥：SAM.gov 每天都会发布完整的 Contract Opportunities 列表，作为公开 CSV 数据提取文件，无需密钥，也没有速率限制——https://s3.amazonaws.com/falextracts/Contract%20Opportunities/datagov/ContractOpportunitiesFullCSV.csv（同一个 falextracts 存储桶也链接在 SAM.gov 自己的 Data Services 页面上）。GitHub Actions 任务（scripts/samgov-upsert.sh，计划配置位于 .github/workflows/samgov-refresh.yml）每天都会将数据载入 samgov_opportunities。

该镜像通过相关性而非简单的标题或描述筛选来排列匹配结果（rpc/search_samgov_opportunities，迁移 075）：title 的权重远高于 description（setweight() + ts_rank_cd）。此前两种方案都存在问题，且都在实际运行中被发现：对“cybersecurity”进行简单的描述匹配时，海军硬件公告（HOSE,NONMETALLIC、WASHER）排在了前面，因为公告模板中的 DFARS/NIST 条款文本碰巧包含这个词，而这些公告实际与网络安全无关；随后采用的“优先匹配标题，不匹配时再匹配描述”的方案也在下一层遇到了同样的问题——“cloud computing”落入描述匹配层后，结果中出现了水箱维修和 MRI 翻新项目，因为无论实际范围如何，SAM.gov 的公告模板都会插入标准的云计算服务条款文本，而 phraseto_tsquery 仍会匹配这段原样的模板文本。直接在源头修正排序即可解决问题：标题命中一次的权重约为描述中单次提及的 2.5 倍，因此它会在同一组结果中排到前面，无需依靠硬性分层才能得到正确结果。这仍然严格比实时 API 的 title= 参数覆盖范围更广（已在 fleet #311 中从不存在的 keyword= 参数修正）——实时 API 只会匹配标题。无论由哪条路径返回，所有 sam_search_opportunities 响应都会包含一个 mirror 对象，报告快照的新鲜度（snapshot_date、rows_in_mirror）。只有在以下情况才会使用实时 API：未配置或未载入镜像，或者明确提供的 posted_from 超出了镜像的 snapshot_date（默认 30 天的时间范围不会触发这种情况——只有你实际传入的参数才会触发）。单个机会查询和 set-aside 搜索不受影响——机会 CSV 未涵盖这些端点类型，因此始终使用实时 API。实体搜索和排除名单后来也有了各自的镜像（迁移 135），默认无需密钥即可查询。

适用场景

• “联邦政府正在采购哪些网络安全产品或服务？” → sam_search_opportunities({keyword: "cybersecurity"}) → 正在进行的 RFP。
• “查找面向 AI 的 SBIR/STTR 小型企业预留项目。” → sam_set_aside_opportunities({set_aside: "SBIR"})，按描述筛选。
• “X 是否在联邦政府注册？” → sam_entity_search({business_name: "X"}) → CAGE/UEI 以及 NAICS 覆盖范围。
• “他们是否在排除名单上？” → sam_search_exclusions（无需密钥）。**它回答的是“今天是否被禁止”，而不是“曾经是否被禁止”：**SAM.gov 每日发布的 Exclusions 数据提取文件只包含当前仍生效的排除项，因此，已终止的取消资格记录会完全缺失于源数据中。虽然接受 include_terminated，但它无法显示这些记录——在 2026-09-13 测量时，禁用该筛选条件后，对四个名称抽样的 400 条记录中，终止日期均不在过去。请据此解读空结果。

常见误区

• 招标机会的生命周期状态。“进行中”“已归档”“已授标”“已取消”——机会会在不同状态之间变动。筛选“进行中”，以查看当前需要采取行动的项目。
• **NAICS 代码很重要。**公司会按特定 NAICS 代码注册；SAM.gov 会限制它们可以竞标的合同。进行竞争情报分析的 Agent 需要读取 NAICS 代码，而不只是公司名称。
• **UEI 已取代 DUNS。**自 2022 年 4 月起，SAM.gov 使用唯一实体标识符（UEI）取代 DUNS 号码。旧数据中会引用 DUNS；新数据则使用 UEI。sam_entity_search 会同时返回两者，方便交叉引用。
• **查询语言：镜像与实时接口。**镜像路径（常见情况）会对标题和描述进行全文匹配，因此使用描述性短语即可。实时 API 回退路径只匹配标题，因此冗长的描述性查询会比聚焦的查询返回更少结果——如果结果少于预期，请检查响应的 source 字段（sam.gov-mirror 与 sam.gov-live）。
• **小企业保留项目筛选。**常见的保留项目代码：SBA（小企业）、8A（8(a) 计划）、WOSB（女性所有企业）、SDVOSBC（服务伤残退伍军人所有企业）、HZC（HUBZone）、SBIR（SBIR/STTR）。代码错误会导致结果为空，而不是报错。
• 简短或常见词语缩写在镜像中会降低精度。"IT services" 的效果会大打折扣——Postgres 的 english 全文搜索配置会将“IT”视为停用词并将其删除，因此查询会在不提示的情况下变成仅搜索 "services"（约 12k 条匹配结果，大多无关）。"artificial intelligence"、"cybersecurity"、"cloud computing" 等多音节或有辨识度的词语排名效果较好；单独使用两个字母的缩写则不然。如果简写形式也是常见英语单词，请优先使用完整短语（例如“information technology services”“help desk support”）。
• 地理位置的定义较宽泛。“履约地点”指合同的执行地点，而不是授标机构所在地。

快速开始

添加到 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "samgov": {
      "url": "https://gateway.pipeworx.io/samgov/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/samgov/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 以及网关范围内的其他工具。因此，你看到的工具数量会多于此表：目前，单一工具包端点会列出约 30 个共享工具，以及该工具包自有的工具。连接的 initialize 响应会说明确切范围，也是当天情况的权威依据。

这是有意为之，并非意外复用。元工具可以让限定范围的连接回答此工具包未涵盖的问题——通过 ask_pipeworx 跨整个目录进行路由——无需添加第二个 MCP 服务。目前无法挂载不带这些工具的工具包端点；如果额外的架构定义占用的上下文多于路由带来的价值，请连接完整网关，而不是连接多个工具包端点。

或者连接完整的 Pipeworx 网关，直接列出所有工具包的工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和相同的 1689+ 个数据源。唯一的区别是，哪个工具包的工具会被直接列出；无论连接哪一个，ask_pipeworx 都能访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/sam_search_opportunities \
  -H 'Content-Type: application/json' \
  -d '{"keyword":"software development","naics":"541512","posted_from":"01/01/2024","posted_to":"12/31/2024","limit":20}'

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/sam_search_opportunities。查找工具：使用 {"query":"..."} 向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需经过网关：

{
  "mcpServers": {
    "samgov": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-samgov"]
    }
  }
}

或者直接运行，确认服务能够启动：

npx -y @pipeworx/mcp-samgov

它通过 stdin/stdout 使用 MCP 通信，并为仅此工具包的工具响应 initialize/tools/list/tools/call——不包含上方网关连接额外提供的共享元工具。来源相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

无需直接调用工具，你可以用通俗的英语提问—— 这在上方的 pack 端点和完整网关上都适用：

ask_pipeworx({ question: "your question about Samgov data" })

网关会选择合适的工具并自动填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT