Lorcana Mcp

lorcana-mcp

Claude を Disney Lorcana のカードデータに接続する MCP サーバーです。TCGPlayer からコレクションをエクスポートして Claude に渡すと、インクコスト、ステータス、キーワード、能力、フォーマットでの使用可否などの情報がすべて補完され、さらに dreamborn.ink にすぐインポートできるファイルも作成されます。

---

概要

できること： これを Claude に接続すると、実際に所有しているカードを把握した Disney Lorcana のエキスパートになります。TCGPlayer、dreamborn.ink、Wiki の間を行き来する必要はもうありません。

接続すると、次のように Claude に話しかけるだけで使えます。

• 🗂️ 「~/Downloads/export.csv にあるコレクションの情報を補完して」 — TCGPlayer の基本的なエクスポートデータを、カードデータベース（コスト、ステータス、キーワード、能力など）に変換し、dreamborn.ink にインポートできるファイルも作成します
• 🔎 「big pete っていうカードは何？」 — 正確な名前やスペルを覚えていなくてもカードを見つけます
• 🎴 「アンバーの、低コストで回避能力を持つキャラクターを見せて」 — 色、コスト、キーワード、レア度などでカードプール全体を検索します
• 🎵 「『Be Our Guest』を無料で歌えるのは誰？」 — 楽曲に最適な歌い手の組み合わせを見つけます
• 📋 「このデッキは合法？ 4x Goofy - Musketeer, 4x...」 — 任意のデッキリストのマナカーブ、色、トーナメントでの使用可否を確認します
• 💰 「このデッキを完成させるには何が足りなくて、いくらかかる？」 — デッキリストをコレクションと比較し、不足分の価格を最新の市場データで算出します
• 🏗️ 「コア構築のアンバー／サファイアのデッキを組んで」 — コレクションから、ルールに適合しマナカーブのバランスが取れたデッキリスト、完成までの価格を抑えた理想的な構成、または市場価格に基づくフルデッキを自動で作成します
• ✅ 「コレクションのデータはまだ正確？」 — CSV を最新のカードデータと照合し、古くなった情報を検出します

公開カード API とエクスポートした CSV のみを使用します。アカウント、ログイン、設定は不要です。

1 分以内に使い始める

Claude Desktop — ワンクリック： lorcana-mcp.mcpb をダウンロードしてダブルクリックします（または Settings → Extensions → Install extension… を選択します）。ターミナルも Python のインストールも設定も不要です。

