Pulltrader

Pulltrader — 集换式卡牌 MCP 服务

在 AI 助手中识别卡牌、查询近期已售同款、总结其市场价值、绘制价格历史图表，并比较卖家在 eBay、Pulltrader 和其他卡牌市场平台上最终能拿到的金额。

面向集换式卡牌研究与销售的公开、只读 Model Context Protocol 服务。提供 8 个工具：用于查询 Kapture 被盗卡登记信息的工具；4 个基于 Pulltrader 卡牌数据的工具（卡牌识别、已售同款商品查询、市场价值和价格历史）；以及 3 个基于带日期和版本的费用表、通过 Pulltrader 确定性卖家经济模型引擎运行的工具。

市场数据是根据近期销售记录得出的估算值。费用计算是确定性的——由服务计算，绝不会要求模型从文字描述中推断费用。eBay 数据会明确标注为估算值。

• 传输方式： Streamable HTTP（POST /mcp）
• 身份验证： 无（公开、只读）
• 端点： https://mcp.pulltrader.app/mcp
• 注册表名称： app.pulltrader/seller-economics
• 协议： 2025-06-18（如果客户端请求的版本存在，则会原样返回）

适用对象

集换式卡牌卖家、经销商、商店和收藏者，无需离开助手，就能了解卡牌是什么、值多少钱，以及出售后实际能拿到多少钱。

功能与限制

功能	不具备的功能
将卡牌的文字描述解析为结构化字段	根据图像识别卡牌（仅支持文本）
返回近期可比的已售记录（价格 + 日期）	返回商品刊登、推广或单笔销售的外链 URL
总结市场价值：中位数、平均值、p10–p90、波动性、置信度	声称价值有保证或提供财务建议
按天 / 周 / 月绘制价格历史图表并显示趋势	执行任何写入、下单或账户变更
估算各销售方式的卖家费用和净收入	声称某个平台始终是费用最低的平台
计算达到目标净收入所需的价格	模拟拍卖形式（落槌价、买家溢价、寄售）
说明自身的假设、数据新鲜度和限制	支持非卡牌类别或 USD 以外的货币

工具

Kapture 证书查询（基于数据）

check_kapture_cert 接受 { "cert": "00123456" }，并保留前导零。 CLEAN 仅表示没有匹配到已核实的失窃报告。STOLEN 会包含 Kapture 报告以及可选的 Pulltrader 找回表单链接。该工具不会收集 个人信息、推断持有人身份或提交找回报告。后端保存 KAPTURE_API_KEY；无需新增 Worker 密钥。在 Kapture 提供报告 API 之前，找回流程需要手动完成。请参阅 pulltrader-backend/docs/KAPTURE.md。

卡牌研究（数据支持）

这些工具连接到 Pulltrader 后端。卡牌数据为有限公开：仅提供数量受限的销售样本，不包含单个商品刊登或联盟链接，且只提供目录参考图片。

每个工具都接受 query（自然语言描述，例如 "2023 Panini Prizm Victor Wembanyama #136 Silver PSA 10"）或 item（结构化字段：player_athlete、year_manufactured、set_name、card_number、parallel_variety、grader、grade、sport）。两者必须提供其一。

工具	返回内容
identify_card	标准字段（球员／运动员、年份、系列、编号、平行版、评级机构、评级、类别），以及置信度和已解析的字段。仅接受 query。不提供卡牌定价。
search_card_sales	最近可比成交记录的限量样本（价格 + 日期），以及市场概况。可选 limit。
summarize_card_market	标准市场价值：中位数、均值、p10–p90、波动性、样本量、置信度。
get_card_price_history	可用于生成图表的时间序列及趋势。可选 interval：day | week | month。

如果 eBay 没有带日期的可比成交记录，search_card_sales 和 summarize_card_market 会回退至权威供应商价格，并提供 market_value、value_source（TCG Market | CardSightAI | eBay Comps）、price_change_7d、price_change_30d 和一张目录 image。

