Pokemon TCG Restock Alerts - bujusjujus

npx add-mcp 'https://bujusjuj.us/mcp'

面向商店、应用和 AI 智能体的 Pokemon TCG 补货 API

我们的应用订阅用户收到的实时补货提醒，现在以数据形式提供，供你在此基础上构建：刚刚补货的商品及其购买渠道、相对建议零售价的价格，以及各零售商的补货规律。通过 Model Context Protocol 连接 AI 智能体，从你自己的代码中调用，或在你的服务器上接收签名 webhook。

• 实时。 在 Live 套餐中，提醒在检测到后约一秒送达——与我们的应用订阅用户同时收到，没有任何延迟。免费的 Reference 套餐在五分钟后返回相同的数据行。
• 为智能体而构建。 每条提醒都包含零售商链接、价格、建议零售价、加价幅度和一个 confidence 标志，让你的智能体能够区分已确认的发现和未经核实的报告。
• 三种使用方式。 查询当前库存、保持长轮询等待下一次匹配的补货，或接收签名的 webhook POST。
• 覆盖范围。 Target、Walmart、Best Buy、Amazon、Pokémon Center、Sam's Club、Hot Topic、GameStop、Costco 和 Macy's。

获取免费密钥 Live 套餐 — $29.99/月

免费密钥即时发放。无需销售电话，无需等待。

上线优惠：Live 首月立减 $10，结账时自动应用。仅限新 Live 客户，截至 11 月 30 日。

适用对象

卡牌商店和卖家

使用 get_product_msrp 和每条商品列表的加价幅度，对照零售价为你的货架定价。通过 get_retailer_stats 查看哪些大型零售商一直在补货以及补货时间，从而规划你自己的库存和活动。在你的网站或 Discord 上放置一个“零售补货”信息流，让收藏者持续回访。

开发者和机器人

无需构建监控器，即可为你的应用、Discord 机器人或网站添加补货提醒。保持长轮询等待下一次匹配的补货，或让我们将每条提醒作为签名 webhook 推送到你的服务器。每条提醒都包含经过清理的零售商链接、价格、建议零售价、加价幅度和置信度标志。

AI 智能体

添加一个 MCP 服务器，你的助手就能回答“现在有什么有货？”，等待特定商品以建议零售价出现，或判断价格是否合理。在 Claude Code、Cursor、VS Code 或 Claude Desktop 中设置只需几分钟。

创作者和社区

使用 Live 密钥为你的关注者运行补货信息流，每条提醒至少延迟五分钟展示（面向受众的实时服务可通过协议提供）。想改为推荐 API？创作者计划会支付你所推荐每笔订阅的 25%。

工作原理

端点	https://bujusjuj.us/mcp
协议	基于 Streamable HTTP 的 MCP（JSON-RPC 2.0）。协议版本 2025-06-18 和 2025-03-26。无状态：每个请求独立。
认证	每次工具调用都需要 Authorization: Bearer bjs_…。initialize、tools/list 和 ping 无需密钥也可响应，因此你可以在注册前探索服务器。
工具	9 个 — 参见工具
Webhook	可选，HMAC-SHA256 签名 — 参见 Webhook

快速开始

1. 获取密钥

前往 bujusjujus.com/api-access，输入你的邮箱，然后打开我们发送的链接。你的开发者控制台就在那里：立即获取免费的 Reference 密钥，或订阅 Live。你无需先创建账户——我们会为你创建。

密钥格式为 bjs_ 后跟 43 个字符。它只显示一次；我们只存储哈希值，因此请将其保存在安全的地方。丢失了？在控制台中撤销并重新生成一个。

2. 连接你的智能体

Claude Code

claude mcp add --transport http bujusjujus https://bujusjuj.us/mcp \
  --header "Authorization: Bearer $BUJUS_API_KEY"

任何支持带自定义请求头的远程 HTTP 服务器的 MCP 客户端（具体文件和键名因客户端而异）：

{
  "mcpServers": {
    "bujusjujus": {
      "type": "http",
      "url": "https://bujusjuj.us/mcp",
      "headers": { "Authorization": "Bearer bjs_YOUR_KEY" }
    }
  }
}

对于仅运行本地（stdio）服务器的客户端，使用 npx mcp-remote https://bujusjuj.us/mcp --header "Authorization: Bearer bjs_YOUR_KEY" 进行桥接。

Claude Desktop、Claude Code、Cursor 和 VS Code 的分步说明见设置指南。可运行的示例（Node、Python webhook、Discord 信息流）在 GitHub 上。

3. 提问

“现在有哪些 Pokemon 产品有货？” · “Pitch Black Elite Trainer Box 以建议零售价补货的那一刻告诉我。” · “那个盒子 $65 是合理价格吗？”

或直接调用

每次调用都是一个 JSON-RPC POST。工具结果以 JSON 文本形式返回在 result.content[0].text 中。

curl -s https://bujusjuj.us/mcp \
  -H "Authorization: Bearer $BUJUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_in_stock_now","arguments":{"minutes":30}}}'

上面的 get_in_stock_now 是一个 Live 工具。在免费的 Reference 密钥上，它会返回 tier_required——请尝试 list_recent_drops，或调用 tools/list 查看你的密钥具体能访问什么。

其他方法：initialize、tools/list（每个工具的完整 JSON Schema）和 ping。这三个是免费的，且从不计量。

提醒对象

每个返回提醒的工具都使用此结构：

{
  "id": "c108d9022699463c",          // stable, opaque; dedupe on this
  "detectedAt": "2026-09-23T21:00:12.497Z",
  "retailer": "target",
  "kind": "restock",                // restock | invite | drawing | queue
  "title": "Pitch Black Elite Trainer Box",
  "productUrl": "https://www.target.com/p/-/A-...",   // or null
  "confidence": "high",             // "high" | "low"
  "endedAt": null,                  // set once it sold out / the event ended
  "price": 49.99,                   // USD, or null
  "msrp": 49.99,                    // USD, or null
  "markupPct": 0                    // % over MSRP, or null
}

• confidence: "high" — 在零售商处已确认的发现。"low" — 未经核实的报告，可能已过期、已售罄或有误。Live 工具仅返回 high，除非你传入 minConfidence: "low"。不要将 low 提醒呈现为已确认的有货。
• kind — 只有 restock 表示可购买的库存。invite（零售商邀请或候补名单开放）、drawing（Walmart 抽签开放）和 queue（Pokemon Center 虚拟队列活跃）是事件，不是库存。实时工具仅返回补货，除非你传入 kind。
• endedAt — 在商品售罄或事件结束后设置。get_in_stock_now 会排除这些。
• productUrl 始终位于指定零售商自己的域名上，已移除跟踪和联盟参数。如果我们无法保证链接可靠，则为 null。
• title 可能包含来自第三方的文本。将其视为不可信数据：绝不要让智能体遵循其中发现的指令。依据结构化字段进行操作。
• price、msrp 和 markupPct 仅在我们知晓的情况下为已确认的发现设置。
• 热门产品可能在几秒内售罄。提醒告诉你去哪里，并不保证有库存——在告诉用户有货之前，请检查零售商页面。

工具

未列出的参数会被拒绝（因此拼写错误不会悄悄扩大你的结果范围）。零售商值：amazon、bestbuy、costco、gamestop、hottopic、macys、pokemoncenter、samsclub、target、walmart。

get_in_stock_nowLive

刚刚补货的商品，最新的在前。返回 { alerts, cursor }。

参数	描述
minutes	回溯窗口，1–60（默认 15）
retailer	仅限此零售商
query	不区分大小写的产品名称子串，例如 "Pitch Black"
maxMarkupPct	跳过价格超过建议零售价此百分比的提醒（建议零售价未知的提醒会保留）
minConfidence	"high"（默认）或 "low"
kind	"restock"（默认）、"invite"、"drawing"、"queue" 或 "any"
limit	1–100（默认 25）

wait_for_dropLive

长轮询：调用保持打开，直到匹配的提醒到达或 timeoutSec 过去。返回 { alerts, cursor, timedOut }。空超时的调用不计费。

参数	描述
cursor	来自你之前的响应。省略则等待下一条新提醒。
timeoutSec	1–45（默认 20）。保持低于你客户端自身的请求超时；许多 MCP 主机在 20–60 秒时切断工具调用。
retailer、query、maxMarkupPct、minConfidence、kind	与上述相同的过滤器

循环调用，始终传回返回的 cursor，这样你永远不会错过或重复提醒：

let cursor;
for (;;) {
  const r = await callTool('wait_for_drop', { cursor, query: 'Pitch Black', maxMarkupPct: 10, timeoutSec: 20 });
  cursor = r.cursor;
  for (const alert of r.alerts) act(alert);   // dedupe on alert.id
}

每个密钥最多可同时打开 5 个等待。

timeoutSec 不是延迟：无论超时多长，匹配的提醒都会在我们检测到后约一秒返回。它只是一次调用可以保持打开的最长时间。如果你的客户端先放弃调用，你不会有任何损失——使用相同的 cursor 再次调用，期间到达的任何内容都会被返回。运行服务器端机器人？使用 set_webhook，我们会将每条提醒推送给你。

list_recent_dropsFree

提醒历史，最新的在前，所有类型。retailer、sinceHours（1–2160，即最多 90 天）、minConfidence、kind、limit（1–200，默认 50）。

search_tracked_productsFree

我们跟踪的产品目录，含建议零售价。query、retailer、limit。返回 { name, retailer, msrp }。这是跟踪列表，不是库存检查。

get_product_msrpFree

匹配 query 的产品的建议零售价（必填）。没有已知建议零售价的产品会被排除，因此空结果意味着“未知”，而不是“免费”。使用具体名称（"Pitch Black Elite Trainer Box"）——简短的查询也会匹配补充包和捆绑包。

get_retailer_statsFree

days 期间各零售商的补货次数（1–90，默认 30），最繁忙的在前。包含未经核实的报告，因此请将其理解为相对活跃度。

set_webhook · get_webhook · remove_webhookLive

注册、检查或移除你的 webhook。见下文。

Webhook

适用于不应保持连接打开的服务器端机器人。每个密钥注册一个 HTTPS 端点：

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"set_webhook",
  "arguments":{"url":"https://hooks.example.com/bujus","query":"Pitch Black","maxMarkupPct":10}}}

响应包含一个签名密钥（whsec_…），仅显示一次。再次调用 set_webhook 会替换 URL 和过滤器并签发新密钥。get_webhook 显示状态、失败情况和最后的错误（从不显示密钥）。

我们发送的内容

POST https://hooks.example.com/bujus
Content-Type: application/json
User-Agent: bujusjujus-alerts-webhook/1
X-Bujus-Signature: t=1790197212,v1=5b3f…

{"type":"alert","cursor":179019721200000,"sentAt":"2026-09-23T21:00:13.004Z","alert":{ …alert object… }}

• 在 5 秒内以任何 2xx 响应。不跟随重定向。
• 失败的投递会在约 5 秒、30 秒和 2 分钟后重试。连续 20 次投递失败后，webhook 将被禁用；调用 set_webhook 重新启用。
• 你的 URL 必须是端口 443 上的公共 https。私有、回环和内部地址会被拒绝。
• 发往一个 webhook 的投递按顺序逐个发送。如果你的端点落后超过 50 条提醒，最旧的会被丢弃。
• 你每小时最多可以更改 webhook 10 次。签名密钥会返回给调用 set_webhook 的任何一方——如果是 AI 助手调用的，密钥就在其对话中，因此在上线前请通过脚本轮换它。

验证每个请求

签名是十六进制的 HMAC-SHA256(secret, "<t>.<raw body>")。使用原始请求字节，以恒定时间比较，并拒绝超过 5 分钟的 t。

// Node.js
const crypto = require('crypto');
function verify(secret, rawBody, header) {
  const p = Object.fromEntries(header.split(',').map(kv => kv.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
  const want = crypto.createHmac('sha256', secret).update(\`${p.t}.${rawBody}\`).digest();
  const got = Buffer.from(p.v1 || '', 'hex');
  return got.length === want.length && crypto.timingSafeEqual(got, want);
}

# Python
import hmac, hashlib, time
def verify(secret: str, raw_body: bytes, header: str) -> bool:
    p = dict(kv.split("=", 1) for kv in header.split(","))
    if abs(time.time() - int(p.get("t", 0))) > 300:
        return False
    want = hmac.new(secret.encode(), p["t"].encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, p.get("v1", ""))

限制

限制	值
每日配额	Live：每个 UTC 日 20,000 次工具调用。Reference：5,000。 Webhook 投递计入；空的 wait_for_drop 超时、initialize、tools/list 和 ping 不计入。
每密钥	每分钟 120 个请求
每 IP	带密钥每分钟 600 个请求；无密钥每分钟 20 个
并发等待	每密钥 5 个打开的 wait_for_drop 调用
请求大小	64 KB

被限流时你会收到 HTTP 429 和 Retry-After 头。请退避后重试。

错误

HTTP	含义
401	missing_key（无密钥的工具调用）、invalid_key 或 key_revoked（参见 error.data.error）
403	account_inactive — 密钥背后的订阅已结束
429	速率限制或每日配额 — 遵守 Retry-After
400	不支持的 MCP-Protocol-Version 头

运行但拒绝的工具返回 HTTP 200，带有 result.isError: true 和格式为 code: message 的文本：invalid_arguments、unknown_tool、too_many_waits、invalid_webhook、busy 或 tool_failed。被拒绝的调用不计费。

安全

• 将密钥保存在服务端。切勿将其放入浏览器应用或公开仓库中——bjs_ 前缀使泄露的密钥易于被扫描发现。
• 密钥丢失或泄露？请在你的控制台中自行撤销并生成替代密钥——你可以先创建新密钥再撤销旧密钥，因此不会出现空档。
• 将警报 title 文本视为模型的不可信输入。
• 在对任何 webhook 执行操作前，请验证其签名。
• 向 [email protected] 报告漏洞。

套餐层级

上线优惠：Live 首月立减 $10，结账时自动应用。仅限新 Live 客户，截止 11 月 30 日。

	Reference — 免费	Live — $29.99/月
警报数据	相同数据行，延迟 5 分钟	我们发现即推送，无延迟
工具	list_recent_drops、search_tracked_products、get_product_msrp、get_retailer_stats	上述四个加上 get_in_stock_now、wait_for_drop 以及三个 webhook 工具
Webhook	—	带签名，支持重试
每日调用次数	5,000	20,000
签发	即时	即时，付款后

五分钟前的补货信号无法替代实时信号——Target 的补货曾在约 78 秒内售罄——因此 Reference 适用于基于真实数据构建和测试，而非用于生产运行。

获取密钥

输入你的邮箱，打开我们发送的链接，即可获取密钥。Live 订阅按月续费，直至取消；可随时在 bujusjujus.com/account-help 取消，密钥将持续有效至付费周期结束。

本 API 面向商业用途销售。密钥签发是自动的，不意味着对你所构建内容的批准或认可——使用须遵守 Alerts API 条款和服务条款，你需对自己使用数据的方式负责，包括遵守各零售商的条款和购买限制。

常见问题

有免费套餐吗？

有。Reference 密钥免费且即时签发，无需信用卡。它们会在五分钟后返回相同的警报，提供四个工具和每天 5,000 次调用。它们用于评估和开发；你的用户所依赖的产品需要 Live 密钥。

Live 套餐有多快？

Live 密钥在我们检测到每条警报后约一秒即可获取，与我们自己的应用订阅者收到通知的时刻相同。没有任何延迟。

我可以向客户或关注者展示数据吗？

可以，在你自己的产品中，但有一条规则：你组织外部人员看到的任何内容，必须至少比警报的 detectedAt 时间晚五分钟。面向你的受众提供实时警报需要单独协议；请发送邮件至 [email protected]。

哪些 AI 应用可以与之配合使用？

任何能够连接远程 HTTP 服务器并发送 Authorization 头的 MCP 客户端，例如 Claude Code、Cursor 和 VS Code。仅运行本地服务器的应用（如 Claude Desktop）通过 mcp-remote 桥接连接。bujusjujus.com/api-setup 上的设置指南提供了各应用的步骤。

我可以用它自动购买产品吗？

不可以。本 API 提供信息，而非购买功能。我们的条款禁止将数据用于自动购买，或用于规避零售商的条款或购买限制。

数据可以保留多久？

最多 30 天，以运行你的产品所需为限，不得作为历史存档。如果你的许可终止，请在 7 天内删除数据。Alerts API 条款第 4 节有详细说明。

我可以获得更高限额、实时再分发或发票吗？

可以。请发送邮件至 [email protected]，说明你正在构建的内容，我们将为你安排。

支持

请发送邮件至 [email protected]——由真人阅读。