内容
# lorcana-mcp
[](https://pypi.org/project/lorcana-mcp/)
[](https://pypi.org/project/lorcana-mcp/)
[](LICENSE)
[](https://registry.modelcontextprotocol.io/servers/io.github.IcaroBichir/lorcana)
[](https://mcp.so/server/lorcana-mcp)
连接 Claude 到迪士尼 Lorcana 卡片数据的 MCP 服务器。导出您在 TCGPlayer 上的收藏，交给 Claude，然后获取包含墨水成本、属性、关键词、能力和格式合法性的完整丰富数据，以及一个可导入到 [dreamborn.ink](https://dreamborn.ink) 的文件。
---
## 工具
启动服务器后，Claude 上提供了四种工具：
| 工具 | 功能 |
| --- | --- |
| `enrich_csv` | 丰富原始 TCGPlayer 导出的 CSV 文件，添加墨水、成本、类型、子类型、STR/WIL/Lore、Inkable、关键词和能力。写入丰富的 CSV 文件和一个可导入到 dreamborn.ink 的文件。 |
| `lookup_card` | 按名称查找任何卡片。返回完整属性、能力文本、格式合法性和卡片图像 URL。 |
| `filter_collection` | 过滤您的收藏，以获取给定格式的卡片：`core`、`infinity`、`core_zh`、`core_ja` 或 `poorcana`。 |
| `audit_csv` | 将丰富的收藏与实时 API 数据进行比较，并报告任何过时或错误字段。 |
---
## 已列出
| 目录 | 链接 |
| --- | --- |
| MCP Registry（官方） | [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/servers/io.github.IcaroBichir/lorcana) |
| mcp.so | [mcp.so/server/lorcana-mcp](https://mcp.so/server/lorcana-mcp) |
| PyPI | [pypi.org/project/lorcana-mcp](https://pypi.org/project/lorcana-mcp/) |
---
## 安装
```bash
pip install lorcana-mcp
```
或从源代码安装：
```bash
git clone https://github.com/IcaroBichir/lorcana-mcp
cd lorcana-mcp
pip install .
```
---
## 添加到 Claude
### Claude 代码（CLI）
```bash
claude mcp add lorcana -- lorcana-mcp serve
```
### Claude 桌面版
找到 `claude_desktop_config.json`（macOS：`~/Library/Application Support/Claude/`，Windows：`%APPDATA%\Claude\`），并添加：
```json
{
"mcpServers": {
"lorcana": {
"command": "lorcana-mcp",
"args": ["serve"]
}
}
}
```
保存后重启 Claude 桌面版。
### Cursor / 其他 MCP 客户端
任何支持 stdio MCP 服务器的客户端都可以使用 `lorcana-mcp serve` 作为命令。
---
## 用法
一旦服务器连接成功，只需自然地与 Claude 交谈。不需要斜杠命令。
### 丰富收藏
从 TCGPlayer 导出收藏 → **我的收藏 → 导出 CSV**，然后：
> "在 /Users/me/Downloads/Lorcana_063026.csv 中丰富我的收藏"
Claude 将从 API 中获取卡片数据，并在您的输入旁边写入两个文件：
- `enriched_Lorcana_063026.csv` — 您的收藏，新增 10 列
- `dreamborn_Lorcana_063026.csv` — 可在 dreamborn.ink 上导入
在重新运行时，将以前丰富的的文件作为缓存传递，以跳过已见过的卡片：
> "使用 /Users/me/Downloads/Lorcana_new.csv 中的 /Users/me/lorcana/enriched_Lorcana_old.csv 作为缓存来丰富"
### 查询卡片
> "查找 Mirage - Super Recruiter"
> "Alma Madrigal - Heart of the Family 的属性是什么？"
> "Will o' the Wisp 在 Core 中是否合法？"
返回：墨水颜色、成本、类型、子类型、STR/WIL/Lore、inkable 状态、关键词、完整能力文本、格式合法性和卡片图像 URL。
### 按格式过滤收藏
> "我的哪些卡片在 Core Constructed 中是合法的？"
> "显示我的 Infinity 合法卡片，按墨水颜色分组"
> "我有哪些 Poorcana 合法卡片在 Amber 中？"
有效格式：`core`、`infinity`、`core_zh`、`core_ja`、`poorcana`
Poorcana 过滤使用您的丰富 CSV 中的 Rarity 列（仅普通 + 非普通）- 无需 API 调用。
Core/Infinity/区域合法性来自 [duels.ink](https://duels.ink)，它跟踪每个区域的当前轮换。
### 审核现有丰富文件
> "审核我在 /Users/me/lorcana/enriched_collection.csv 中的收藏"
在新系列发布后或卡片数据看起来不正确时非常有用。将每张非促销卡片与实时 API 数据进行比较，并报告字段不匹配的情况。
---
## 丰富列
增强程序在原始 TCGPlayer 导出中添加了以下 10 列：
| 列 | 描述 |
| --- | --- |
| 墨水 | 墨水颜色（s）- 双墨水卡片显示两种，例如 `Amber, Steel` |
| 墨水成本 | 玩牌的数字成本（1-12） |
| 卡片类型 | 角色 / 动作 / 动作 - 歌曲 / 物品 / 地点 |
| 子类型 | 例如 `Storyborn, Hero, Toy` |
| 力量 | ⚔ 属性 - 空白为动作、物品 |
| 智慧 | 🛡 属性 - 空白为动作、物品 |
| Lore 点数 | ◆ 每回合获得 - 空白为动作、物品 |
| 可墨水 | 是 / 否 |
| 关键词 | 用逗号分隔：`Evasive`、`Shift 3`、`Singer 5`、`Resist +1`等 |
| 能力 | 完整的卡片文本，用管道分隔行 |
---
## 数据源
| 源 | 系列 | 用于 |
| --- | --- | --- |
| [LorcanaJSON](https://lorcanajson.org) | 所有系列（1-14+） | 系列 12+ 的主要源；1-11 的备用源 |
| [lorcana-api.com](https://lorcana-api.com) | 系列 1-11 | 首选系列 1-11（更丰富的正文） |
| [duels.ink](https://duels.ink) | 所有系列 | 格式合法性、卡片图像 |
卡片数据在 `~/.cache/lorcana-mcp/` 中本地缓存 24 小时。使用 CLI 管理缓存：
```bash
lorcana-mcp cache stats # 显示条目数量、过期状态和文件大小
lorcana-mcp cache clear # 删除所有缓存的响应（下次使用时刷新获取）
```
---
## 支持的系列
| 系列 | 名称 |
| --- | --- |
| 1 | 第一章 |
| 2 | Rise of the Floodborn |
| 3 | 进入墨水之地 |
| 4 | 乌苏拉的回归 |
| 5 | 闪烁的天空 |
| 6 | 绿宝石海 |
| 7 | Archazia 的岛屿 |
| 8 | Jafar 的统治 |
| 9 | 传说 |
| 10 | 井中的低语 |
| 11 | 冬天的咒语 |
| 12 | 未知的荒野 |
| 13 | 藤蔓的攻击！ |
| 14 | Hyperia 城 |
只要系列名称被添加到内部映射中，新系列就会通过 LorcanaJSON 自动获取。如果新系列无法解析，请打开一个问题。
---
## TCGPlayer 导出格式
前往 [TCGPlayer](https://www.tcgplayer.com) → **我的账户 → 我的收藏 → 导出**。原始文件有诸如产品名称、系列名称、编号、稀有度、条件、印刷和 `添加数量`（这是实际拥有的数量列 - `总数量` 在导出时始终为空）等列。
> **促销卡片：** 在 dreamborn 输出中跳过，因为 dreamborn 使用内部促销系列编号，这些编号与 TCGPlayer 的格式不匹配。在导入其余卡片后，通过 dreamborn.ink 的卡片搜索手动添加它们。
---
## CLI 参考
```
lorcana-mcp --version
lorcana-mcp serve 启动 MCP 服务器（stdio）
lorcana-mcp cache stats 显示缓存信息
lorcana-mcp cache clear 清除缓存的 API 响应
```
---
## 开发
```bash
git clone https://github.com/IcaroBichir/lorcana-mcp
cd lorcana-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```
74 个测试，无需网络调用。
---
## 许可证
MIT - 请参阅 [LICENSE](LICENSE)。
<!-- mcp-name: io.github.IcaroBichir/lorcana -->
