search_cards
Search Magic: The Gathering cards using text queries to find specific cards by name, type, abilities, or other attributes. Returns matching cards with basic details like name, set, and collector number.
Instructions
Search for MTG cards by a text query, e.g. 'oracle text includes: draw cards'. Returns a list of matching cards (with basic fields: name, set, collector_number, ID). If no matches are found, returns an error message from Scryfall.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | A full text query, e.g. 't:goblin pow=2 o:haste' |
Implementation Reference
- index.ts:242-248 (handler)The handler function that executes the search_cards tool by querying the Scryfall API search endpoint with the provided query string and processing the response.
async function handleSearchCards(query: string) { const url = `https://api.scryfall.com/cards/search?q=${encodeURIComponent( query )}`; const response = await fetch(url); return handleScryfallResponse(response); } - index.ts:72-88 (schema)Defines the input schema, name, and description for the search_cards tool.
const SEARCH_CARDS_TOOL: Tool = { name: "search_cards", description: "Search for MTG cards by a text query, e.g. 'oracle text includes: draw cards'. " + "Returns a list of matching cards (with basic fields: name, set, collector_number, ID). " + "If no matches are found, returns an error message from Scryfall.", inputSchema: { type: "object", properties: { query: { type: "string", description: "A full text query, e.g. 't:goblin pow=2 o:haste'" } }, required: ["query"] } }; - index.ts:186-194 (registration)Registers the search_cards tool (via SEARCH_CARDS_TOOL) in the list of available tools returned by listTools.
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:374-377 (registration)Dispatches calls to the search_cards tool by extracting the query argument and invoking the handler function.
case "search_cards": { const { query } = args as { query: string }; return await handleSearchCards(query); } - index.ts:197-239 (helper)Helper function used by the search_cards handler to process Scryfall API responses, handling errors and formatting successful JSON results.
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 }; }