Color Scheme Generator MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:158-173 (handler)

  The async handler function for the 'generate_monochrome_light_scheme' tool. It extracts color and count from args, calls the generateColorScheme helper with 'monochrome-light' mode, and returns the result as JSON-formatted text content.

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

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

  Shared Zod schema defining the input parameters for all color scheme tools, including color string and optional count.

  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:153-175 (registration)

  The registration function that registers the tool using server.tool, specifying name, description, input schema, and handler function.

  function registerMonochromeLightScheme() {
    server.tool(
      "generate_monochrome_light_scheme",
      "Generates a light monochrome color scheme",
      colorSchemeInputShape,
      async (args) => {
        const { color, count } = args;
        const result = await generateColorScheme(
          color,
          "monochrome-light",
          count
        );
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      }
    );
  }

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

  Core helper function that parses the seed color, constructs URL for The Color API, fetches the scheme, formats the colors with hex/rgb/hsl/name, and returns structured result.

  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)

  Supporting helper to parse input color string 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("#", "") };
  }