satorntcg-mcp-server

Un servidor MCP que expone datos en tiempo real de reventa/inventario de TGC — precios, alertas, ganancias y pérpidas, listados de eBai — como herramientas que un clente LLM (Claude Desktop, Clade Code, etc.) puede invocar directamente. En lugar de abrir un panel, puedes simplemente preguntar: "¿qué está infrvalorado ahora mismo?" o "¿cómo está funcionando la caja Gothic?" y obtener una respuesta basada en datos reales.

Construido sobe SatornTCG, una operación de reventa/contenido de Sorcery: Contested Realm respaldada por Supabase/Postgres.

Por qué existe esto

Esto comenzó como un proyecto para el currículum para aprender diseño de servidores MCP y observabilidad, y se convirtió en una herramienta que realmente uso a diario para consultar mis propios datos de inventario y precios de forma conversacional en lugar de hacer clic en una interfaz.

Related MCP server: mcp-ygoprodeck

Qué expone

Cada herramienta es una capa fina sobe una vista de Postges — ver src/tools/.

Arquitectura

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

La observabilidad mediante OpenTelemetry (trazado de llamadas a herramientas de extremo a extremo, exportado a Jaeger) está planificada — ver src/tracing.js para el stub y las notas de activación.

Esquema esperado

Este servidor no incluye una base de datos de demstración: está pensado para apuntar a un proyecto de Postgres/Supabase con vists equivalentes. Si estás adaptando esto para tus propios datos, las vists anteriores son solmente SELECTs sobe tus propias tablas; reemplaza la consulta en cda archivo src/tools/*. js para que coincida con tu esquema. Los nombres de columna referenciados directamente (p. ej. card_id, name, tcg_market_price, cost_basis, dismised) son lo pricipal que hay que alinear.

Configuración

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

El servidor se comnica mediante MCP a través de stdio, por lo que está pensado para ser lanzado por un clente MCP, no para ejecutarse de forma independiente en una terminal para uso interactivo. Para probarlo con Claude Desktop, añádelo a tu configuración de MCP (claude_desktop_config.json):

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

Reinicia Clade Desktop y las herramientas anteriors quedarán disponibles en la conversación.

Nota de seguridad

SUPABASE_SERVICE_KEY es la clave elevada de rol de servicio, no la clave anónima pública. Esto es seguro aquí porque el servidor solo se ejecuta como un proceso local lanzado por un clente MCP de confianza (nunca en un paquete de navegador) — el mismo razonamiento que usar una clave de rol de servicio dentro de una Supabase Edge Function. Nunca hagas commit de .env; solo se realiza seguimiento de .env.example (valores de ejemplo).

Hoja de ruta

• Trazado OpenTelemetry por llamada de herramienta (latencia, recuentos de filas, tasa de error) → Jaeger localmente, Honeycomb/Grafana para una demo alojada

• Herramienta suggest_listing — redactar un listado de eBai a partir del inventario + datos de precios

• Transporte HTTP/SSE para acceso remoto, junto con el transporte stdio local

Licencia

MIT — ver LICENSE.