mtg-oracle

Instructions

Implementation Reference

• src/tools/analyze-deck.ts:206-411 (handler)

  The main handler function that executes deck analysis by parsing the deck list, looking up cards in the database, computing mana curves, color distribution, type breakdown, mana base analysis, and format legality checks.

  export function handler(db: Database.Database, params: AnalyzeDeckParams): AnalyzeDeckResult {
    // 1. Parse the deck list
    let parsed: ParsedDeck;
    try {
      parsed = parseDeckList(params.deck_list);
    } catch (err) {
      return {
        success: false,
        message: `Failed to parse deck list: ${err instanceof Error ? err.message : String(err)}`,
      };
    }
  
    const allEntries = [...parsed.main, ...parsed.sideboard];
    if (allEntries.length === 0) {
      return { success: false, message: 'Deck list is empty — no cards found.' };
    }
  
    // 2. Look up each card
    const resolved: ResolvedCard[] = [];
    const notFound: CardNotFound[] = [];
  
    for (const entry of allEntries) {
      const result = lookupCard(db, entry.name);
      if (result.card) {
        resolved.push({ entry, card: result.card });
      } else {
        notFound.push({
          name: entry.name,
          suggestion: result.suggestion,
        });
      }
    }
  
    // Also resolve main-only for analysis (sideboard excluded from curve/type/color)
    const mainEntries = parsed.main;
    const resolvedMain: ResolvedCard[] = [];
    for (const entry of mainEntries) {
      const result = lookupCard(db, entry.name);
      if (result.card) {
        resolvedMain.push({ entry, card: result.card });
      }
    }
  
    // 3. Compute mana curve (main deck non-land cards only)
    const cmcBuckets: Record<string, number> = {};
    for (let i = 0; i <= 6; i++) cmcBuckets[String(i)] = 0;
    cmcBuckets['7+'] = 0;
  
    for (const { entry, card } of resolvedMain) {
      if (classifyType(getTypeLine(card)) === 'Land') continue;
      const cmc = card.cmc ?? 0;
      const key = cmc >= 7 ? '7+' : String(Math.floor(cmc));
      cmcBuckets[key] = (cmcBuckets[key] ?? 0) + entry.count;
    }
  
    const mana_curve: ManaCurveEntry[] = Object.entries(cmcBuckets).map(([cmc, count]) => ({
      cmc,
      count,
    }));
  
    // 4. Color distribution (main deck)
    const colorCounts: Record<string, number> = { W: 0, U: 0, B: 0, R: 0, G: 0, Colorless: 0 };
    for (const { entry, card } of resolvedMain) {
      const colors = extractColors(card);
      if (colors.length === 0) {
        colorCounts['Colorless'] += entry.count;
      } else {
        for (const c of colors) {
          colorCounts[c] = (colorCounts[c] ?? 0) + entry.count;
        }
      }
    }
  
    const color_distribution: ColorCount[] = Object.entries(colorCounts)
      .map(([color, count]) => ({
        color: COLOR_NAMES[color] ?? color,
        count,
      }));
  
    // 5. Type breakdown (main deck)
    const typeCounts: Record<string, number> = {};
    for (const type of [...TYPE_CATEGORIES, 'Other']) typeCounts[type] = 0;
  
    for (const { entry, card } of resolvedMain) {
      const type = classifyType(getTypeLine(card));
      typeCounts[type] = (typeCounts[type] ?? 0) + entry.count;
    }
  
    const type_breakdown: TypeCount[] = Object.entries(typeCounts)
      .filter(([, count]) => count > 0)
      .map(([type, count]) => ({ type, count }));
  
    // 6. Mana base analysis (main deck)
    const landCount = typeCounts['Land'] ?? 0;
    const mainCardCount = mainEntries.reduce((sum, e) => sum + e.count, 0);
    const landPercentage = mainCardCount > 0 ? (landCount / mainCardCount) * 100 : 0;
  
    // Color sources from lands
    const colorSources: Record<string, number> = {};
    for (const { entry, card } of resolvedMain) {
      if (classifyType(getTypeLine(card)) !== 'Land') continue;
      const producedColors = countColorSources(
        getTypeLine(card),
        card.oracle_text,
        extractColors(card),
      );
      for (const c of producedColors) {
        colorSources[c] = (colorSources[c] ?? 0) + entry.count;
      }
    }
  
    // Color requirements from mana costs
    const colorRequirements: Record<string, number> = {};
    for (const { entry, card } of resolvedMain) {
      const reqs = extractColorRequirements(card.mana_cost);
      for (const [c, n] of Object.entries(reqs)) {
        colorRequirements[c] = (colorRequirements[c] ?? 0) + (n * entry.count);
      }
    }
  
    // Unique colors in the deck
    const uniqueColors = new Set<string>();
    for (const { card } of resolvedMain) {
      for (const c of extractColors(card)) {
        uniqueColors.add(c);
      }
    }
  
    const format = params.format ?? (parsed.format_hint === 'commander' ? 'commander' : undefined);
    const recommendedLands = getRecommendedLands(mainCardCount, uniqueColors.size, format);
  
    const warnings: string[] = [];
    if (recommendedLands !== null) {
      const diff = landCount - recommendedLands;
      if (diff < -3) {
        warnings.push(`Land count (${landCount}) is ${Math.abs(diff)} below the recommended ${recommendedLands} for a ${mainCardCount}-card deck.`);
      } else if (diff > 3) {
        warnings.push(`Land count (${landCount}) is ${diff} above the recommended ${recommendedLands} for a ${mainCardCount}-card deck.`);
      }
    }
  
    // Check color source coverage
    for (const [color, reqCount] of Object.entries(colorRequirements)) {
      const sourceCount = colorSources[color] ?? 0;
      if (sourceCount < 8 && reqCount > 5) {
        const colorName = COLOR_NAMES[color] ?? color;
        warnings.push(`Low ${colorName} sources (${sourceCount}) for ${reqCount} ${colorName} pips in mana costs. Consider adding more ${colorName} sources.`);
      }
    }
  
    const mana_base: ManaBaseAnalysis = {
      land_count: landCount,
      land_percentage: Math.round(landPercentage * 10) / 10,
      recommended_lands: recommendedLands,
      color_sources: colorSources,
      color_requirements: colorRequirements,
      warnings,
    };
  
    // 7. Format legality check
    let format_legality: DeckAnalysis['format_legality'];
    if (params.format) {
      const illegalCards: Array<{ name: string; status: string }> = [];
      const checkedNames = new Set<string>();
  
      for (const { card } of resolved) {
        if (checkedNames.has(card.name)) continue;
        checkedNames.add(card.name);
  
        const legalities = db.prepare(
          'SELECT * FROM legalities WHERE card_id = ? AND LOWER(format) = LOWER(?)'
        ).get(card.id, params.format) as LegalityRow | undefined;
  
        if (!legalities) {
          illegalCards.push({ name: card.name, status: 'not_legal' });
        } else if (legalities.status !== 'legal') {
          illegalCards.push({ name: card.name, status: legalities.status });
        }
      }
  
      format_legality = {
        format: params.format,
        all_legal: illegalCards.length === 0,
        illegal_cards: illegalCards,
      };
    }
  
    // 8. Assemble result
    const sideboardCount = parsed.sideboard.reduce((sum, e) => sum + e.count, 0);
  
    const analysis: DeckAnalysis = {
      main_count: mainCardCount,
      sideboard_count: sideboardCount,
      commander: parsed.commander,
      format_hint: parsed.format_hint,
      mana_curve,
      color_distribution,
      type_breakdown,
      mana_base,
      format_legality,
      cards_not_found: notFound,
    };
  
    return { success: true, analysis };
  }

• src/tools/analyze-deck.ts:9-12 (schema)

  The Zod schema defining the input parameters for the 'analyze_deck' tool.

  export const AnalyzeDeckInput = z.object({
    deck_list: z.string().describe('The deck list in plain text or MTGO .dek XML format'),
    format: z.string().optional().describe('Format to check legality against (e.g., "modern", "commander", "standard")'),
  });

• src/server.ts:281-287 (registration)

  Registration of the 'analyze_deck' tool in the server implementation, connecting the tool name, schema, and handler.

  'analyze_deck',
  'Analyze a Magic: The Gathering deck list. Paste a deck list (plain text format like \'4 Lightning Bolt\' per line, or MTGO .dek XML) and get mana curve, color distribution, type breakdown, mana base analysis, and format legality check. Use this when a user shares a deck list and wants feedback.',
  AnalyzeDeckInput.shape,
  async (params) => {
    try {
      const result = analyzeDeckHandler(db, params);
      return { content: [{ type: 'text' as const, text: formatAnalyzeDeck(result) }] };