get_archetype

Instructions

Implementation Reference

• src/tools/get-archetype.ts:51-87 (handler)

  The main handler function that queries the database for an archetype by name (case-insensitive). Returns archetype details (description, gameplan, win_conditions, strengths, weaknesses, example_decks) or a not-found result with suggestions.

  export function getArchetype(
    db: Database.Database,
    input: GetArchetypeInputType,
  ): GetArchetypeResult {
    // 1. Exact match (case-insensitive)
    const row = db
      .prepare('SELECT * FROM archetypes WHERE LOWER(name) = LOWER(?)')
      .get(input.name) as ArchetypeRow | undefined;
  
    if (row) {
      return {
        found: true,
        archetype: {
          name: row.name,
          description: row.description,
          gameplan: row.gameplan,
          win_conditions: parseJson(row.win_conditions),
          strengths: parseJson(row.strengths),
          weaknesses: parseJson(row.weaknesses),
          example_decks: parseJson(row.example_decks),
        },
      };
    }
  
    // 2. Not found — suggest similar entries via LIKE
    const suggestions = db
      .prepare('SELECT name FROM archetypes 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 archetype found matching "${input.name}".`,
      suggestions: suggestionNames.length > 0 ? suggestionNames : undefined,
    };
  }

• src/tools/get-archetype.ts:1-26 (schema)

  Input schema (GetArchetypeInput with 'name' string) and result types (ArchetypeInfo interface, GetArchetypeResult union type).

  import type Database from 'better-sqlite3';
  import { z } from 'zod';
  
  // --- Input Schema ---
  
  export const GetArchetypeInput = z.object({
    name: z.string().describe('Archetype name (e.g. "aggro", "control", "combo", "midrange", "tempo", "value")'),
  });
  
  export type GetArchetypeInputType = z.infer<typeof GetArchetypeInput>;
  
  // --- Result Types ---
  
  export interface ArchetypeInfo {
    name: string;
    description: string;
    gameplan: string;
    win_conditions: string[];
    strengths: string[];
    weaknesses: string[];
    example_decks: string[];
  }
  
  export type GetArchetypeResult =
    | { found: true; archetype: ArchetypeInfo }
    | { found: false; message: string; suggestions?: string[] };

• src/server.ts:191-216 (registration)

  Registers the 'get_archetype' tool on the MCP server with description, input schema, and async handler that calls getArchetype() and formats the result.

  // 6. get_archetype
  server.tool(
    'get_archetype',
    'Get a detailed explanation of a Hearthstone deck archetype (aggro, control, combo, midrange, tempo, value). Includes gameplan, win conditions, strengths, weaknesses, and example decks. Use this when explaining deck building strategy.',
    GetArchetypeInput.shape,
    async (params) => {
      try {
        const result = getArchetype(db, params);
        return {
          content: [
            { type: 'text' as const, text: formatGetArchetype(result) },
          ],
        };
      } catch (err) {
        return {
          content: [
            {
              type: 'text' as const,
              text: `Error: ${err instanceof Error ? err.message : String(err)}`,
            },
          ],
          isError: true,
        };
      }
    },
  );

• src/format.ts:219-261 (helper)

  Formats the GetArchetypeResult into a human-readable Markdown string with sections for description, gameplan, win conditions, strengths, weaknesses, and example decks.

  export function formatGetArchetype(result: GetArchetypeResult): 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 a = result.archetype;
    const lines: string[] = [];
    lines.push(`# ${a.name}`);
    lines.push('');
    lines.push(`## Description`);
    lines.push(a.description);
    lines.push('');
    lines.push(`## Gameplan`);
    lines.push(a.gameplan);
    lines.push('');
    lines.push(`## Win Conditions`);
    for (const wc of a.win_conditions) {
      lines.push(`- ${wc}`);
    }
    lines.push('');
    lines.push(`## Strengths`);
    for (const s of a.strengths) {
      lines.push(`- ${s}`);
    }
    lines.push('');
    lines.push(`## Weaknesses`);
    for (const w of a.weaknesses) {
      lines.push(`- ${w}`);
    }
    if (a.example_decks.length > 0) {
      lines.push('');
      lines.push(`## Example Decks`);
      for (const ed of a.example_decks) {
        lines.push(`- ${ed}`);
      }
    }
    return lines.join('\n');
  }

• src/tools/get-archetype.ts:30-37 (helper)

  Helper function parseJson that safely parses JSON string fields from the database into string arrays.

  function parseJson(raw: string | null): string[] {
    if (!raw) return [];
    try {
      return JSON.parse(raw) as string[];
    } catch {
      return [];
    }
  }