@trishchuk/coolors-mcp 1.0.0

package/src/tools/gradient-generator.tool.ts

@@ -0,0 +1,250 @@
+import { z } from "zod";
+
+import { Hct } from "../color/hct/index.js";
+import {
+  hslToRgb,
+  labToRgb,
+  parseColor,
+  rgbToHex,
+  rgbToHsl,
+  rgbToLab,
+} from "../color/index.js";
+import { RGB } from "../color/types.js";
+
+export const gradientGeneratorTool = {
+  description:
+    "Generate a smooth gradient between colors with multiple interpolation methods",
+  execute: async (args: {
+    colors: string[];
+    easing?: "ease-in-out" | "ease-in" | "ease-out" | "linear";
+    format?: "array" | "css-linear" | "css-radial" | "hex";
+    interpolation?: "hct" | "hsl" | "lab" | "lch" | "rgb";
+    steps: number;
+  }) => {
+    const {
+      colors,
+      easing = "linear",
+      format = "array",
+      interpolation = "lab",
+      steps,
+    } = args;
+
+    if (colors.length < 2) {
+      return "Error: At least 2 colors are required for a gradient";
+    }
+
+    // Parse input colors
+    const parsedColors: RGB[] = [];
+    for (const color of colors) {
+      const parsed = parseColor(color);
+      if (!parsed) {
+        return `Invalid color format: ${color}`;
+      }
+      parsedColors.push(parsed);
+    }
+
+    // Apply easing function
+    const applyEasing = (t: number): number => {
+      switch (easing) {
+        case "ease-in":
+          return t * t;
+        case "ease-in-out":
+          return t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
+        case "ease-out":
+          return t * (2 - t);
+        default:
+          return t;
+      }
+    };
+
+    // Generate gradient colors
+    const gradient: RGB[] = [];
+    const segmentSteps = Math.floor(steps / (colors.length - 1));
+    const extraSteps = steps % (colors.length - 1);
+
+    for (let segment = 0; segment < colors.length - 1; segment++) {
+      const start = parsedColors[segment];
+      const end = parsedColors[segment + 1];
+      const currentSteps = segmentSteps + (segment < extraSteps ? 1 : 0);
+
+      for (let step = 0; step < currentSteps; step++) {
+        const t = applyEasing(step / currentSteps);
+
+        let interpolatedColor: RGB;
+
+        switch (interpolation) {
+          case "hct": {
+            // HCT interpolation (Material Design color space)
+            const startHct = Hct.fromInt(
+              (255 << 24) | (start.r << 16) | (start.g << 8) | start.b,
+            );
+            const endHct = Hct.fromInt(
+              (255 << 24) | (end.r << 16) | (end.g << 8) | end.b,
+            );
+
+            // Interpolate hue (shortest path)
+            let hueDiff = endHct.hue - startHct.hue;
+            if (hueDiff > 180) hueDiff -= 360;
+            if (hueDiff < -180) hueDiff += 360;
+
+            const interpolatedHct = Hct.from(
+              (startHct.hue + hueDiff * t + 360) % 360,
+              startHct.chroma + (endHct.chroma - startHct.chroma) * t,
+              startHct.tone + (endHct.tone - startHct.tone) * t,
+            );
+
+            const argb = interpolatedHct.toInt();
+            interpolatedColor = {
+              b: argb & 0xff,
+              g: (argb >> 8) & 0xff,
+              r: (argb >> 16) & 0xff,
+            };
+            break;
+          }
+
+          case "hsl": {
+            // HSL interpolation
+            const startHsl = rgbToHsl(start);
+            const endHsl = rgbToHsl(end);
+
+            // Handle hue interpolation (shortest path)
+            let hueDiff = endHsl.h - startHsl.h;
+            if (hueDiff > 180) hueDiff -= 360;
+            if (hueDiff < -180) hueDiff += 360;
+
+            interpolatedColor = hslToRgb({
+              h: (startHsl.h + hueDiff * t + 360) % 360,
+              l: startHsl.l + (endHsl.l - startHsl.l) * t,
+              s: startHsl.s + (endHsl.s - startHsl.s) * t,
+            });
+            break;
+          }
+
+          case "lab": {
+            // LAB interpolation (perceptually uniform)
+            const startLab = rgbToLab(start);
+            const endLab = rgbToLab(end);
+
+            interpolatedColor = labToRgb({
+              a: startLab.a + (endLab.a - startLab.a) * t,
+              b: startLab.b + (endLab.b - startLab.b) * t,
+              l: startLab.l + (endLab.l - startLab.l) * t,
+            });
+            break;
+          }
+
+          case "lch": {
+            // LCH interpolation (cylindrical LAB)
+            const startLab = rgbToLab(start);
+            const endLab = rgbToLab(end);
+
+            // Convert LAB to LCH
+            const startL = startLab.l;
+            const startC = Math.sqrt(
+              startLab.a * startLab.a + startLab.b * startLab.b,
+            );
+            const startH = (Math.atan2(startLab.b, startLab.a) * 180) / Math.PI;
+
+            const endL = endLab.l;
+            const endC = Math.sqrt(endLab.a * endLab.a + endLab.b * endLab.b);
+            const endH = (Math.atan2(endLab.b, endLab.a) * 180) / Math.PI;
+
+            // Interpolate in LCH
+            let hueDiff = endH - startH;
+            if (hueDiff > 180) hueDiff -= 360;
+            if (hueDiff < -180) hueDiff += 360;
+
+            const l = startL + (endL - startL) * t;
+            const c = startC + (endC - startC) * t;
+            const h = ((startH + hueDiff * t) * Math.PI) / 180;
+
+            // Convert back to LAB then RGB
+            interpolatedColor = labToRgb({
+              a: c * Math.cos(h),
+              b: c * Math.sin(h),
+              l: l,
+            });
+            break;
+          }
+
+          case "rgb": {
+            // Simple RGB interpolation
+            interpolatedColor = {
+              b: Math.round(start.b + (end.b - start.b) * t),
+              g: Math.round(start.g + (end.g - start.g) * t),
+              r: Math.round(start.r + (end.r - start.r) * t),
+            };
+            break;
+          }
+
+          default:
+            interpolatedColor = start; // Fallback
+        }
+
+        gradient.push(interpolatedColor);
+      }
+    }
+
+    // Add the last color
+    gradient.push(parsedColors[parsedColors.length - 1]);
+
+    // Format output
+    const hexColors = gradient.map(rgbToHex);
+
+    switch (format) {
+      case "css-linear": {
+        const stops = hexColors.map((color, i) => {
+          const percent = (i / (hexColors.length - 1)) * 100;
+          return `${color} ${percent.toFixed(1)}%`;
+        });
+        return `linear-gradient(90deg, ${stops.join(", ")})`;
+      }
+
+      case "css-radial": {
+        const stops = hexColors.map((color, i) => {
+          const percent = (i / (hexColors.length - 1)) * 100;
+          return `${color} ${percent.toFixed(1)}%`;
+        });
+        return `radial-gradient(circle, ${stops.join(", ")})`;
+      }
+
+      case "hex":
+        return hexColors.join(", ");
+
+      case "array":
+      default:
+        return `Generated gradient with ${steps} steps:
+${hexColors.map((color, i) => `${i + 1}. ${color}`).join("\n")}
+
+Interpolation: ${interpolation}
+Easing: ${easing}
+Input colors: ${colors.join(" → ")}`;
+    }
+  },
+  name: "generate_gradient",
+  parameters: z.object({
+    colors: z
+      .array(z.string())
+      .min(2)
+      .describe("Colors to create gradient between (minimum 2)"),
+    easing: z
+      .enum(["linear", "ease-in", "ease-out", "ease-in-out"])
+      .default("linear")
+      .describe("Easing function for gradient transition"),
+    format: z
+      .enum(["hex", "css-linear", "css-radial", "array"])
+      .default("array")
+      .describe("Output format for the gradient"),
+    interpolation: z
+      .enum(["rgb", "hsl", "lab", "lch", "hct"])
+      .default("lab")
+      .describe(
+        "Color space for interpolation (lab/lch/hct are perceptually smooth)",
+      ),
+    steps: z
+      .number()
+      .min(3)
+      .max(100)
+      .describe("Number of colors in the gradient"),
+  }),
+};

