get_card_by_name
Retrieve Magic: The Gathering card details by its exact English name using Scryfall API. Returns JSON data for the most relevant card printing matching the provided name.
Instructions
Retrieve a card by its exact English name, e.g. 'Black Lotus'. Returns the card data in JSON. If multiple cards share that exact name, Scryfall returns one (usually the most relevant printing).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Exact name of the card, e.g. 'Lightning Bolt' |
Implementation Reference
- index.ts:256-263 (handler)The main handler function for the 'get_card_by_name' tool. It constructs the Scryfall API URL for exact name search and fetches the card data, using the shared response handler.async function handleGetCardByName(name: string) { // Tilde in URL means 'exact' mode for the card name const url = `https://api.scryfall.com/cards/named?exact=${encodeURIComponent( name )}`; const response = await fetch(url); return handleScryfallResponse(response); }
- index.ts:107-122 (schema)The Tool object definition for 'get_card_by_name', including name, description, and inputSchema for validation.const GET_CARD_BY_NAME_TOOL: Tool = { name: "get_card_by_name", description: "Retrieve a card by its exact English name, e.g. 'Black Lotus'. Returns the card data in JSON. " + "If multiple cards share that exact name, Scryfall returns one (usually the most relevant printing).", inputSchema: { type: "object", properties: { name: { type: "string", description: "Exact name of the card, e.g. 'Lightning Bolt'" } }, required: ["name"] } };
- index.ts:186-194 (registration)Registration in the SCRYFALL_TOOLS array, which is returned by the listTools handler.const SCRYFALL_TOOLS = [ SEARCH_CARDS_TOOL, GET_CARD_BY_ID_TOOL, GET_CARD_BY_NAME_TOOL, RANDOM_CARD_TOOL, GET_RULINGS_TOOL, GET_PRICES_BY_ID_TOOL, GET_PRICES_BY_NAME_TOOL ] as const;
- index.ts:382-385 (registration)In the CallToolRequestSchema handler switch statement, dispatches 'get_card_by_name' calls to the handler function.case "get_card_by_name": { const { name } = args as { name: string }; return await handleGetCardByName(name); }
- index.ts:197-239 (helper)Shared helper function used by the handler to process Scryfall API responses and format them for MCP.async function handleScryfallResponse(response: Response) { if (!response.ok) { // Attempt to parse Scryfall error let errorObj: ScryfallError | null = null; try { errorObj = (await response.json()) as ScryfallError; } catch { // fall back to generic } if (errorObj && errorObj.object === "error") { return { content: [ { type: "text", text: `Scryfall error: ${errorObj.details} (code=${errorObj.code}, status=${errorObj.status})` } ], isError: true }; } else { return { content: [ { type: "text", text: `HTTP error ${response.status}: ${response.statusText}` } ], isError: true }; } } // If okay, parse JSON const data = await response.json(); return { content: [ { type: "text", text: JSON.stringify(data, null, 2) } ], isError: false }; }