satorntcg-mcp-server

一个 MCP 服务器，将实时的 TCG 转售/库存数据——定价、提醒、盈亏、eBay 列表——作为工具暴露出来，供 LLM 客户端（Claude Desktop、Claude Code 等）直接调用。无需打开仪表盘，你只需问：“现在哪些被低估了？” 或 “Gothic 盒子表现如何？” 就能得到基于真实数据的答案。

基于 SatornTCG 构建，这是一个由 Supabase/Postgres 支持的 Sorcery: Contested Realm 转售/内容业务。

为什么存在

这最初是一个为了学习 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。

它期望的 Schema

此服务器不附带演示数据库——它旨在指向一个具有等效视图的 Postgres/Supabase 项目。如果你要将其适配到自己的数据，上面的视图只是对你自己的表执行 SELECT；请替换每个 src/tools/*.js 文件中的查询以匹配你的 Schema。直接引用的列名（例如 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 使用 MP 协议通信，因此它应由 MP 客户端启动，而不是在终端中独立运行以供交互使用。要使用 Claude Desktop 进行测试，请将其添加到你的 MP 配置（claude_desktop_config.json）中：

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

重启 Claude Desktop，上述工具即可在对话中使用。

安全说明

SUPABASE_SERVICE_KEY 是提权的 service-role 密钥，而不是公开的 anon 密钥。这里这样做是安全的，因为该服务器只会作为由受信任的 MP 客户端启动的本地进程运行（绝不会出现在浏览器打包文件中）——这与在 Supabase Edge Function 中使用 service role 密钥的道理相同。切勿提交 .env；只有 .env.example（占位值）会被跟踪。

路线图

• 按工具调用进行 OpenTelemetry 追踪（延迟、行数、错误率）→ 本地使用 Jaeger，托管演示使用 Honeycomb/Grafana

• suggest_listing 工具——根据库存 + 定价数据起草 eBay 列表

• 用于远程访问的 HTTP/SSE 传输，与本地 stdio 传输并存

许可证

MIT——参见 LICENSE。