Analyze a raw deck list (a list of card names, not a collection CSV) and return its ink curve, composition, and Core Constructed legality — the tool for "is this decklist actually good/legal", independent of what you own or can afford.

Accepts one card per line, e.g. "4x Goofy - Musketeer" or "4 Goofy - Musketeer" (both "4x" and "4 " are accepted; qty is optional and defaults to 1). Lines starting with "#" or "//" are treated as comments and skipped.

Reports: ink curve (1-2/3-4/5-6/7+ cost brackets), inkable vs. uninkable count, color split, card type split, an estimated lore-per-turn (sum of Character lore values), a Core Constructed legality check (60-card minimum, max 4 copies of any card, at most 2 ink colors), and any card names that couldn't be resolved.

Behavior: card names are matched the same simple way as lookup_card (exact, then substring) — not fuzzy-resolved like resolve_card — so a typo'd or oddly-abbreviated name lands in the unresolved list rather than being guessed. Unresolved lines are excluded from every stat (curve, color split, lore/turn, legality counts), so a deck list with several unresolved names will under-report its true totals; always check that list before trusting the numbers. The legality check is Core Constructed only — it does not check rotation-group safety (whether the deck's cards survive the next rotation) or Infinity/Poorcana rules; for rotation safety, cross-reference the card list against search_cards filtered by set, or build fresh via build_deck(rotation_safe=True).

Usage guidelines: use this on a decklist you already have — hand-written, pasted from elsewhere, or build_deck's output — to sanity-check curve and legality before playtesting or buying anything. It never touches your collection, so it can't tell you what's missing or what it costs; for that, feed the same deck list to what_am_i_missing instead.

Args: deck_list: Raw deck list text, one card per line.

Audit an already-enriched Lorcana collection CSV against live API data and report exactly which fields drifted from the current source of truth — a correctness check on data already in the CSV, not a re-enrichment.

Checks Ink color, Ink Cost, Card Type, Subtypes, Inkable, and stats (Strength / Willpower / Lore Points) for every non-promo card, one live API call per unique card. Promo rows are always skipped entirely (counted separately as "promos skipped") since there's no reliable live source to diff a promo printing against. Ability/Keyword text is not checked — only the structured fields above.

Behavior: reports every field-level mismatch as "csv_value" → "api_value", grouped by card. One known, harmless false-positive class: Subtypes differences that are purely separator/ordering (e.g. "Storyborn/Ally/Toy" vs "Storyborn, Ally, Toy") — same data, different formatting convention, most common in newer sets. Skim for those before treating every reported line as a real error. A completely clean CSV returns a one-line "no discrepancies found" summary instead of an empty list.

Usage guidelines: run this after a new set releases, after any manual CSV edits, or whenever enrichment output looks suspicious — not as a routine step after every enrich_csv call, since it re-fetches from the live API per unique card and adds real latency on a large collection. If it turns up genuine (non-Subtypes-formatting) discrepancies, the fix is to re-run enrich_csv, not to hand-edit the CSV — this tool only reports drift, it does not write any changes back to the file.

Args: csv_path: Absolute path to an enriched Lorcana collection CSV.

Automatically assemble a legal, curve-balanced ~60-card decklist for an ink pair and format, in one of 3 modes:

• "collection": build only from cards you own (capped at owned quantity per card). If fewer than 60 legal owned cards exist, reports the shortfall honestly instead of padding with irrelevant fillers.

• "ideal": build the best deck regardless of ownership. If collection_csv is given, also shows what you already own, what's missing, and the price to complete it (via tcgcsv.com).

• "market": build the best deck ignoring any collection, and prices every card in it (not just the gap) via tcgcsv.com.

This is a heuristic curve/keyword-value builder — it optimizes ink curve, stat efficiency, and keyword value, not multi-card combos or synergy packages. See the disclaimer at the bottom of every result.

