lego-oracle

Instructions

Implementation Reference

• src/tools/get-minifig.ts:42-108 (handler)

  The handler function that executes the "get_minifig" tool logic, performing database lookups and returning minifig details.

  export function handler(db: Database.Database, params: GetMinifigParams): GetMinifigResult {
    if (!params.fig_num && !params.name) {
      return { found: false, message: 'Provide either fig_num or name to look up a minifig.' };
    }
  
    let figRow: { fig_num: string; name: string; num_parts: number | null; img_url: string | null } | undefined;
  
    // 1. Exact fig_num match
    if (params.fig_num) {
      figRow = db.prepare('SELECT * FROM minifigs WHERE fig_num = ?').get(params.fig_num) as typeof figRow;
    }
  
    // 2. FTS5 name search
    if (!figRow && params.name) {
      figRow = db.prepare(`
        SELECT m.* FROM minifigs_fts fts
        JOIN minifigs m ON m.rowid = fts.rowid
        WHERE minifigs_fts MATCH ?
        ORDER BY fts.rank
        LIMIT 1
      `).get(params.name) as typeof figRow;
    }
  
    // 3. LIKE fallback
    if (!figRow && params.name) {
      figRow = db.prepare(
        'SELECT * FROM minifigs WHERE LOWER(name) LIKE LOWER(?) LIMIT 1'
      ).get(`%${params.name}%`) as typeof figRow;
    }
  
    if (!figRow) {
      const searchTerm = params.fig_num ?? params.name ?? '';
      const suggestions = db.prepare(
        'SELECT fig_num, name FROM minifigs WHERE LOWER(name) LIKE LOWER(?) LIMIT 5'
      ).all(`%${searchTerm.split(' ')[0]}%`) as Array<{ fig_num: string; name: string }>;
  
      return {
        found: false,
        message: `No minifig found matching "${searchTerm}"`,
        suggestions: suggestions.length > 0
          ? suggestions.map(s => `${s.fig_num} (${s.name})`)
          : undefined,
      };
    }
  
    // Fetch all sets this minifig appears in
    const sets = db.prepare(`
      SELECT s.set_num, s.name as set_name, s.year, t.name as theme_name, im.quantity
      FROM inventory_minifigs im
      JOIN inventories inv ON im.inventory_id = inv.id
      JOIN sets s ON inv.set_num = s.set_num
      LEFT JOIN themes t ON s.theme_id = t.id
      WHERE im.fig_num = ?
      ORDER BY s.year DESC, s.name
    `).all(figRow.fig_num) as MinifigSetAppearance[];
  
    return {
      found: true,
      minifig: {
        fig_num: figRow.fig_num,
        name: figRow.name,
        num_parts: figRow.num_parts,
        img_url: figRow.img_url,
        sets,
      },
    };
  }

• src/tools/get-minifig.ts:6-11 (schema)

  Zod schema and TypeScript type definitions for the "get_minifig" tool input parameters.

  export const GetMinifigInput = z.object({
    fig_num: z.string().optional().describe('Exact minifig number (e.g. "fig-000100")'),
    name: z.string().optional().describe('Minifig name for fuzzy search if fig_num not provided'),
  });
  
  export type GetMinifigParams = z.infer<typeof GetMinifigInput>;

• src/server.ts:162-170 (registration)

  Registration of the "get_minifig" tool in the server implementation, mapping it to the handler logic.

  'get_minifig',
  'Get complete details for a specific LEGO minifigure including every set it appears in. Use this when you know a minifig name or fig number and want to find which sets include it.',
  GetMinifigInput.shape,
  async (params) => {
    try {
      const result = getMinifigHandler(db, params);
      return { content: [{ type: 'text' as const, text: formatGetMinifig(result) }] };
    } catch (err) {
      return { content: [{ type: 'text' as const, text: `Error getting minifig: ${err instanceof Error ? err.message : String(err)}` }], isError: true };