Lorcana Mcp

lorcana-mcp

将 Claude 连接到 Disney Lorcana 卡牌数据的 MCP 服务。将你从 TCGPlayer 导出的收藏交给 Claude，即可为其补全墨水费用、属性、关键词、能力和赛制合法性等信息，并生成可直接导入 dreamborn.ink 的文件。

---

简明介绍

**它的作用：**将此服务接入 Claude，让它成为了解你实际收藏的 Disney Lorcana 专家——不必再在 TCGPlayer、dreamborn.ink 和维基之间来回切换。

连接后，你只需像这样与 Claude 对话：

• 🗂️ “补全我位于 ~/Downloads/export.csv 的收藏信息”——将基础的 TCGPlayer 导出文件转换为完整的卡牌数据库（费用、属性、关键词、能力），并生成可导入 dreamborn.ink 的文件
• 🔎 “那张卡叫什么来着，大皮特？”——即使你不记得卡牌的准确名称或拼写，也能找到它
• 🎴 “给我看看 Amber 中费用低的 Evasive 角色”——按颜色、费用、关键词、稀有度等条件搜索整个卡池
• 🎵 “谁可以免费演唱 Be Our Guest？”——为歌曲找出最佳 Singer 组合
• 📋 “这套牌合法吗？4x Goofy - Musketeer, 4x...”——检查任意牌组列表的费用曲线、颜色和赛事合法性
• 💰 “完成这套牌还缺什么？要花多少钱？”——将牌组列表与收藏进行比较，并根据实时市场数据为缺少的卡牌估价
• 🏗️ “帮我组一套 Core Constructed Amber/Sapphire 牌组”——自动从你的收藏中组出合法且费用曲线均衡的牌组列表；也可提供估价后即可补齐的理想牌组，或完整的市场牌组
• ✅ “我的收藏数据还是最新的吗？”——根据实时卡牌数据核查你的 CSV，并标记过时信息

所有数据均来自公开卡牌 API 和你自己导出的 CSV——无需账户、登录，也无需任何配置。

不到一分钟即可运行

**Claude Desktop——一键安装：**下载 lorcana-mcp.mcpb 并双击（或选择 Settings → Extensions → Install extension…）。无需终端、无需安装 Python，也无需任何配置。

其他方式——一条命令：

1. 连接服务（uvx 会按需获取；请先安装 uv，或者运行 pip install lorcana-mcp 并移除 uvx）：

claude mcp add lorcana -- uvx lorcana-mcp serve

如果你使用 Claude Desktop 配置、Cursor、VS Code、Windsurf、Cline 或 Zed？所有客户端的安装说明都在 docs/INSTALL.md 中。

2. 与它对话： 从 TCGPlayer 导出你的收藏（My Account → My Collection → Export），然后只需说：

“补全我位于 /path/to/your/export.csv 的收藏信息”

就是这么简单——其余工作交给 Claude。以下内容是参考详情，供你在需要更多控制时查阅。

---

工具

服务运行后，Claude 中即可使用 13 个工具：

