hearthstone-oracle

Instructions

Implementation Reference

• src/tools/get-card.ts:55-90 (handler)

  The main handler function for the get_card tool. It performs database lookups (exact then fuzzy) and returns card details or suggestions.

  export function getCard(
    db: Database.Database,
    input: GetCardInputType,
  ): GetCardResult {
    // 1. Exact match (case-insensitive)
    const exact = db
      .prepare('SELECT * FROM cards WHERE LOWER(name) = LOWER(?)')
      .get(input.name) as CardRow | undefined;
  
    if (exact) {
      return { found: true, card: toCardDetail(exact) };
    }
  
    // 2. Fuzzy match via LIKE
    const fuzzy = db
      .prepare('SELECT * FROM cards WHERE LOWER(name) LIKE LOWER(?)')
      .get(`%${input.name}%`) as CardRow | undefined;
  
    if (fuzzy) {
      return { found: true, card: toCardDetail(fuzzy) };
    }
  
    // 3. Not found — provide suggestions based on first word
    const firstWord = input.name.split(/\s+/)[0];
    const suggestions = db
      .prepare('SELECT name FROM cards WHERE LOWER(name) LIKE LOWER(?) LIMIT 5')
      .all(`%${firstWord}%`) as Array<{ name: string }>;
  
    const suggestionNames = suggestions.map((s) => s.name);
  
    return {
      found: false,
      message: `No card found matching "${input.name}".`,
      suggestions: suggestionNames.length > 0 ? suggestionNames : undefined,
    };
  }

• src/tools/get-card.ts:8-10 (schema)

  Input schema for the get_card tool, requiring a name string.

  export const GetCardInput = z.object({
    name: z.string().describe('Card name to look up (exact or partial match)'),
  });

• src/server.ts:83-108 (registration)

  Registration of the get_card tool within the MCP server.

  // 2. get_card
  server.tool(
    'get_card',
    'Get complete details for a specific Hearthstone card including stats, text, keywords, and type. Use this when you know the card name (or close to it) and need full information. Supports fuzzy matching.',
    GetCardInput.shape,
    async (params) => {
      try {
        const result = getCard(db, params);
        return {
          content: [
            { type: 'text' as const, text: formatGetCard(result) },
          ],
        };
      } catch (err) {
        return {
          content: [
            {
              type: 'text' as const,
              text: `Error: ${err instanceof Error ? err.message : String(err)}`,
            },
          ],
          isError: true,
        };
      }
    },
  );