卖家收益（确定性计算，不执行 I/O）

工具	返回内容
compare_selling_costs	对比不同销售方式下单笔销售的预估费用和净收入，包含各方式的费用明细、与 eBay 基准的差额，以及所用假设。必需参数：sale_price。
calculate_required_sale_price	计算通过单一方式达到目标到手金额所需的单件价格；提供 acquisition_cost 时，则计算目标净利润所需的价格。必需参数：target_net。
explain_selling_method	以清晰的结构说明每种方式如何管理商品刊登、履约和收取费用。此工具与 compare_selling_costs 使用相同的计算引擎，因此结果始终一致。

共享输入参数（compare_selling_costs、calculate_required_sale_price）：

字段	类型	默认值	说明
currency	enum USD	USD	仅支持 USD
quantity	integer	1	每笔订单的固定费用仅收取一次
shipping_amount	number	0	会影响 eBay 的计费基数
item_category	enum trading_cards	trading_cards	仅限交易卡
seller_plan	free|starter|pro|shop	free	市场平台的结算等级
seller_level	enum	根据套餐确定	可明确覆盖结算等级
seller_covers_fees	boolean	false	若为 false，则由买家支付平台费用
ebay_store_subscription	boolean	false	eBay Store 费率（12.35%），而非个人卖家费率（13.25%）
acquisition_cost	number	—	将输出切换为净利润
ebay_fee_percent_override	number	—	覆盖预估的 eBay FVF 百分比（固定值）

支持的方式： ebay、pulltrader_marketplace、pulltrader_fbp、pulltrader_storefront、pulltrader_pos，以及预估的竞争平台 tcgplayer、manapool、misprint、fanatics_collect、goldin（默认关闭，可通过 methods 启用）。竞争平台数据仅模拟固定价格／立即购买的卖家费用。

示例提示词

• “这张卡是什么：2023 Bowman Chrome Elly De La Cruz PSA 10？”
• “显示这张卡近期的成交记录和市场价值。”
• “2018 Prizm Luka Doncic Silver PSA 10 过去一年的价格历史是什么？”
• “比较我以 $250 售出一张评级卡后的预估收入。”
• “一张 $80 的卡在 eBay 和 Pulltrader 上分别能让我留下多少钱？”
• “我得卖多少钱，扣除费用后才能净得 $200？”
• “说明这项结算预估背后的假设。”

示例响应（文本摘要）

On a $250.00 trading-card sale, estimated seller proceeds by method:
- Sell it yourself on eBay: keep $216.47 (estimated) (fees $33.53, 13.41%)
- Pulltrader marketplace (you ship): keep $235.00 (fees $15.00, 6%)
- Your Pulltrader storefront (you ship): keep $250.00 (fees $0.00, 0%)
For these inputs, Your Pulltrader storefront (you ship) returns about $33.53 more than Sell it yourself on eBay.
Estimate based on fee schedules updated 2026-06-01 (Pulltrader) and 2026-06-27 (eBay, estimated). Estimates only, for trading cards in USD. ...

eBay = 13.25% 的个人卖家最终成交费 + 每笔订单 $0.40 费用（订单金额超过 $10）。店面保留 100% 收益，因为 Pulltrader 不对店面/POS 收取 卖家费用——这里只收取平台费用，默认由买家支付。Pulltrader 卡片销售始终会收取平台费用（默认由买家支付）。

连接

Claude（网页 / 桌面版）

Settings → Connectors → Add custom connector → URL https://mcp.pulltrader.app/mcp。

ChatGPT

Settings → Apps & Connectors → Advanced → 启用 Developer mode → Create → URL https://mcp.pulltrader.app/mcp。

Cursor / 通用

将其添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "scout-by-pulltrader": {
      "url": "https://mcp.pulltrader.app/mcp"
    }
  }
}