工具	功能说明
enrich_csv	为原始 TCGPlayer 导出文件补充 Ink、Cost、Type、Subtypes、STR/WIL/Lore、Inkable、Keywords 和 Abilities。会在输入文件旁生成补充信息后的 CSV 和可导入 dreamborn.ink 的文件。设置 refresh_prices=True 还会通过实时查询 tcgcsv.com 刷新 TCG Market Price。
lookup_card	按名称查询任意卡牌。返回完整属性、技能文本、赛制合法性和卡牌图片 URL。
resolve_card	对非正式、有拼写错误或缺少副标题的卡牌名称进行模糊匹配（例如 “goofy musketeer” 和 “elsa”）。返回一个可信度高的匹配项、按排名排列的前 3 个候选项以供辨别，或未找到结果。
list_printings	并排列出某张卡牌的所有印次，或所有共享同一角色名的卡牌：系列、编号、费用、属性、稀有度、各赛制合法性和最低市场价格。可选的 fmt 参数会添加 ✓/✗ 合法性列。适用于查询“X 的哪个印次符合 Core 赛制要求／价格最低？”。
search_cards	按颜色、类型、稀有度、系列、费用范围、关键词、技能文本或子类型搜索完整卡池，并支持分页。
find_song_synergies	查找所有能演唱指定歌曲的角色（或满足指定费用门槛的角色），并分别列出享有 Singer 关键词折扣的角色和仅满足费用要求的角色。还可标记你已拥有的卡牌。
filter_collection	筛选出在指定赛制中合法的收藏卡牌：core、infinity、core_zh、core_ja 或 poorcana。
audit_csv	将补充信息后的收藏 CSV 与实时 API 数据进行比对，并报告过时或错误的字段。
analyze_deck	分析原始套牌列表（每行一张，格式为 4x Card Name），包括墨水曲线、可墨水化卡牌占比、颜色分布、卡牌类型、每回合预估传说值，以及 Core Constructed 合法性（至少 60 张、每种卡牌最多 4 张、墨水颜色不超过 2 种）。
what_am_i_missing	将套牌列表与您的收藏进行比对，显示已拥有、缺少或数量不足的卡牌，并通过 tcgcsv.com 实时估算补齐套牌所需的 TCGPlayer 费用。
build_deck	自动组建一副合法、费用曲线均衡的约 60 张套牌，适用于指定的墨水颜色组合／赛制，支持 3 种模式：collection（仅使用您拥有的卡牌）、ideal（不考虑是否拥有，组建最佳套牌；如果提供收藏 CSV，则估算补齐费用）或 market（组建并计算最佳套牌的全部费用，不考虑是否拥有）。还支持 format="coconut"，即 Ravensburger 的多人单例测试版（最多 3 种墨水颜色；除所选 Coconut 关联的角色卡最多可使用 4 张外，其他卡牌均限 1 张）。传入 theme（如 "princess"／"detective" 这样的分类或角色名）即可组建部族套牌；如果省略墨水颜色，则会自动选择。设置 include_preview=True 可使用尚未合法的已公布系列卡牌。这是基于启发式费用曲线／关键词价值的构建器，不会检测协同／连招。
build_sealed_deck	使用开包得到的卡池组建最佳 40 张 现开／预售前赛事 套牌（6 包，约 72 张）。每行输入一张卡牌，可输入名称（非正式名称或拼写错误也可以），或卡牌上印刷的收藏编号（123、123/204）；因此可由 MCP 客户端将卡池照片转录后直接传入。现开规则：至少 40 张，不限墨水颜色，不限同名卡数量。会按卡池深度为所有墨水颜色组合排名，围绕卡池最深的组合构建套牌，仅在需要凑满 40 张时加入其他墨水颜色，并列出最佳备牌以及任何有歧义／无法识别的行（绝不猜测）。
get_meta	返回人工维护的 Core Constructed 环境快照：每种双墨水颜色组合的等级、大致环境占比和打法风格，以及近期赛事结果；也可筛选指定颜色组合（ink_colors="Emerald,Steel"）。传入 event=（如 "nac"、"asia"、"kobe" 等）则改为返回该赛事的完整排名和套牌列表。这不是实时查询——目前没有像卡牌数据那样的免费结构化数据源——因此这是随版本发布打包的版本化快照，工具输出也会明确说明这一点。

---

收录于

目录	链接
MCP Registry (官方)	registry.modelcontextprotocol.io
mcp.so	mcp.so/server/lorcana-mcp
PyPI	pypi.org/project/lorcana-mcp

---

安装

如果使用下文介绍的 uvx 或 Claude Desktop bundle，则无需安装任何内容。若要显式安装此软件包：

pip install lorcana-mcp
# or:  uv tool install lorcana-mcp

从源代码安装：

git clone https://github.com/IcaroBichir/lorcana-mcp
cd lorcana-mcp
pip install .

