Color Scheme Generator MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:225-241 (handler)

  Inline async handler function that destructures input args, invokes the generateColorScheme helper with 'analogic-complement' mode, and returns the result as formatted JSON text content.

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

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

  Shared Zod schema defining the tool's input shape: required color string and optional count (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:220-242 (registration)

  Registration function that calls server.tool to register the tool with its name, description, schema reference, and inline handler. Invoked from registerTools().

  function registerAnalogicComplementScheme() {
    server.tool(
      "generate_analogic_complement_scheme",
      "Generates an analogic complement color scheme",
      colorSchemeInputShape,
      async (args) => {
        const { color, count } = args;
        const result = await generateColorScheme(
          color,
          "analogic-complement",
          count
        );
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      }
    );
  }

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

  Core helper that parses color input, fetches color scheme from TheColorAPI using the specified mode ('analogic-complement'), formats the colors with hex/rgb/hsl/name, and structures the response.

  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)

  Helper to parse and normalize color input strings to API-compatible hex, rgb, or hsl parameters.

  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("#", "") };
  }