それ以外 — コマンド 1 つ：

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」）。確度の高い一致候補を 1 件、判別用に順位付けした上位 3 件、または該当なしを返します。
list_printings	カードのすべての版、またはキャラクター名が共通するすべてのカードを、セット、番号、コスト、ステータス、レアリティ、フォーマットごとの使用可否、最安市場価格とともに並べて表示します。省略可能な fmt を指定すると、使用可否の ✓/✗ 列が追加されます。「X のうち Core で使用可能な版／最安の版はどれ？」という質問に対応します。
search_cards	カラー、タイプ、レアリティ、セット、コスト範囲、キーワード、能力テキスト、サブタイプで、全カードプールをページネーション付きで検索します。
find_song_synergies	指定した歌、またはコストのしきい値で歌えるキャラクターをすべて検索し、Singer キーワードによるコスト軽減候補と、通常のコスト条件を満たすカードに分類します。所有カードも任意で表示できます。
filter_collection	コレクションから、指定したフォーマット（core、infinity、core_zh、core_ja、poorcana）で使用可能なカードを抽出します。
audit_csv	補完済みコレクションを最新の API データと照合し、古くなったフィールドや誤ったフィールドを報告します。
analyze_deck	生のデッキリスト（1 行に 4x Card Name）を分析し、インクカーブ、インク可能カードの比率、カラーの内訳、カードタイプ、ターンごとの推定ロア、Core Constructed の合法性（60 枚以上、同一カードは最大 4 枚、インクカラーは 2 色以下）を表示します。
what_am_i_missing	デッキリストをコレクションと照合し、すでに所有しているカード、不足しているカードや枚数、および完成に必要な費用の TCGPlayer リアルタイム見積もり（tcgcsv.com 経由）を表示します。
build_deck	インクの組み合わせ／フォーマットに合わせて、合法でカーブのバランスが取れた約 60 枚のデッキリストを自動構築します。モードは 3 種類です。collection（所有カードのみ）、ideal（所有状況を問わず最適なデッキ。コレクション CSV を渡すと完成に必要な費用を算出）、market（所有状況を無視し、価格をすべて算出した最適なデッキ）。format="coconut"（Ravensburger のマルチプレイヤー用シングルトンのベータ版。インクカラーは最大 3 色で、選んだ Coconut に関連するキャラクターのみ最大 4 枚、それ以外は各 1 枚）にも対応します。theme（"princess"／"detective" などの分類、またはキャラクター名）を渡すとテーマデッキを構築できます。インクカラーを省略すると自動で選択されます。また、include_preview=True を指定すると、まだ使用可能になっていない発表済みセットのカードも使用できます。相乗効果やコンボを検出するものではなく、カーブとキーワードの価値に基づくヒューリスティックな構築ツールです。
build_sealed_deck	開封したカードプール（6 パック、約 72 枚）から、最適な 40 枚のシールド／プレリリースデッキを構築します。1 行にカードを 1 枚ずつ指定します。カード名（略称や誤記でも可）、またはカードに印刷されたコレクター番号（123、123/204）を指定できます。そのため、カードプールの写真を MCP クライアントで文字起こしし、そのまま渡せます。シールドのルールは、40 枚以上、インクの制限なし、同一カードの枚数制限なしです。カードプールの厚みでインクの組み合わせをすべて順位付けし、最も厚い組み合わせを軸に構築します。40 枚に届かない場合にのみ追加のインクを採用し、最適なサイドボードカードと、曖昧または認識できなかった行（推測は行いません）も一覧表示します。
get_meta	手動で管理している Core Constructed のメタゲームスナップショットを返します。2 色のインクの組み合わせごとのティア、概算のメタ占有率、プレイスタイルと、最近の大会結果を確認できます。任意で ink_colors="Emerald,Steel" のように指定すると、1 つの組み合わせに絞り込めます。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 バンドルを使用する場合、インストールは不要です。パッケージを明示的にインストールするには、次のようにします。

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 バンドル： リリースページにある lorcana-mcp.mcpb は、ランタイムが同梱されたワンクリックインストーラーです。packaging/mcpb/ からビルドされています。

---

クライアントへの追加

lorcana-mcp はローカルの stdio サーバーです。お使いのマシンで実行されるため、ホスティングも API キーも不要です。すべてのクライアント向けのコピー＆ペースト可能な設定を含む完全なガイドは docs/INSTALL.md をご覧ください。概要は次のとおりです。

クライアント	対応状況	方法
Claude Desktop	✅	ワンクリックで使える .mcpb バンドル、または下記の設定
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（ウェブ） · ChatGPT	❌	これらにはホスト型のリモートサーバーが必要です。このサーバーはローカル専用です — docs/INSTALL.md をご覧ください

Claude Code（CLI）

claude mcp add lorcana -- uvx lorcana-mcp serve

Claude Desktop（手動設定）

最も簡単なのはワンクリックバンドルです。手動で設定する場合は、claude_desktop_config.json を編集してください（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\、または Settings → Developer → Edit Config）。

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

uv ではなく pip でインストールした場合は、"command": "lorcana-mcp", "args": ["serve"] を使用してください。保存後、Claude Desktop を完全に終了してから再起動してください。

---

使用方法

サーバーに接続したら、Claude に自然な言葉で話しかけるだけです。スラッシュコマンドは必要ありません。

コレクションを拡充する

TCGPlayer からコレクションをエクスポートします → My Collection → Export CSV を選択し、次のように依頼します。

"/Users/me/Downloads/Lorcana_063026.csv にあるコレクションを拡充して"

Claude は API からカードデータを取得し、入力ファイルと同じ場所に 2 つのファイルを書き出します。