**Claude Desktop bundle：**发布页面上的 lorcana-mcp.mcpb——一键安装，内置运行时。由 packaging/mcpb/ 构建。

---

添加到客户端

lorcana-mcp 是一个本地 stdio 服务——在你的计算机上运行，无需托管或 API 密钥。docs/INSTALL.md 是完整指南，其中包含适用于所有客户端的可直接复制粘贴的配置。简要说明如下：

客户端	支持情况	方法
Claude Desktop	✅	一键安装 .mcpb bundle，或使用下方配置
Claude Code	✅	claude mcp add lorcana -- uvx lorcana-mcp serve
Cursor · VS Code · Windsurf · Cline · Zed	✅	stdio 配置——参见 docs/INSTALL.md
任何其他 stdio MCP 客户端	✅	命令：uvx lorcana-mcp serve（若通过 pip 安装，则使用 lorcana-mcp serve）
Claude.ai (web) · ChatGPT	❌	这些服务需要托管的远程服务；本服务仅在本地运行——参见 docs/INSTALL.md

Claude Code (CLI)

claude mcp add lorcana -- uvx lorcana-mcp serve

Claude Desktop（手动配置）

最简单的方式是使用一键安装 bundle。如果要手动配置，请编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\，或前往设置 → 开发者 → 编辑配置）：

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

如果通过 pip 而非 uv 安装，请使用 "command": "lorcana-mcp", "args": ["serve"]。保存后，完全退出并重新打开 Claude Desktop。

---

用法

连接服务后，只需自然地与 Claude 对话，无需使用斜杠命令。

丰富收藏集信息

从 TCGPlayer 导出你的收藏集：前往 My Collection → Export CSV，然后：

“丰富 /Users/me/Downloads/Lorcana_063026.csv 中的收藏集信息”

Claude 会从 API 获取卡牌数据，并在输入文件旁写入两个文件：

• enriched_Lorcana_063026.csv — 添加了 10 个新列的收藏集
• dreamborn_Lorcana_063026.csv — 可直接导入 dreamborn.ink

再次运行时，将之前丰富过的文件作为缓存传入，以跳过已查询过的卡牌：

“使用 /Users/me/lorcana/enriched_Lorcana_old.csv 作为缓存，丰富 /Users/me/Downloads/Lorcana_new.csv”

无需重新从 TCGPlayer 导出，即可按需刷新价格：

“重新丰富 /Users/me/lorcana/enriched_Lorcana_063026.csv 中的收藏集信息并刷新价格”

refresh_prices=True 会通过 tcgcsv.com 实时查询对应印刷版本的价格，并覆盖每一行的 TCG Market Price——适用于价格已过时的丰富版 CSV。

查询卡牌

“查询 Mirage - Super Recruiter”

“Alma Madrigal - Heart of the Family 的属性是什么？”

“Will o' the Wisp 在 Core 赛制中是否合法？”

返回：墨水颜色、费用、类型、子类型、STR/WIL/Lore、可否墨水化、关键词、完整能力文本、赛制合法性以及卡牌图片 URL。

解析非正式或拼写错误的卡牌名称

“查找卡牌 ‘goofy musketeer’”

“那张叫 ‘big pete’ 的卡是什么？”

“查询 ‘elsa’——不确定是哪个版本”

系统会对查询进行分词，并与所有卡牌的名称和副标题进行评分；可容忍缺少连字符、缺少副标题、词序不同以及轻微拼写错误。若匹配结果有充分把握且仅有一张卡牌，则返回完整详情；若有多张卡牌都可能匹配（例如，单独的角色名称可能对应该角色的每个印刷版本），则返回按匹配度排序的前 3 个结果及置信度分数；若查询与任何卡牌都不相似，则不返回结果。

搜索完整卡池

“显示所有位于紫罗兰色、费用不超过 3 且具有闪避能力的角色”

“查找玩具角色”

“搜索来自《未知荒野》的稀有钢铁卡牌”