format="coconut" builds for Format Coconut (Ravensburger's multiplayer singleton beta, open since 2026-07-28 — rules/card pool may still change; see the project CLAUDE.md's "Format Coconut" section). It needs coconut_card, allows up to 3 ink colors (one must match the Coconut's own ink), has no rotation and no tracked banned list (every released card is treated as legal), and every card in the build is capped at 1 copy except the Coconut's associated real character, which may run up to 4 — this replaces the usual max-4-of-anything rule entirely. Call with format="coconut" and no coconut_card to get the full list of the 18 beta Coconuts to choose from.

Args: ink_colors: Comma-separated ink color(s), e.g. "Amber,Sapphire". 1-2 colors for core/core_zh/core_ja/poorcana, 1-6 for infinity, 1-3 for coconut (must include the Coconut card's own ink — see coconut_card). May be omitted entirely when format="coconut" and coconut_card is also omitted — that combination just lists the 18 beta Coconut cards (filtered to the given ink(s), if any) and doesn't build anything yet. mode: "collection", "ideal", or "market". format: "core", "infinity", "core_zh", "core_ja", "poorcana", or "coconut". collection_csv: Absolute path to an enriched collection CSV. Required for mode="collection"; optional for "ideal"; ignored for "market". rotation_safe: If True and format="core", restrict to the rotation group that will still be legal after the next rotation event. No-op (with a note) for other formats. coconut_card: Required when format="coconut" — fuzzy name of one of the 18 beta Coconut cards (e.g. "Ariel", "Mickey Mouse", "snow white"). Ignored for every other format. include_preview: If True and format is "core" or "infinity", also admit cards from announced sets that aren't legal yet (e.g. Hyperia City before its release date) — whatever LorcanaJSON has revealed so far, which may be a partial set. Preview cards are marked in the decklist and usually have no TCGPlayer price yet. No-op (with a note) for other formats. theme: Optional deck theme — a classification ("princess", "detective", "seven dwarfs", "villain", ...) or a character name ("mickey mouse", "stitch"). Cards of that classification/ name, and cards whose text references it (payoffs like "your Princess characters get +1 ¤"), are strongly preferred. If ink_colors is omitted, the two-ink pair with the most theme cards in the legal pool is chosen automatically (not for coconut, which needs its Coconut's ink).

Build the best 40-card Sealed (prerelease) deck from a player's opened card pool — for prerelease events, where everyone opens 6 booster packs (~72 cards) on-site and has ~45 minutes to build.

Sealed rules applied: 40-card minimum; NO ink-color limit; NO copy limit (every copy you opened is playable, even 5+); the stamped prerelease promo is allowed; unused cards are the sideboard (swappable between games). No format-legality or rotation check — the set doesn't need to be released yet.

Strategy: ranks every two-ink pair by pool depth and builds around the best one (or ink_colors), splashing a third/fourth ink only when the core pair can't reach 40 on its own — common from 6 packs. Ink is colorless in Lorcana, so a splash costs synergy, not consistency.

Input — pool is one card per line, quantity optional ("2x Card Name", "2 Card Name", or just "Card Name"; repeats are summed). Each line can be:

• a card name, informal or misspelled is fine ("mickey best in town");

• the collector number printed at the card's bottom ("123", "123/204", "123/204 EN 14") — matched within set_name.

If the user sends a PHOTO of their pool: read every visible card from the image and pass one line per card. Prefer the collector number when it's legible (most reliable); otherwise the name + subtitle. Count duplicates. Then tell the user which cards came back ambiguous/unrecognized so they can confirm, and re-call with corrected lines.

Output: ink-pair ranking, the 40-card list by cost, splash notes, stats (curve, inkable count, lore), the strongest sideboard cards, and any ambiguous/unrecognized lines (excluded from the build — never guessed). Heuristic curve/keyword-value scoring with Shift-chain awareness, not a full synergy engine: review the list before sleeving it.

Args: pool: The opened cards, one per line (names and/or collector numbers). ink_colors: Optional comma-separated core inks to force, e.g. "Amber,Steel" (any number allowed in Sealed). Empty = auto-pick the deepest pair. set_name: The prerelease set, used to scope name matching and to read collector numbers. Default "Hyperia City" (Set 14).

Enrich a raw TCGPlayer Lorcana CSV export with full card data — the required first step before any other tool here can read your collection (filter_collection, audit_csv, what_am_i_missing, build_deck, and find_song_synergies's collection_csv all expect this tool's output, not the raw TCGPlayer export).

Fetches card data from LorcanaJSON (sets 12+) and lorcana-api.com (sets 1–11) and adds Ink color, Ink Cost, Card Type, Subtypes, Strength, Willpower, Lore Points, Inkable, Keywords, and Abilities to each row. Both sources are disk-cached 24h, so a second run soon after the first is fast regardless of cache_path.

Behavior: writes two new files next to the input — never modifies input_path itself — and always reports fill-rate stats per column plus any cards it couldn't match (usually a name typo in the export, or a brand-new card the APIs haven't indexed yet). Promo cards (Set Name "Disney Lorcana Promo Cards") are matched by name against their non-promo equivalent for stats, and separately resolved to a dreamborn.ink-importable (Set Number, Card Number) row when this server's built-in promo table covers that card; promos it doesn't recognize are listed for manual entry rather than guessed. cache_path only skips re-fetching for card names already present in that prior enriched CSV — it does not skip enrichment for new cards in the input.

