Color Scheme Generator MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:199-217 (registration)

  registerComplementScheme(): Registers the MCP tool 'generate_complement_scheme' with description, input schema reference, and inline handler.

  function registerComplementScheme() {
    server.tool(
      "generate_complement_scheme",
      "Generates a complementary color scheme with opposite colors on the color wheel",
      colorSchemeInputShape,
      async (args) => {
        const { color, count } = args;
        const result = await generateColorScheme(color, "complement", count);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      }
    );
  }

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

  Shared Zod input schema for color scheme tools: color (string), optional count (int 3-10, default 5).

  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:204-215 (handler)

  Handler executes tool logic: calls generateColorScheme('complement' mode) and returns formatted JSON as text content.

  async (args) => {
    const { color, count } = args;
    const result = await generateColorScheme(color, "complement", count);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

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

  Core helper implementing scheme generation: parses color, queries The Color API with mode, formats multi-format color list.

  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)

  parseColorInput: Normalizes user color input to API-compatible hex/rgb/hsl format.

  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)

  registerTools(): Called from src/index.ts to register all color scheme tools, including generate_complement_scheme.

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