筛选条件包括：墨水颜色、卡牌类型（Character / Action / Item / Location / Song）、稀有度、系列名称、费用范围、关键字、能力文本子串和副类型；所有条件均可组合使用，并支持分页（offset + limit）。结果按墨水颜色分组，并按费用排序。

查找哪些角色可以演唱歌曲

“哪些角色可以演唱 Be Our Guest？”

“显示可以演唱费用为 7 的歌曲的琥珀色角色”

“哪些角色可以演唱 Friends on the Other Side？其中哪些是我拥有的？”（传入经过增强的收藏集 CSV）

如果角色印刷费用达到歌曲费用，或者具有匹配的 Singer X 关键字，就可以演唱该歌曲——Singer 关键字仅在演唱歌曲时有效，可让低费用角色发挥超出其实际费用的能力。结果分为具有 Singer 关键字的“折扣”候选角色（优先显示 Singer 数值最高的角色，其次是实际费用最低的角色）和符合费用要求的普通角色（优先显示费用最低的角色）。传入 collection_csv 可标记你拥有的卡牌。

按赛制筛选收藏集

“我的哪些卡牌符合核心构筑赛制？”

“显示我符合 Infinity 赛制的卡牌，并按墨水颜色分组”

“我有哪些符合 Poorcana 赛制的琥珀色卡牌？”

有效赛制：core、infinity、core_zh、core_ja、poorcana

Poorcana 筛选使用经过增强的 CSV 中的 Rarity 列（仅普通 + 非普通）——无需调用 API。

核心赛制、Infinity 赛制和地区赛制的合法性数据来自 duels.ink，该网站会追踪各地区当前的轮换情况。

审核现有的增强文件

“审核我的收藏集文件：/Users/me/lorcana/enriched_collection.csv”

适用于新系列发布后，或卡牌数据看起来有误时。将每张非促销卡牌与实时 API 数据进行比对，并逐字段报告差异。

分析牌组列表

“分析这套牌组：4x Goofy - Musketeer, 4x Elsa - Spirit of Winter, ...”（粘贴完整列表，每行一张卡牌）

接受 4x Card Name 或 4 Card Name 格式；若省略数量，默认为 1。以 # 或 // 开头的行会被视为注释。

返回内容包括：墨水曲线（费用区间为 1-2/3-4/5-6/7+）、可墨化与不可墨化卡牌数量、颜色分布、卡牌类型分布、每回合预估传说值（角色传说值总和）、核心构筑赛制合法性检查（至少 60 张卡牌、任一卡牌最多 4 张、墨水颜色不超过 2 种），以及无法解析的卡牌名称。

检查牌组列表还缺哪些卡牌

“要组好这套牌，我还缺什么？”（粘贴牌组列表，并提供收藏集 CSV）

“组齐这套琥珀色/钢铁牌组需要多少钱？”

牌组列表格式与 analyze_deck 相同。会将列表与经过增强的收藏集 CSV 交叉比对，然后将结果分为你已有足够数量的卡牌，以及缺少或数量不足的卡牌。对于数量不足的卡牌（你已拥有至少一个印刷版本），价格直接取自 CSV 自带的 TCG Market Price 列——无需联网。只有你一张都没有的卡牌，才会通过 tcgcsv.com 查询实时 TCGPlayer 价格（从所有系列/稀有度中选取最便宜的印刷版本，因为游戏玩法相同）；而且只有至少有一张卡牌确实需要查询时才会进行查询。实时价格数据会缓存 24 小时，因此首次需要查询时，加载缓存需要稍长一点时间。

---

增强列

增强器会向原始 TCGPlayer 导出文件添加以下 10 列：