package/src/tools/image-extraction.tools.ts

@@ -0,0 +1,289 @@
+/**
+ * MCP tools for image color extraction
+ */
+
+import type { Tool } from "../types.js";
+
+type ImageData = {
+  data: number[] | Uint8ClampedArray;
+  height: number;
+  width: number;
+};
+
+type McpTool = Tool<unknown>;
+
+import {
+  extractColors,
+  ExtractedColor,
+  extractThemePalette,
+} from "../color/extract-colors.js";
+import { generateMaterialTheme } from "../color/material-theme.js";
+
+/**
+ * Extract dominant colors from image data
+ */
+export const extractImageColorsTool: McpTool = {
+  description:
+    "Extract dominant colors from an image. Input should be image data as an array of RGBA values.",
+  execute: async (args: unknown, _context: unknown) => {
+    const {
+      format = "json",
+      imageData,
+      maxColors = 5,
+      quality = "medium",
+    } = args as {
+      format?: string;
+      imageData: ImageData;
+      maxColors?: number;
+      quality?: "high" | "low" | "medium";
+    };
+
+    try {
+      // Convert data array to Uint8ClampedArray if needed
+      const data =
+        imageData.data instanceof Uint8ClampedArray
+          ? imageData.data
+          : new Uint8ClampedArray(imageData.data);
+
+      const processedImageData = {
+        data,
+        height: imageData.height,
+        width: imageData.width,
+      };
+
+      // Extract colors
+      const colors = extractColors(processedImageData, {
+        filter: true,
+        maxColors,
+        quality,
+        scoringEnabled: true,
+      });
+
+      // Format output based on requested format
+      switch (format) {
+        case "css":
+          return formatAsCSS(colors);
+
+        case "palette":
+          return formatAsPalette(colors);
+
+        case "json":
+        default:
+          return formatAsJSON(colors);
+      }
+    } catch (error) {
+      return `Error extracting colors: ${error instanceof Error ? error.message : String(error)}`;
+    }
+  },
+  inputSchema: {
+    properties: {
+      format: {
+        description: "Output format: json, css, or palette (default: json)",
+        enum: ["json", "css", "palette"],
+        type: "string",
+      },
+      imageData: {
+        description: "Image data with RGBA values",
+        properties: {
+          data: {
+            description: "Flat array of RGBA values (0-255)",
+            items: { type: "number" },
+            type: "array",
+          },
+          height: {
+            description: "Image height in pixels",
+            type: "number",
+          },
+          width: {
+            description: "Image width in pixels",
+            type: "number",
+          },
+        },
+        required: ["data", "width", "height"],
+        type: "object",
+      },
+      maxColors: {
+        description: "Maximum number of colors to extract (default: 5)",
+        maximum: 20,
+        minimum: 1,
+        type: "number",
+      },
+      quality: {
+        description:
+          "Extraction quality: low, medium, or high (default: medium)",
+        enum: ["low", "medium", "high"],
+        type: "string",
+      },
+    },
+    required: ["imageData"],
+    type: "object",
+  },
+  name: "extract_image_colors",
+};
+
+/**
+ * Generate a Material Design theme from an image
+ */
+export const generateThemeFromImageTool: McpTool = {
+  description: "Generate a complete Material Design 3 theme from an image",
+  execute: async (args: unknown, _context: unknown) => {
+    const {
+      imageData,
+      includeCustomColors = true,
+      isDark = false,
+    } = args as {
+      imageData: ImageData;
+      includeCustomColors?: boolean;
+      isDark?: boolean;
+    };
+
+    try {
+      // Convert data array to Uint8ClampedArray if needed
+      const data =
+        imageData.data instanceof Uint8ClampedArray
+          ? imageData.data
+          : new Uint8ClampedArray(imageData.data);
+
+      const processedImageData = {
+        data,
+        height: imageData.height,
+        width: imageData.width,
+      };
+
+      // Extract theme palette
+      const palette = extractThemePalette(processedImageData);
+
+      // Convert primary color to hex for theme generation
+      const sourceColor = palette.primary.hex;
+
+      // Generate Material theme
+      const theme = generateMaterialTheme(sourceColor, { isDark });
+
+      // Add custom colors from extracted palette
+      if (includeCustomColors && palette.secondary) {
+        theme.customColors = {
+          secondary: {
+            color: palette.secondary.hex,
+            hct: palette.secondary.hct,
+            population: palette.secondary.population,
+          },
+        };
+
+        if (palette.tertiary) {
+          theme.customColors.tertiary = {
+            color: palette.tertiary.hex,
+            hct: palette.tertiary.hct,
+            population: palette.tertiary.population,
+          };
+        }
+      }
+
+      // Format output
+      let output = `# Material Design 3 Theme from Image\n\n`;
+      output += `## Source Colors\n`;
+      output += `- Primary: ${palette.primary.hex} (${palette.primary.percentage.toFixed(1)}%)\n`;
+
+      if (palette.secondary) {
+        output += `- Secondary: ${palette.secondary.hex} (${palette.secondary.percentage.toFixed(1)}%)\n`;
+      }
+      if (palette.tertiary) {
+        output += `- Tertiary: ${palette.tertiary.hex} (${palette.tertiary.percentage.toFixed(1)}%)\n`;
+      }
+
+      output += `\n## Theme Colors (${isDark ? "Dark" : "Light"} Mode)\n\n`;
+      output += `### Primary\n`;
+      output += `- primary: ${theme.schemes[isDark ? "dark" : "light"].primary}\n`;
+      output += `- onPrimary: ${theme.schemes[isDark ? "dark" : "light"].onPrimary}\n`;
+      output += `- primaryContainer: ${theme.schemes[isDark ? "dark" : "light"].primaryContainer}\n`;
+      output += `- onPrimaryContainer: ${theme.schemes[isDark ? "dark" : "light"].onPrimaryContainer}\n`;
+
+      output += `\n### Surface\n`;
+      output += `- surface: ${theme.schemes[isDark ? "dark" : "light"].surface}\n`;
+      output += `- onSurface: ${theme.schemes[isDark ? "dark" : "light"].onSurface}\n`;
+      output += `- surfaceVariant: ${theme.schemes[isDark ? "dark" : "light"].surfaceVariant}\n`;
+      output += `- onSurfaceVariant: ${theme.schemes[isDark ? "dark" : "light"].onSurfaceVariant}\n`;
+
+      output += `\n### Background\n`;
+      output += `- background: ${theme.schemes[isDark ? "dark" : "light"].background}\n`;
+      output += `- onBackground: ${theme.schemes[isDark ? "dark" : "light"].onBackground}\n`;
+
+      return output;
+    } catch (error) {
+      return `Error generating theme: ${error instanceof Error ? error.message : String(error)}`;
+    }
+  },
+  inputSchema: {
+    properties: {
+      imageData: {
+        description: "Image data with RGBA values",
+        properties: {
+          data: {
+            description: "Flat array of RGBA values (0-255)",
+            items: { type: "number" },
+            type: "array",
+          },
+          height: {
+            description: "Image height in pixels",
+            type: "number",
+          },
+          width: {
+            description: "Image width in pixels",
+            type: "number",
+          },
+        },
+        required: ["data", "width", "height"],
+        type: "object",
+      },
+      includeCustomColors: {
+        description: "Include custom colors from image (default: true)",
+        type: "boolean",
+      },
+      isDark: {
+        description: "Generate dark theme (default: false for light theme)",
+        type: "boolean",
+      },
+    },
+    required: ["imageData"],
+    type: "object",
+  },
+  name: "generate_theme_from_image",
+};
+
+// Helper functions for formatting
+
+function formatAsCSS(colors: ExtractedColor[]): string {
+  let css = ":root {\n";
+  colors.forEach((color, index) => {
+    css += `  --extracted-color-${index + 1}: ${color.hex}; /* ${color.percentage.toFixed(1)}% */\n`;
+  });
+  css += "}\n\n";
+
+  css += "/* Color Details */\n";
+  colors.forEach((color, index) => {
+    css += `/* Color ${index + 1}: ${color.hex}\n`;
+    css += `   RGB: rgb(${color.rgb.r}, ${color.rgb.g}, ${color.rgb.b})\n`;
+    css += `   HCT: hct(${color.hct.h.toFixed(1)}, ${color.hct.c.toFixed(1)}, ${color.hct.t.toFixed(1)})\n`;
+    css += `   Population: ${color.percentage.toFixed(1)}%\n`;
+    css += `*/\n\n`;
+  });
+
+  return css;
+}
+
+function formatAsJSON(colors: ExtractedColor[]): string {
+  return JSON.stringify(colors, null, 2);
+}
+
+function formatAsPalette(colors: ExtractedColor[]): string {
+  let output = "# Extracted Color Palette\n\n";
+
+  colors.forEach((color, index) => {
+    output += `## Color ${index + 1}\n`;
+    output += `- Hex: ${color.hex}\n`;
+    output += `- RGB: rgb(${color.rgb.r}, ${color.rgb.g}, ${color.rgb.b})\n`;
+    output += `- HCT: H:${color.hct.h.toFixed(1)}° C:${color.hct.c.toFixed(1)} T:${color.hct.t.toFixed(1)}\n`;
+    output += `- Usage: ${color.percentage.toFixed(1)}%\n\n`;
+  });
+
+  return output;
+}