• enriched_Lorcana_063026.csv — 10 個の新しい列を追加したコレクション
• dreamborn_Lorcana_063026.csv — dreamborn.ink にインポートできる形式

再実行時に、以前に拡充したファイルをキャッシュとして渡すと、すでに確認済みのカードをスキップできます。

"/Users/me/Downloads/Lorcana_new.csv を、/Users/me/lorcana/enriched_Lorcana_old.csv をキャッシュとして使って拡充して"

TCGPlayer から再エクスポートせずに価格を更新するには、次のように依頼します。

"/Users/me/lorcana/enriched_Lorcana_063026.csv にあるコレクションを再拡充して、価格を更新して"

refresh_prices=True を指定すると、各行の TCG Market Price が、そのカードの正確な印刷版についての tcgcsv.com のリアルタイム検索結果で上書きされます。拡充済み CSV の価格が古くなった場合に便利です。

カードを検索する

"Mirage - Super Recruiter を検索して"

"Alma Madrigal - Heart of the Family のステータスは？"

"Will o' the Wisp は Core で使用できますか？"

返される情報：インクの色、コスト、タイプ、サブタイプ、STR/WIL/Lore、インク化可能かどうか、キーワード、能力テキスト全文、フォーマットでの使用可否、カード画像の URL。

あいまいな名前やスペルミスのカード名を解決する

"カード「goofy musketeer」を探して"

"「big pete」っていうカードは何？"

"「elsa」を検索して — どのバージョンかはわからない"

クエリをトークン化し、すべてのカードの名前とサブタイトルに照らしてスコアを付けます。ダッシュやサブタイトルの欠落、単語の順序、軽微なスペルミスを許容します。確度の高い一致が 1 件の場合は詳細をすべて返します。複数の候補が考えられる場合（例：キャラクターのすべての印刷版に一致する単独の名前）は、信頼度スコア付きの上位 3 件を返します。どのカードにも似ていないクエリの場合は、何も返しません。

カードプール全体を検索する

「アメジストの、コストが3以下のエヴェイシブを持つキャラクターをすべて表示して」

「トイ・キャラクターを検索して」

「『Wilds Unknown』のレアなスティールのカードを検索して」

インクの色（複数可）、カードタイプ（Character／Action／Item／Location／Song）、レアリティ、セット名、コスト範囲、キーワード、アビリティテキストの一部、サブタイプで絞り込めます。これらはすべて組み合わせ可能で、ページネーション（offset + limit）にも対応しています。結果はインクの色ごとにまとめられ、コスト順に並びます。

誰が歌を歌えるかを調べる

「『Be Our Guest』を歌えるキャラクターは？」

「コスト7の歌を歌えるアンバーのキャラクターを表示して」

「『Friends on the Other Side』を歌えるのは誰？そのうち、私が持っているのはどれ？」（エンリッチ済みのコレクションCSVを渡してください）

キャラクターは、印刷されたコストが歌のコスト以上である場合、または一致する Singer X キーワードを持つ場合に、その歌を歌えます。Singerがあれば、実際のコストが低いキャラクターでも、歌う場合に限りコストを上回ることができます。結果は、Singerキーワードによる「割引」候補（Singerの値が高い順、次に実際のコストが低い順）と、通常のコスト条件を満たすカード（コストが低い順）に分かれます。所有状況を表示するには、collection_csv を渡してください。

フォーマットごとにコレクションを絞り込む

「私のカードのうち、Core Constructedで使用できるのはどれ？」

「Infinityで使用できるカードをインクの色ごとにまとめて表示して」

「Amberのカードのうち、Poorcanaで使用できるものはどれ？」

有効なフォーマット：core、infinity、core_zh、core_ja、poorcana

Poorcanaでの絞り込みでは、エンリッチ済みCSVのRarity列を使用します（Common + Uncommonのみ）。API呼び出しは不要です。

Core／Infinity／地域別の使用可否は、各地域の現在のローテーションを追跡しているduels.inkの情報を使用します。

既存のエンリッチ済みファイルを監査する