列	说明
Ink	墨水颜色；双色卡牌会显示两种颜色，例如 Amber, Steel
Ink Cost	打出卡牌所需的数值费用（1–12）
Card Type	Character / Action / Action - Song / Item / Location
Subtypes	例如 Storyborn, Hero, Toy
Strength	⚔ 数值；Action、Item 留空
Willpower	🛡 数值；Action、Item 留空
Lore Points	每次探索获得的 ◆；Action、Item 留空
Inkable	Yes / No
Keywords	以逗号分隔：Evasive、Shift 3、Singer 5、Resist +1 等
Abilities	完整卡牌文本，各行以竖线分隔

---

数据源

来源	系列	用途
LorcanaJSON	所有系列（1–14+）	Set 12+ 的主要来源；Set 1–11 的备用来源
lorcana-api.com	Set 1–11	Set 1–11 的首选来源（卡牌正文更丰富）
duels.ink	所有系列	格式合法性、卡牌图片
tcgcsv.com	所有系列	TCGPlayer 市场价格（每日镜像）

卡牌数据会实时获取，并在本地缓存 24 小时，缓存位置为 ~/.cache/lorcana-mcp/。如果无法访问 LorcanaJSON，服务会回退到内置卡牌快照（lorcana_mcp/data/allcards_fallback.json.gz，每次发布时刷新），并仅警告一次数据可能已过时。使用 CLI 管理缓存：

lorcana-mcp cache stats   # show entry count, expiry status, and file size
lorcana-mcp cache clear   # delete all cached responses (fresh fetch on next use)

---

支持的系列

系列	名称
1	The First Chapter
2	Rise of the Floodborn
3	Into the Inklands
4	Ursula's Return
5	Shimmering Skies
6	Azurite Sea
7	Archazia's Island
8	Reign of Jafar
9	Fabled
10	Whispers in the Well
11	Winterspell
12	Wilds Unknown
13	Attack of the Vine!
14	Hyperia City

只要将新系列名称添加到内部映射中，LorcanaJSON 就会自动提供新系列的数据。如果无法解析新系列，请提交 issue。

---

TCGPlayer 导出格式

前往 TCGPlayer → My Account → My Collection → Export。原始文件包含 Product Name、Set Name、Number、Rarity、Condition、Printing 和 Add to Quantity 等列（这是实际拥有数量所在的列；导出文件中的 Total Quantity 始终为空）。

**Promo 卡牌：**系统会尽可能自动解析。dreamborn.ink 的批量导入会将 promo 表示为 (Set Number, Card Number)，其中 Set Number 是该 promo 发售对应的 LJ 系列，Card Number 是完整的 "N/Series" 字符串（例如 "57/P3"）——这一点已通过实际的 dreamborn 导出文件验证，而非仅根据其卡牌浏览页面判断（之前仅依据页面显示信息进行的尝试会静默破坏导入数据；请参阅 CHANGELOG.md 中的 0.2.2/0.2.3 条目）。尚未收录在该映射中的 promo，仍需在导入其余卡牌后通过 dreamborn.ink 的卡牌搜索手动添加。

---

CLI 参考

lorcana-mcp --version
lorcana-mcp serve          Start the MCP server (stdio)
lorcana-mcp cache stats    Show cache info
lorcana-mcp cache clear    Clear cached API responses

---

保持最新

卡牌数据始终是实时的（从公共 API 获取，缓存 24 小时），但内置的环境数据快照（get_meta）以及任何工具或行为变更，只有在更新软件包后才会更新：

pip install -U lorcana-mcp        # or: uv tool upgrade lorcana-mcp

Claude Desktop .mcpb 用户：重新下载 lorcana-mcp.mcpb 并重新安装——该捆绑包固定使用精确版本，不会自动更新。更新后请重启 MCP 客户端，以便重新连接到新服务。

接收新版本发布通知：

• 服务每天会检查一次 PyPI（失败时静默处理、会缓存、只发送一次请求）；如果本地版本落后，启动时会向 stderr 输出一行提示——可在 Claude Code 的 MCP 日志或 Claude Desktop 的日志文件中查看——并在 get_meta 的输出中附加一条说明。要退出检查，请在服务的 env 中设置 LORCANA_MCP_NO_UPDATE_CHECK=1。
• 或者关注代码仓库：选择 Watch → Custom → Releases，或订阅 Atom 源 https://github.com/IcaroBichir/lorcana-mcp/releases.atom。