package/src/tools/index.ts

@@ -0,0 +1,39 @@
+// Tool Registry Index - Export all tools
+
+// Color tools
+export { colorConversionTool } from "./color-conversion.tool.js";
+export { colorDistanceTool } from "./color-distance.tool.js";
+// Legacy tools (if needed)
+export { convertColor } from "./colors.js";
+export { contrastCheckerTool } from "./contrast-checker.tool.js";
+
+// Dislike analyzer tools
+export {
+  analyzeColorLikabilityTool,
+  fixDislikedColorsBatchTool,
+} from "./dislike-analyzer.tool.js";
+
+export { gradientGeneratorTool } from "./gradient-generator.tool.js";
+
+// Image extraction tools
+export {
+  extractImageColorsTool,
+  generateThemeFromImageTool,
+} from "./image-extraction.tools.js";
+
+// Material Design tools
+export {
+  generateMaterialThemeTool,
+  generateTonalPaletteTool,
+  harmonizeColorsTool,
+} from "./material-theme.tools.js";
+export { paletteGeneratorTool } from "./palette-generator.tool.js";
+export { paletteWithLocksTool } from "./palette-with-locks.tool.js";
+
+// Theme matching tools
+export {
+  generateThemeCssTool,
+  matchThemeColorsBatchTool,
+  matchThemeColorTool,
+  refactorCssWithThemeTool,
+} from "./theme-matching.tools.js";