已测试的客户端： Claude（网页/桌面版）、ChatGPT 开发者模式、Cursor、MCP Inspector。我们不声称与所有助手都普遍兼容。

公共访问与速率限制

/mcp 端点是公开的，只读。单独的卖家资源已在 /seller/mcp 实现；OAuth 已配置，登录试点尚待推出。请参阅 Seller MCP。

限制	默认值	说明
所有 POST /mcp	60 / IP / 分钟	HTTP 429 + Retry-After。KV 不可用时故障开放。
数据工具（identify / comps / market / history）	8 / IP / 分钟，40 / IP / 天	工具 isError RATE_LIMITED。KV 不可用时故障关闭。
数据工具全局限制	10,000 / 天	用于模型 + comps 开支的熔断器。
批次大小	5 条消息	拒绝更大的批次。

需要 MCP_ABUSE KV 命名空间（参见 wrangler.toml）。可通过 PUBLIC_RATE_LIMIT_PER_MIN、DATA_RATE_LIMIT_PER_MIN、DATA_RATE_LIMIT_PER_DAY、DATA_GLOBAL_LIMIT_PER_DAY 调整。

错误

输入问题会作为工具结果返回，其中 isError: true 并带有稳定代码，而不是 JSON-RPC 错误：INVALID_INPUT、NOT_FOUND、RATE_LIMITED、UPSTREAM_ERROR、UPSTREAM_TIMEOUT、DATA_BACKEND_UNAVAILABLE、INTERNAL_ERROR。未知方法和格式错误的信封使用标准 JSON-RPC 错误代码。

四个卡片工具需要后端桥接（PULLTRADER_API_BASE + SCOUT_MCP_SECRET）。没有桥接时，它们会降级为 DATA_BACKEND_UNAVAILABLE；三个卖家收益工具是纯工具，始终可用。

数据来源与费用时效性

• 卡片数据仅限公开数据，且仅供估算：近期已售 comps 的限量样本，由共享的 Pulltrader 域引擎汇总。
• Pulltrader 费用与 Pulltrader 权威内部费用配置一致。
• eBay 费用是已公布集换式卡牌费率的估算值（分级的个人卖家/Store 最终成交费 + 按订单金额收取的每单费用），并按计划更新和审查。请参阅 docs/FEE_SCHEDULES.md。若费率表已超过审查日期，响应会发出警告。

当前费率表版本通过 /version 实时提供。

局限性

• eBay 估算不包括推广刊登费、国际费用、买家支付的销售税，以及卖家自己的运单费用。
• 市场价值是根据近期销售估算得出，不包括费用、税款和运费。
• 不构成财务建议；实际收益和实际价值可能有所不同。
• 此版本仅支持集换式卡牌 / USD。

开发

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest
npm run dev         # wrangler dev (local)

部署和提交至注册表需要明确批准——请参阅 docs/DEPLOYMENT.md 和 docs/DISTRIBUTION.md。不要在开发会话中部署或发布。

更多信息

• PRIVACY · SECURITY · TERMS · CHANGELOG
• 费率表与更新流程

部署前提条件

wrangler kv namespace create MCP_ABUSE
wrangler kv namespace create MCP_ABUSE --preview
# Paste ids into wrangler.toml [[kv_namespaces]] binding MCP_ABUSE
wrangler secret put SCOUT_MCP_SECRET

路线图

• 基于图像的卡片识别。
• 运动员/球员资料工具。
• 完成 /seller/mcp 的登录卖家试点；全局用户级配额仍是未来的工作。

---

由 Pulltrader 构建并维护。支持邮箱：[email protected]

_{此存储库是 Pulltrader MCP Worker 的公开镜像，每次发布时从 Pulltrader monorepo 导出。欢迎在此提交问题和疑问；拉取请求会应用到上游。wrangler.toml 中的 KV ID 已脱敏——部署从 monorepo 运行。}