@trishchuk/coolors-mcp 1.0.0

package/src/tools/material-theme.tools.ts

@@ -0,0 +1,250 @@
+/**
+ * Material Design Theme Tools
+ * Tools for Material Design 3 color theme generation and management
+ */
+
+import { z } from "zod";
+
+import {
+  adjustTemperature,
+  blend,
+  corePaletteFromRgb,
+  harmonize,
+  parseColor,
+  type RGB,
+  rgbToHct,
+  rgbToHex,
+  TonalPalette,
+} from "../color/index.js";
+
+/**
+ * Generate Material Design 3 Theme
+ */
+export const generateMaterialThemeTool = {
+  description:
+    "Generate a complete Material Design 3 color theme from a source color",
+  execute: async (args: {
+    includeCustomColors?: boolean;
+    sourceColor: string;
+  }) => {
+    const source = parseColor(args.sourceColor);
+    if (!source) {
+      return `Invalid color format: ${args.sourceColor}`;
+    }
+
+    const corePalette = corePaletteFromRgb(source);
+
+    // Generate key colors for light theme
+    const lightTheme = {
+      background: rgbToHex(corePalette.neutral.tone(99)),
+      error: rgbToHex(corePalette.error.tone(40)),
+      errorContainer: rgbToHex(corePalette.error.tone(90)),
+      onBackground: rgbToHex(corePalette.neutral.tone(10)),
+
+      onError: rgbToHex(corePalette.error.tone(100)),
+      onErrorContainer: rgbToHex(corePalette.error.tone(10)),
+      onPrimary: rgbToHex(corePalette.primary.tone(100)),
+      onPrimaryContainer: rgbToHex(corePalette.primary.tone(10)),
+
+      onSecondary: rgbToHex(corePalette.secondary.tone(100)),
+      onSecondaryContainer: rgbToHex(corePalette.secondary.tone(10)),
+      onSurface: rgbToHex(corePalette.neutral.tone(10)),
+      onSurfaceVariant: rgbToHex(corePalette.neutralVariant.tone(30)),
+
+      onTertiary: rgbToHex(corePalette.tertiary.tone(100)),
+      onTertiaryContainer: rgbToHex(corePalette.tertiary.tone(10)),
+      outline: rgbToHex(corePalette.neutralVariant.tone(50)),
+      primary: rgbToHex(corePalette.primary.tone(40)),
+
+      primaryContainer: rgbToHex(corePalette.primary.tone(90)),
+      secondary: rgbToHex(corePalette.secondary.tone(40)),
+      secondaryContainer: rgbToHex(corePalette.secondary.tone(90)),
+      surface: rgbToHex(corePalette.neutral.tone(99)),
+
+      surfaceVariant: rgbToHex(corePalette.neutralVariant.tone(90)),
+      tertiary: rgbToHex(corePalette.tertiary.tone(40)),
+      tertiaryContainer: rgbToHex(corePalette.tertiary.tone(90)),
+    };
+
+    // Generate key colors for dark theme
+    const darkTheme = {
+      background: rgbToHex(corePalette.neutral.tone(10)),
+      error: rgbToHex(corePalette.error.tone(80)),
+      errorContainer: rgbToHex(corePalette.error.tone(30)),
+      onBackground: rgbToHex(corePalette.neutral.tone(90)),
+
+      onError: rgbToHex(corePalette.error.tone(20)),
+      onErrorContainer: rgbToHex(corePalette.error.tone(90)),
+      onPrimary: rgbToHex(corePalette.primary.tone(20)),
+      onPrimaryContainer: rgbToHex(corePalette.primary.tone(90)),
+
+      onSecondary: rgbToHex(corePalette.secondary.tone(20)),
+      onSecondaryContainer: rgbToHex(corePalette.secondary.tone(90)),
+      onSurface: rgbToHex(corePalette.neutral.tone(90)),
+      onSurfaceVariant: rgbToHex(corePalette.neutralVariant.tone(80)),
+
+      onTertiary: rgbToHex(corePalette.tertiary.tone(20)),
+      onTertiaryContainer: rgbToHex(corePalette.tertiary.tone(90)),
+      outline: rgbToHex(corePalette.neutralVariant.tone(60)),
+      primary: rgbToHex(corePalette.primary.tone(80)),
+
+      primaryContainer: rgbToHex(corePalette.primary.tone(30)),
+      secondary: rgbToHex(corePalette.secondary.tone(80)),
+      secondaryContainer: rgbToHex(corePalette.secondary.tone(30)),
+      surface: rgbToHex(corePalette.neutral.tone(10)),
+
+      surfaceVariant: rgbToHex(corePalette.neutralVariant.tone(30)),
+      tertiary: rgbToHex(corePalette.tertiary.tone(80)),
+      tertiaryContainer: rgbToHex(corePalette.tertiary.tone(30)),
+    };
+
+    let result = `Material Design 3 Theme
+Source Color: ${args.sourceColor}
+
+LIGHT THEME:
+${Object.entries(lightTheme)
+  .map(([key, value]) => `  ${key}: ${value}`)
+  .join("\n")}
+
+DARK THEME:
+${Object.entries(darkTheme)
+  .map(([key, value]) => `  ${key}: ${value}`)
+  .join("\n")}`;
+
+    if (args.includeCustomColors) {
+      result += `\n\nTONAL PALETTES:
+Primary: ${[0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100]
+        .map((t) => rgbToHex(corePalette.primary.tone(t)))
+        .join(", ")}
+Secondary: ${[40, 80].map((t) => rgbToHex(corePalette.secondary.tone(t))).join(", ")}
+Tertiary: ${[40, 80].map((t) => rgbToHex(corePalette.tertiary.tone(t))).join(", ")}`;
+    }
+
+    return result;
+  },
+  name: "generate_material_theme",
+  parameters: z.object({
+    includeCustomColors: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe("Include custom color palettes"),
+    sourceColor: z.string().describe("Source color for theme generation"),
+  }),
+};
+
+/**
+ * Harmonize Colors Tool
+ */
+export const harmonizeColorsTool = {
+  description:
+    "Harmonize colors to work better together using Material Design algorithms",
+  execute: async (args: {
+    colors: string[];
+    factor?: number;
+    method?: "blend" | "harmonize" | "temperature";
+  }) => {
+    const colors = args.colors.map((c) => parseColor(c));
+    if (colors.some((c) => c === null)) {
+      return "One or more invalid color formats";
+    }
+
+    const validColors = colors as RGB[];
+    const method = args.method || "harmonize";
+    const factor = args.factor || 0.5;
+    const results: string[] = [];
+
+    switch (method) {
+      case "blend": {
+        // Blend all colors together
+        let result = validColors[0];
+        for (let i = 1; i < validColors.length; i++) {
+          result = blend(result, validColors[i], factor);
+        }
+        results.push(rgbToHex(result));
+        break;
+      }
+
+      case "harmonize": {
+        // Harmonize all colors with the first one
+        const source = validColors[0];
+        results.push(rgbToHex(source)); // Keep source unchanged
+
+        for (let i = 1; i < validColors.length; i++) {
+          results.push(rgbToHex(harmonize(validColors[i], source, factor)));
+        }
+        break;
+      }
+
+      case "temperature": {
+        // Adjust temperature of all colors
+        const amount = (factor - 0.5) * 2; // Convert to -1 to 1
+        for (const color of validColors) {
+          results.push(rgbToHex(adjustTemperature(color, amount)));
+        }
+        break;
+      }
+    }
+
+    return `Harmonized Colors (${method}):
+Original: ${args.colors.join(", ")}
+Result: ${results.join(", ")}`;
+  },
+  name: "harmonize_colors",
+  parameters: z.object({
+    colors: z
+      .array(z.string())
+      .min(2)
+      .max(10)
+      .describe("Array of colors to harmonize"),
+    factor: z
+      .number()
+      .min(0)
+      .max(1)
+      .optional()
+      .default(0.5)
+      .describe("Harmonization strength (0-1)"),
+    method: z
+      .enum(["blend", "harmonize", "temperature"])
+      .optional()
+      .default("harmonize")
+      .describe("Harmonization method"),
+  }),
+};
+
+/**
+ * Generate Tonal Palette Tool
+ */
+export const generateTonalPaletteTool = {
+  description: "Generate a Material Design tonal palette from a color",
+  execute: async (args: { color: string; tones?: number[] }) => {
+    const rgb = parseColor(args.color);
+    if (!rgb) {
+      return `Invalid color format: ${args.color}`;
+    }
+
+    const palette = TonalPalette.fromRgb(rgb);
+    const tones = args.tones || [
+      0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100,
+    ];
+
+    const hct = rgbToHct(rgb);
+    const colors = tones.map((tone) => ({
+      hex: rgbToHex(palette.tone(tone)),
+      tone,
+    }));
+
+    return `Tonal Palette for ${args.color}
+HCT: h=${hct.h.toFixed(1)}°, c=${hct.c.toFixed(1)}, t=${hct.t.toFixed(1)}
+
+${colors.map(({ hex, tone }) => `Tone ${tone}: ${hex}`).join("\n")}`;
+  },
+  name: "generate_tonal_palette",
+  parameters: z.object({
+    color: z.string().describe("Base color for palette"),
+    tones: z
+      .array(z.number())
+      .optional()
+      .describe("Custom tone values (default: Material standard tones)"),
+  }),
+};

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

