search_cards
Find Magic: The Gathering cards by entering a text query, such as 'oracle text includes: draw cards', and receive matching results with name, set, collector number, and ID. Uses Scryfall API for accurate searches.
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:72-88 (schema)Tool schema definition for 'search_cards', specifying name, description, and input schema requiring a 'query' string.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)Registration of all tools including SEARCH_CARDS_TOOL in the SCRYFALL_TOOLS array, used for listing tools.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:366-368 (registration)MCP server request handler for listing tools, returning the SCRYFALL_TOOLS array containing search_cards.newServer.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: SCRYFALL_TOOLS }));
- index.ts:242-248 (handler)Handler function that executes the search_cards tool by querying the Scryfall API with the provided query 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:374-377 (registration)Dispatch case in the CallToolRequestHandler switch statement that routes 'search_cards' calls to the handleSearchCards function.case "search_cards": { const { query } = args as { query: string }; return await handleSearchCards(query); }