explain_concept

Instructions

Implementation Reference

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

  The main handler function that queries the database for a game concept by name, returning either the concept info or suggestions if not found.

  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-23 (schema)

  Input schema (zod) and result types for the explain_concept tool. Input requires a 'name' string; result is either found (ConceptInfo) or not found (message + suggestions).

  export const ExplainConceptInput = z.object({
    name: z.string().describe('Game concept name (e.g. "tempo", "card advantage", "mana curve")'),
  });
  
  export type ExplainConceptInputType = z.infer<typeof ExplainConceptInput>;
  
  // --- Result Types ---
  
  export interface ConceptInfo {
    name: string;
    category: string;
    description: string;
    hearthstone_application: string;
  }
  
  export type ExplainConceptResult =
    | { found: true; concept: ConceptInfo }
    | { found: false; message: string; suggestions?: string[] };

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

  Registration of the 'explain_concept' tool on the MCP server, wiring up the input schema and calling the handler.

  // 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,
        };
      }

• src/format.ts:351-370 (helper)

  Formats the ExplainConceptResult into a human-readable markdown string for display.

  export function formatExplainConcept(result: ExplainConceptResult): string {
    if (!result.found) {
      let msg = result.message;
      if (result.suggestions && result.suggestions.length > 0) {
        msg += '\n\nDid you mean:\n';
        msg += result.suggestions.map((s) => `- ${s}`).join('\n');
      }
      return msg;
    }
  
    const c = result.concept;
    const lines: string[] = [];
    lines.push(`## ${c.name}`);
    lines.push('');
    lines.push(`**Category:** ${c.category}`);
    lines.push('');
    lines.push(c.description);
    lines.push('');
    lines.push(`**In Hearthstone:** ${c.hearthstone_application}`);
    return lines.join('\n');