---

开发

git clone https://github.com/IcaroBichir/lorcana-mcp
cd lorcana-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

共有 355 项测试，无需网络调用。每次拉取请求以及推送到 main 时，CI 都会在 Python 3.11、3.12 和 3.13 上运行完整测试套件（参见 .github/workflows/tests.yml）。

---

许可证

MIT——详见 LICENSE。

---

🤖 CLAUDE 必读

如果你是已连接此 MCP 服务的 AI Agent（无论是否为 Claude），请在调用工具前阅读本节。这是正确使用此服务的快速指南。

应调用哪个工具

用户想要……	调用……	而不是……
将原始 TCGPlayer 导出文件转换为真正的数据库	enrich_csv	—
无需重新导出即可更新过期价格	使用 refresh_prices=True 调用 enrich_csv	手动 curl TCGPlayer
查询用户明确提供了准确名称的卡牌统计信息	lookup_card	—
按非正式、部分或拼写错误的名称查找卡牌（例如“goofy musketeer”“big pete”“elsa”）	resolve_card	lookup_card——它只进行简单的子字符串匹配，对于名称中缺少准确破折号或拼写的卡牌，会错误地报告“未找到”
查询某张卡牌的哪个印刷版本在某个赛制中合法、购买价格最低，或是否有 Enchanted 版本	list_printings（传入 fmt 以添加合法性列）	lookup_card——它会静默地只返回最新印刷版本
按颜色、类型、稀有度、系列、费用、关键字、能力文本或副类型浏览／筛选所有卡牌	search_cards	—
查询歌手组合／“谁能免费演唱这首歌”	find_song_synergies	—
查询收藏卡牌在各赛制（Core、Infinity、Poorcana 等）中的合法性	filter_collection	—
根据实时数据核对已增强的 CSV	audit_csv	—
评估曲线、颜色平衡和合法性的牌组列表	analyze_deck	—
“要完成这副牌，我还需要买什么？要花多少钱？”	what_am_i_missing	—
“帮我组一副[公主／侦探／史迪奇]牌组”	build_deck(theme=...)——省略 ink_colors 以自动选择最佳颜色组合，或传入用户指定的墨水颜色	按副类型筛选 search_cards 的结果并手动组牌
“帮我组一副适合[墨水颜色组合]的牌组”	build_deck——如果用户尚未说明，请先询问三种模式（collection／ideal／market）中的哪一种	手动根据 search_cards 的结果组建牌组列表
“这是我的预售／现开卡池”（卡牌列表或开出的卡牌照片）	build_sealed_deck——如果是照片，请读取每张卡牌的收藏编号（或名称），每张卡牌一行，然后向用户确认任何有歧义或无法识别的行	build_deck（构筑赛规则：60 张卡牌、每种最多 4 张、2 种墨水）

严格规则

