get_rulings

Instructions

Implementation Reference

• src/tools/get-rulings.ts:32-64 (handler)

  Main handler function that looks up a card by name (case-insensitive exact match, then LIKE), queries rulings from the database, and returns the results or a not-found message.

  export function handler(db: Database.Database, params: GetRulingsParams): GetRulingsResult {
    // Look up card by name (case-insensitive exact match first, then LIKE)
    let card = db.prepare(
      'SELECT * FROM cards WHERE LOWER(name) = LOWER(?)'
    ).get(params.card_name) as CardRow | undefined;
  
    if (!card) {
      card = db.prepare(
        'SELECT * FROM cards WHERE LOWER(name) LIKE LOWER(?)'
      ).get(`%${params.card_name}%`) as CardRow | undefined;
    }
  
    if (!card) {
      return {
        found: false,
        message: `No card found matching "${params.card_name}"`,
      };
    }
  
    const rows = db.prepare(
      'SELECT * FROM rulings WHERE card_id = ? ORDER BY published_at'
    ).all(card.id) as RulingRow[];
  
    return {
      found: true,
      card_name: card.name,
      rulings: rows.map(r => ({
        source: r.source,
        published_at: r.published_at,
        comment: r.comment,
      })),
    };
  }

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

  Zod input schema for the 'get_rulings' tool: expects a 'card_name' string parameter.

  export const GetRulingsInput = z.object({
    card_name: z.string().describe('Name of the card to get rulings for'),
  });

• src/tools/get-rulings.ts:15-28 (schema)

  Output types: RulingEntry interface, GetRulingsResult discriminated union (found/message).

  export interface RulingEntry {
    source: string | null;
    published_at: string | null;
    comment: string;
  }
  
  export type GetRulingsResult = {
    found: true;
    card_name: string;
    rulings: RulingEntry[];
  } | {
    found: false;
    message: string;
  };

• src/server.ts:107-119 (registration)

  Tool registration using server.tool('get_rulings', ...) with description, input schema, and handler invocation with formatting.

  server.tool(
    'get_rulings',
    'Get official rulings for a specific Magic card. Use this when a user asks about specific interactions, edge cases, or how a card works in unusual situations. Returns timestamped rulings from Wizards of the Coast.',
    GetRulingsInput.shape,
    async (params) => {
      try {
        const result = getRulingsHandler(db, params);
        return { content: [{ type: 'text' as const, text: formatGetRulings(result) }] };
      } catch (err) {
        return { content: [{ type: 'text' as const, text: `Error getting rulings: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
      }
    },
  );

• src/format.ts:154-171 (helper)

  Formatting helper that converts GetRulingsResult into a human-readable string with a heading and bullet-pointed rulings.

  export function formatGetRulings(result: GetRulingsResult): string {
    if (!result.found) {
      return result.message;
    }
  
    if (result.rulings.length === 0) {
      return `No rulings found for "${result.card_name}".`;
    }
  
    const lines: string[] = [`# Rulings for ${result.card_name} (${result.rulings.length})\n`];
    for (const ruling of result.rulings) {
      const datePart = ruling.published_at ? `${ruling.published_at}` : '';
      const sourcePart = ruling.source ? ` (${ruling.source})` : '';
      lines.push(`- ${datePart}${sourcePart}: ${ruling.comment}`);
    }
  
    return lines.join('\n');
  }