lorcana-mcp 是一个面向 Disney Lorcana 集换式卡牌游戏的 MCP（Model Context Protocol）服务器，使用户能够通过 Claude 或其他 MCP 客户端以自然语言查询 Card、分析卡组并构建卡组。
用途 该服务器用于在 MCP 客户端中检索迪士尼洛卡纳卡牌信息、进行规则校验的卡组合法性检查、查看卡组统计，并与 Dreamborn/Pixelborn 卡组列表进行往返导入导出。
主要能力
- 卡牌搜索：支持用自然语言按名称（如“Show me all cards named Moana”）、颜色、稀有度、费用、力量、意志力、传说值等条件查询，也支持关键字与能力搜索（如 Evasive、Bodyguard、Shift、Ward、Reckless、Singer、Resist 等）。对于普通关键字查询，建议使用 keyword 参数以匹配结构化能力列表；对于带具体数值的查询（如 Singer 5、Resist +2），建议使用 body_text 参数，因为关键字数值存放在卡牌完整文本中。
- 统计与聚合：可统计每个系列的卡牌数量、颜色分布、最常见特征、印墨曲线（各费用的卡牌数量）、可打墨的传奇卡数量等。
- 跨条件组合查询：例如“How many amber characters have 3 or more lore?”、“Find cheap (cost 2-3) characters with high strength (4+) in steel”、“How many cards in set 1 have Evasive and cost less than 4?”。
- 卡组构建：build_deck(colors, playstyle="balanced") 工具会引导模型按指定颜色与玩法风格（aggressive / control / lore-race / balanced）组装合法卡组，遵循至少 60 张、最多两种印墨、同名卡最多 4 张等规则。
- 数据规模：2,506 张独特卡牌，3,192 个印刷版本（含异画与促销卡），每日刷新。每张卡带 printings 数组存放不同系列、编号与稀有度；同一张卡只保留一行，搜索“Elsa”不会因促销重印而重复出现。
- 输出格式：search_cards 支持 response_format 参数，可选 "json"（默认，卡片对象列表）或 "toon"（由 toons Rust 库编码的 TOON 字符串，含一行列标题，每张卡一行）。由于卡牌结构不一（例如法术与物品没有力量/意志力/传说值），外层 cards 使用 YAML 风格的逐卡块，内层 printings 为完整表格。
- 无第三方运行时依赖：启动时从 https://danielenricocahall.github.io/lorcana-mcp/allCards.json 拉取卡牌 JSON，该快照由 data_pipeline/fetch_cards.py 每日从 Lorcast API 拉取、规范化并发布到 gh-pages 分支；运行时从不直接调用 Lorcast，因此不受其可用性与速率限制影响。
使用方式 推荐通过 uvx 运行，无需克隆代码或使用 Docker。也可在 Claude Desktop 的 claude_desktop_config.json 中配置。服务器同时发布到 GHCR 与 MCP Registry。容器方式可挂载卷以在重启间保留卡牌缓存。不暴露端口，MCP 通信通过 stdio 进行。
可用环境变量
- LORCANA_API（默认：https://danielenricocahall.github.io/lorcana-mcp/allCards.json）
- LORCANA_CACHE_PATH（默认：cards.json）——本地缓存文件
- LORCANA_HTTP_TIMEOUT_SECONDS（默认：60）
- LORCANA_REFRESH_ON_STARTUP（默认：false）——true 时总是重新拉取并填充存储
- LORCANA_SKIP_IF_DB_EXISTS（默认：true）——false 时即使缓存已存在也会重新拉取
性能说明 经 benchmarks/bench_toon.py 对实时 2,506 张卡数据集测试（使用 tiktoken cl100k_base 作为 Claude 分词器的代理），TOON 格式相比 JSON 可减少 token。由于嵌套的 printings 数组，TOON 的相对节省较印刷版本合并前更小（合并前同一查询约减少 50%），但绝对 token 数因每张独特卡只出现一次而显著下降。复现命令：PYTHONPATH=. uv run python benchmarks/bench_toon.py（需已填充 cards.json 缓存）。
适用场景 适合在 Claude 等 MCP 客户端中进行卡牌检索、卡组构筑与校验、卡牌数据统计分析，以及需要与 Dreamborn/Pixelborn 交换卡组列表的玩家与开发者。
限制与声明 该项目为个人非官方粉丝与工程项目，与 Disney、Ravensburger 或 Disney Lorcana TCG 团队无关联、未获其背书、赞助或审核。项目依据 Ravensburger 的 Disney Lorcana TCG 社区准则构建与分发，仅使用公开与社区数据源。所有 Disney Lorcana TCG 名称、卡牌文本、商标及相关知识产权归 Disney 与 Ravensburger 所有。项目非商业用途，仅代表作者个人观点，不代表其雇主。
MCP Registry 所有权验证：注册表读取已发布包描述中的 mcp-name 行以确认所有权，标识为 mcp-name: io.github.danielenricocahall/lorcana-mcp。
