search_by_colors
Search Magic: The Gathering cards by color combinations using exact, contains, or at-most matching modes. Filter by printed colors or color identity, including colorless options.
Instructions
Find cards by colors or color identity.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| colors | No | ||
| identity | No | Filter by color identity instead of printed colors | |
| include_colorless | No | Include colorless cards | |
| mode | No | contains | |
| page | No |
Implementation Reference
- src/mcp-server.ts:111-120 (handler)The core handler function implementing the search_by_colors tool logic. It constructs a Scryfall query string using color operators based on mode (exact/contains/at_most) and identity flag, optionally includes colorless, fetches paginated results via Scryfall.searchCards, extracts and summarizes card data, and returns structured JSON output.async ({ colors = [], mode, include_colorless, identity, page }: { colors?: Array<"W" | "U" | "B" | "R" | "G">; mode: "exact" | "contains" | "at_most"; include_colorless?: boolean; identity?: boolean; page?: number }) => { const op = mode === "exact" ? "=" : mode === "contains" ? ">=" : "<="; const opKey = identity ? "c" : "color"; // c = color identity const parts = [colors.length ? `${opKey}${op}${colors.join("")}` : undefined, include_colorless ? "is:colorless" : undefined]; const q = joinParts(parts); 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:92-102 (schema)Zod input schema defining parameters for color search (colors array, mode enum, flags for colorless/identity, page) and output schema for paginated results (total count and array of summarized cards using shared cardSummaryShape).const searchByColorsInput = { colors: z.array(z.enum(["W", "U", "B", "R", "G"])).min(0).max(5).optional(), mode: z.enum(["exact", "contains", "at_most"]).default("contains"), include_colorless: z.boolean().optional().describe("Include colorless cards"), identity: z.boolean().optional().describe("Filter by color identity instead of printed colors"), page: z.number().int().min(1).optional() } as const; const searchByColorsOutput = { total: z.number().int().nonnegative(), results: z.array(z.object(cardSummaryShape)) } as const;
- src/mcp-server.ts:103-110 (registration)The server.registerTool call registering the 'search_by_colors' tool with its name, title, description, and references to input/output schemas. The third argument (handler) follows inline.server.registerTool( "search_by_colors", { title: "Search by colors", description: "Find cards by colors or color identity.", inputSchema: searchByColorsInput, outputSchema: searchByColorsOutput },
- src/mcp-server.ts:36-46 (helper)Shared helper function 'summarize' used by the handler to transform raw Scryfall card data into the standardized CardSummary shape for output results.const summarize = (card: any): CardSummary => ({ name: card?.name, mana_cost: card?.mana_cost, type_line: card?.type_line, oracle_text: card?.oracle_text, set: card?.set, collector_number: String(card?.collector_number ?? ""), scryfall_uri: card?.scryfall_uri, image: card?.image_uris?.normal ?? card?.image_uris?.large ?? card?.image_uris?.small, prices: card?.prices });
- src/mcp-server.ts:21-34 (schema)Shared Zod object shape 'cardSummaryShape' defining the structure of individual card summaries in the tool's output results array.const cardSummaryShape = { name: z.string(), mana_cost: z.string().optional(), type_line: z.string(), oracle_text: z.string().optional(), set: z.string(), collector_number: z.string(), scryfall_uri: z.string().url(), image: z.string().url().optional(), prices: z .object({ usd: z.string().nullable().optional(), eur: z.string().nullable().optional(), tix: z.string().nullable().optional() }) .partial() .optional() } as const;