hearthstone-oracle

Instructions

Implementation Reference

• src/tools/get-matchup.ts:31-72 (handler)

  The implementation of the get_matchup tool logic.

  export function getMatchup(
    db: Database.Database,
    input: GetMatchupInputType,
  ): GetMatchupResult {
    // Check both orderings since the table stores one direction
    const row = db
      .prepare(
        `SELECT * FROM matchup_framework WHERE
          (LOWER(archetype_a) = LOWER(?) AND LOWER(archetype_b) = LOWER(?))
          OR
          (LOWER(archetype_a) = LOWER(?) AND LOWER(archetype_b) = LOWER(?))`,
      )
      .get(input.archetype_a, input.archetype_b, input.archetype_b, input.archetype_a) as MatchupInfo | undefined;
  
    if (row) {
      return {
        found: true,
        matchup: {
          archetype_a: row.archetype_a,
          archetype_b: row.archetype_b,
          favoured: row.favoured,
          reasoning: row.reasoning,
          key_tension: row.key_tension,
          archetype_a_priority: row.archetype_a_priority,
          archetype_b_priority: row.archetype_b_priority,
        },
      };
    }
  
    // Not found — suggest available archetypes
    const archetypes = db
      .prepare('SELECT DISTINCT archetype_a FROM matchup_framework UNION SELECT DISTINCT archetype_b FROM matchup_framework')
      .all() as Array<{ archetype_a: string }>;
  
    const availableNames = archetypes.map((a) => a.archetype_a);
  
    return {
      found: false,
      message: `No matchup found for "${input.archetype_a}" vs "${input.archetype_b}".`,
      suggestions: availableNames.length > 0 ? availableNames : undefined,
    };
  }

• src/tools/get-matchup.ts:6-9 (schema)

  Input validation schema for get_matchup.

  export const GetMatchupInput = z.object({
    archetype_a: z.string().describe('First archetype name (e.g. "aggro", "control")'),
    archetype_b: z.string().describe('Second archetype name (e.g. "combo", "midrange")'),
  });

• src/server.ts:248-273 (registration)

  Registration of the get_matchup tool within the MCP server.

  // 8. get_matchup
  server.tool(
    'get_matchup',
    'Get the theoretical matchup dynamics between two Hearthstone archetypes. Explains who is favoured, why, the key strategic tension, and what each side should prioritise.',
    GetMatchupInput.shape,
    async (params) => {
      try {
        const result = getMatchup(db, params);
        return {
          content: [
            { type: 'text' as const, text: formatGetMatchup(result) },
          ],
        };
      } catch (err) {
        return {
          content: [
            {
              type: 'text' as const,
              text: `Error: ${err instanceof Error ? err.message : String(err)}`,
            },
          ],
          isError: true,
        };
      }
    },
  );