1. csv_path / input_path / collection_csv 始终使用绝对路径。相对路径会相对于服务进程的当前工作目录解析，而不是用户的目录——这可能会静默失败或指向错误的文件。如果没有绝对路径，请询问用户或先查找文件。
2. 除非用户提供的名称你确信完全准确且拼写无误，否则默认使用 resolve_card，而不是 lookup_card。拿不准时，resolve_card 宽容得多，而且不会增加成本。
3. 绝不要手动编写价格查询逻辑。find_song_synergies、what_am_i_missing 和 build_deck 已经会在内部调用 tcgcsv.com，并使用 24 小时缓存和最低价印刷版逻辑。不要用 curl 查询 TCGPlayer，也不要自行抓取价格。
4. 不同印刷版的玩法完全相同（基础版、Enchanted、Epic、promo——名称、费用、属性和技能都相同）。所有价格相关工具都会自动选择最便宜的印刷版；不要质疑看起来低得可疑的结果，也不要把稀有度当作玩法参考。用户需要查看各印刷版明细时（例如某印刷版在某赛制中是否合法、哪款最便宜、是否有 Enchanted 版），请使用 list_printings。
5. 如果用户说数据不正确或已过时，请建议先运行 lorcana-mcp cache clear，再判断工具是否出现故障——卡牌和价格数据的缓存有效期为 24 小时。
6. 工具输出含糊是功能特性，不是错误。resolve_card 和 find_song_synergies 可能会返回按相关度排序的“你是不是想找”列表，而非单个答案——请把列表提供给用户，不要自行猜测他们指的是哪一个。
7. build_deck 使用的是费用曲线/关键词价值启发式，而不是协同引擎。它无法识别多卡组合（如 Merlin/Mim 弹回、Steelsong 等）——不要把它的输出描述成完整的、经过赛事调优的牌组列表。应将其视为值得审查和调整的有力起点，而非最终答案。

已知注意事项（从经验中总结——参见 CHANGELOG.md）

• Product ID（CSV 第 1 列）≠ TCGplayer Id（第 2 列）。只有 Product ID 与外部价格 API（LorcanaJSON 的 externalLinks.tcgPlayerId、tcgcsv.com 的 productId）匹配。第 2 列是无关的次要 ID——如果要针对这些数据编写自定义代码，用它进行匹配会静默地返回零结果。
• Promo 卡牌通过 PROMO_DREAMBORN_ROW/PROMO_DREAMBORN_ROW_BY_NUMBER（api.py）解析——这一点已通过真实的 dreamborn.ink 导出文件验证，而非其卡牌浏览器展示（先前基于浏览器猜测的方法曾静默地破坏过一次真实导入；见 CHANGELOG.md 0.2.2）。Promo 卡牌在 dreamborn 导出中的 Card Number 是完整的 "N/Series" 字符串，不会拆分成单独的系列字段——如果要扩展此映射，请勿再次拆分。尚未加入映射的卡牌仍需在导入后通过 dreamborn.ink 的搜索功能手动录入。
• 搜索结果中看起来重复的行其实是不同印刷版，并非错误——search_cards 和 find_song_synergies 已经会在内部按名称去重异画版/Enchanted 再版，因此结果数量比原始卡牌列表预期的更少也不足为奇。

如果你要修改这个代码库

• 每次更改前后都运行 pytest——共 355 项测试，全部无需联网（外部调用均已模拟；tests/conftest.py 也会停用 PyPI 更新检查）。
• 代码布局：纯逻辑和可测试逻辑位于 api.py（卡牌数据 + 模糊匹配 + 定价）、deck.py（套牌列表解析／分析）、deckbuilder.py（构筑赛套牌合成）、sealed.py（现开牌池解析 + 40 张牌套牌构建）、enricher.py（CSV 流水线）、meta.py + tournaments.py（打包的环境／赛事快照），以及 update_check.py（PyPI 版本检查）。server.py 只负责将这些内容封装为 MCP 工具并格式化输出——请保持这种做法，不要直接把逻辑写进工具函数。lorcana_mcp/data/allcards_fallback.json.gz 是离线卡牌数据备用文件（使用 scripts/update_fallback_snapshot.py 刷新）。
• 发布时需更新四个文件中的版本号（pyproject.toml、server.json、packaging/mcpb/pyproject.toml——包括其中的 version 和 lorcana-mcp== 固定版本号，以及 packaging/mcpb/manifest.json），添加一条 CHANGELOG.md 记录，并在工具行为发生变化时更新此 README 和 docs/INSTALL.md。查看 git log，确认符合 chore: release X.Y.Z 模式。
• 发布是单独且明确的步骤（python -m build、twine upload、mcp-publisher publish）——切勿认为更新了 pyproject.toml 中的版本号，就代表内容已发布到 PyPI 或注册表。告诉用户某项功能“已上线”前，请先确认。