Writes two output files next to the input: enriched_{filename} — enriched collection CSV dreamborn_{filename} — import-ready CSV for dreamborn.ink

Usage guidelines: run this on every fresh TCGPlayer export before doing anything else with it. Pass cache_path pointing at your previous enriched CSV on a re-export to speed things up — otherwise every row re-fetches from the API even for cards you've already enriched before. Use refresh_prices=True specifically to bring an existing enriched CSV's prices current without a fresh TCGPlayer export (it only touches the price column, not the card-data columns); leave it off for a same-day fresh export, since the TCGPlayer download already has current prices and refreshing adds an extra tcgcsv.com call per row.

Args: input_path: Absolute path to the raw TCGPlayer CSV export. cache_path: Optional path to a previous enriched CSV to speed up re-runs by skipping API calls for cards already seen. refresh_prices: If True, overwrite each row's TCG Market Price with a live tcgcsv.com lookup for that exact printing, instead of leaving whatever the raw TCGPlayer export had at download time. Use this to bring an old enriched CSV's prices current without re-exporting from TCGPlayer.

Filter an enriched collection CSV down to the cards you own that are legal in a specific play format — answers "which of my cards can I actually play in format X", grouped by ink color with owned quantities.

Legality data comes from a live duels.ink fetch, which tracks Core EN, Infinity, Core ZH, and Core JA rotation. Poorcana (Common/Uncommon only, 50-card min) is the one exception: it's derived purely from the CSV's own Rarity column, no external lookup, so it still works offline and always reflects the CSV's rarity data exactly.

Behavior: promo rows (Set Name == "Disney Lorcana Promo Cards") are always excluded from Core/Infinity/regional results, not flagged as illegal — duels.ink's legality table is keyed by (set, number) and promos don't map onto that cleanly (see "Promo cards" in the reference doc). Any other row duels.ink doesn't recognize (usually a card from a set duels.ink hasn't indexed yet) is silently skipped and counted in a "rows skipped" footer — that's a data-lag note, not a legality verdict, so don't read a skipped row as "illegal". Requires the enriched CSV's columns (Set Name, Number, Ink, Ink Cost, Add to Quantity, etc.) — running this against the raw TCGPlayer export (pre-enrich_csv) will silently undercount or return nothing useful.

Usage guidelines: run this when you want to see your full legal card pool for a format before hand-building a deck, or to sanity-check whether a deck idea is even feasible with what you own. If you want a finished decklist rather than just the eligible pool, use build_deck with mode="collection" instead — it already applies this same legality filter internally as part of assembling a curve-balanced list, so you don't need to call both.

Args: csv_path: Absolute path to an enriched Lorcana collection CSV. format: "core", "infinity", "core_zh", "core_ja", or "poorcana".

Find every Character that can sing a given song — the tool for building or checking a Singer/song combo (e.g. the Amber/Steel Steelsong package), not for general card search (use search_cards for that).

A character can sing a song if its printed ink cost meets the song's cost outright, OR it has a "Singer X" keyword with X meeting the song's cost — Singer lets a cheap character punch above its actual cost for singing purposes only (see the Steelsong package: Amber Singers unlocking expensive Steel songs for free). Provide either song_name (resolved the same fuzzy way as resolve_card, so "beauty and beast" or a slight typo still works) or a raw cost threshold — exactly one is required; passing neither, or both, returns an error message instead of guessing.

Results are grouped: Singer-keyword characters first (the actual "discount" picks — highest Singer value, then cheapest actual cost), followed by characters that simply cost enough to sing it outright, cheapest first. This only tells you who can sing — it doesn't check whether that character is otherwise good (stats, other abilities) or whether you own enough copies to make the combo consistent unless you pass collection_csv, in which case each result is annotated with owned quantity so you can see the combo's real consistency at a glance.

Args: song_name: Name of a Song card, e.g. "Be Our Guest". Fuzzy-matched. cost: Raw song cost threshold to use instead of song_name, e.g. 5. colors: Optional comma-separated ink color(s) to restrict characters to, e.g. "Amber,Steel". collection_csv: Optional path to an enriched collection CSV — when given, each character is flagged with how many copies you own. limit: Max characters to list (default 50, capped at 200).

