Color Scheme Generator MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:266-284 (registration)

  Registers the 'generate_quad_scheme' tool using server.tool, providing description, shared schema, and inline async handler that calls generateColorScheme with mode='quad'.

  function registerQuadScheme() {
    server.tool(
      "generate_quad_scheme",
      "Generates a quad color scheme with four evenly spaced colors on the color wheel",
      colorSchemeInputShape,
      async (args) => {
        const { color, count } = args;
        const result = await generateColorScheme(color, "quad", count);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      }
    );
  }

• src/tools/index.ts:94-108 (schema)

  Zod-based input schema shared across all color scheme tools, defining 'color' and optional 'count' parameters.

  const colorSchemeInputShape = {
    color: z
      .string()
      .describe(
        "The seed color in hex (098765), RGB (0,71,171), or HSL (215,100%,34%) format"
      ),
    count: z
      .number()
      .int()
      .min(3)
      .max(10)
      .default(5)
      .optional()
      .describe("Number of colors to generate (3-10, default: 5)"),
  };

• src/tools/index.ts:46-91 (helper)

  Core helper function that parses the seed color, calls The Color API with the specified mode and count, formats the colors array, and returns structured scheme data.

  async function generateColorScheme(
    color: string,
    mode: string,
    count: number = 5
  ) {
    const { param, value } = parseColorInput(color);
    const url = `https://www.thecolorapi.com/scheme?${param}=${value}&mode=${mode}&count=${count}&format=json`;
  
    try {
      const response = await fetch(url);
      if (!response.ok) {
        throw new Error(
          `Color API request failed: ${response.status} ${response.statusText}`
        );
      }
  
      const data: any = await response.json();
  
      if (!data.colors || !Array.isArray(data.colors)) {
        throw new Error("Invalid response from Color API");
      }
  
      // Format the response for better readability
      const colors = data.colors.map((color: any, index: number) => ({
        position: index + 1,
        hex: color.hex?.value || "N/A",
        rgb: color.rgb
          ? `rgb(${color.rgb.r}, ${color.rgb.g}, ${color.rgb.b})`
          : "N/A",
        hsl: color.hsl
          ? `hsl(${color.hsl.h}, ${color.hsl.s}%, ${color.hsl.l}%)`
          : "N/A",
        name: color.name?.value || "Unknown",
      }));
  
      return {
        scheme_mode: mode,
        seed_color: data.seed?.hex?.value || value,
        color_count: colors.length,
        colors: colors,
      };
    } catch (error) {
      console.error(`Error generating ${mode} color scheme:`, error);
      throw error;
    }
  }

• src/tools/index.ts:6-43 (helper)

  Utility function to parse and normalize seed color input into API-compatible {param, value} for hex, rgb, or hsl formats.

  function parseColorInput(color: string): { param: string; value: string } {
    const cleanColor = color.trim();
  
    // Check for hex format
    if (cleanColor.startsWith("#")) {
      return { param: "hex", value: cleanColor.substring(1) };
    } else if (/^[0-9A-Fa-f]{6}$/.test(cleanColor)) {
      return { param: "hex", value: cleanColor };
    }
  
    // Check for RGB format
    if (
      cleanColor.toLowerCase().includes("rgb") ||
      /^\d+,\d+,\d+$/.test(cleanColor)
    ) {
      const rgbMatch = cleanColor.match(/(\d+),\s*(\d+),\s*(\d+)/);
      if (rgbMatch) {
        return {
          param: "rgb",
          value: `${rgbMatch[1]},${rgbMatch[2]},${rgbMatch[3]}`,
        };
      }
    }
  
    // Check for HSL format
    if (cleanColor.toLowerCase().includes("hsl") || cleanColor.includes("%")) {
      const hslMatch = cleanColor.match(/(\d+),\s*(\d+)%,\s*(\d+)%/);
      if (hslMatch) {
        return {
          param: "hsl",
          value: `${hslMatch[1]},${hslMatch[2]}%,${hslMatch[3]}%`,
        };
      }
    }
  
    // Default to hex if format is unclear
    return { param: "hex", value: cleanColor.replace("#", "") };
  }

• src/tools/index.ts:287-296 (registration)

  Exports the registerTools function which invokes registerQuadScheme among others to register all color scheme tools.

  export function registerTools() {
    registerMonochromeScheme();
    registerMonochromeDarkScheme();
    registerMonochromeLightScheme();
    registerAnalogicScheme();
    registerComplementScheme();
    registerAnalogicComplementScheme();
    registerTriadScheme();
    registerQuadScheme();
  }