@@ -0,0 +1,135 @@
+/**
+ * Palette Generator Tool
+ * Generate color palettes from a base color
+ */
+
+import { z } from "zod";
+
+import { parseColor, rgbToHex, rgbToHsl } from "../color/index.js";
+
+export const paletteGeneratorTool = {
+  description: "Generate a color palette from a base color",
+  execute: async (args: {
+    baseColor: string;
+    count?: number;
+    type?:
+      | "analogous"
+      | "complementary"
+      | "monochromatic"
+      | "tetradic"
+      | "triadic";
+  }) => {
+    const base = parseColor(args.baseColor);
+    if (!base) {
+      return `Invalid color format: ${args.baseColor}`;
+    }
+
+    const type = args.type || "monochromatic";
+    const count = args.count || 5;
+    const hsl = rgbToHsl(base);
+    const palette: string[] = [];
+
+    switch (type) {
+      case "analogous": {
+        // Colors adjacent on the color wheel
+        const step = 30;
+        for (let i = 0; i < count; i++) {
+          const h = (hsl.h + (i - Math.floor(count / 2)) * step + 360) % 360;
+          const color = parseColor(`hsl(${h}, ${hsl.s}%, ${hsl.l}%)`);
+          if (color) palette.push(rgbToHex(color));
+        }
+        break;
+      }
+      case "complementary": {
+        // Base color and its complement
+        palette.push(rgbToHex(base));
+        const complement = parseColor(
+          `hsl(${(hsl.h + 180) % 360}, ${hsl.s}%, ${hsl.l}%)`,
+        );
+        if (complement) palette.push(rgbToHex(complement));
+
+        // Add variations
+        for (let i = 2; i < count; i++) {
+          const l = hsl.l + (i % 2 === 0 ? 20 : -20);
+          const h = i < count / 2 ? hsl.h : (hsl.h + 180) % 360;
+          const color = parseColor(
+            `hsl(${h}, ${hsl.s}%, ${Math.max(10, Math.min(90, l))}%)`,
+          );
+          if (color) palette.push(rgbToHex(color));
+        }
+        break;
+      }
+      case "monochromatic": {
+        // Generate different lightness values
+        const step = 80 / (count - 1);
+        for (let i = 0; i < count; i++) {
+          const l = 10 + i * step;
+          const color = parseColor(`hsl(${hsl.h}, ${hsl.s}%, ${l}%)`);
+          if (color) palette.push(rgbToHex(color));
+        }
+        break;
+      }
+      case "tetradic": {
+        // Four colors in rectangle on color wheel
+        for (let i = 0; i < Math.min(4, count); i++) {
+          const h = (hsl.h + i * 90) % 360;
+          const color = parseColor(`hsl(${h}, ${hsl.s}%, ${hsl.l}%)`);
+          if (color) palette.push(rgbToHex(color));
+        }
+        // Add variations for remaining colors
+        for (let i = 4; i < count; i++) {
+          const baseIdx = i % 4;
+          const h = (hsl.h + baseIdx * 90) % 360;
+          const l = hsl.l + (i < 8 ? 15 : -15);
+          const color = parseColor(
+            `hsl(${h}, ${hsl.s}%, ${Math.max(10, Math.min(90, l))}%)`,
+          );
+          if (color) palette.push(rgbToHex(color));
+        }
+        break;
+      }
+      case "triadic": {
+        // Three colors evenly spaced on color wheel
+        for (let i = 0; i < Math.min(3, count); i++) {
+          const h = (hsl.h + i * 120) % 360;
+          const color = parseColor(`hsl(${h}, ${hsl.s}%, ${hsl.l}%)`);
+          if (color) palette.push(rgbToHex(color));
+        }
+        // Add variations for remaining colors
+        for (let i = 3; i < count; i++) {
+          const baseIdx = i % 3;
+          const h = (hsl.h + baseIdx * 120) % 360;
+          const l = hsl.l + (i < 6 ? 20 : -20);
+          const color = parseColor(
+            `hsl(${h}, ${hsl.s}%, ${Math.max(10, Math.min(90, l))}%)`,
+          );
+          if (color) palette.push(rgbToHex(color));
+        }
+        break;
+      }
+    }
+
+    return `Generated ${type} palette:
+${palette.map((color, i) => `${i + 1}. ${color}`).join("\n")}`;
+  },
+  name: "generate_palette",
+  parameters: z.object({
+    baseColor: z.string().describe("Base color for palette generation"),
+    count: z
+      .number()
+      .min(3)
+      .max(10)
+      .default(5)
+      .describe("Number of colors to generate"),
+    type: z
+      .enum([
+        "monochromatic",
+        "analogous",
+        "complementary",
+        "triadic",
+        "tetradic",
+      ])
+      .default("monochromatic")
+      .describe("Type of color palette"),
+  }),
+};

