satorntcg-mcp-server

Ein MCP-Server, der Live-Resale-/Inventardaten für TCG bereitstellt — Preise, Alerts, Gewinn & Verlust, eBay-Listings — als Tools, die ein LLM-Client (Claude Desktop, Claude Code, etc.) direkt aufrufen kann. Statt ein Dashboard zu öffnen, kannst du einfach fragen: „was ist gerade unterbewertet“ oder „wie schlägt sich die Gothic box“ und bekommst eine Antwort, die auf echten Daten basiert.

Basiert auf SatornTCG, einem Resale-/Content-Betrieb rund um Sorcery: Contested Realm, der von Supabase/Postgres unterstützt wird.

Warum es das gibt

Das begann als Projekt für meinen Lebenslauf, um MCP-Server-Design und Observability zu lernen, und wurde zu einem Tool, das ich tatsächlich täglich nutze, um meine eigenen Inventar- und Preisdaten konversationell abzufragen, statt mich durch eine UI zu klicken.

Related MCP server: mcp-ygoprodeck

Was es bereitstellt

Jedes Tool ist ein dünner Wrapper um eine Postgres-View — siehe src/tools/.

Architektur

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

Observability über OpenTelemetry (Ende-zu-Ende-Tracing von Tool-Aufrufen, exportiert nach Jaeger) ist geplant — siehe src/tracing.js für den Stub und Aktivierungshinweise.

Erwartetes Schema

Dieser Server enthält keine Demo-Datenbank — er ist dafür gedacht, auf ein Postgres/Supabase-Projekt mit entsprechenden Views zu zeigen. Wenn du das für deine eigenen Daten anpasst, sind die obigen Views lediglich SELECTs über deine eigenen Tabellen; tausche die Abfrage in jeder src/tools/*.js-Datei aus, damit sie zu deinem Schema passt. Die direkt referenzierten Spaltennamen (z. B. card_id, name, tcg_market_price, cost_basis, dismissed) sind das Wichtigste, das du angleichen musst.

Setup

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

Der Server spricht MCP über stdio und soll daher von einem MCP-Client gestartet werden — nicht für den eigenständigen Betrieb in einem Terminal zur interaktiven Nutzung. Um es mit Claude Desktop zu testen, füge es zu deiner MCP-Konfiguration (claude_desktop_config.json) hinzu:

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

Starte Claude Desktop neu, und die obigen Tools stehen im Chat zur Verfügung.

Sicherheitshinweis

SUPABASE_SERVICE_KEY ist der erhöhte Service-Role-Key, nicht der öffentliche Anon-Key. Das ist hier unbedenklich, weil der Server nur als lokaler Prozess läuft, der von einem vertrauenswürdigen MCP-Client gestartet wird (niemals in einem Browser-Bundle) — dieselbe Überlegung wie bei der Verwendung eines Service-Role-Keys in einer Supabase Edge Function. Commite niemals .env; nur .env.example (Platzhalterwerte) wird versioniert.

Roadmap

• OpenTelemetry-Tracing pro Tool-Aufruf (Latenz, Zeilenzahlen, Fehlerrate) → Jaeger lokal, Honeycomb/Grafana für eine gehostete Demo

• suggest_listing-Tool — ein eBay-Listing aus Inventar- und Preisdaten entwerfen

• HTTP/SSE-Transport für den Fernzugriff, neben dem lokalen stdio-Transport

Lizenz

MIT — siehe LICENSE.