Disney Lorcana MCP

Disney Lorcana MCP Server

一个 MCP 服务，可让 Claude（或任何 MCP 客户端）搜索、分析并构筑 Disney Lorcana TCG 套牌。用日常语言询问卡牌，即可获得经过规则检查的套牌验证、墨水曲线和关键词分类，并与 Dreamborn/Pixelborn 双向导入导出套牌列表。

2,506 张独特卡牌（包含异画和促销卡在内，共 3,192 个印刷版本），每日更新。 无需 API 密钥、无需数据库、没有速率限制——该服务使用我们自己的流水线发布的快照，因此查询时永远不依赖第三方 API 是否可用。

工具

工具	功能
search_cards	按名称、颜色、费用、稀有度、类型、关键词、属性、系列和卡牌文本筛选并获取卡牌。支持 response_format="toon"，可减少约 10% 的令牌用量
count_cards	统计符合筛选条件的卡牌数量，无需获取卡牌对象
aggregate_cards	按 cost（墨水曲线）、rarity、color、set_code 或 type 分组统计
resolve_card	将非正式、不完整或拼写错误的卡牌名称模糊匹配到最相近的卡牌
top_traits	统计所有卡牌中最常见的特质（Storyborn、Hero、Villain、Ally 等）
validate_deck	根据赛制规则检查套牌（≥60 张卡牌、每张最多 4 张、≤2 种墨水、双墨水要求）；返回 {legal, total_cards, inks, violations}
deck_stats	墨水曲线、颜色分布、可支付墨水费用的卡牌数量、类型分布、关键词数量、子类型数量，以及每张卡牌的关键词标签
import_deck	将 Dreamborn/Pixelborn 套牌列表解析为匹配的卡牌，并为无法匹配的行提供模糊匹配候选项
export_deck	将套牌重新导出为兼容 Dreamborn/Pixelborn 的文本列表
server_status	启动元数据（卡牌数量、配置）

安装

uvx（推荐——无需克隆，无需 Docker）

uvx lorcana-cards-mcp

Claude Desktop / claude_desktop_config.json：

{
  "mcpServers": {
    "lorcana": {
      "command": "uvx",
      "args": ["lorcana-cards-mcp"]
    }
  }
}

Claude CLI：

claude mcp add --scope user -- lorcana uvx lorcana-cards-mcp

pip / pipx

pipx install lorcana-cards-mcp   # then run: lorcana-cards-mcp

Docker

该服务也已发布到 GHCR 和 MCP Registry。

docker run --rm -i ghcr.io/danielenricocahall/lorcana-mcp:latest

{
  "mcpServers": {
    "lorcana": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/danielenricocahall/lorcana-mcp:latest"]
    }
  }
}

如需在容器重启后保留卡牌缓存，请挂载一个卷：

docker run --rm -i \
  -e LORCANA_CACHE_PATH=/data/cards.json \
  -e LORCANA_SKIP_IF_DB_EXISTS=true \
  -v lorcana_mcp_data:/data \
  ghcr.io/danielenricocahall/lorcana-mcp:latest

从克隆的仓库安装

uv run python main.py

docker build -t lorcana-mcp:latest .
docker run --rm -i lorcana-mcp:latest

# or via compose
docker compose build
docker compose run --rm -T lorcana-mcp

不会公开任何端口；MCP 通信通过 stdio 进行。

示例问题

连接到 MCP 客户端后，你可以用自然语言提出以下问题：

查找卡牌

• “显示所有名为 Moana 的卡牌”
• “卡牌 Maui - Hero to All 的效果是什么？”
• “查找所有传奇琥珀卡牌”

构筑套牌

• “力量至少为 3 的红宝石角色卡中，费用最低的是哪些？”
• “显示费用不超过 4 且可支付墨水费用的蓝宝石卡牌”
• “查找意志力至少为 5 的钢铁角色卡”
• “翡翠中有哪些传说值为 3 的角色卡？”

关键词与能力搜索

• “费用恰好为 5 的 Singer 卡牌有多少张？”
• “第一系列中有多少张具备 Evasive 的角色卡？”
• “有多少张红宝石卡牌具备 Reckless？”
• “查找文本中包含 Ward 的所有卡牌”
• “显示紫水晶中的 Shift 卡牌”

统计与聚合

• “每个系列有多少张卡牌？”
• “所有卡牌的颜色分布是什么样的？”
• “最常见的特质有哪些？”
• “显示墨水曲线——每种费用对应多少张卡牌？”
• “有多少张传奇卡牌可以支付墨水费用？”

多条件筛选

• “有多少张传说值至少为 3 的琥珀角色卡？”
• “查找钢铁中费用较低（2–3）、力量较高（4+）的角色卡”
• “第 1 系列中有多少张具备 Evasive 且费用低于 4 的卡牌？”

注意： 对于普通关键词查询（Evasive、Bodyguard、Shift 等），请使用 keyword 参数——它会根据结构化能力列表进行筛选，比子字符串搜索更可靠。对于 Singer 5 或 Resist +2 这类特定数值的查询，请使用 body_text（关键词数值位于卡牌完整文本中，而非能力列表中）。