「/Users/me/lorcana/enriched_collection.csv にあるコレクションを監査して」

新しいセットの発売後や、カードのデータに誤りがあると思われる場合に便利です。プロモカード以外のすべてのカードをライブAPIデータと比較し、フィールドごとの差異を報告します。

デッキリストを分析する

「このデッキを分析して：4x Goofy - Musketeer、4x Elsa - Spirit of Winter、…」（カードを1行に1枚ずつ、全リストを貼り付けてください）

4x Card Nameまたは4 Card Nameの形式に対応しています。数量を省略した場合は1枚として扱います。#または//で始まる行はコメントとして扱われます。

結果には、インクカーブ（コスト帯1～2／3～4／5～6／7以上）、インク可能カードとインク不可カードの枚数、色の内訳、カードタイプの内訳、推定伝承獲得数／ターン（キャラクターの伝承値の合計）、Core Constructedの合法性チェック（最低60枚、同じカードは最大4枚、インクの色は最大2色）、解決できなかったカード名が含まれます。

デッキリストに足りないカードを確認する

「このデッキを組むには何が足りない？」（デッキリストを貼り付け、コレクションCSVを指定してください）

「このアンバー／スティールのリストを完成させるには、いくらかかる？」

analyze_deckと同じデッキリスト形式です。エンリッチ済みコレクションCSVと照合し、すでに必要な枚数を持っているカードと、不足しているカードに分けます。不足しているカードのうち、同じカードの印刷版を1枚以上持っている場合、価格はCSV内のTCG Market Price列から取得するため、ネットワークへのアクセスは不要です。1枚も持っていないカードのみ、tcgcsv.comを通じてTCGPlayerのライブ価格を照会します（ゲームプレイ上は同一のため、全セット／レアリティから最安の印刷版を取得します）。この処理も、実際に価格が必要なカードが1枚以上ある場合に限られます。ライブ価格データは24時間キャッシュされるため、価格が必要な最初の呼び出しでは、キャッシュの準備に少し時間がかかります。

---

拡張された列

エンリッチャーは、TCGPlayer の生データのエクスポートに次の 10 列を追加します。

列	説明
インク	インクの色。デュアルインクのカードには両方が表示されます（例：Amber, Steel）
インクコスト	プレイに必要な数値コスト（1～12）
カードタイプ	キャラクター／アクション／アクション - 歌／アイテム／ロケーション
サブタイプ	例：Storyborn, Hero, Toy
ストレングス	⚔ のステータス。アクション、アイテムでは空欄です
意志力	🛡 のステータス。アクション、アイテムでは空欄です
ロアポイント	クエストごとに獲得する◆。アクション、アイテムでは空欄です
インク化可能	はい／いいえ
キーワード	カンマ区切り：Evasive、Shift 3、Singer 5、Resist +1 など
アビリティ	カードの全文。行はパイプで区切られます

---

データソース

ソース	セット	用途
LorcanaJSON	全セット（1～14+）	セット 12 以降の主要ソース。セット 1～11 のフォールバック
lorcana-api.com	セット 1～11	セット 1～11 の推奨ソース（より詳細な本文）
duels.ink	全セット	フォーマットでの使用可否、カード画像
tcgcsv.com	全セット	TCGPlayer の市場価格（日次ミラー）

カードデータはリアルタイムで取得され、~/.cache/lorcana-mcp/ に 24 時間ローカルキャッシュされます。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 などの列があります（実際に所有している数量の列は Add to Quantity です。エクスポートでは Total Quantity は常に空欄です）。

プロモカード： 可能な場合は自動的に解決されます。dreamborn.ink の一括インポートでは、プロモカードは (Set Number, Card Number) として表されます。Set Number はプロモの配布に紐づく LJ セット、Card Number は完全な "N/Series" 文字列（例："57/P3"）です。これは実際の dreamborn エクスポートに基づいて検証済みであり、カードブラウザーの表示だけに基づくものではありません（表示だけを基にした以前の試みでは、インポートが気づかれないまま破損しました。CHANGELOG.md の 0.2.2/0.2.3 の記載を参照）。このマップにまだ登録されていないプロモは、残りをインポートした後、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 クライアントを再起動してください。

