hearthstone-oracle

Instructions

Implementation Reference

• src/tools/explain-concept.ts:27-60 (handler)

  The handler function for `explain_concept` that queries the `game_concepts` table and returns concept details or suggestions.

  export function explainConcept(
    db: Database.Database,
    input: ExplainConceptInputType,
  ): ExplainConceptResult {
    // Exact match (case-insensitive)
    const row = db
      .prepare('SELECT * FROM game_concepts WHERE LOWER(name) = LOWER(?)')
      .get(input.name) as ConceptInfo | undefined;
  
    if (row) {
      return {
        found: true,
        concept: {
          name: row.name,
          category: row.category,
          description: row.description,
          hearthstone_application: row.hearthstone_application,
        },
      };
    }
  
    // Not found — suggest similar entries via LIKE
    const suggestions = db
      .prepare('SELECT name FROM game_concepts WHERE LOWER(name) LIKE LOWER(?) LIMIT 5')
      .all(`%${input.name}%`) as Array<{ name: string }>;
  
    const suggestionNames = suggestions.map((s) => s.name);
  
    return {
      found: false,
      message: `No game concept found matching "${input.name}".`,
      suggestions: suggestionNames.length > 0 ? suggestionNames : undefined,
    };
  }

• src/tools/explain-concept.ts:6-8 (schema)

  Input validation schema for the `explain_concept` tool using zod.

  export const ExplainConceptInput = z.object({
    name: z.string().describe('Game concept name (e.g. "tempo", "card advantage", "mana curve")'),
  });

• src/server.ts:275-303 (registration)

  Registration of the `explain_concept` tool in the MCP server.

  // 9. explain_concept
  server.tool(
    'explain_concept',
    'Explain a fundamental Hearthstone game concept like card advantage, tempo, value, board control, or mana curve. Includes how the concept applies specifically to Hearthstone.',
    ExplainConceptInput.shape,
    async (params) => {
      try {
        const result = explainConcept(db, params);
        return {
          content: [
            {
              type: 'text' as const,
              text: formatExplainConcept(result),
            },
          ],
        };
      } catch (err) {
        return {
          content: [
            {
              type: 'text' as const,
              text: `Error: ${err instanceof Error ? err.message : String(err)}`,
            },
          ],
          isError: true,
        };
      }
    },
  );