hearthstone-oracle

Instructions

Implementation Reference

• src/tools/decode-deck.ts:83-167 (handler)

  The handler function that executes the decode_deck tool logic.

  export function decodeDeck(
    db: Database.Database,
    input: DecodeDeckInputType,
  ): DecodeDeckResult {
    let decoded: { cards: Array<[number, number]>; heroes: number[]; format: number };
  
    try {
      decoded = decode(input.deck_code);
    } catch (err) {
      return {
        success: false,
        message: `Invalid deck code: ${err instanceof Error ? err.message : String(err)}`,
      };
    }
  
    // Format
    const format = decoded.format === 1 ? 'Wild' : 'Standard';
  
    // Hero class — try to look up hero in DB first, then fall back to map
    let heroClass = 'UNKNOWN';
    if (decoded.heroes.length > 0) {
      const heroDbfId = decoded.heroes[0];
      // Try DB lookup
      const heroRow = db
        .prepare('SELECT player_class FROM cards WHERE id = ?')
        .get(String(heroDbfId)) as { player_class: string | null } | undefined;
  
      if (heroRow?.player_class) {
        heroClass = heroRow.player_class;
      } else if (HERO_CLASS_MAP[heroDbfId]) {
        heroClass = HERO_CLASS_MAP[heroDbfId];
      }
    }
  
    // Cards
    const cards: Array<{ card: CardSummary; count: number }> = [];
    const manaCurve: Record<string, number> = {};
    const typeDistribution: Record<string, number> = {};
    let totalCards = 0;
  
    for (const [dbfId, count] of decoded.cards) {
      const row = db
        .prepare('SELECT * FROM cards WHERE id = ?')
        .get(String(dbfId)) as CardRow | undefined;
  
      let cardSummary: CardSummary;
      if (row) {
        cardSummary = toCardSummary(row);
      } else {
        // Unknown card — create placeholder
        cardSummary = {
          name: `Unknown Card (${dbfId})`,
          mana_cost: null,
          type: null,
          player_class: null,
          rarity: null,
          text: null,
          attack: null,
          health: null,
          keywords: [],
        };
      }
  
      cards.push({ card: cardSummary, count });
      totalCards += count;
  
      // Mana curve
      const bucket = manaCurveBucket(cardSummary.mana_cost);
      manaCurve[bucket] = (manaCurve[bucket] ?? 0) + count;
  
      // Type distribution
      const cardType = cardSummary.type ?? 'UNKNOWN';
      typeDistribution[cardType] = (typeDistribution[cardType] ?? 0) + count;
    }
  
    return {
      success: true,
      format,
      hero_class: heroClass,
      cards,
      total_cards: totalCards,
      mana_curve: manaCurve,
      type_distribution: typeDistribution,
    };
  }

• src/tools/decode-deck.ts:9-13 (schema)

  Input validation schema for the decode_deck tool.

  export const DecodeDeckInput = z.object({
    deck_code: z.string().describe('Hearthstone deck code (base64 deckstring)'),
  });
  
  export type DecodeDeckInputType = z.infer<typeof DecodeDeckInput>;

• src/server.ts:137-147 (registration)

  Registration of the decode_deck tool in the server.

  // 4. decode_deck
  server.tool(
    'decode_deck',
    'Decode a Hearthstone deck code into its full card list with mana curve and card type breakdown. Use this when a user shares a deck code and wants to see what\'s in it.',
    DecodeDeckInput.shape,
    async (params) => {
      try {
        const result = decodeDeck(db, params);
        return {
          content: [
            { type: 'text' as const, text: formatDecodeDeck(result) },