satorntcg-mcp-server

Сервер MCP, предоставляющий актуальные данные по перепродаже/инвентарю TCG — цены, оповещения, прибыль и убытки, лоты eBay — в виде инструментов, которые LLM-клиент (Claude Desktop, Claude Code и т. д.) может вызывать напрямую. Вместо того чтобы открывать дашборд, можно просто спросить: «что сейчас недооценено» или «как дела у бокса Gothic» — и получить ответ, основанный на реальных данных.

Построен на основе SatornTCG — проекта по перепродаже и созданию контента для Sorcery: Contested Realm, работающего на Supabase/Postgres.

Почему это существует

Это начиналось как проект для резюме, чтобы изучить проектирование MCP-серверов и наблюдаемость, а превратилось в инструмент, которым я реально пользуюсь каждый день, чтобы запрашивать свои данные по инвентарю и ценам в диалоговом режиме, а не кликая по интерфейсу.

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

Наблюдаемость черes OpenTelemetry (сквозная трассировка вызовов инструментов с экспортом в Jaeger) запланирована — см. src/tracing.js (заглушка) и заметки по активации.

Ожидаемая схема

Этот сервер не поставляется с демонстрационной базой данных — он предназначен для подкючения к проекту Postgres/Supabase с аналогчными предсталениями. Если вы адаптируете его под свои данные, предсталения выше — это просто SELECT по вашим табlицам; замените запрос в каждом файле 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

Сервер общается по MCP через stdio, поэтому его запусkает MCP-клиент, а не использует отдельно в терминале для интерактивной работы. Чтобы проверить его в Claude Desktop, добавьте его в ваш MCP-конфиг (claude_desktop_config.json):

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

Перезапустите Clade Desktop — и перечисленные выше инструменты станут доступны в диалоге.

Примечание по безопастности

SUPABASE_SERVICE_KEY — это повыенный ключ сервисной роли, а не публичный анонимный ключ. Здес это безопастно, потому что сервер всегда работает только как локальный процес, запусkаемый доверенным MCP-клиентом (никогда в сотаве браузерной сборки), — та же логika, что и при использовании ключа сервисной роли внутри Supabase Edge Function. Никогда не коммитьте .env; в репозитории отслеживается только .env.example (значения-заглушки).

Дорожная карта

• Отслеживание OpenTelemetry для каждого вызова инструмента (задержка, количестrow строк, частота ошибок) → Jaeger локально, Honeycomb/Grafana для размещённого демо

• Инструмент suggest_listing — черновик лота eBay на оснove данных инвентаря и цен

• Транспорт HTTP/SSE для удалённого доступа наряду с локальным транспортом stdio

Лицензия

MIT — см. LICENSE.