Search by format legality
search_by_formatSearch Magic: The Gathering cards by format legality. Filter results by format, status (legal, banned, restricted), and colors to find cards for specific game formats.
Instructions
Find cards by legality in a given format.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| format | Yes | ||
| status | No | legal | |
| colors | No | ||
| page | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| total | Yes | ||
| results | Yes |
Implementation Reference
- src/mcp-server.ts:184-192 (handler)Handler function that builds a Scryfall search query for cards legal (or banned/restricted) in a specific format, optionally filtered by colors, fetches the results, summarizes each card, and returns structured output with total count and results.
async ({ format, status, colors = [], page }: { format: typeof formats[number]; status: "legal" | "banned" | "restricted"; colors?: Array<"W" | "U" | "B" | "R" | "G">; page?: number }) => { const legal = `${status}:${format}`; // e.g., legal:commander const colorPart = colors.length ? `color>=${colors.join("")}` : undefined; const q = joinParts([legal, colorPart]); const data: any = (await Scryfall.searchCards({ q, page })) as any; const items: any[] = Array.isArray(data?.data) ? data.data : []; const out = { total: Number(data?.total_cards ?? items.length), results: items.map(summarize) }; return { structuredContent: out } as any; } - src/mcp-server.ts:170-175 (schema)Zod input schema defining parameters: format (enum from formats array), status (legal/banned/restricted), optional colors array, and page.
const searchByFormatInput = { format: z.enum(formats), status: z.enum(["legal", "banned", "restricted"]).default("legal"), colors: z.array(z.enum(["W", "U", "B", "R", "G"])).min(0).max(5).optional(), page: z.number().int().min(1).optional() } as const; - src/mcp-server.ts:176-193 (registration)McpServer tool registration for 'search_by_format', specifying title, description, input/output schemas, and the handler function.
server.registerTool( "search_by_format", { title: "Search by format legality", description: "Find cards by legality in a given format.", inputSchema: searchByFormatInput, outputSchema: searchByColorsOutput }, async ({ format, status, colors = [], page }: { format: typeof formats[number]; status: "legal" | "banned" | "restricted"; colors?: Array<"W" | "U" | "B" | "R" | "G">; page?: number }) => { const legal = `${status}:${format}`; // e.g., legal:commander const colorPart = colors.length ? `color>=${colors.join("")}` : undefined; const q = joinParts([legal, colorPart]); const data: any = (await Scryfall.searchCards({ q, page })) as any; const items: any[] = Array.isArray(data?.data) ? data.data : []; const out = { total: Number(data?.total_cards ?? items.length), results: items.map(summarize) }; return { structuredContent: out } as any; } ); - src/mcp-server.ts:153-169 (helper)Const array of supported Magic: The Gathering formats used to define the enum in the input schema.
const formats = [ "standard", "pioneer", "modern", "legacy", "vintage", "commander", "oathbreaker", "pauper", "paupercommander", "historic", "timeless", "alchemy", "brawl", "duel", "predh" ] as const;