Us Auctions

@pipeworx/us-auctions

来自市场两端的实时美国拍卖标的——约 1,900 家商业拍卖行，以及所有可访问的政府剩余物资、查封物资和税契来源。支持按关键词、州或距邮政编码的距离搜索，还能查到拍卖结束后拍卖网站会删除的成交价。

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

工具

• us_auctions_search(keyword?, state?, asset_type?, segment?, source?, auction_house?, near_zip?, radius_miles?, max_price?, closing_within_hours?, limit?) — 通用标的搜索。传入 near_zip 后，结果会按距离排序，并在每条记录中提供 distance_miles。
• us_auctions_closing_soon(...) — 搜索同一批标的，按最早结束时间排序，并提供 hours_remaining。回答“我现在还能竞拍什么”。
• us_auction_events(state?, keyword?, auction_house?, closes_after?, closes_before?, min_lots?, limit?) — 查询拍卖场次，而不是标的。“下周我附近有哪些拍卖会？”
• us_auction_houses(state?, keyword?, limit?) — 查询我们覆盖的拍卖商及其当前在售数量，并按标的数量排序。可将名称传回上面两个工具。
• us_auctions_sold_comps(keyword?, asset_type?, state?, segment?, limit?) — 最低价 / 中位价 / 平均价 / 最高成交价，以及近期示例。这是差异化优势。
• us_auctions_coverage() — 按来源统计数量、未结束的拍卖场次数量、保留的成交记录，以及每个来源的上次刷新时间。

身份验证

调用方无需密钥。网关会在每次调用时注入此包的数据凭据； 此包本身无状态，不保留任何密钥。

与相邻软件包的关系

• gov-auctions — 使用同一数据存储，并按 segment='government' 筛选。由于它以更狭义的服务范围发布到 npm 和 MCP Registry，因此单独保留；询问剩余物资皮卡的调用方不应开始收到遗产拍卖的古董。
• gsa-auctions — 实时 GSA 联邦剩余物资 API。它不由数据库提供，因此其标的不在此数据存储中，也不会出现在这里。

数据来源

由 workers/auction-scraper 采集（每个来源使用一个适配器，并在定时任务触发之间恢复游标）。各来源的特殊情况请参阅该工作器。

• hibid — 商业来源。GraphQL，无需身份验证。约 1,900 家美国拍卖行。
• govdeals、allsurplus — 州和地方政府以及企业剩余物资。allsurplus 还覆盖 govliquidation.com 和 go-dove.com；它们是同一目录在不同域名下提供的版本，不要为它们构建适配器。
• publicsurplus、bid4assets、irs、txauction — 政府来源的其余部分。

否则后来者只能吃过苦头才会发现的事

• 此项目已禁用聚合函数和 group=（PGRST123）。 没有 count()。精确计数通过 Prefer: count=exact 和 Content-Range 末尾获取；us_auction_houses 中的每家拍卖行汇总数据，是在 pack 中基于有界行拉取计算的，而不是由数据库计算。
• 必须使用 final_price > 0，绝不能只用 not.is.null。 收尾任务会根据最后一笔已知出价冻结 final_price，而没有收到任何出价的商业拍品会冻结为 0。将这些拍品计为可比项，会把所有中位数都拉向 $0，而响应看起来仍然完全正常。
• 活动日期是本地日历日期，不是时间点。 closes_on / starts_on 是日期，因为 HiBid 发布的拍卖时间不带时区。 拍品级别的 closes_at 才是真正的时间点（由倒计时推算），这就是 closing_within_hours 依据拍品时间，而 us_auction_events 依据日期的原因。 不要通过解析本地字符串来“修复”此问题——这会悄无声息地将美国西海岸晚间的拍卖移到次日。
• 未筛选的搜索要用两个查询，而不是一个 or=。 按 closes_at 排序，同时将 closes_at >= now() 与 closes_at IS NULL 通过 OR 连接，无法利用索引；即使是最简单的调用，也会扫描整个活跃数据池并触发 8s 语句超时——结果时而是硬性 500 错误，时而是悄无声息地返回空结果。拆分查询返回的行及顺序完全相同。
• 坐标是 ZIP 邮区质心。 大多数来源只发布 ZIP 邮区，没有更精细的位置，因此拍品的位置就是所在城镇的位置。distance_miles 以城镇为单位；响应中已说明，今后也应继续如此说明。
• 关键词搜索先全文搜索，再子串搜索。 search_tsv（迁移 092 中的加权存储列）会进行词干提取，并检索描述；仅当全文搜索无结果时才会运行三元组 ILIKE 搜索，因为拍卖标题中有许多不完整的型号，tsquery 无法匹配单词内部的内容。

快速开始

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

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

此端点实际提供的内容

https://gateway.pipeworx.io/us-auctions/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 的共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall，以及网关范围内的其他工具。因此你看到的工具数量会多于此表中的数量：目前，单 pack 端点除了该 pack 自带的工具外，还会列出大约 30 个共享工具。连接的 initialize 响应会说明其确切范围，并且是当天范围的权威说明。

这是刻意如此，并非意外的多路复用。元工具让范围受限的连接能够回答此 pack 不涵盖的问题——通过可跨整个目录进行路由的 ask_pipeworx——而无需添加第二个 MCP 服务。目前无法在不包含这些工具的情况下挂载 pack 端点；如果额外的 schema 占用的上下文超出路由功能带来的收益，请连接一次完整网关，而不是连接多个 pack 端点。

或者连接完整的 Pipeworx 网关，直接列出每个 pack 的工具，而不只是此 pack 的工具：

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

两个 URL 都会接入同一个网关和同一批 1808+ 个数据源。唯一的区别是哪个 pack 的工具会被直接列出；无论通过哪个端点，ask_pipeworx 都能访问所有工具。

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

curl -X POST https://gateway.pipeworx.io/v1/tools/us_auctions_search \
  -H 'Content-Type: application/json' \
  -d '{"keyword":"forklift","limit":10}'

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

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

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

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

也可以直接运行，确认它能正常启动：

npx -y @pipeworx/mcp-us-auctions

它通过 stdin/stdout 使用 MCP 通信，并针对仅限此软件包的工具响应 initialize/tools/list/tools/call——不包含上方网关连接所添加的任何共享元工具。相同的源代码，相同的工具，无需 ask_pipeworx 路由。

使用 ask_pipeworx

你也可以用通俗的英语提问，而不是直接调用工具——这既适用于上方的软件包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Us Auctions data" })

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

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT