carddata

# carddata

carddata 是一个小型本地桥接程序，用于连接托管的 HobbyCardIndex 卡牌价格 MCP 服务，该服务追踪体育卡和集换式卡牌的 近期成交价格。你可以像收藏者那样描述一张卡牌——年份、 系列、运动员或角色、卡牌编号——并获取 匹配结果及其未评级和 PSA 10 价格，然后获取 某张卡牌的完整信息，查看其在每个评级下的成交价：未评级、PSA 7 至 PSA 10、BGS 9.5、CGC 10 和 SGC 10。你还可以读取方案目录，了解商业 API 和应用方案的价格与内容。

该桥接程序本身不保存任何价格。它在本地返回工具列表，内容与从实时端点捕获的信息 完全一致，并将每次工具调用转发至上游， 原样返回收到的结果。这里提供三个只读工具。原始服务 还提供一个结账工具；本次重建有意不包含该工具，因此此软件包中的任何内容都不会 发起购买或处理付款。

工具

• search_cards — 查找卡牌及其近期成交 价格。必填：query（年份、系列、运动员或 角色，以及已知时的卡牌编号，2 到 120 个字符）。选填：category（例如 baseball、basketball、football、hockey、soccer、 pokemon、magic、yugioh、one piece）和 limit （1 到 5 个匹配项，默认为 5）。最多返回 5 个 匹配卡牌及其未评级和 PSA 10 价格、card_id 和卡牌页面链接。 需要 HobbyCardIndex API 密钥。
• get_card_prices — 某张卡牌在每个评级下的近期成交价格。必填：card_id（由 search_cards 返回的 ID）。返回未评级、PSA 7、 PSA 8、PSA 9、PSA 10、BGS 9.5、CGC 10 和 SGC 10 的价格，单位为美元，并附上卡牌页面链接，可查看近期成交和价格历史。需要 HobbyCardIndex API 密钥。
• list_plans — 读取当前提供的方案。 无需参数，无需 API 密钥即可使用。 返回商业 API 的各档规格（请求数、照片 扫描数、成交查询数、证书查询数）以及 Pro、Dealer 和 Enterprise 应用方案，包括美元计价的月费、条款和购买方式。 此工具只读取目录，不会发起购买。

配置

• HOBBYCARDINDEX_MCP_URL（可选）— 覆盖 上游端点。默认值为 https://hobbycardindex.com/api/v1/mcp。（此 覆盖钩子是本次重建自行标注的还原内容。）
• HOBBYCARDINDEX_API_KEY（可选）— 设置后，每个上游请求都会携带 X-API-Key: <key> 请求头，使用调用者自己的 HobbyCardIndex API 密钥。未设置时，不会发送密钥请求头。（请求头名称由 原始注册记录确定；该记录未指定 软件包环境变量名称，因此从此环境变量转发密钥属于已标注的还原内容——原始接口是在未提供密钥的情况下捕获的。）

转发机制

首次调用工具时，客户端会在上游打开一个可流式传输的 HTTP 会话：发送 JSON-RPC initialize 请求（protocolVersion 为 2025-03-26，clientInfo 名称为 carddata），然后发送 notifications/initialized 通知，接着发送携带调用者参数原样不变的 tools/call 请求。上游在 initialize 响应中返回 Mcp-Session-Id 请求头时，该值会附加到该会话后续的 每个请求中，并在进程运行期间重复使用。 响应可能以普通 JSON 或服务器发送事件的形式到达；两者都会读取。

成功的上游结果会原样透传，包括上游设置的任何 isError 标志。 失败情况——JSON-RPC 错误、非 2xx 状态、无法读取的响应，或 无法完成的请求——会以 isError 结果返回，其文本以 carddata error: 开头（此错误呈现方式是本次重建自行标注的还原内容）。

CLI

每个工具也可作为子命令使用，并接受一个 JSON 参数字符串：

npx @reneturcios/carddata search_cards '{"query":"1989 Upper Deck Ken Griffey Jr 1"}'
npx @reneturcios/carddata get_card_prices '{"card_id":12345}'
npx @reneturcios/carddata list_plans '{}'
npx @reneturcios/carddata --version

退出代码：成功时为 0，结果包含 isError 时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/carddata mcp

MCP 客户端配置：

{
  "mcpServers": {
    "carddata": {
      "command": "npx",
      "args": ["-y", "@reneturcios/carddata", "mcp"]
    }
  }
}

## Docker

docker run -i ghcr.io/cloudcorprecords/carddata
docker run --rm ghcr.io/cloudcorprecords/carddata --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他参数则会正常传递给命令行工具。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全通过模拟的 JSON-RPC 上游运行，不会发起实时网络调用。

许可证

MIT — 请参阅 LICENSE。