carddata

carddata

carddata は、スポーツカードやトレーディングカードの現在の落札価格を追跡する、ホスト型の HobbyCardIndex カード価格 MCP サーバーへの小規模なローカルブリッジです。コレクターが使うように、年、セット、選手またはキャラクター、カード番号を説明すると、一致するカードと未鑑定品および PSA 10 の価格が返されます。その後、カードを 1 枚指定して詳細を取得し、未鑑定品、PSA 7 から PSA 10、BGS 9.5、CGC 10、SGC 10 の各グレードでの落札価格を確認できます。また、プラン一覧を読み込み、商用 API とアプリの各プランの料金や内容を確認することもできます。

このブリッジ自体は価格を保持しません。ライブエンドポイントから取得したとおりに、ツール一覧をローカルで返し、各ツール呼び出しを上流に転送して、返ってきた内容を変更せずに返します。ここで利用できるのは読み取り専用の 3 つのツールです。元のサーバーにはチェックアウト用ツールもありましたが、この再構築には意図的に含めていないため、このパッケージが購入を開始したり、支払いを処理したりすることはありません。

ツール

• search_cards — カードと現在の落札価格を検索します。必須：query（年、セット、選手またはキャラクター、分かる場合はカード番号。2～120 文字）。任意：category（例：野球、バスケットボール、アメリカンフットボール、ホッケー、サッカー、ポケモン、マジック、遊戯王、ワンピース）と limit（一致件数。1～5 件、デフォルトは 5）。一致するカードを最大 5 件返し、未鑑定品（未グレーディング）と PSA 10 の価格、card_id、カードページへのリンクを含みます。HobbyCardIndex API キーが必要です。
• get_card_prices — 1 枚のカードについて、すべてのグレードの現在の落札価格を返します。必須：card_id（search_cards が返した ID）。未鑑定品、PSA 7、PSA 8、PSA 9、PSA 10、BGS 9.5、CGC 10、SGC 10 の価格を米ドルで返し、最近の落札情報と価格履歴を確認できるカードページへのリンクも含みます。HobbyCardIndex API キーが必要です。
• list_plans — 現在提供中のプランを確認します。引数は不要で、API キーなしで動作します。商用 API の各プラン（リクエスト数、写真スキャン数、落札価格の照会数、認証番号の照会数）と、アプリの Pro、Dealer、Enterprise プランについて、月額料金（米ドル）、利用条件、購入方法を返します。このツールはプラン一覧を読み取るだけで、購入を開始することはありません。

設定

• HOBBYCARDINDEX_MCP_URL（任意）— 上流エンドポイントを上書きします。デフォルトは https://hobbycardindex.com/api/v1/mcp です。（この上書き用フックは、この再構築で独自に追加したものとして明記されています。）
• HOBBYCARDINDEX_API_KEY（任意）— 設定すると、呼び出し元自身の HobbyCardIndex API キーを使い、上流へのすべてのリクエストに X-API-Key: <key> ヘッダーが付与されます。設定されていない場合、キーのヘッダーは送信されません。（ヘッダー名は元のレジストリレコードで確認されていますが、レコードにはパッケージの環境変数名が記載されていません。そのため、この環境変数からキーを転送する動作は、再構築で独自に追加したものとして明記されています。元のインターフェースはキーなしで取得されました。）

転送の仕組み

最初のツール呼び出し時に、クライアントは上流とのストリーム可能な HTTP セッションを開きます。まず JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo 名 carddata）を送り、次に notifications/initialized 通知を送り、その後、呼び出し元の引数を変更せずに含めた tools/call リクエストを送ります。上流が initialize に Mcp-Session-Id ヘッダーを付けて応答した場合、その値はセッションの後続リクエストすべてに付与され、プロセスの終了まで同じセッションが再利用されます。応答は通常の JSON またはサーバー送信イベントとして届く場合があり、どちらも読み取られます。

上流からの成功結果は、上流が設定した isError フラグも含めて、そのまま返されます。JSON-RPC エラー、2xx 以外のステータス、読み取れない応答、または完了できないリクエストによる失敗は、テキストが carddata error: で始まる isError 結果として返されます（この表示方法は、この再構築で独自に追加したものとして明記されています）。

CLI

各ツールは、1 つの JSON 引数文字列を受け取るサブコマンドとしても実行できます。

npx @reneturcios/carddata search_cards '{"query":"1989 Upper Deck Ken Griffey Jr 1"}'
npx @reneturcios/carddata get_card_prices '{"card_id":12345}'
npx @reneturcios/carddata list_plans '{}'
npx @reneturcios/carddata --version

終了コード：成功時は 0、isError 結果の場合は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/carddata mcp

MCP クライアントの設定：

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

Docker

docker run -i ghcr.io/cloudcorprecords/carddata
docker run --rm ghcr.io/cloudcorprecords/carddata --version

コンテナのデフォルトコマンドは mcp なので、最初の形式は stdio MCP サーバーです。それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートはすべて、スタブ化された JSON-RPC アップストリームに対して実行されます。実際のネットワーク呼び出しはありません。

ライセンス

MIT — LICENSE を参照してください。