satorntcg-mcp-server

リアルタイムな TCG 転売・在庫データ（価格、アラート、損益、eBay リスティング）を、LLM クライアント（Claude Desktop、Claude Code など）が直接呼び出せるツールとして公開する MCP サーバーです。ダッシュボードを開く代わりに、"いま何が割安か" や "Gothic box の調子はどうか" と尋ねるだけで、実データに基づいた回答が得られます。

これは、Supabase/Postgres をバックエンドとする Sorcery: Contested Realm の転売・コンテンツ運営である SatornTCG を基盤としています。

なぜこれを作ったのか

これは、MCP サーバーの設計と可観測性を学ぶための履歴書用のプロジェクトとして始まりましたが、やがて UI をクリックする代わりに自分の在庫・価格データを会話形式で照会するために毎日使うツールになりました。

Related MCP server: mcp-ygoprodeck

公開するツール

各ツールは Postgres ビューの薄いラッパーです — src/tools/ を参照してください。

アーキテクチャ

Claude Desktop / Claude Code (MCP client)
        │  stdio
        ▼
  src/index.js  ── registers tools, routes tool calls
        │
        ▼
  src/tools/*.js ── one file per domain, each tool = { name, description, inputSchema, handler }
        │
        ▼
  src/supabaseClient.js ── service-role Supabase client
        │
        ▼
  Postgres (Supabase) ── views: v_active_alerts, v_inventory_dashboard,
                          v_latest_prices, v_box_pnl, v_global_pnl,
                          v_ebay_active, v_ebay_sold, v_stale_listings,
                          v_price_gainers_losers, v_listing_price_alerts

OpenTelemetry による可観測性（ツール呼び出しをエンドツーエンドでトレースし、Jaeger にエクスポート）を計画中です — スタブと有効化のメモについては src/tracing.js を参照してください。

前提とするスキーマ

このサーバーにはデモデータベースは同梱されていません。同等のビューを持つ Postgres/Supabase プロジェクトを参照させることを想定しています。独自のデータに合わせて改変する場合、上記のビューは自分のテーブルに対する単なる SELECT です。各 src/tools/*.js ファイル内のクエリを自分のスキーマに合わせて置き換えてください。直接参照されるカラム名（例: card_id、name、tcg_market_price、cost_basis、dismissed）を合わせることが主なポイントです。

セットアップ

git clone <this-repo>
cd satorntcg-mcp-server
npm install
cp .env.example .env
# fill in SUPABASE_URL and SUPABASE_SERVICE_KEY in .env
npm start

このサーバーは stdio 上で MCP 通信を行うため、MCP クライアントから起動されることを想定しており、対話用途でターミナルで単独実行するためのものではありません。Claude Desktop でテストするには、MCP 設定（claude_desktop_config.json）に追加してください：

{
  "mcpServers": {
    "satorntcg": {
      "command": "node",
      "args": ["/absolute/path/to/satorntcg-mcp-server/src/index.js"]
    }
  }
}

Claude Desktop を再起動すると、上記のツールが会話で使えるようになります。

セキュリティに関する注意

SUPABASE_SERVICE_KEY は、公開 anon キーではなく、権限昇格されたサービスロールキーです。このサーバーは信頼できる MCP クライアントによって起動されるローカルプロセスとしてのみ実行されるため（ブラウザバンドル内では決して実行されません）、ここでは安全です。これは、Supabase Edge Function 内でサービスロールキーを使用するのと同じ考え方です。.env は決してコミットしないでください。バージョン管理されるのは .env.example（プレースホルダー値）のみです。

ロードマップ

• OpenTelemetry によるツール呼び出しごとのトレース（レイテンシ、行数、エラー率）→ ローカルでは Jaeger、ホステッドデモでは Honeycomb/Grafana

• suggest_listing ツール — 在庫と価格データから eBay リスティングの下書きを作成する

• リモートアクセス用の HTTP/SSE トランスポート（ローカルの stdio トランスポートと並行して）

ライセンス

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