saleroom

saleroom

あの時計は実際いくらで落札されたのでしょうか。そして、今日はいくらの価値があるのでしょうか。saleroom は、20 の高級品カテゴリーにわたる落札価格を追跡する altfinance のオークション結果サービス向けの読み取り専用クライアントです。対象カテゴリーには、時計、ハンドバッグ、ジュエリー、宝石、自動車とオートバイ、航空機、ワインとウイスキー、アート、デザイン、ファッション、コインなどがあります。テーブルの一覧表示、テーブルのカラム確認、販売履歴に対するフィルターや並べ替えを使ったクエリの実行、概要統計や価格推移の参照、単一アイテムの適正価格帯の確認、市場全体の一括検索、事前計算されたブランド／モデルの価格指数の参照、価格アラートの表示ができます。

ここでは取引も入札も変更も行われません。9 つのツールはすべて読み取り専用です。レスポンスはサービスから返された内容そのままで、途中で削除、名称変更、要約されることはありません。

Configuration

2 つの環境変数でクライアントを制御します。

• ALTFINANCE_API_KEY（必須） — すべてのリクエストで Authorization: Bearer <key> として送信されます。設定されていない場合、リクエストを行う前にすべてのツールが ALTFINANCE_API_KEY is not set で失敗します。
• ALTFINANCE_API_URL（任意） — API のベース URL です。デフォルトは https://api.altfndata.com です。

Tools

• list_tables — 利用可能なオークションテーブルの一覧を、最新の説明とカラム数とともに返します。引数はありません。
• get_table_schema — 1 つのテーブルのカラム名と型を返します。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 のテーブル名、フィルター演算子、並べ替え、フィールド選択とページネーションのルール、トレンドのバケット、2 つの環境変数が固定されており、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 with body {filters?, sort?, fields?, limit?, offset?} （未設定の フィールドは省略）— query_table。
• POST <base>/v1/tables/{table}/stats with body {filters?} — market_stats。
• GET <base>/v1/tables/{table}/trend with bucket and a JSON-encoded filters query parameter when set — price_trend。
• POST <base>/v1/price-check with body {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

各ツールは、1 つの 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 — Copyright (c) 2026 Rene Turcios