Search Cards

Instructions

Implementation Reference

• src/server.ts:43-43 (registration)

  Registration of the search_cards tool via registerSearchCards() call in createServer()

  registerSearchCards(server, db);

• src/tools/search-cards.ts:28-83 (handler)

  Handler function registerSearchCards that registers the 'search_cards' tool with the MCP server, defines the Zod input schema, builds SearchFilters from args, calls the database searchCards function, and formats results

  export function registerSearchCards(server: McpServer, db: Database.Database): void {
    server.registerTool(
      'search_cards',
      {
        title: 'Search Cards',
        description:
          'Search Disney Lorcana cards by name, rules text, or filters (ink color, type, rarity, set, cost range). Returns paginated results.',
        inputSchema: {
          query: z.string().optional().describe('Search by card name or rules text'),
          ink: z.string().optional().describe('Filter by ink color (e.g. Amber, Amethyst, Emerald, Ruby, Sapphire, Steel)'),
          type: z.string().optional().describe('Filter by card type (e.g. Character, Song, Item, Action, Location)'),
          rarity: z.string().optional().describe('Filter by rarity (e.g. Common, Uncommon, Rare, Super Rare, Legendary, Enchanted)'),
          set: z.string().optional().describe('Filter by set code'),
          cost_min: z.number().optional().describe('Minimum ink cost (inclusive)'),
          cost_max: z.number().optional().describe('Maximum ink cost (inclusive)'),
          limit: z.number().optional().default(20).describe('Max results to return (default 20)'),
          cursor: z.number().optional().describe('Offset for pagination'),
        },
      },
      async (args) => {
        const filters: SearchFilters = {
          query: args.query,
          color: args.ink,
          type: args.type,
          rarity: args.rarity,
          setCode: args.set,
          costMin: args.cost_min,
          costMax: args.cost_max,
          limit: args.limit,
          offset: args.cursor,
        };
  
        const { rows, total } = searchCards(db, filters);
  
        if (rows.length === 0) {
          return {
            content: [{ type: 'text' as const, text: 'No cards found matching your search criteria.' }],
          };
        }
  
        const offset = args.cursor ?? 0;
        const parts = rows.map(formatCard);
        const footer: string[] = [];
        footer.push(`\n---\nShowing ${offset + 1}–${offset + rows.length} of ${total} results.`);
        if (offset + rows.length < total) {
          footer.push(`Use cursor: ${offset + rows.length} to see more.`);
        }
  
        return {
          content: [
            { type: 'text' as const, text: parts.join('\n\n') + footer.join(' ') },
          ],
        };
      },
    );
  }

• src/tools/search-cards.ts:7-26 (helper)

  formatCard helper function that formats a CardRow into a human-readable string for display

  function formatCard(card: CardRow): string {
    const lines: string[] = [];
    lines.push(`**${card.full_name ?? card.name}**`);
    lines.push(`  Ink: ${card.color} | Cost: ${card.cost ?? '—'} | Inkwell: ${card.inkwell ? 'Yes' : 'No'}`);
    lines.push(`  Type: ${card.type}${card.subtypes_text ? ` — ${card.subtypes_text}` : ''}`);
    if (card.type === 'Character') {
      lines.push(`  Strength: ${card.strength ?? '—'} | Willpower: ${card.willpower ?? '—'} | Lore: ${card.lore ?? '—'}`);
    }
    if (card.type === 'Location' && card.move_cost !== null) {
      lines.push(`  Lore: ${card.lore ?? '—'} | Move Cost: ${card.move_cost}`);
    }
    lines.push(`  Rarity: ${card.rarity ?? '—'} | Set: ${card.set_code ?? '—'}`);
    if (card.full_text) {
      lines.push(`  Text: ${card.full_text}`);
    }
    if (card.story) {
      lines.push(`  Franchise: ${card.story}`);
    }
    return lines.join('\n');
  }

• src/types.ts:45-60 (schema)

  SearchFilters interface defining all possible filter fields passed to the database search function

  export interface SearchFilters {
    query?: string;
    color?: string;
    type?: string;
    cost?: number;
    costOp?: 'eq' | 'lte' | 'gte';
    costMin?: number;
    costMax?: number;
    rarity?: string;
    setCode?: string;
    story?: string;
    inkwell?: boolean;
    hasKeyword?: string;
    limit?: number;
    offset?: number;
  }

• src/data/db.ts:51-136 (handler)

  Core database searchCards function that builds dynamic SQL queries with filters, FTS text search, and pagination

  export function searchCards(
    db: Database.Database,
    filters: SearchFilters,
  ): SearchResult {
    const conditions: string[] = [];
    const params: (string | number)[] = [];
  
    if (filters.query) {
      const ftsQuery = sanitizeFtsQuery(filters.query);
      if (ftsQuery.length > 0) {
        conditions.push(
          'c.id IN (SELECT rowid FROM cards_fts WHERE cards_fts MATCH ?)',
        );
        params.push(ftsQuery);
      }
    }
  
    if (filters.color) {
      conditions.push('LOWER(c.color) = LOWER(?)');
      params.push(filters.color);
    }
  
    if (filters.type) {
      conditions.push('LOWER(c.type) = LOWER(?)');
      params.push(filters.type);
    }
  
    if (filters.cost !== undefined) {
      const op = filters.costOp ?? 'eq';
      const sqlOp = op === 'lte' ? '<=' : op === 'gte' ? '>=' : '=';
      conditions.push(`c.cost ${sqlOp} ?`);
      params.push(filters.cost);
    }
  
    if (filters.costMin !== undefined) {
      conditions.push('c.cost >= ?');
      params.push(filters.costMin);
    }
  
    if (filters.costMax !== undefined) {
      conditions.push('c.cost <= ?');
      params.push(filters.costMax);
    }
  
    if (filters.rarity) {
      conditions.push('LOWER(c.rarity) = LOWER(?)');
      params.push(filters.rarity);
    }
  
    if (filters.setCode) {
      conditions.push('c.set_code = ?');
      params.push(filters.setCode);
    }
  
    if (filters.story) {
      conditions.push('LOWER(c.story) = LOWER(?)');
      params.push(filters.story);
    }
  
    if (filters.inkwell !== undefined) {
      conditions.push('c.inkwell = ?');
      params.push(filters.inkwell ? 1 : 0);
    }
  
    if (filters.hasKeyword) {
      conditions.push('c.keyword_abilities LIKE ?');
      params.push(`%${filters.hasKeyword}%`);
    }
  
    const where =
      conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
    const limit = filters.limit ?? 20;
    const offset = filters.offset ?? 0;
  
    const countRow = db
      .prepare(`SELECT COUNT(*) as count FROM cards c ${where}`)
      .get(...params) as { count: number };
  
    const rows = db
      .prepare(
        `SELECT c.* FROM cards c ${where} ORDER BY c.cost ASC, c.name ASC LIMIT ? OFFSET ?`,
      )
      .all(...params, limit, offset) as CardRow[];
  
    return { rows, total: countRow.count };
  }