satorntcg-mcp-server

MCP 서버로, 실시간 TCG 재판매/재고 데이터 — 가격, 알림, 손익, eBay 목록 — 를 LLM 클라이언트(Claude Desktop, Claude Code 등)가 직접 호출할 수 있는 도구로 노출합니다. 대시보드를 여는 대신 "지금 저평가된 건 뭐지" 또는 *"Gothic box는 어떻게 성과를 내고 있나요"*라고 물어보기만 하면 실제 데이터에 기반한 답변을 얻을 수 있습니다.

SatornTCG를 기반으로 하며, Supabase/Postgres로 구동되는 Sorcery: Contested Realm 재판매/콘텐츠 운영입니다.

왜 만들었나

MCP 서버 설계와 관측 가능성(observability)을 배우기 위한 포트폴리오 프로젝트로 시작했지만, 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 키가 아니라 권한이 높은 service-role 키입니다. 이 서버는 신뢰할 수 있는 MCP 클라이언트가 실행하는 로컬 프로세스로만 동작하며(절대 브라우저 번들로 실행되지 않음) Supabase Edge Function 내부에서 service role 키를 사용하는 것과 같은 이유로 안전합니다. .env는 절대 커밋하지 마세요. 오직 .env.example(플레이스홀더 값)만 추적됩니다.

로드맵

• 도구 호출별 OpenTelemetry 추적(지연 시간, 행 수, 오류율) → 로컬에서는 Jaeger, 호스팅 데모에서는 Honeycomb/Grafana

• suggest_listing 도구 — 인벤토리 + 가격 데이터로 eBay 목록 초안 작성

• 로컬 stdio 전송과 함께 원격 접근을 위한 HTTP/SSE 전송

라이선스

MIT — LICENSE 참조.