mtg-oracle

Instructions

Implementation Reference

• src/tools/get-card.ts:74-165 (handler)

  The handler function that executes the logic to retrieve card information from the database, including fetching details, faces, rulings, and legalities.

  export function handler(db: Database.Database, params: GetCardParams): GetCardResult {
    // 1. Exact match (case-insensitive)
    let card = db.prepare(
      'SELECT * FROM cards WHERE LOWER(name) = LOWER(?)'
    ).get(params.name) as CardRow | undefined;
  
    // 2. Fuzzy fallback via LIKE
    if (!card) {
      card = db.prepare(
        'SELECT * FROM cards WHERE LOWER(name) LIKE LOWER(?)'
      ).get(`%${params.name}%`) as CardRow | undefined;
    }
  
    if (!card) {
      // Try to find suggestions
      const suggestions = db.prepare(
        'SELECT name FROM cards WHERE LOWER(name) LIKE LOWER(?) LIMIT 5'
      ).all(`%${params.name.split(' ')[0]}%`) as Array<{ name: string }>;
  
      return {
        found: false,
        message: `No card found matching "${params.name}"`,
        suggestions: suggestions.length > 0 ? suggestions.map(s => s.name) : undefined,
      };
    }
  
    // Fetch faces
    const faces = db.prepare(
      'SELECT * FROM card_faces WHERE card_id = ? ORDER BY face_index'
    ).all(card.id) as CardFaceRow[];
  
    // Fetch rulings
    const rulings = db.prepare(
      'SELECT * FROM rulings WHERE card_id = ? ORDER BY published_at'
    ).all(card.id) as RulingRow[];
  
    // Fetch legalities
    const legalityRows = db.prepare(
      'SELECT * FROM legalities WHERE card_id = ?'
    ).all(card.id) as LegalityRow[];
  
    const legalities: Record<string, string> = {};
    for (const row of legalityRows) {
      legalities[row.format] = row.status;
    }
  
    const cardDetail: CardDetail = {
      id: card.id,
      name: card.name,
      mana_cost: card.mana_cost,
      cmc: card.cmc,
      type_line: card.type_line,
      oracle_text: card.oracle_text,
      power: card.power,
      toughness: card.toughness,
      loyalty: card.loyalty,
      colors: card.colors ? JSON.parse(card.colors) as string[] : [],
      color_identity: card.color_identity ? JSON.parse(card.color_identity) as string[] : [],
      keywords: card.keywords ? JSON.parse(card.keywords) as string[] : [],
      rarity: card.rarity,
      set_code: card.set_code,
      set_name: card.set_name,
      released_at: card.released_at,
      image_uri: card.image_uri,
      scryfall_uri: card.scryfall_uri,
      edhrec_rank: card.edhrec_rank,
      artist: card.artist,
      faces: faces.map(f => ({
        face_index: f.face_index,
        name: f.name,
        mana_cost: f.mana_cost,
        type_line: f.type_line,
        oracle_text: f.oracle_text,
        power: f.power,
        toughness: f.toughness,
        colors: f.colors ? JSON.parse(f.colors) as string[] : [],
      })),
      rulings: rulings.map(r => ({
        source: r.source,
        published_at: r.published_at,
        comment: r.comment,
      })),
      legalities,
      price_usd: card.price_usd,
      price_usd_foil: card.price_usd_foil,
      price_eur: card.price_eur,
      price_eur_foil: card.price_eur_foil,
      price_tix: card.price_tix,
    };
  
    return { found: true, card: cardDetail };
  }

• src/tools/get-card.ts:7-9 (schema)

  Input Zod schema validation for the 'get_card' tool.

  export const GetCardInput = z.object({
    name: z.string().describe('Card name to look up'),
  });

• src/server.ts:105-111 (registration)

  Registration of the 'get_card' tool in the MCP server setup.

  'get_card',
  'Get complete details for a specific Magic card including oracle text, mana cost, type, power/toughness, rulings, and format legality. Use this when you know the exact card name (or close to it) and need full information. Supports fuzzy matching — partial names work.',
  GetCardInput.shape,
  async (params) => {
    try {
      const result = getCardHandler(db, params);
      return { content: [{ type: 'text' as const, text: formatGetCard(result) }] };