Search by colors

Instructions

Implementation Reference

• src/mcp-server.ts:92-102 (schema)

  Input schema (searchByColorsInput) and output schema (searchByColorsOutput) Zod shapes for the search_by_colors tool, defining parameters like colors array, mode (exact/contains/at_most), and output with total count and summarized card results.

  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-121 (registration)

  Registration of the search_by_colors tool using server.registerTool, including title, description, schemas, and the inline async handler function that builds a Scryfall color query and returns summarized results.

  server.registerTool(
      "search_by_colors",
      {
          title: "Search by colors",
          description: "Find cards by colors or color identity.",
          inputSchema: searchByColorsInput,
          outputSchema: searchByColorsOutput
      },
      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:111-120 (handler)

  The core handler logic for search_by_colors: constructs Scryfall query using color operator based on mode and identity flag, optionally adds colorless filter, fetches cards via Scryfall.searchCards, summarizes results, and returns structured content with total and card summaries.

  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:21-46 (helper)

  Shared helper: cardSummaryShape Zod object used in output schema, and summarize function that extracts key fields from Scryfall card data into a compact summary used by search_by_colors and other tools.

  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;
  type CardSummary = z.infer<z.ZodObject<typeof cardSummaryShape>>;
  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
  });