新しいリリースがあったときに通知を受け取る方法：

• サーバーは 1 日に 1 回ほど PyPI を確認します（失敗時は通知せず、キャッシュを使用し、リクエストは 1 回のみ）。更新が必要な場合、起動時に stderr に 1 行の通知を出力します。これは 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件あり、ネットワークへの接続は不要です。CIでは、すべてのプルリクエストとmainへのプッシュのたびに、Python 3.11、3.12、3.13で全テストスイートを実行します（.github/workflows/tests.ymlを参照）。

---

ライセンス

MIT — LICENSEを参照してください。

---

🤖 CLAUDE READ THIS

このMCPサーバーに接続されたAIエージェント（Claudeなど）は、ツールを呼び出す前にこのセクションを読んでください。正しく使うための手早いガイドです。

呼び出すツール

ユーザーの要望...	呼び出すツール...	呼び出さないツール...
TCGPlayerからエクスポートした未加工データを、実際に使えるデータベースにしたい	enrich_csv	—
再エクスポートせずに古い価格を最新の状態にしたい	refresh_prices=Trueを指定してenrich_csv	TCGPlayerを手動でcurlする
名前が正確に指定されたカードの統計情報を知りたい	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 — ユーザーが指定していない場合は、まず3つのモード（collection／ideal／market）のどれにするか尋ねます	search_cardsの検索結果から手作業でデッキリストを組み立てる
「これがプレリリース／シールドのカードプールです」（開封したカードのリストまたは写真）	build_sealed_deck — 写真の場合は各カードのコレクター番号（または名前）を1行に1枚ずつ書き出し、不明確または認識できない行があればユーザーに確認します	build_deck（構築戦のルール：60枚、同名カードは4枚まで、インクは2色）

厳守事項

1. csv_path／input_path／collection_csv には必ず絶対パスを渡してください。 相対パスはユーザーのものではなく、サーバープロセスの作業ディレクトリを基準に解決されるため、エラーが通知されないまま失敗したり、誤ったファイルを指したりします。絶対パスがわからない場合は、ユーザーに尋ねるか、先にファイルを探してください。
2. ユーザーが正確でスペルも正しいと確信できる名前を指定していない限り、lookup_card より resolve_card を優先してください。 迷ったら、resolve_card のほうが確実に柔軟で、追加コストもかかりません。
3. 価格検索を独自に実装しないでください。 find_song_synergies、what_am_i_missing、build_deck はすでに内部で tcgcsv.com を呼び出し、24 時間キャッシュと最安印刷版の判定を利用しています。自分で TCGPlayer に curl したり、価格をスクレイピングしたりしないでください。
4. ゲームプレイ上の内容は、どの印刷版でも同じです（通常版、Enchanted、Epic、プロモで、名前、コスト、ステータス、能力は同一です）。価格に対応したツールは、すでに最安の印刷版を自動で選ぶため、疑わしいほど安い結果を疑ったり、レアリティをゲームプレイ上の指標として扱ったりしないでください。ユーザーが印刷版ごとの内訳（フォーマットで使用できるもの、最安のもの、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）です。 外部の価格 API（LorcanaJSON の externalLinks.tcgPlayerId、tcgcsv.com の productId）と一致するのは Product ID のみです。列 2 は無関係な副次的 ID です。このデータを使った独自コードを作成する場合、列 2 で照合すると結果が何も返らず、エラーも通知されません。
• プロモカードは PROMO_DREAMBORN_ROW／PROMO_DREAMBORN_ROW_BY_NUMBER（api.py）を通じて解決されます。 これはカードブラウザーの表示ではなく、実際の dreamborn.ink エクスポートで検証済みです（以前、ブラウザー表示を基に推測した結果、実際のインポートが気づかれないまま破損しました。CHANGELOG.md 0.2.2）。プロモの 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 で更新できます）。
• リリース時には、4つのファイル（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 やレジストリに公開されたと思い込まないでください。機能が「利用可能」だとユーザーに伝える前に確認してください。