Return a hand-maintained Core Constructed metagame snapshot: a tier list of every two-ink pair (archetype name, tier, rough meta share, playstyle) plus a summary of recent notable tournament results — for answering "what's strong right now" or "how does my ink pair compare". With event set, returns that tournament's full standings and decklists instead.

Unlike every other tool here, this is NOT a live fetch. There is no free, structured feed for competitive metagame share or tournament decklists — inkDecks.com and lorcana.gg publish this as HTML, and tournament results circulate as social-media images, not an API. This tool instead returns a versioned snapshot bundled into the package at release time (see lorcana_mcp/meta.py / tournaments.py and the CHANGELOG for when it was last refreshed). The response states its own snapshot date and sources up front, and flags which rows have actually been checked against a real recent tournament result versus older, unverified metagame-tracker data — don't treat an old row's tier/meta-share as more current than it is. Tournament decklists are transcribed from card-grid images: counts/art are reliable, but a few 1-of tech slots and some subtitles are best-effort (per-list notes flag where).

Usage guidelines: reach for this when a player asks what's currently good, whether a given ink pair is competitive, or wants context before calling build_deck. For a specific event's lists, pass event (the plain snapshot output lists which events are available). It complements build_deck/analyze_deck, which build or evaluate one concrete deck.

Args: ink_colors: Optional pair of ink colors to filter to one tier-list row, comma- or slash-separated, e.g. "Emerald,Steel" or "Amber/Sapphire" (order doesn't matter). Ignored if event is set. event: Optional tournament key or name fragment (e.g. "nac", "kobe", "asia-championship-2026") to get that event's full standings + decklists instead of the tier list.

List every printed version of a Lorcana card — or every card sharing a character name — side by side: each one's set, card number(s), cost, stats, rarity, per-format legality, and the cheapest market price to acquire it.

Reach for this whenever the answer depends on which printing: "is any Milo Thatch legal in Core?", "which Elsa is cheapest?", "did this card ever get an Enchanted?", "what's the current-set version vs. the rotated-out one?". lookup_card silently collapses to just the newest printing; this shows them all.

Matching, in order: exact full name ("Elsa - Spirit of Winter"); exact character name ("Elsa" → every distinct Elsa card); full-name substring; then a fuzzy resolve. A bare character name lists every subtitle; a full name lists that one card's base + Enchanted/Epic printings. Enchanted and Epic printings are gameplay-identical to the base — they only change the number, rarity, and price, which is exactly what this tool compares.

fmt (optional): one of core, infinity, core_ja, core_zh, poorcana, coconut. When given, adds a legality column for just that format and lists legal cards first. Legality/images come from duels.ink and prices from tcgcsv.com (a daily TCGPlayer mirror); both are fetched live, cached 24h, and shown as "?" / omitted (never errored) when unavailable.

Args: name: A card's full name, or a bare character name. fmt: Optional play format to flag legality for.

Look up one specific, already-known Lorcana card by (near-)exact name and return its full stats, abilities, and format legality in one call.

Behavior: tries an exact name match against LorcanaJSON first, then falls back to a plain substring match — this is simple matching, not fuzzy scoring. If the same card name exists across multiple sets/printings and set_name isn't given, it silently returns the most recent printing rather than listing the alternatives (Enchanted/Epic/promo variants are gameplay-identical to the base card either way, so this rarely matters for stats — but a specific older printing's card ID/legality nuance won't surface without set_name). Card data (LorcanaJSON + duels.ink) is fetched live and cached on disk for 24h — see lorcana-mcp cache stats / cache clear if you suspect stale data right after a new set drops.

Usage guidelines: reach for this first when you already have a specific printed card name (even with the subtitle omitted, e.g. "Mirage") — it's the cheapest, most precise lookup. If it returns "no card found" for a name you're unsure is spelled/formatted correctly (informal phrasing, missing dashes, a likely typo, or a bare first name meant to cover several printings), retry with resolve_card instead, which fuzzy-matches and will disambiguate multiple candidates rather than failing outright. For browsing/filtering many cards by criteria instead of one known name, use search_cards.

Args: name: Card name, e.g. "Mirage - Super Recruiter" or just "Mirage". set_name: Optional set name to narrow the search, e.g. "Wilds Unknown".

Resolve an informal, misspelled, or subtitle-less card name to specific card(s).

Unlike lookup_card's simple substring match, this tokenizes the query and scores it against every card's name and subtitle, tolerating missing dashes ("goofy musketeer"), missing subtitles ("Elsa" — which returns all her versions), word order, and minor typos ("musketer"). Use this when lookup_card fails or when you're not sure of a card's exact printed name.

Returns one of three shapes:

• A single confident match: full card detail (same as lookup_card).

• Multiple plausible matches: a ranked top-3 list with confidence scores, for you to disambiguate (e.g. "Pete" with no further qualifier, or a bare character name matching several printings).

• No match: nothing scored above the noise floor.

Args: name: Informal, partial, or misspelled card name. set_name: Optional set name to narrow the search, e.g. "Wilds Unknown".

Search the full Lorcana card pool (all sets, every printed card) by any combination of filters — not your collection. This is a discovery tool for "what cards fit X criteria", independent of what you own or have priced.

All filters are optional and ANDed together, except colors: a card matches if it has ANY of the given colors, so dual-ink cards surface for either half. Calling with no filters at all returns the entire card pool, paginated.

Behavior: always fetches from a live, in-process-cached copy of LorcanaJSON (see the "Card data APIs" reference) — never reads a local CSV, so results always include the newest released set. A card that has no Strength/Willpower/Lore (Action, Item, Location) shows "—" for those stats rather than being excluded. Results are grouped and displayed by ink color, then returned as one or more Markdown tables; when more results exist than limit, the response tells you the exact offset to pass next — call again with that offset rather than guessing pages.

Usage guidelines: use this to browse/filter by criteria (e.g. "every Evasive Sapphire character costing 3 or less") — if you already have a specific (possibly misspelled or subtitle-less) card name in mind, use resolve_card or lookup_card instead, they're cheaper and more precise for a single known card. Results carry no ownership or price information; to check what you already own, cross-reference the card names against an enriched collection CSV yourself, or use what_am_i_missing / find_song_synergies's collection_csv param for tools that do that automatically. To narrow to a specific play format's legal pool, combine with set_name, or post-filter the result against filter_collection's format logic.

Args: colors: Comma-separated ink color(s), e.g. "Amber,Steel". Case-insensitive. card_type: "Character", "Action", "Item", "Location", or "Song" (Action cards with the Song subtype). rarity: "Common", "Uncommon", "Rare", "Super Rare", "Legendary", "Enchanted", "Epic", "Iconic", or "Special". set_name: Set name substring, e.g. "Wilds Unknown". cost_min: Minimum ink cost, inclusive. Pass -1 (default) for no minimum. cost_max: Maximum ink cost, inclusive. Pass -1 (default) for no maximum. keyword: Keyword ability name, e.g. "Evasive", "Rush", "Bodyguard", "Shift". ability_text: Substring to search for in full ability text (case-insensitive). subtype: Subtype/classification, e.g. "Toy", "Hero", "Villain", "Princess". offset: Pagination offset, 0-based. limit: Max results in this page (default 25, capped at 200).

Compare a deck list against your collection: what you already own, what's missing or short, and the estimated cost to complete it — the shopping-list counterpart to analyze_deck, which checks curve/legality but never looks at ownership.

Cross-references a raw deck list (same format as analyze_deck: 4x Card Name per line) against an enriched collection CSV. Card names are matched the same simple exact-then-substring way as lookup_card (not fuzzy like resolve_card); a name that doesn't resolve is dropped from the "Already have"/"Missing" tallies and listed separately under an "unresolved" section instead of being silently skipped — check that section if the totals look short. For every card you're short on, price comes first from the CSV's own TCG Market Price if you already own at least one printing (no network needed); only cards you own zero copies of fall back to a live TCGPlayer lookup via tcgcsv.com for the cheapest printing across all sets/rarities (gameplay is identical regardless of rarity or art). That fallback fetch only fires if at least one card actually needs it, and its price data is cached 24h — the reported total is always a snapshot, not a quote.

Usage guidelines: use this once you have a specific decklist in hand (hand-written, or build_deck's output) and want to know what to buy or borrow before playtesting it. It doesn't check Core Constructed legality or curve — run analyze_deck on the same list for that. If instead you want a deck built around what you can realistically complete rather than checking a fixed list, use build_deck(mode="ideal"), which folds this same ownership/pricing logic into deck construction itself.

Args: deck_list: Raw deck list text, one card per line (e.g. "4x Goofy - Musketeer"). collection_csv: Absolute path to an enriched Lorcana collection CSV.