MCP 提示词

• build_deck(colors, playstyle="balanced") — 引导模型组建符合要求的 Lorcana 卡组（至少 60 张卡、≤2 种墨水、每张卡最多 4 张），并满足指定的颜色和玩法风格（aggressive / control / lore-race / balanced）。使用上文的搜索/聚合工具，以及服务器指令中内置的规则。

卡牌数据与启动行为

启动时，服务器会从 https://danielenricocahall.github.io/lorcana-mcp/allCards.json 获取卡牌 JSON 列表。快照由 data_pipeline/fetch_cards.py 每日刷新，该脚本从 Lorcast API 获取数据，将每张卡规范化为我们的内部架构，并将列表发布到 gh-pages 分支。这个中间层使运行中的服务器不受 Lorcast 可用性和速率限制的影响——运行时不会直接调用 Lorcast。

卡牌以 Python 列表的形式保存在内存中，以便快速筛选。数据集包含 2,506 张独特卡牌，每张卡都带有一个 printings 数组，记录其替代系列、编号和稀有度（总计 3,192 个印刷版本）。将各印刷版本合并到每张卡对应的一行后，搜索“Elsa”只会返回每张不同的 Elsa 一次，而不会因每次促销重印而重复显示。服务器还会使用本地 JSON 文件缓存（LORCANA_CACHE_PATH，默认为 cards.json），这样后续启动时便可跳过网络获取。

配置

• 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 时，即使缓存已有数据，也会获取数据并重新填充

TOON 响应格式

search_cards 接受一个 response_format 参数：

• "json"（默认）— 卡牌对象列表，与先前版本保持一致。
• "toon" — 一个 TOON 字符串，包含一行列标题和每张卡对应的一行，由基于 Rust 的 toons 库编码（官方社区参考实现）。

示例（search_cards(name="elsa", limit=2, response_format="toon")）：

cards[2]:
  - id: crd_01c4835a62df4960bb973aeff81f2bb2
    name: Elsa
    version: Ice Maker
    full_name: Elsa - Ice Maker
    cost: 7
    ...
    printings[3]{set_code,set_name,number,rarity}:
      "7",Archazia's Island,69,Super Rare
      C2,Lorcana Challenge Year 3,2,Promo
      C2,Lorcana Challenge Year 3,6,Promo
  - id: crd_04bca46a8e2d4e9ba0fbdbfc6c99e51e
    name: Elsa
    ...

外层的 cards[2]: 会采用 YAML 风格的逐卡区块（而非单个表格），因为卡牌的结构各不相同——例如，行动卡和物品卡没有力量/意志/传说值。内层的 printings[N]{...}: 区块则是完整的表格格式，因为每个印刷版本都具有相同的四个字段。

基准测试

使用 benchmarks/bench_toon.py 对实时的 2,506 张卡牌数据集进行测量，并用 tiktoken cl100k_base 进行分词（作为 Claude 分词器的替代指标）：

查询	行数	JSON 令牌数	TOON 令牌数	Δ
color="amber", limit=200	200	44,101	39,680	−10.0%
color="ruby", limit=50	50	10,522	9,519	−9.5%
card_type="action", limit=50（稀疏列）	50	10,154	9,250	−8.9%
body_text="when", limit=50（较长的完整文本）	50	11,602	10,391	−10.4%
name="elsa", limit=20	14	3,488	2,940	−15.7%
总计		79,867	71,780	−10.1%

注意：与合并印刷版本之前相比，TOON 在此处节省的令牌比例较低（PR-#29 之前，同样的查询显示约 50% 的降幅）。这是嵌套 printings 数组的结构性影响——TOON 的列式编码在顶层字段上更有效，但在每个印刷版本条目内部会退回 JSON 风格的编码，因此数组会稀释相对收益。尽管如此，与合并前同等数量的行相比，令牌绝对数量仍显著下降，因为现在每张独特卡牌只表示一次，并附带一个较小的印刷版本列表，而不是拆成 1-3 行完整记录。

使用 PYTHONPATH=. uv run python benchmarks/bench_toon.py 复现（需要已填充的 cards.json 缓存）。

免责声明

这是一个个人的非官方粉丝工程项目。它与 Disney、Ravensburger 或 Disney Lorcana TCG 团队无关，未获其认可、赞助或审核。本项目依据 Ravensburger 的 Disney Lorcana TCG Community Code 构建和分发，仅使用公开可用的社区数据来源。所有 Disney Lorcana TCG 名称、卡牌文本、商标及相关知识产权均归 Disney 和 Ravensburger 所有。本项目不用于商业用途，仅反映我的个人观点，不代表我的雇主。

---

_{MCP Registry 所有权验证 — Registry 会读取已发布的软件包描述中的这一行，以确认本项目拥有该服务名称。}

mcp-name: io.github.danielenricocahall/lorcana-mcp