search_cards
Search Magic: The Gathering cards by name, set, rarity, type, or format legality. Returns paginated results with prices and metadata.
Instructions
Search Magic: The Gathering cards by name (substring), set code, rarity, type, or format legality. Returns a paginated list with prices and basic metadata. Use this for catalog lookups; for a specific printing prefer get_card with set+number.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Substring to search card name + flavor name. Optional; omit to filter purely by setCode/rarity/type/format. | |
| setCode | No | 3-5 character set code (e.g. 'lea', 'mh3'). | |
| rarity | No | Filter by rarity. | |
| type | No | Substring match against card type line (e.g. 'Goblin', 'Instant'). | |
| format | No | Filter to cards with a legality entry in this format (e.g. 'modern', 'commander'). | |
| legality | No | Used with 'format'. Defaults to 'legal' when format is set. | |
| page | No | 1-based page index. | |
| limit | No | Page size (max 100). |
Implementation Reference
- src/tools/search-cards.ts:30-35 (handler)The handler function that executes the search_cards tool logic. It calls the external API at /api/v1/cards passing all filter parameters as query string.
export async function searchCards(input: Record<string, unknown>) { return apiFetch({ path: "/api/v1/cards", query: input as Record<string, string | number | undefined>, }); } - src/tools/search-cards.ts:4-28 (schema)Input validation schema using Zod. Defines all search parameters: q (substring), setCode, rarity, type, format, legality, page, and limit.
export const searchCardsInputSchema = { q: z .string() .optional() .describe("Substring to search card name + flavor name. Optional; omit to filter purely by setCode/rarity/type/format."), setCode: z.string().optional().describe("3-5 character set code (e.g. 'lea', 'mh3')."), rarity: z .enum(["common", "uncommon", "rare", "mythic"]) .optional() .describe("Filter by rarity."), type: z .string() .optional() .describe("Substring match against card type line (e.g. 'Goblin', 'Instant')."), format: z .string() .optional() .describe("Filter to cards with a legality entry in this format (e.g. 'modern', 'commander')."), legality: z .enum(["legal", "banned", "restricted"]) .optional() .describe("Used with 'format'. Defaults to 'legal' when format is set."), page: z.number().int().min(1).optional().describe("1-based page index."), limit: z.number().int().min(1).max(100).optional().describe("Page size (max 100)."), }; - src/tools/search-cards.ts:37-43 (registration)The tool definition/registration object with name 'search_cards', description, input schema, and handler reference.
export const searchCardsTool = { name: "search_cards", description: "Search Magic: The Gathering cards by name (substring), set code, rarity, type, or format legality. Returns a paginated list with prices and basic metadata. Use this for catalog lookups; for a specific printing prefer get_card with set+number.", inputSchema: z.object(searchCardsInputSchema), handler: searchCards, }; - src/tools/index.ts:50-50 (registration)Tool imported and included in the tools array (line 50) that is registered with the MCP server in src/server.ts.
searchCardsTool,