saleroom

saleroom

那块手表实际卖了多少钱？今天又值多少钱？saleroom 是一款只读客户端，用于访问 altfinance 拍卖结果服务。该服务追踪 20 个奢侈品类别的成交价：手表、手袋、珠宝、宝石、汽车和摩托车、飞机、葡萄酒和威士忌、艺术品、设计品、时装、硬币等。你可以列出各张表、查看表的列、对销售历史运行筛选和排序查询、读取汇总统计数据和价格趋势、查询单件物品的公允价值区间、一次搜索整个市场、查阅预先计算的品牌／型号价格指数，以及查看价格提醒。

这里的所有功能都不会交易、出价或更改任何内容：全部 9 个工具都只读。响应会原样返回服务提供的内容——不会在传递过程中删减、重命名或汇总。

配置

两个环境变量用于控制客户端：

• ALTFINANCE_API_KEY（必需）——每次请求都会在 Authorization: Bearer <key> 中发送。未设置时，所有工具都会在发出任何请求之前报错：ALTFINANCE_API_KEY is not set。
• ALTFINANCE_API_URL（可选）——API 基础 URL。默认为 https://api.altfndata.com。

工具

• list_tables — 列出可用的拍卖数据表，附带实时描述和列数。不接受参数。
• get_table_schema — 查看某张表的列名和类型。需要提供 table。
• query_table — 使用 filters、sort、fields 选择和分页功能查询数据表（limit 为 1–500，offset ≥ 0）。需要提供 table，其他参数均可选。
• market_stats — 查看某张表或筛选后细分数据的成交价汇总：数量、中位数、百分位数、平均值、最小值／最大值、销售日期跨度和主要卖家。需要提供 table，filters 可选。
• price_trend — 查看成交价随时间的变化，按 year、quarter 或 month 分桶。需要提供 table，bucket 和 filters 均可选。
• price_check — 根据可比销售记录估算单件物品的公允价值区间，并附来源链接。需要提供 item，category 可选。目前支持的类别为手袋、手表和汽车。
• search — 一次性跨所有类别搜索整个市场的关键词，并按成交价合并结果。需要提供 query，category 可选。
• market_index — 查询按品牌或型号预先计算的价格指数（手袋、手表、汽车）。需要提供 query，category 可选。
• list_alerts — 以只读方式查看价格提醒，或获取启用提醒的说明。不接受参数。

20 张表分别为：watches、handbags、jewelry、gems、automobile、motorcycle、aircraft、wine_whisky、works_of_art、fine_art、design、fashion、shoes、automobilia、books、coins、other_automobile、perfume、accessories 和 musical_instruments。

筛选条件的格式为 {column, operator, value}。运算符包括 eq、neq、gt、gte、lt、lte、like、in、not_in、is_null 和 is_not_null。使用 is_null／is_not_null 时省略 value；使用 in／not_in 时传入数组。排序条件的格式为 {field, direction}，其中 direction 为 asc 或 desc。

所有校验都会在发出请求前进行。未知运算符会报错：unknown filter operator: <op>；需要值但未提供时会报错：filter value is required for operator <op>；limit 超出 1–500 范围时会报错：limit must be an integer between 1 and 500。上游返回非 2xx 响应时会报错：altfinance error: HTTP <status>；API 无法访问时会报错：altfinance unreachable。

端点来源

原始服务的项目记录明确了这 9 个工具、 20 个表名、筛选运算符、排序、 字段选择和分页规则、趋势分桶以及 两个环境变量，也明确了这 9 个端点均为只读。 记录仅在文字说明中提及各工具的参数名称， 未明确规定筛选/排序 JSON 结构、身份验证 标头或请求路径。以下内容均为重构结果， 并已标注：

• Authorization: Bearer <key> 标头——重构结果 （记录仅明确规定使用 API 密钥身份验证）。
• GET <base>/v1/tables — list_tables。
• GET <base>/v1/tables/{table}/schema — get_table_schema。
• POST <base>/v1/tables/{table}/query，请求正文为 {filters?, sort?, fields?, limit?, offset?}（省略未设置的 字段）— query_table。
• POST <base>/v1/tables/{table}/stats，请求正文为 {filters?} — market_stats。
• GET <base>/v1/tables/{table}/trend；设置时使用 bucket 和 JSON 编码的 filters 查询参数 — price_trend。
• POST <base>/v1/price-check，请求正文为 {item, category?} — price_check。
• GET <base>/v1/search?q=&category= — search。
• GET <base>/v1/market-index?query=&category= — market_index。
• GET <base>/v1/alerts — list_alerts。

CLI

每个工具都是一个子命令，接受一个 JSON 参数字符串：

npx @reneturcios/saleroom list_tables '{}'
npx @reneturcios/saleroom query_table '{"table":"watches","filters":[{"column":"brand","operator":"eq","value":"Rolex"}],"limit":10}'
npx @reneturcios/saleroom price_check '{"item":"Rolex Submariner 1968","category":"watches"}'
npx @reneturcios/saleroom --version

输出为工具的结果文本（成功时为上游 JSON）。退出代码：成功时为 0，运行时错误（包括验证失败或上游失败）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/saleroom mcp

MCP 客户端配置：

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

Docker

docker run -i ghcr.io/cloudcorprecords/saleroom
docker run --rm ghcr.io/cloudcorprecords/saleroom list_tables '{}'

开发

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