万智牌卡牌查询

它解决什么问题

维护卡表、写构筑分析、做中文卡牌索引时，常见的痛点是数据散落多处、字段命名不统一，中文卡牌名与英文原词混排，人工拼装查询既慢又容易错。@org-rn88lg3j/gathering-card-lookup 把这类请求收敛到同一个 MCP 服务端上：大模型只负责理解意图和提取参数，数据获取全部交给 scripts.tools 里的函数，返回 result["raw"] 这份原始 JSON，由你决定如何渲染。

核心能力

• 精确查询：scripts.tools.get_card_by_set_and_number 用系列代码加收集编号定位单张卡牌，适合「NEO 的 046/306 是什么」这类请求。
• 结构化搜索：搜索工具接受查询字符串，支持 t:creature c:r、pow>=5、mv<2、s:TDM -t:creature 这类过滤条件；配合 page、page_size、order、unique 控制分页、排序与去重粒度（按 id、oracle_id 或 illustration_id）。
• 系列数据：get_sets 按发布日期倒序返回全部系列，get_set 按 set_code 取单个系列详情，get_set_cards 拉取某系列的全部卡牌。
• 活字乱刷：scripts.tools.hzls 用卡牌图像把文本拼成图片，可选 cut_full_image 与 with_link 水印开关。
• 中文优先：priority_chinese 默认为 true，中文卡牌排在结果前列。

工作流程

1. 检查 scripts.config.settings.api_key，为空时用 AskUserQuestion 向用户索取密钥，再调用 scripts.config.set_api_key(key) 保存。
2. 按用户意图选择工具函数并提取参数。
3. 以关键字参数调用，例如 scripts.tools.get_set_cards(set_code='NEO', page_size=50, order='collector_number')。
4. 读 result["success"] 与 result["message"] 判断成败，把 result["raw"] 整理后展示给用户。

适用边界与注意点

• 密钥是硬门槛：缺少 XBY_APIKEY 时禁止自行搜索或编造数据，必须先询问用户，因此无人值守或离线场景跑不起来。
• 查询语法有学习成本：过滤条件写错通常不会报错，而是静默返回不符合预期的结果集，接入前先用 mv<2、s:TDM -t:creature 这类样例验证一遍。
• 分页上限：page_size 最大为 100，批量拉取整个系列需要自己实现翻页与终止逻辑。
• 活字乱刷不是数据接口：hzls 产出图片，不参与卡牌数值查询链路。
• 该技能定位是路由层，最终数据质量取决于上游 API 的更新频率。