package/src/tools/palette-with-locks.tool.ts

@@ -0,0 +1,221 @@
+import { z } from "zod";
+
+import {
+  colorDistance,
+  hslToRgb,
+  labToRgb,
+  parseColor,
+  rgbToHex,
+  rgbToHsl,
+  rgbToLab,
+} from "../color/index.js";
+import { HSL, RGB } from "../color/types.js";
+
+export const paletteWithLocksTool = {
+  description:
+    "Generate a color palette while preserving specific locked colors",
+  execute: async (args: {
+    colorSpace?: "hsl" | "lab";
+    lockedColors: string[];
+    mode?: "contrast" | "gradient" | "harmony";
+    totalColors: number;
+  }) => {
+    const {
+      colorSpace = "hsl",
+      lockedColors,
+      mode = "harmony",
+      totalColors,
+    } = args;
+
+    if (lockedColors.length >= totalColors) {
+      return `Error: Number of locked colors (${lockedColors.length}) must be less than total colors (${totalColors})`;
+    }
+
+    // Parse and validate locked colors
+    const parsedLocked: RGB[] = [];
+    for (const color of lockedColors) {
+      const parsed = parseColor(color);
+      if (!parsed) {
+        return `Invalid color format: ${color}`;
+      }
+      parsedLocked.push(parsed);
+    }
+
+    const palette: string[] = [];
+    const remainingSlots = totalColors - lockedColors.length;
+
+    // Add locked colors to palette
+    lockedColors.forEach((color) => palette.push(color));
+
+    switch (mode) {
+      case "contrast": {
+        // Generate contrasting colors
+        for (let i = 0; i < remainingSlots; i++) {
+          let bestColor: null | RGB = null;
+          let maxMinDistance = 0;
+
+          // Try random colors and pick the one with maximum minimum distance
+          for (let attempt = 0; attempt < 100; attempt++) {
+            const candidate: RGB = {
+              b: Math.floor(Math.random() * 256),
+              g: Math.floor(Math.random() * 256),
+              r: Math.floor(Math.random() * 256),
+            };
+
+            let minDistance = Infinity;
+            for (const locked of parsedLocked) {
+              const dist = colorDistance(candidate, locked, "deltaE2000");
+              if (dist < minDistance) minDistance = dist;
+            }
+
+            if (minDistance > maxMinDistance) {
+              maxMinDistance = minDistance;
+              bestColor = candidate;
+            }
+          }
+
+          if (bestColor) {
+            palette.push(rgbToHex(bestColor));
+            parsedLocked.push(bestColor);
+          }
+        }
+        break;
+      }
+
+      case "gradient": {
+        // Create gradient between locked colors
+        if (parsedLocked.length < 2) {
+          return "Gradient mode requires at least 2 locked colors";
+        }
+
+        const steps = Math.floor(remainingSlots / (parsedLocked.length - 1));
+
+        for (let i = 0; i < parsedLocked.length - 1; i++) {
+          const start = parsedLocked[i];
+          const end = parsedLocked[i + 1];
+
+          for (let step = 1; step <= steps; step++) {
+            const t = step / (steps + 1);
+
+            if (colorSpace === "lab") {
+              // Interpolate in LAB space
+              const startLab = rgbToLab(start);
+              const endLab = rgbToLab(end);
+
+              const interpolated = 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,
+              });
+
+              palette.push(rgbToHex(interpolated));
+            } else {
+              // Interpolate in HSL space
+              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;
+
+              const interpolated = hslToRgb({
+                h: (startHsl.h + hueDiff * t + 360) % 360,
+                l: startHsl.l + (endHsl.l - startHsl.l) * t,
+                s: startHsl.s + (endHsl.s - startHsl.s) * t,
+              });
+
+              palette.push(rgbToHex(interpolated));
+            }
+          }
+        }
+        break;
+      }
+
+      case "harmony": {
+        // Generate harmonious colors based on locked colors
+        const baseHsl = rgbToHsl(parsedLocked[0]);
+        const hueStep = 360 / totalColors;
+
+        for (let i = 0; i < remainingSlots; i++) {
+          let newHue = baseHsl.h;
+          let attempts = 0;
+          let bestColor: null | RGB = null;
+          let maxMinDistance = 0;
+
+          // Try different hues to find one that's not too close to locked colors
+          while (attempts < 36) {
+            newHue = (baseHsl.h + attempts * 10) % 360;
+            const candidate = hslToRgb({
+              h: newHue,
+              l: baseHsl.l + (Math.random() - 0.5) * 20,
+              s: baseHsl.s + (Math.random() - 0.5) * 20,
+            });
+
+            // Check minimum distance to all locked colors
+            let minDistance = Infinity;
+            for (const locked of parsedLocked) {
+              const dist = colorDistance(candidate, locked, "deltaE2000");
+              if (dist < minDistance) minDistance = dist;
+            }
+
+            // Keep the candidate with the largest minimum distance
+            if (minDistance > maxMinDistance && minDistance > 10) {
+              maxMinDistance = minDistance;
+              bestColor = candidate;
+            }
+
+            attempts++;
+          }
+
+          if (bestColor) {
+            palette.push(rgbToHex(bestColor));
+            parsedLocked.push(bestColor); // Add to locked for next iteration
+          }
+        }
+        break;
+      }
+    }
+
+    // Sort palette to have locked colors marked
+    const result: string[] = [];
+    const lockedSet = new Set(lockedColors.map((c) => c.toLowerCase()));
+
+    palette.forEach((color) => {
+      if (lockedSet.has(color.toLowerCase())) {
+        result.push(`${color} (locked)`);
+      } else {
+        result.push(color);
+      }
+    });
+
+    return `Generated palette with ${lockedColors.length} locked colors:
+${result.map((color, i) => `${i + 1}. ${color}`).join("\n")}
+
+Mode: ${mode}
+Color space: ${colorSpace}
+Total colors: ${totalColors}`;
+  },
+  name: "generate_palette_with_locks",
+  parameters: z.object({
+    colorSpace: z
+      .enum(["hsl", "lab"])
+      .default("hsl")
+      .describe("Color space for interpolation (affects gradient smoothness)"),
+    lockedColors: z
+      .array(z.string())
+      .min(1)
+      .describe("Colors that must be included in the palette"),
+    mode: z
+      .enum(["harmony", "contrast", "gradient"])
+      .default("harmony")
+      .describe(
+        "Generation mode: harmony (similar), contrast (different), or gradient (smooth transition)",
+      ),
+    totalColors: z
+      .number()
+      .min(2)
+      .max(20)
+      .describe("Total number of colors in the final palette"),
+  }),
+};